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