Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

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.
+*/