examples/widgets/doc/src/orderform.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   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 Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/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 richtext/orderform
  30     \title Order Form Example
  31
  32     \brief The Order Form example shows how to generate rich text documents by
  33     combining a simple template with data input by the user in a dialog. Data
  34     is extracted from a \c DetailsDialog object and displayed on a QTextEdit
  35     with a QTextCursor, using various formats. Each form generated is added
  36     to a QTabWidget for easy access.
  37
  38     \image orderform-example.png
  39
  40     \section1 DetailsDialog Definition
  41
  42     The \c DetailsDialog class is a subclass of QDialog, implementing a slot
  43     \c verify() to allow contents of the \c DetailsDialog to be verified later.
  44     This is further explained in \c DetailsDialog Implementation.
  45
  46     \snippet richtext/orderform/detailsdialog.h 0
  47
  48     The constructor of \c DetailsDialog accepts parameters \a title and
  49     \a parent. The class defines four \e{getter} functions: \c orderItems(),
  50     \c senderName(), \c senderAddress(), and \c sendOffers() to allow data
  51     to be accessed externally.
  52
  53     The class definition includes input widgets for the required
  54     fields, \c nameEdit and \c addressEdit. Also, a QCheckBox and a
  55     QDialogButtonBox are defined; the former to provide the user with the
  56     option to receive information on products and offers, and the latter
  57     to ensure that buttons used are arranged according to the user's native
  58     platform. In addition, a QTableWidget, \c itemsTable, is used to hold
  59     order details.
  60
  61     The screenshot below shows the \c DetailsDialog we intend to create.
  62
  63     \image orderform-example-detailsdialog.png
  64
  65     \section1 DetailsDialog Implementation
  66
  67     The constructor of \c DetailsDialog instantiates the earlier defined fields
  68     and their respective labels. The label for \c offersCheckBox is set and the
  69     \c setupItemsTable() function is invoked to setup and populate
  70     \c itemsTable. The QDialogButtonBox object, \c buttonBox, is instantiated
  71     with \uicontrol OK and \uicontrol Cancel buttons. This \c buttonBox's \c accepted() and
  72     \c rejected() signals are connected to the \c verify() and \c reject()
  73     slots in \c DetailsDialog.
  74
  75     \snippet richtext/orderform/detailsdialog.cpp 0
  76
  77     A QGridLayout is used to place all the objects on the \c DetailsDialog.
  78
  79     \snippet richtext/orderform/detailsdialog.cpp 1
  80
  81     The \c setupItemsTable() function instantiates the QTableWidget object,
  82     \c itemsTable, and sets the number of rows based on the QStringList
  83     object, \c items, which holds the type of items ordered. The number of
  84     columns is set to 2, providing a "name" and "quantity" layout. A \c for
  85     loop is used to populate the \c itemsTable and the \c name item's flag
  86     is set to Qt::ItemIsEnabled or Qt::ItemIsSelectable. For demonstration
  87     purposes, the \c quantity item is set to a 1 and all items in the
  88     \c itemsTable have this value for quantity; but this can be modified by
  89     editing the contents of the cells at run time.
  90
  91     \snippet richtext/orderform/detailsdialog.cpp 2
  92
  93     The \c orderItems() function extracts data from the \c itemsTable and
  94     returns it in the form of a QList<QPair<QString,int>> where each QPair
  95     corresponds to an item and the quantity ordered.
  96
  97     \snippet richtext/orderform/detailsdialog.cpp 3
  98
  99     The \c senderName() function is used to return the value of the QLineEdit
 100     used to store the name field for the order form.
 101
 102     \snippet richtext/orderform/detailsdialog.cpp 4
 103
 104     The \c senderAddress() function is used to return the value of the
 105     QTextEdit containing the address for the order form.
 106
 107     \snippet richtext/orderform/detailsdialog.cpp 5
 108
 109     The \c sendOffers() function is used to return a \c true or \c false
 110     value that is used to determine if the customer in the order form
 111     wishes to receive more information on the company's offers and promotions.
 112
 113     \snippet richtext/orderform/detailsdialog.cpp 6
 114
 115     The \c verify() function is an additionally implemented slot used to
 116     verify the details entered by the user into the \c DetailsDialog. If
 117     the details entered are incomplete, a QMessageBox is displayed
 118     providing the user the option to discard the \c DetailsDialog. Otherwise,
 119     the details are accepted and the \c accept() function is invoked.
 120
 121     \snippet richtext/orderform/detailsdialog.cpp 7
 122
 123     \section1 MainWindow Definition
 124
 125     The \c MainWindow class is a subclass of QMainWindow, implementing two
 126     slots - \c openDialog() and \c printFile(). It also contains a private
 127     instance of QTabWidget, \c letters.
 128
 129     \snippet richtext/orderform/mainwindow.h 0
 130
 131     \section1 MainWindow Implementation
 132
 133     The \c MainWindow constructor sets up the \c fileMenu and the required
 134     actions, \c newAction and \c printAction. These actions' \c triggered()
 135     signals are connected to the additionally implemented openDialog() slot
 136     and the default close() slot. The QTabWidget, \c letters, is
 137     instantiated and set as the window's central widget.
 138
 139     \snippet richtext/orderform/mainwindow.cpp 0
 140
 141     The \c createLetter() function creates a new QTabWidget with a QTextEdit,
 142     \c editor, as the parent. This function accepts four parameters that
 143     correspond to we obtained through \c DetailsDialog, in order to "fill"
 144     the \c editor.
 145
 146     \snippet richtext/orderform/mainwindow.cpp 1
 147
 148     We then obtain the cursor for the \c editor using QTextEdit::textCursor().
 149     The \c cursor is then moved to the start of the document using
 150     QTextCursor::Start.
 151
 152     \snippet richtext/orderform/mainwindow.cpp 2
 153
 154     Recall the structure of a \l{Rich Text Document Structure}
 155     {Rich Text Document}, where sequences of frames and
 156     tables are always separated by text blocks, some of which may contain no
 157     information.
 158
 159     In the case of the Order Form Example, the document structure for this portion
 160     is described by the table below:
 161
 162     \table
 163         \row
 164             \li {1, 8} frame with \e{referenceFrameFormat}
 165         \row
 166             \li block \li \c{A company}
 167         \row
 168             \li block
 169         \row
 170             \li block \li \c{321 City Street}
 171         \row
 172             \li block
 173         \row
 174             \li block \li \c{Industry Park}
 175         \row
 176             \li block
 177         \row
 178             \li block \li \c{Another country}
 179     \endtable
 180
 181     This is accomplished with the following code:
 182
 183     \snippet richtext/orderform/mainwindow.cpp 3
 184
 185     Note that \c topFrame is the \c {editor}'s top-level frame and is not shown
 186     in the document structure.
 187
 188     We then set the \c{cursor}'s position back to its last position in
 189     \c topFrame and fill in the customer's name (provided by the constructor)
 190     and address - using a \c foreach loop to traverse the QString, \c address.
 191
 192     \snippet richtext/orderform/mainwindow.cpp 4
 193
 194     The \c cursor is now back in \c topFrame and the document structure for
 195     the above portion of code is:
 196
 197     \table
 198         \row
 199             \li block \li \c{Donald}
 200         \row
 201             \li block \li \c{47338 Park Avenue}
 202         \row
 203             \li block \li \c{Big City}
 204     \endtable
 205
 206     For spacing purposes, we invoke \l{QTextCursor::insertBlock()}
 207     {insertBlock()} twice. The \l{QDate::currentDate()}{currentDate()} is
 208     obtained and displayed. We use \l{QTextFrameFormat::setWidth()}
 209     {setWidth()} to increase the width of \c bodyFrameFormat and we insert
 210     a new frame with that width.
 211
 212     \snippet richtext/orderform/mainwindow.cpp 5
 213
 214     The following code inserts standard text into the order form.
 215
 216     \snippet richtext/orderform/mainwindow.cpp 6
 217     \snippet richtext/orderform/mainwindow.cpp 7
 218
 219     This part of the document structure now contains the date, a frame with
 220     \c bodyFrameFormat, as well as the standard text.
 221
 222     \table
 223         \row
 224             \li block
 225         \row
 226             \li block
 227         \row
 228             \li block \li \c{Date: 25 May 2007}
 229         \row
 230             \li block
 231         \row
 232             \li {1, 4} frame with \e{bodyFrameFormat}
 233         \row
 234             \li block \li \c{I would like to place an order for the following items:}
 235         \row
 236             \li block
 237         \row
 238             \li block
 239     \endtable
 240
 241     A QTextTableFormat object, \c orderTableFormat, is used to hold the type
 242     of item and the quantity ordered.
 243
 244     \snippet richtext/orderform/mainwindow.cpp 8
 245
 246     We use \l{QTextTable::cellAt()}{cellAt()} to set the headers for the
 247     \c orderTable.
 248
 249     \snippet richtext/orderform/mainwindow.cpp 9
 250
 251     Then, we iterate through the QList of QPair objects to populate
 252     \c orderTable.
 253
 254     \snippet richtext/orderform/mainwindow.cpp 10
 255
 256     The resulting document structure for this section is:
 257
 258     \table
 259         \row
 260             \li {1, 11} \c{orderTable} with \e{orderTableFormat}
 261         \row
 262             \li block \li \c{Product}
 263         \row
 264             \li block \li \c{Quantity}
 265         \row
 266             \li block \li \c{T-shirt}
 267         \row
 268             \li block \li \c{4}
 269         \row
 270             \li block \li \c{Badge}
 271         \row
 272             \li block \li \c{3}
 273         \row
 274             \li block \li \c{Reference book}
 275         \row
 276             \li block \li \c{2}
 277         \row
 278             \li block \li \c{Coffee cup}
 279         \row
 280             \li block \li \c{5}
 281     \endtable
 282
 283     The \c cursor is then moved back to \c{topFrame}'s
 284     \l{QTextFrame::lastPosition()}{lastPosition()} and more standard text
 285     is inserted.
 286
 287     \snippet richtext/orderform/mainwindow.cpp 11
 288     \snippet richtext/orderform/mainwindow.cpp 12
 289
 290     Another QTextTable is inserted, to display the customer's
 291     preference regarding offers.
 292
 293     \snippet richtext/orderform/mainwindow.cpp 13
 294
 295     The document structure for this portion is:
 296
 297     \table
 298         \row
 299             \li block
 300         \row
 301             \li block\li \c{Please update my...}
 302         \row
 303             \li {1, 5} block
 304         \row
 305             \li {1, 4} \c{offersTable}
 306         \row
 307             \li block \li \c{I want to receive...}
 308         \row
 309             \li block \li \c{I do not want to receive...}
 310         \row
 311             \li block \li \c{X}
 312     \endtable
 313
 314     The \c cursor is moved to insert "Sincerely" along with the customer's
 315     name. More blocks are inserted for spacing purposes. The \c printAction
 316     is enabled to indicate that an order form can now be printed.
 317
 318     \snippet richtext/orderform/mainwindow.cpp 14
 319
 320     The bottom portion of the document structure is:
 321
 322     \table
 323         \row
 324             \li block
 325         \row
 326             \li {1, 5} block\li \c{Sincerely,}
 327         \row
 328             \li block
 329         \row
 330             \li block
 331         \row
 332             \li block
 333         \row
 334             \li block \li \c{Donald}
 335     \endtable
 336
 337     The \c createSample() function is used for illustration purposes, to create
 338     a sample order form.
 339
 340     \snippet richtext/orderform/mainwindow.cpp 15
 341
 342     The \c openDialog() function opens a \c DetailsDialog object. If the
 343     details in \c dialog are accepted, the \c createLetter() function is
 344     invoked using the parameters extracted from \c dialog.
 345
 346     \snippet richtext/orderform/mainwindow.cpp 16
 347
 348     In order to print out the order form, a \c printFile() function is
 349     included, as shown below:
 350
 351     \snippet richtext/orderform/mainwindow.cpp 17
 352
 353     This function also allows the user to print a selected area with
 354     QTextCursor::hasSelection(), instead of printing the entire document.
 355
 356     \section1 \c main() Function
 357
 358     The \c main() function instantiates \c MainWindow and sets its size to
 359     640x480 pixels before invoking the \c show() function and
 360     \c createSample() function.
 361
 362     \snippet richtext/orderform/main.cpp 0
 363
 364 */