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, 125 insertions, 0 deletions

diff --git a/doc/src/examples/simplewidgetmapper.qdoc b/doc/src/examples/simplewidgetmapper.qdoc
new file mode 100644
index 0000000000..22ca9e7a30
--- /dev/null
+++ b/doc/src/examples/simplewidgetmapper.qdoc
@@ -0,0 +1,125 @@
+/****************************************************************************
+**
+** 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 itemviews/simplewidgetmapper
+    \title Simple Widget Mapper Example
+
+    The Simple Widget Mapper example shows how to use a widget mapper to display
+    data from a model in a collection of widgets.
+
+    \image simplewidgetmapper-example.png
+
+    The QDataWidgetMapper class allows information obtained from a
+    \l{Model Classes}{model} to be viewed and edited in a collection of
+    widgets instead of in an \l{View Classes}{item view}.
+    Any model derived from QAbstractItemModel can be used as the source of
+    data and almost any input widget can be used to display it.
+
+    The example itself is very simple: we create \c Window, a QWidget subclass
+    that we use to hold the widgets used to present the data, and show it. The
+    \c Window class will provide buttons that the user can click to show
+    different records from the model.
+
+    \section1 Window Class Definition
+
+    The class provides a constructor, a slot to keep the buttons up to date,
+    and a private function to set up the model:
+
+    \snippet examples/itemviews/simplewidgetmapper/window.h Window definition
+
+    In addition to the QDataWidgetMapper object and the controls used to make
+    up the user interface, we use a QStandardItemModel to hold our data.
+    We could use a custom model, but this standard implementation is sufficient
+    for our purposes.
+
+    \section1 Window Class Implementation
+
+    The constructor of the \c Window class can be explained in three parts.
+    In the first part, we set up the widgets used for the user interface:
+    
+    \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up widgets
+
+    We also set up the buddy relationships between various labels and the
+    corresponding input widgets.
+
+    Next, we set up the widget mapper, relating each input widget to a column
+    in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}:
+
+    \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the mapper
+
+    We also connect the mapper to the \gui{Next} and \gui{Previous} buttons
+    via its \l{QDataWidgetMapper::}{toNext()} and
+    \l{QDataWidgetMapper::}{toPrevious()} slots. The mapper's
+    \l{QDataWidgetMapper::}{currentIndexChanged()} signal is connected to the
+    \c{updateButtons()} slot in the window which we'll show later.
+
+    In the final part of the constructor, we set up the layout, placing each
+    of the widgets in a grid (we could also use a QFormLayout for this):
+
+    \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the layout
+
+    Lastly, we set the window title and initialize the mapper by setting it to
+    refer to the first row in the model.
+
+    The model is initialized in the window's \c{setupModel()} function. Here,
+    we create a standard model with 5 rows and 3 columns, and we insert some
+    sample names, addresses and ages into each row:
+
+    \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the model
+
+    As a result, each row can be treated like a record in a database, and the
+    widget mapper will read the data from each row, using the column numbers
+    specified earlier to access the correct data for each widget. This is
+    shown in the following diagram:
+
+    \image widgetmapper-simple-mapping.png
+
+    Since the user can navigate using the buttons in the user interface, the
+    example is fully-functional at this point, but to make it a bit more
+    user-friendly, we implement the \c{updateButtons()} slot to show when the
+    user is viewing the first or last records:
+
+    \snippet examples/itemviews/simplewidgetmapper/window.cpp Slot for updating the buttons
+
+    If the mapper is referring to the first row in the model, the \gui{Previous}
+    button is disabled. Similarly, the \gui{Next} button is disabled if the
+    mapper reaches the last row in the model.
+
+    \section1 More Complex Mappings
+
+    The QDataWidgetMapper class makes it easy to relate information from a
+    model to widgets in a user interface. However, it is sometimes necessary
+    to use input widgets which offer choices to the user, such as QComboBox,
+    in conjunction with a widget mapper.
+
+    In these situations, although the mapping to input widgets remains simple,
+    more work needs to be done to expose additional data to the widget mapper.
+    This is covered by the \l{Combo Widget Mapper Example}{Combo Widget Mapper}
+    and \l{SQL Widget Mapper Example}{SQL Widget Mapper}
+    examples.
+*/