diff options
Diffstat (limited to 'src/uiplugin/customwidget.qdoc')
-rw-r--r-- | src/uiplugin/customwidget.qdoc | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/src/uiplugin/customwidget.qdoc b/src/uiplugin/customwidget.qdoc new file mode 100644 index 000000000..7776cac8b --- /dev/null +++ b/src/uiplugin/customwidget.qdoc @@ -0,0 +1,269 @@ +// 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. +*/ + +/*! + \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. +*/ |