Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 364 insertions, 0 deletions

diff --git a/doc/src/examples/orderform.qdoc b/doc/src/examples/orderform.qdoc
new file mode 100644
index 0000000000..d6b421d62e
--- /dev/null
+++ b/doc/src/examples/orderform.qdoc
@@ -0,0 +1,364 @@
+/****************************************************************************
+**
+** 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$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example richtext/orderform
+    \title Order Form Example
+
+    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
+
+*/