fc924ae47e
Widget examples were moved into a widgets subfolder, but qdoc references were not updated. Change-Id: Id2a4573e723745b9827c664c852807d6116f8f6d Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
126 lines
5.2 KiB
Plaintext
126 lines
5.2 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
|
|
** Contact: http://www.qt-project.org/
|
|
**
|
|
** This file is part of the documentation of the Qt Toolkit.
|
|
**
|
|
** $QT_BEGIN_LICENSE:FDL$
|
|
** 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.
|
|
**
|
|
** Other Usage
|
|
** Alternatively, this file may be used in accordance with the terms
|
|
** and conditions contained in a signed written agreement between you
|
|
** and Nokia.
|
|
**
|
|
**
|
|
**
|
|
**
|
|
**
|
|
** $QT_END_LICENSE$
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
\example widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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.
|
|
*/
|