1 files changed, 139 insertions, 0 deletions
diff --git a/doc/src/examples/simplewidgetmapper.qdoc b/doc/src/examples/simplewidgetmapper.qdoc
new file mode 100644
index 0000000..2fdbf25
--- /dev/null
+++ b/doc/src/examples/simplewidgetmapper.qdoc
@@ -0,0 +1,139 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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.
+*/