diff options
Diffstat (limited to 'doc/src/examples/coloreditorfactory.qdoc')
| -rw-r--r-- | doc/src/examples/coloreditorfactory.qdoc | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/doc/src/examples/coloreditorfactory.qdoc b/doc/src/examples/coloreditorfactory.qdoc new file mode 100644 index 0000000000..804b0225cd --- /dev/null +++ b/doc/src/examples/coloreditorfactory.qdoc @@ -0,0 +1,155 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/coloreditorfactory + \title Color Editor Factory Example + + 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 examples/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 examples/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 examples/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 examples/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 examples/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 + \o 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. + \o If the editor requires other constructors or other + initialization than provided by QItemEditorCreatorBase, you + must reimplement + QItemEditorCreatorBase::createWidget(). + \o 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. +*/ |