customwidget.qdoc

Go to the documentation of this file.

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \class QDesignerCustomWidgetInterface
 
    \brief The QDesignerCustomWidgetInterface class enables \QD
    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 that
    enables an analog clock custom widget to be used by \QD:
 
    \snippet 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.
 
    Exporting your custom widget plugin to \QD using the Q_PLUGIN_METADATA()
    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 header:
 
    \snippet plugins/doc_src_qtdesigner.cpp 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
    \li QVariant::ByteArray
    \li QVariant::Bool
    \li QVariant::Color
    \li QVariant::Cursor
    \li QVariant::Date
    \li QVariant::DateTime
    \li QVariant::Double
    \li QVariant::Int
    \li QVariant::Point
    \li QVariant::Rect
    \li QVariant::Size
    \li QVariant::SizePolicy
    \li QVariant::String
    \li QVariant::Time
    \li QVariant::UInt
    \endlist
 
    For a complete example using the QDesignerCustomWidgetInterface
    class, see the \l {customwidgetplugin}{Custom Widget
    Example}. The example shows how to create a custom widget plugin
    for \QD.
 
    \sa QDesignerCustomWidgetCollectionInterface, {Creating Custom Widgets for Qt Widgets 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.
 
    For custom widgets used in C++ and \e{Qt for Python}, use prefixes
    to specify language-specific information in the returned string
    as shown below:
 
    \badcode
    "C++:myheader.h,Python:MyModule"
    \endcode
*/
 
/*!
    \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{customwidgetplugin}{Custom Widget Plugin}
    example exports a custom widget class with the following declaration:
 
    \snippet customwidgetplugin/analogclock.h 0
    \dots
    \snippet customwidgetplugin/analogclock.h 1
 
    \sa {Creating Custom Widgets for Qt Widgets 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 plugins/doc_src_qtdesigner.cpp 12
 
    In the class constructor you add the interfaces to your custom
    widgets to the list which you return in the customWidgets()
    function:
 
    \snippet plugins/doc_src_qtdesigner.cpp 13
 
    Note that instead of exporting each custom widget plugin using the
    Q_PLUGIN_METADATA() macro, you export the entire collection. The
    Q_PLUGIN_METADATA() 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 Widgets 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.
*/