Contents

• Public Functions
• Macros
• Detailed Description

Detailed Description

TheQDesignerCustomWidgetInterface class enables Qt Designer to access and construct custom widgets.

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 forQt Designer to use.

When implementing a custom widget you must subclassQDesignerCustomWidgetInterface to expose your widget toQt Designer. For example, this is the declaration for the plugin used in theCustom Widget Plugin example that enables an analog clock custom widget to be used byQt Designer:

class AnalogClockPlugin :publicQObject,publicQDesignerCustomWidgetInterface{    Q_OBJECT    Q_INTERFACES(QDesignerCustomWidgetInterface)public:    AnalogClockPlugin(QObject*parent=0);    bool isContainer()const;    bool isInitialized()const;QIcon icon()const;QString domXml()const;QString group()const;QString includeFile()const;QString name()const;QString toolTip()const;QString whatsThis()const;QWidget*createWidget(QWidget*parent);void initialize(QDesignerFormEditorInterface*core);private:    bool initialized;};

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 theQ_INTERFACES() macro. This enablesQt Designer to use theqobject_cast() function to query for supported interfaces using nothing but aQObject pointer.

AfterQt Designer loads a custom widget plugin, it calls the interface'sinitialize() function to enable it to set up any resources that it may need. This function is called with aQDesignerFormEditorInterface parameter that provides the plugin with a gateway to all ofQt Designer's API.

Qt Designer constructs instances of the custom widget by calling the plugin'screateWidget() 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 toQt Designer using theQ_EXPORT_PLUGIN2() macro. For example, if a library calledlibcustomwidgetplugin.so (on Unix) orlibcustomwidget.dll (on Windows) contains a widget class calledMyCustomWidget, we can export it by adding the following line to the file containing the plugin implementation:

Q_EXPORT_PLUGIN2(customwidgetplugin, MyCustomWidget)

This macro ensures thatQt Designer can access and construct the custom widget. Without this macro, there is no way forQt Designer 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 subclassQDesignerCustomWidgetCollectionInterface.

Warning: If your custom widget plugin containsQVariant properties, be aware that only the followingtypes are supported:

• QVariant::ByteArray
• QVariant::Bool
• QVariant::Color
• QVariant::Cursor
• QVariant::Date
• QVariant::DateTime
• QVariant::Double
• QVariant::Int
• QVariant::Point
• QVariant::Rect
• QVariant::Size
• QVariant::SizePolicy
• QVariant::String
• QVariant::Time
• QVariant::UInt

For a complete example using theQDesignerCustomWidgetInterface class, see theCustom Widget Example. The example shows how to create a custom widget plugin forQt Designer.

Member Function Documentation

[virtual]QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface()

Destroys the custom widget interface.

[virtual]QString QDesignerCustomWidgetInterface::codeTemplate() const

This function is reserved for future use byQt Designer.

[pure virtual]QWidget * QDesignerCustomWidgetInterface::createWidget(QWidget * parent)

Returns a new instance of the custom widget, with the givenparent.

[virtual]QString QDesignerCustomWidgetInterface::domXml() const

Returns the XML that is used to describe the custom widget's properties toQt Designer.

[pure virtual]QString QDesignerCustomWidgetInterface::group() const

Returns the name of the group to which the custom widget belongs.

[pure virtual]QIcon QDesignerCustomWidgetInterface::icon() const

Returns the icon used to represent the custom widget inQt Designer's widget box.

[pure virtual]QString QDesignerCustomWidgetInterface::includeFile() const

Returns the path to the include file thatuic uses when creating code for the custom widget.

[virtual]void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface * formEditor)

Initializes the widget for use with the specifiedformEditor interface.

See alsoisInitialized().

[pure virtual]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 inQt Designer.

[virtual]bool QDesignerCustomWidgetInterface::isInitialized() const

Returns true if the widget has been initialized; otherwise returns false.

See alsoinitialize().

[pure virtual]QString QDesignerCustomWidgetInterface::name() const

Returns the class name of the custom widget supplied by the interface.

The name returnedmust be identical to the class name used for the custom widget.

[pure virtual]QString QDesignerCustomWidgetInterface::toolTip() const

Returns a short description of the widget that can be used byQt Designer in a tool tip.

[pure virtual]QString QDesignerCustomWidgetInterface::whatsThis() const

Returns a description of the widget that can be used byQt Designer in "What's This?" help for the widget.

Macro Documentation

QDESIGNER_WIDGET_EXPORT

This macro is used when defining custom widgets to ensure that they are correctly exported from plugins for use withQt Designer.

On some platforms, the symbols required byQt Designer 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, theWorld Time Clock Plugin example exports a custom widget class with the following declaration:

class QDESIGNER_WIDGET_EXPORT WorldTimeClock :publicQWidget{    Q_OBJECT    ...};

This function was introduced in Qt 4.1.

See alsoCreating Custom Widgets for Qt Designer.