doc/src/examples/dockwidgets.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example mainwindows/dockwidgets
  30     \title Dock Widgets Example
  31
  32     \brief The Dock Widgets example shows how to add dock windows to an
  33     application. It also shows how to use Qt's rich text engine.
  34
  35     \image dockwidgets-example.png Screenshot of the Dock Widgets example
  36
  37     The application presents a simple business letter template, and has
  38     a list of customer names and addresses and a list of standard
  39     phrases in two dock windows. The user can click a customer to have
  40     their name and address inserted into the template, and click one or
  41     more of the standard phrases. Errors can be corrected by clicking
  42     the Undo button. Once the letter has been prepared it can be printed
  43     or saved as HTML.
  44
  45     \section1 MainWindow Class Definition
  46
  47     Here's the class definition:
  48
  49     \snippet examples/mainwindows/dockwidgets/mainwindow.h 0
  50
  51     We will now review each function in turn.
  52
  53     \section1 MainWindow Class Implementation
  54
  55     \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 0
  56
  57     We start by including \c <QtGui>, a header file that contains the
  58     definition of all classes in the \l QtCore and \l QtGui
  59     libraries. This saves us from having to include
  60     every class individually and is especially convenient if we add new
  61     widgets. We also include \c mainwindow.h.
  62
  63     \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 1
  64
  65     In the constructor, we start by creating a QTextEdit widget. Then we call
  66     QMainWindow::setCentralWidget(). This function passes ownership of
  67     the QTextEdit to the \c MainWindow and tells the \c MainWindow that
  68     the QTextEdit will occupy the \c MainWindow's central area.
  69
  70     Then we call \c createActions(), \c createMenus(), \c
  71     createToolBars(), \c createStatusBar(), and \c createDockWindows()
  72     to set up the user interface. Finally we call \c setWindowTitle() to
  73     give the application a title, and \c newLetter() to create a new
  74     letter template.
  75
  76     We won't quote the \c createActions(), \c createMenus(), \c
  77     createToolBars(), and \c createStatusBar() functions since they
  78     follow the same pattern as all the other Qt examples.
  79
  80     \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 9
  81
  82     We create the customers dock window first, and in addition to a
  83     window title, we also pass it a \c this pointer so that it becomes a
  84     child of \c MainWindow. Normally we don't have to pass a parent
  85     because widgets are parented automatically when they are laid out:
  86     but dock windows aren't laid out using layouts.
  87
  88     We've chosen to restrict the customers dock window to the left and
  89     right dock areas. (So the user cannot drag the dock window to the
  90     top or bottom dock areas.) The user can drag the dock window out of
  91     the dock areas entirely so that it becomes a free floating window.
  92     We can change this (and whether the dock window is moveable or
  93     closable) using QDockWidget::setFeatures().
  94
  95     Once we've created the dock window we create a list widget with the
  96     dock window as parent, then we populate the list and make it the
  97     dock window's widget. Finally we add the dock widget to the \c
  98     MainWindow using \c addDockWidget(), choosing to put it in the right
  99     dock area.
 100
 101     We undertake a similar process for the paragraphs dock window,
 102     except that we don't restrict which dock areas it can be dragged to.
 103
 104     Finally we set up the signal-slot connections. If the user clicks a
 105     customer or a paragraph their \c currentTextChanged() signal will be
 106     emitted and we connect these to \c insertCustomer() and
 107     addParagraph() passing the text that was clicked.
 108
 109     We briefly discuss the rest of the implementation, but have now
 110     covered everything relating to dock windows.
 111
 112     \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 2
 113
 114     In this function we clear the QTextEdit so that it is empty. Next we
 115     create a QTextCursor on the QTextEdit. We move the cursor to the
 116     start of the document and create and format a frame. We then create
 117     some character formats and a table format. We insert a table into
 118     the document and insert the company's name and address into a table
 119     using the table and character formats we created earlier. Then we
 120     insert the skeleton of the letter including two markers \c NAME and
 121     \c ADDRESS. We will also use the \c{Yours sincerely,} text as a marker.
 122
 123     \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 6
 124
 125     If the user clicks a customer we split the customer details into
 126     pieces. We then look for the \c NAME marker using the \c find()
 127     function. This function selects the text it finds, so when we call
 128     \c insertText() with the customer's name the name replaces the marker.
 129     We then look for the \c ADDRESS marker and replace it with each line
 130     of the customer's address. Notice that we wrapped all the insertions
 131     between a \c beginEditBlock() and \c endEditBlock() pair. This means
 132     that the entire name and address insertion is treated as a single
 133     operation by the QTextEdit, so a single undo will revert all the
 134     insertions.
 135
 136     \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 7
 137
 138     This function works in a similar way to \c insertCustomer(). First
 139     we look for the marker, in this case, \c {Yours sincerely,}, and then
 140     replace it with the standard paragraph that the user clicked. Again
 141     we use a \c beginEditBlock() ... \c endEditBlock() pair so that the
 142     insertion can be undone as a single operation.
 143
 144     \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 3
 145
 146     Qt's QTextDocument class makes printing documents easy. We simply
 147     take the QTextEdit's QTextDocument, set up the printer and print the
 148     document.
 149
 150     \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 4
 151
 152     QTextEdit can output its contents in HTML format, so we prompt the
 153     user for the name of an HTML file and if they provide one we simply
 154     write the QTextEdit's contents in HTML format to the file.
 155
 156     \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 5
 157
 158     If the focus is in the QTextEdit, pressing \key Ctrl+Z undoes as
 159     expected. But for the user's convenience we provide an
 160     application-wide undo function that simply calls the QTextEdit's
 161     undo: this means that the user can undo regardless of where the
 162     focus is in the application.
 163 */