source: trunk/doc/src/examples/simplewidgetmapper.qdoc

/****************************************************************************
**
** 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$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** 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.
*/