1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example itemviews/combowidgetmapper

    44     \title Combo Widget Mapper Example

    45 

    46     The Delegate Widget Mapper example shows how to use a custom delegate to

    47     map information from a model to specific widgets on a form.

    48 

    49     \image combo-widget-mapper.png

    50 

    51     In the \l{Simple Widget Mapper Example}, we showed the basic use of a

    52     widget mapper to relate data exposed by a model to simple input widgets

    53     in a user interface. However, sometimes we want to use input widgets that

    54     expose data as choices to the user, such as QComboBox, and we need a way

    55     to relate their input to the values stored in the model.

    56 

    57     This example is very similar to the \l{Simple Widget Mapper Example}.

    58     Again, we create a \c Window class with an almost identical user interface,

    59     except that, instead of providing a spin box so that each person's age

    60     can be entered, we provide a combo box to allow their addresses to be

    61     classified as "Home", "Work" or "Other".

    62 

    63     \section1 Window Class Definition

    64 

    65     The class provides a constructor, a slot to keep the buttons up to date,

    66     and a private function to set up the model:

    67 

    68     \snippet examples/itemviews/combowidgetmapper/window.h Window definition

    69 

    70     In addition to the QDataWidgetMapper object and the controls used to make

    71     up the user interface, we use a QStandardItemModel to hold our data and

    72     a QStringListModel to hold information about the types of address that

    73     can be applied to each person's data.

    74 

    75     \section1 Window Class Implementation

    76 

    77     The constructor of the \c Window class can be explained in three parts.

    78     In the first part, we set up the widgets used for the user interface:

    79 

    80     \snippet examples/itemviews/combowidgetmapper/window.cpp Set up widgets

    81 

    82     Note that we set up the mapping the combo box in the same way as for other

    83     widgets, but that we apply its own model to it so that it will display

    84     data from its own model, the \c typeModel, rather than from the model

    85     containing data about each person.

    86 

    87     Next, we set up the widget mapper, relating each input widget to a column

    88     in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}:

    89 

    90     \snippet examples/itemviews/combowidgetmapper/window.cpp Set up the mapper

    91 

    92     For the combo box, we pass an extra argument to tell the widget mapper

    93     which property to relate to values from the model. As a result, the user

    94     is able to select an item from the combo box, and the corresponding

    95     value stored in the widget's \c currentIndex property will be stored in

    96     the model.

    97 

    98     \omit

    99     However, we also set a delegate on the mapper. As with \l{Delegate Classes},

   100     this changes the way that data is presented to the user. In this case, the

   101     delegate acts as a proxy between the mapper and the input widgets,

   102     translating the data into a suitable form for the combo box but not

   103     interfering with the other input widgets. The implementation is shown later.

   104     \endomit

   105 

   106     The rest of the constructor is very similar to that of the

   107     \l{Simple Widget Mapper Example}:

   108 

   109     \snippet examples/itemviews/combowidgetmapper/window.cpp Set up connections and layouts

   110 

   111     The model is initialized in the window's \c{setupModel()} function. Here,

   112     we create a standard model with 5 rows and 3 columns. In each row, we

   113     insert a name, address, and a value that indicates the type of address.

   114     The address types are stored in a string list model.

   115 

   116     \snippet examples/itemviews/combowidgetmapper/window.cpp Set up the model

   117 

   118     As we insert each row into the model, like a record in a database, we

   119     store values that correspond to items in \c typeModel for each person's

   120     address type. When the widget mapper reads these values from the final

   121     column of each row, it will need to use them as references to values in

   122     \c typeModel, as shown in the following diagram. This is where the

   123     delegate is used.

   124 

   125     \image widgetmapper-combo-mapping.png

   126 

   127     We show the implementation of the \c{updateButtons()} slot for

   128     completeness:

   129 

   130     \snippet examples/itemviews/combowidgetmapper/window.cpp Slot for updating the buttons

   131 

   132     \omit

   133     \section1 Delegate Class Definition and Implementation

   134 

   135     The delegate we use to mediate interaction between the widget mapper and

   136     the input widgets is a small QItemDelegate subclass:

   137 

   138     \snippet examples/itemviews/combowidgetmapper/delegate.h Delegate class definition

   139 

   140     This provides implementations of the two standard functions used to pass

   141     data between editor widgets and the model (see the \l{Delegate Classes}

   142     documentation for a more general description of these functions).

   143 

   144     Since we only provide an empty implementation of the constructor, we

   145     concentrate on the other two functions.

   146 

   147     The \l{QItemDelegate::}{setEditorData()} implementation takes the data

   148     referred to by the model index supplied and processes it according to

   149     the presence of a \c currentIndex property in the editor widget:

   150 

   151     \snippet examples/itemviews/combowidgetmapper/delegate.cpp setEditorData implementation

   152 

   153     If, like QComboBox, the editor widget has this property, it is set using

   154     the value from the model. Since we are passing around QVariant values,

   155     the strings stored in the model are automatically converted to the integer

   156     values needed for the \c currentIndex property.

   157 

   158     As a result, instead of showing "0", "1" or "2" in the combo box, one of

   159     its predefined set of items is shown. We call QItemDelegate::setEditorData()

   160     for widgets without the \c currentIndex property.

   161 

   162     The \l{QItemDelegate::}{setModelData()} implementation performs the reverse

   163     process, taking the value stored in the widget's \c currentIndex property

   164     and storing it back in the model:

   165 

   166     \snippet examples/itemviews/combowidgetmapper/delegate.cpp setModelData implementation

   167     \endomit

   168 

   169     \section1 Summary and Further Reading

   170 

   171     The use of a separate model for the combo box provides a menu of choices

   172     that are separate from the data stored in the main model. Using a named

   173     mapping that relates the combo box's \c currentIndex property to a column

   174     in the model effectively allows us to store a look-up value in the model.

   175 

   176     However, when reading the model outside the context of the widget mapper,

   177     we need to know about the \c typeModel to make sense of these look-up

   178     values. It would be useful to be able to store both the data and the

   179     choices held by the \c typeModel in one place.

   180     This is covered by the \l{SQL Widget Mapper Example}.

   181 */