| /**************************************************************************** |
| ** |
| ** 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/coloreditorfactory |
| \title Color Editor Factory Example |
| \ingroup examples-itemviews |
| \brief This example shows how to create an editor that can be used by |
| a QItemDelegate. |
| |
| \image coloreditorfactoryimage.png |
| |
| When editing data in a QListView, QTableView, or QTreeView, |
| editors are created and displayed by a \l{Delegate |
| Classes}{delegate}. QItemDelegate, which is the default delegate |
| used by Qt's \l{View Classes}{item views}, uses a |
| QItemEditorFactory to create editors for it. A unique instance |
| provided by QItemEditorFactory is by default installed on all |
| item delegates. |
| |
| An item editor factory contains a collection of |
| QItemEditorCreatorBase instances, which are specialized factories |
| that produce editors for one particular QVariant data type (all |
| models in Qt store their data in \l{QVariant}s). An editor can be any |
| Qt or custom widget. |
| |
| In this example, we will create an editor (implemented in the \c |
| ColorListEditor class) that can edit the QColor data type and be |
| used by \l{QItemDelegate}s. We do this by creating a new |
| QItemEditorCreatorBase that produces \c ColorListEditors and |
| register it with a new factory, which we set as the default editor |
| item factory (the unique factory instance). To test our editor, we |
| have implemented the \c Window class, which displays a |
| QTableWidget in which \l{QColor}s can be edited. |
| |
| \section1 Window Class Implementation |
| |
| In the Window class, we create the item editor creator |
| base for our color editor and add it to the default factory. |
| We also create a QTableWidget in which our editor can be |
| tested. It is filled with some data and displayed in a window. |
| |
| We take a closer look at the constructor: |
| |
| \snippet itemviews/coloreditorfactory/window.cpp 0 |
| |
| The QStandardItemEditorCreator is a convenience class that |
| inherits QItemEditorCreatorBase. Its constructor takes a template |
| class, of which instances are returned from |
| \l{QItemEditorCreatorBase::}{createWidget()}. The creator uses a |
| constructor that takes a QWidget as its only parameter; the |
| template class must provide this. This way, there is no need to |
| subclass QStandardItemEditorCreator. |
| |
| After the new factory has been set, all standard item delegates |
| will use it (i.e, also delegates that were created before the new |
| default factory was set). |
| |
| The \c createGUI() function sets up the table and fills it |
| with data. |
| |
| \section1 ColorListEditor Definition |
| |
| The ColorListEditor inherits QComboBox and lets the user |
| select a QColor from its popup list. |
| |
| \snippet itemviews/coloreditorfactory/colorlisteditor.h 0 |
| |
| QItemDelegate manages the interaction between the editor and |
| the model, i.e., it retrieves data to edit from the model and |
| store data from the editor in the model. The data that is edited |
| by an editor is stored in the editor's user data property, and the |
| delegate uses Qt's \l{Qt's Property System}{property system} to |
| access it by name. We declare our user data property with the |
| Q_PROPERTY macro. The property is set to be the user type with the |
| USER keyword. |
| |
| \section1 ColorListEditor Implementation |
| |
| The constructor of \c ColorListEditor simply calls \c |
| populateList(), which we will look at later. We move on to the |
| \c color() function: |
| |
| \snippet itemviews/coloreditorfactory/colorlisteditor.cpp 0 |
| |
| We return the data that is selected in the combobox. The data |
| is stored in the Qt::DecorationRole as the color is then also |
| displayed in the popup list (as shown in the image above). |
| |
| \snippet itemviews/coloreditorfactory/colorlisteditor.cpp 1 |
| |
| The \c findData() function searches the items in the combobox |
| and returns the index of the item that has \c color in the |
| Qt::Decoration role. |
| |
| \snippet itemviews/coloreditorfactory/colorlisteditor.cpp 2 |
| |
| Qt knows some predefined colors by name. We simply loop |
| through these to fill our editor with items. |
| |
| \section1 Further Customization of Item View Editors |
| |
| You can customize Qt's \l{Model/View Programming}{model view |
| framework} in many ways. The procedure shown in this example is |
| usually sufficient to provide custom editors. Further |
| customization is achieved by subclassing QItemEditorFactory |
| and QItemEditorCreatorBase. It is also possible to subclass |
| QItemDelegate if you don't wish to use a factory at all. |
| |
| Possible suggestions are: |
| |
| \list |
| \li If the editor widget has no user property defined, the delegate |
| asks the factory for the property name, which it in turn |
| asks the item editor creator for. In this case, you can use |
| the QItemEditorCreator class, which takes the property |
| name to use for editing as a constructor argument. |
| \li If the editor requires other constructors or other |
| initialization than provided by QItemEditorCreatorBase, you |
| must reimplement |
| QItemEditorCreatorBase::createWidget(). |
| \li You could also subclass QItemEditorFactory if you only want |
| to provide editors for certain kinds of data or use another |
| method of creating the editors than using creator bases. |
| \endlist |
| |
| In this example, we use a standard QVariant data type. You can |
| also use custom types. In the \l{Star Delegate Example}, we |
| show how to store a custom data type in a QVariant and paint |
| and edit it in a class that inherits QItemDelegate. |
| */ |
