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