/****************************************************************************

**

** Copyright (C) 2009 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: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 Technology Preview License Agreement accompanying

** this package.

**

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** 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.

*/