/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $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.
*/