/**************************************************************************** ** ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). ** 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 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 http://www.qtsoftware.com/contact. ** $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. */