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