| /**************************************************************************** |
| ** |
| ** 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/spinboxdelegate |
| \title Spin Box Delegate Example |
| \ingroup examples-itemviews |
| \brief The Spin Box Delegate example shows how to create an editor for a custom delegate in |
| the model/view framework by reusing a standard Qt editor widget. |
| |
| The model/view framework provides a standard delegate that is used by default |
| with the standard view classes. For most purposes, the selection of editor |
| widgets available through this delegate is sufficient for editing text, boolean |
| values, and other simple data types. However, for specific data types, it is |
| sometimes necessary to use a custom delegate to either display the data in a |
| specific way, or allow the user to edit it with a custom control. |
| |
| \image spinboxdelegate-example.png |
| |
| This concepts behind this example are covered in the |
| \l{Model/View Programming#Delegate Classes}{Delegate Classes} chapter |
| of the \l{Model/View Programming} overview. |
| |
| \section1 SpinBoxDelegate Class Definition |
| |
| The definition of the delegate is as follows: |
| |
| \snippet itemviews/spinboxdelegate/delegate.h 0 |
| |
| The delegate class declares only those functions that are needed to |
| create an editor widget, display it at the correct location in a view, |
| and communicate with a model. Custom delegates can also provide their |
| own painting code by reimplementing the \c paintEvent() function. |
| Furthermore it is also possible to reuse (and avoid deleting) the editor |
| widget by reimplementing the \a destroyEditor() function. A reused widget |
| could be a mutable member created in the constructor and deleted in |
| the destructor. |
| |
| \section1 SpinBoxDelegate Class Implementation |
| |
| Delegates are often stateless. The constructor only needs to |
| call the base class's constructor with the parent QObject as its |
| argument: |
| |
| \snippet itemviews/spinboxdelegate/delegate.cpp 0 |
| |
| Since the delegate is a subclass of QStyledItemDelegate, the data it retrieves |
| from the model is displayed in a default style, and we do not need to |
| provide a custom \c paintEvent(). |
| |
| The \c createEditor() function returns an editor widget, in this case a |
| spin box that restricts values from the model to integers from 0 to 100 |
| inclusive. |
| |
| \snippet itemviews/spinboxdelegate/delegate.cpp 1 |
| |
| We install an event filter on the spin box to ensure that it behaves in |
| a way that is consistent with other delegates. The implementation for |
| the event filter is provided by the base class. |
| |
| The \c setEditorData() function reads data from the model, converts it |
| to an integer value, and writes it to the editor widget. |
| |
| \snippet itemviews/spinboxdelegate/delegate.cpp 2 |
| |
| Since the view treats delegates as ordinary QWidget instances, we have |
| to use a static cast before we can set the value in the spin box. |
| |
| The \c setModelData() function reads the contents of the spin box, and |
| writes it to the model. |
| |
| \snippet itemviews/spinboxdelegate/delegate.cpp 3 |
| |
| We call \l{QSpinBox::interpretText()}{interpretText()} to make sure that |
| we obtain the most up-to-date value in the spin box. |
| |
| The \c updateEditorGeometry() function updates the editor widget's |
| geometry using the information supplied in the style option. This is the |
| minimum that the delegate must do in this case. |
| |
| \snippet itemviews/spinboxdelegate/delegate.cpp 4 |
| |
| More complex editor widgets may divide the rectangle available in |
| \c{option.rect} between different child widgets if required. |
| |
| \section1 The Main Function |
| |
| This example is written in a slightly different way to many of the |
| other examples supplied with Qt. To demonstrate the use of a custom |
| editor widget in a standard view, it is necessary to set up a model |
| containing some arbitrary data and a view to display it. |
| |
| We set up the application in the normal way, construct a standard item |
| model to hold some data, set up a table view to use the data in the |
| model, and construct a custom delegate to use for editing: |
| |
| \snippet itemviews/spinboxdelegate/main.cpp 0 |
| |
| The table view is informed about the delegate, and will use it to |
| display each of the items. Since the delegate is a subclass of |
| QStyledItemDelegate, each cell in the table will be rendered using standard |
| painting operations. |
| |
| We insert some arbitrary data into the model for demonstration purposes: |
| |
| \snippet itemviews/spinboxdelegate/main.cpp 1 |
| \snippet itemviews/spinboxdelegate/main.cpp 2 |
| |
| Finally, the table view is displayed with a window title, and we start |
| the application's event loop: |
| |
| \snippet itemviews/spinboxdelegate/main.cpp 3 |
| |
| Each of the cells in the table can now be edited in the usual way, but |
| the spin box ensures that the data returned to the model is always |
| constrained by the values allowed by the spin box delegate. |
| */ |