| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** 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. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example itemviews/simplewidgetmapper |
| \title Simple Widget Mapper Example |
| \ingroup examples-itemviews |
| \brief 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 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 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 itemviews/simplewidgetmapper/window.cpp Set up the mapper |
| |
| We also connect the mapper to the \uicontrol{Next} and \uicontrol{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 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 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 itemviews/simplewidgetmapper/window.cpp Slot for updating the buttons |
| |
| If the mapper is referring to the first row in the model, the \uicontrol{Previous} |
| button is disabled. Similarly, the \uicontrol{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. |
| */ |