summaryrefslogtreecommitdiffstats
path: root/doc/src/examples/orderform.qdoc
blob: 8d611437224645f1e38718264c97fd6aac62b4b0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example richtext/orderform
    \title Order Form Example

    \brief The Order Form example shows how to generate rich text documents by
    combining a simple template with data input by the user in a dialog.
    
    Data is extracted from a \c DetailsDialog object and displayed on a QTextEdit
    with a QTextCursor, using various formats. Each form generated is added
    to a QTabWidget for easy access.

    \image orderform-example.png

    \section1 DetailsDialog Definition

    The \c DetailsDialog class is a subclass of QDialog, implementing a slot
    \c verify() to allow contents of the \c DetailsDialog to be verified later.
    This is further explained in \c DetailsDialog Implementation.

    \snippet examples/richtext/orderform/detailsdialog.h 0

    The constructor of \c DetailsDialog accepts parameters \a title and
    \a parent. The class defines four \e{getter} functions: \c orderItems(),
    \c senderName(), \c senderAddress(), and \c sendOffers() to allow data
    to be accessed externally.

    The class definition includes input widgets for the required
    fields, \c nameEdit and \c addressEdit. Also, a QCheckBox and a
    QDialogButtonBox are defined; the former to provide the user with the
    option to receive information on products and offers, and the latter
    to ensure that buttons used are arranged according to the user's native
    platform. In addition, a QTableWidget, \c itemsTable, is used to hold
    order details.

    The screenshot below shows the \c DetailsDialog we intend to create.

    \image orderform-example-detailsdialog.png

    \section1 DetailsDialog Implementation

    The constructor of \c DetailsDialog instantiates the earlier defined fields
    and their respective labels. The label for \c offersCheckBox is set and the
    \c setupItemsTable() function is invoked to setup and populate
    \c itemsTable. The QDialogButtonBox object, \c buttonBox, is instantiated
    with \gui OK and \gui Cancel buttons. This \c buttonBox's \c accepted() and
    \c rejected() signals are connected to the \c verify() and \c reject()
    slots in \c DetailsDialog.

    \snippet examples/richtext/orderform/detailsdialog.cpp 0

    A QGridLayout is used to place all the objects on the \c DetailsDialog.

    \snippet examples/richtext/orderform/detailsdialog.cpp 1

    The \c setupItemsTable() function instantiates the QTableWidget object,
    \c itemsTable, and sets the number of rows based on the QStringList
    object, \c items, which holds the type of items ordered. The number of
    columns is set to 2, providing a "name" and "quantity" layout. A \c for
    loop is used to populate the \c itemsTable and the \c name item's flag
    is set to Qt::ItemIsEnabled or Qt::ItemIsSelectable. For demonstration
    purposes, the \c quantity item is set to a 1 and all items in the
    \c itemsTable have this value for quantity; but this can be modified by
    editing the contents of the cells at run time.

    \snippet examples/richtext/orderform/detailsdialog.cpp 2

    The \c orderItems() function extracts data from the \c itemsTable and
    returns it in the form of a QList<QPair<QString,int>> where each QPair
    corresponds to an item and the quantity ordered.

    \snippet examples/richtext/orderform/detailsdialog.cpp 3

    The \c senderName() function is used to return the value of the QLineEdit
    used to store the name field for the order form.

    \snippet examples/richtext/orderform/detailsdialog.cpp 4

    The \c senderAddress() function is used to return the value of the
    QTextEdit containing the address for the order form.

    \snippet examples/richtext/orderform/detailsdialog.cpp 5

    The \c sendOffers() function is used to return a \c true or \c false
    value that is used to determine if the customer in the order form
    wishes to receive more information on the company's offers and promotions.

    \snippet examples/richtext/orderform/detailsdialog.cpp 6

    The \c verify() function is an additionally implemented slot used to
    verify the details entered by the user into the \c DetailsDialog. If
    the details entered are incomplete, a QMessageBox is displayed
    providing the user the option to discard the \c DetailsDialog. Otherwise,
    the details are accepted and the \c accept() function is invoked.

    \snippet examples/richtext/orderform/detailsdialog.cpp 7

    \section1 MainWindow Definition

    The \c MainWindow class is a subclass of QMainWindow, implementing two
    slots - \c openDialog() and \c printFile(). It also contains a private
    instance of QTabWidget, \c letters.

    \snippet examples/richtext/orderform/mainwindow.h 0

    \section1 MainWindow Implementation

    The \c MainWindow constructor sets up the \c fileMenu and the required
    actions, \c newAction and \c printAction. These actions' \c triggered()
    signals are connected to the additionally implemented openDialog() slot
    and the default close() slot. The QTabWidget, \c letters, is
    instantiated and set as the window's central widget.

    \snippet examples/richtext/orderform/mainwindow.cpp 0

    The \c createLetter() function creates a new QTabWidget with a QTextEdit,
    \c editor, as the parent. This function accepts four parameters that
    correspond to we obtained through \c DetailsDialog, in order to "fill"
    the \c editor.

    \snippet examples/richtext/orderform/mainwindow.cpp 1

    We then obtain the cursor for the \c editor using QTextEdit::textCursor().
    The \c cursor is then moved to the start of the document using
    QTextCursor::Start.

    \snippet examples/richtext/orderform/mainwindow.cpp 2

    Recall the structure of a \l{Rich Text Document Structure}
    {Rich Text Document}, where sequences of frames and
    tables are always separated by text blocks, some of which may contain no
    information.

    In the case of the Order Form Example, the document structure for this portion
    is described by the table below:

    \table
        \row
            \o {1, 8} frame with \e{referenceFrameFormat}
        \row
            \o block \o \c{A company}
        \row
            \o block
        \row
            \o block \o \c{321 City Street}
        \row
            \o block
        \row
            \o block \o \c{Industry Park}
        \row
            \o block
        \row
            \o block \o \c{Another country}
    \endtable

    This is accomplished with the following code:

    \snippet examples/richtext/orderform/mainwindow.cpp 3

    Note that \c topFrame is the \c {editor}'s top-level frame and is not shown
    in the document structure.

    We then set the \c{cursor}'s position back to its last position in
    \c topFrame and fill in the customer's name (provided by the constructor)
    and address - using a \c foreach loop to traverse the QString, \c address.

    \snippet examples/richtext/orderform/mainwindow.cpp 4

    The \c cursor is now back in \c topFrame and the document structure for
    the above portion of code is:

    \table
        \row
            \o block \o \c{Donald}
        \row
            \o block \o \c{47338 Park Avenue}
        \row
            \o block \o \c{Big City}
    \endtable

    For spacing purposes, we invoke \l{QTextCursor::insertBlock()}
    {insertBlock()} twice. The \l{QDate::currentDate()}{currentDate()} is
    obtained and displayed. We use \l{QTextFrameFormat::setWidth()}
    {setWidth()} to increase the width of \c bodyFrameFormat and we insert
    a new frame with that width.

    \snippet examples/richtext/orderform/mainwindow.cpp 5

    The following code inserts standard text into the order form.

    \snippet examples/richtext/orderform/mainwindow.cpp 6
    \snippet examples/richtext/orderform/mainwindow.cpp 7

    This part of the document structure now contains the date, a frame with
    \c bodyFrameFormat, as well as the standard text.

    \table
        \row
            \o block
        \row
            \o block
        \row
            \o block \o \c{Date: 25 May 2007}
        \row
            \o block
        \row
            \o {1, 4} frame with \e{bodyFrameFormat}
        \row
            \o block \o \c{I would like to place an order for the following items:}
        \row
            \o block
        \row
            \o block
    \endtable

    A QTextTableFormat object, \c orderTableFormat, is used to hold the type
    of item and the quantity ordered.

    \snippet examples/richtext/orderform/mainwindow.cpp 8

    We use \l{QTextTable::cellAt()}{cellAt()} to set the headers for the
    \c orderTable.

    \snippet examples/richtext/orderform/mainwindow.cpp 9

    Then, we iterate through the QList of QPair objects to populate
    \c orderTable.

    \snippet examples/richtext/orderform/mainwindow.cpp 10

    The resulting document structure for this section is:

    \table
        \row
            \o {1, 11} \c{orderTable} with \e{orderTableFormat}
        \row
            \o block \o \c{Product}
        \row
            \o block \o \c{Quantity}
        \row
            \o block \o \c{T-shirt}
        \row
            \o block \o \c{4}
        \row
            \o block \o \c{Badge}
        \row
            \o block \o \c{3}
        \row
            \o block \o \c{Reference book}
        \row
            \o block \o \c{2}
        \row
            \o block \o \c{Coffee cup}
        \row
            \o block \o \c{5}
    \endtable

    The \c cursor is then moved back to \c{topFrame}'s
    \l{QTextFrame::lastPosition()}{lastPosition()} and more standard text
    is inserted.

    \snippet examples/richtext/orderform/mainwindow.cpp 11
    \snippet examples/richtext/orderform/mainwindow.cpp 12

    Another QTextTable is inserted, to display the customer's
    preference regarding offers.

    \snippet examples/richtext/orderform/mainwindow.cpp 13

    The document structure for this portion is:

    \table
        \row
            \o block
        \row
            \o block\o \c{Please update my...}
        \row
            \o {1, 5} block
        \row
            \o {1, 4} \c{offersTable}
        \row
            \o block \o \c{I want to receive...}
        \row
            \o block \o \c{I do not want to recieve...}
        \row
            \o block \o \c{X}
    \endtable

    The \c cursor is moved to insert "Sincerely" along with the customer's
    name. More blocks are inserted for spacing purposes. The \c printAction
    is enabled to indicate that an order form can now be printed.

    \snippet examples/richtext/orderform/mainwindow.cpp 14

    The bottom portion of the document structure is:

    \table
        \row
            \o block
        \row
            \o {1, 5} block\o \c{Sincerely,}
        \row
            \o block
        \row
            \o block
        \row
            \o block
        \row
            \o block \o \c{Donald}
    \endtable

    The \c createSample() function is used for illustration purposes, to create
    a sample order form.

    \snippet examples/richtext/orderform/mainwindow.cpp 15

    The \c openDialog() function opens a \c DetailsDialog object. If the
    details in \c dialog are accepted, the \c createLetter() function is
    invoked using the parameters extracted from \c dialog.

    \snippet examples/richtext/orderform/mainwindow.cpp 16

    In order to print out the order form, a \c printFile() function is
    included, as shown below:

    \snippet examples/richtext/orderform/mainwindow.cpp 17

    This function also allows the user to print a selected area with
    QTextCursor::hasSelection(), instead of printing the entire document.

    \section1 \c main() Function

    The \c main() function instantiates \c MainWindow and sets its size to
    640x480 pixels before invoking the \c show() function and
    \c createSample() function.

    \snippet examples/richtext/orderform/main.cpp 0

*/