--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tools/designer/src/lib/uilib/customwidget.qdoc	Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,309 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 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:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \class QDesignerCustomWidgetInterface
+
+    \brief The QDesignerCustomWidgetInterface class enables Qt Designer
+    to access and construct custom widgets.
+
+    \inmodule QtDesigner
+
+    QDesignerCustomWidgetInterface provides a custom widget with an
+    interface. The class contains a set of functions that must be subclassed
+    to return basic information about the widget, such as its class name and
+    the name of its header file. Other functions must be implemented to
+    initialize the plugin when it is loaded, and to construct instances of
+    the custom widget for \QD to use.
+
+    When implementing a custom widget you must subclass
+    QDesignerCustomWidgetInterface to expose your widget to \QD. For
+    example, this is the declaration for the plugin used in the
+    \l{Custom Widget Plugin Example}{Custom Widget Plugin example} that
+    enables an analog clock custom widget to be used by \QD:
+
+    \snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0
+
+    Note that the only part of the class definition that is specific
+    to this particular custom widget is the class name. In addition,
+    since we are implementing an interface, we must ensure that it's
+    made known to the meta object system using the Q_INTERFACES()
+    macro. This enables \QD to use the qobject_cast() function to
+    query for supported interfaces using nothing but a QObject
+    pointer.
+
+    After \QD loads a custom widget plugin, it calls the interface's
+    initialize() function to enable it to set up any resources that it
+    may need. This function is called with a QDesignerFormEditorInterface
+    parameter that provides the plugin with a gateway to all of \QD's API.
+
+    \QD constructs instances of the custom widget by calling the plugin's
+    createWidget() function with a suitable parent widget. Plugins must
+    construct and return an instance of a custom widget with the specified
+    parent widget. 
+
+    In the implementation of the class you must remember to export
+    your custom widget plugin to \QD using the Q_EXPORT_PLUGIN2()
+    macro. For example, if a library called \c libcustomwidgetplugin.so
+    (on Unix) or \c libcustomwidget.dll (on Windows) contains a widget
+    class called \c MyCustomWidget, we can export it by adding the
+    following line to the file containing the plugin implementation:
+
+    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 14
+
+    This macro ensures that \QD can access and construct the custom widget.
+    Without this macro, there is no way for \QD to use it.
+
+    When implementing a custom widget plugin, you build it as a
+    separate library. If you want to include several custom widget
+    plugins in the same library, you must in addition subclass
+    QDesignerCustomWidgetCollectionInterface.
+
+    \warning If your custom widget plugin contains QVariant
+    properties, be aware that only the following \l
+    {QVariant::Type}{types} are supported:
+
+    \list
+    \o QVariant::ByteArray
+    \o QVariant::Bool
+    \o QVariant::Color
+    \o QVariant::Cursor
+    \o QVariant::Date
+    \o QVariant::DateTime
+    \o QVariant::Double
+    \o QVariant::Int
+    \o QVariant::Point
+    \o QVariant::Rect
+    \o QVariant::Size
+    \o QVariant::SizePolicy
+    \o QVariant::String
+    \o QVariant::Time
+    \o QVariant::UInt
+    \endlist
+
+    For a complete example using the QDesignerCustomWidgetInterface
+    class, see the \l {designer/customwidgetplugin}{Custom Widget
+    Example}. The example shows how to create a custom widget plugin
+    for \QD.
+
+    \sa QDesignerCustomWidgetCollectionInterface {Creating Custom
+    Widgets for Qt Designer}
+*/
+
+/*!
+    \fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface()
+
+    Destroys the custom widget interface.
+*/
+
+/*!
+    \fn QString QDesignerCustomWidgetInterface::name() const
+
+    Returns the class name of the custom widget supplied by the interface.
+
+    The name returned \e must be identical to the class name used for the
+    custom widget.
+*/
+
+/*!
+    \fn QString QDesignerCustomWidgetInterface::group() const
+
+    Returns the name of the group to which the custom widget belongs.
+*/
+
+/*!
+    \fn QString QDesignerCustomWidgetInterface::toolTip() const
+
+    Returns a short description of the widget that can be used by \QD
+    in a tool tip.
+*/
+
+/*!
+    \fn QString QDesignerCustomWidgetInterface::whatsThis() const
+
+    Returns a description of the widget that can be used by \QD in
+    "What's This?" help for the widget.
+*/
+
+/*!
+    \fn QString QDesignerCustomWidgetInterface::includeFile() const
+
+    Returns the path to the include file that \l uic uses when
+    creating code for the custom widget.
+*/
+
+/*!
+    \fn QIcon QDesignerCustomWidgetInterface::icon() const
+
+    Returns the icon used to represent the custom widget in \QD's
+    widget box.
+*/
+
+/*!
+    \fn bool QDesignerCustomWidgetInterface::isContainer() const
+
+    Returns true if the custom widget is intended to be used as a
+    container; otherwise returns false.
+
+    Most custom widgets are not used to hold other widgets, so their
+    implementations of this function will return false, but custom
+    containers will return true to ensure that they behave correctly
+    in \QD.
+*/
+
+/*!
+    \fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent)
+
+    Returns a new instance of the custom widget, with the given \a
+    parent.
+*/
+
+/*!
+    \fn bool QDesignerCustomWidgetInterface::isInitialized() const
+
+    Returns true if the widget has been initialized; otherwise returns
+    false.
+
+    \sa initialize()
+*/
+
+/*!
+    \fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor)
+
+    Initializes the widget for use with the specified \a formEditor
+    interface.
+
+    \sa isInitialized()
+*/
+
+/*!
+    \fn QString QDesignerCustomWidgetInterface::domXml() const
+
+    Returns the XML that is used to describe the custom widget's
+    properties to \QD.
+*/
+
+/*!
+    \fn QString QDesignerCustomWidgetInterface::codeTemplate() const
+
+    This function is reserved for future use by \QD.
+
+    \omit
+    Returns the code template that \QD includes in forms that contain
+    the custom widget when they are saved.
+    \endomit
+*/
+
+/*!
+    \macro QDESIGNER_WIDGET_EXPORT
+    \relates QDesignerCustomWidgetInterface
+    \since 4.1
+
+    This macro is used when defining custom widgets to ensure that they are
+    correctly exported from plugins for use with \QD.
+
+    On some platforms, the symbols required by \QD to create new widgets
+    are removed from plugins by the build system, making them unusable.
+    Using this macro ensures that the symbols are retained on those platforms,
+    and has no side effects on other platforms.
+
+    For example, the \l{designer/worldtimeclockplugin}{World Time Clock Plugin}
+    example exports a custom widget class with the following declaration:
+
+    \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 0
+    \dots
+    \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 2
+
+    \sa {Creating Custom Widgets for Qt Designer}
+*/
+
+
+
+
+
+/*!
+    \class QDesignerCustomWidgetCollectionInterface
+
+    \brief The QDesignerCustomWidgetCollectionInterface class allows
+    you to include several custom widgets in one single library.
+
+    \inmodule QtDesigner
+
+    When implementing a custom widget plugin, you build it as a
+    separate library. If you want to include several custom widget
+    plugins in the same library, you must in addition subclass
+    QDesignerCustomWidgetCollectionInterface.
+
+    QDesignerCustomWidgetCollectionInterface contains one single
+    function returning a list of the collection's
+    QDesignerCustomWidgetInterface objects. For example, if you have
+    several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and
+    \c CustomWidgetThree, the class definition may look like this:
+
+    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 12
+
+    In the class constructor you add the interfaces to your custom
+    widgets to the list which you return in the customWidgets()
+    function:
+
+    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 13
+
+    Note that instead of exporting each custom widget plugin using the
+    Q_EXPORT_PLUGIN2() macro, you export the entire collection. The
+    Q_EXPORT_PLUGIN2() macro ensures that \QD can access and construct
+    the custom widgets. Without this macro, there is no way for \QD to
+    use them.
+
+    \sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for
+    Qt Designer}
+*/
+
+/*!
+    \fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() {
+
+    Destroys the custom widget collection interface.
+*/
+
+/*!
+    \fn QList<QDesignerCustomWidgetInterface*> QDesignerCustomWidgetCollectionInterface::customWidgets() const
+
+    Returns a list of interfaces to the collection's custom widgets.
+*/