class QDesignerCustomWidgetInterface

The QDesignerCustomWidgetInterface class enables Qt Widgets Designer to access and construct custom widgets. More…

Synopsis

Virtual methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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

When implementing a custom widget you must subclass QDesignerCustomWidgetInterface to expose your widget to Qt Widgets Designer. For example, this is the declaration for the plugin used in the Custom Widget Plugin example that enables an analog clock custom widget to be used by Qt Widgets Designer:

class AnalogClockPlugin(QObject, QDesignerCustomWidgetInterface):

    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")
    Q_INTERFACES(QDesignerCustomWidgetInterface)
# public
    AnalogClockPlugin = explicit(QObject parent = None)
    bool isContainer() override
    bool isInitialized() override
    QIcon icon() override
    QString domXml() override
    QString group() override
    QString includeFile() override
    QString name() override
    QString toolTip() override
    QString whatsThis() override
    QWidget createWidget(QWidget parent) override
    def initialize(core):
# private
    initialized = False

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 Qt Widgets Designer to use the qobject_cast() function to query for supported interfaces using nothing but a QObject pointer.

After Qt Widgets Designer 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 Qt Widgets Designer’s API.

Qt Widgets Designer 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 Qt Widgets Designer using the Q_PLUGIN_METADATA() macro. For example, if a library called libcustomwidgetplugin.so (on Unix) or libcustomwidget.dll (on Windows) contains a widget class called MyCustomWidget, we can export it by adding the following line to the file containing the plugin header:

Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")

This macro ensures that Qt Widgets Designer can access and construct the custom widget. Without this macro, there is no way for Qt Widgets 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 subclass QDesignerCustomWidgetCollectionInterface .

Warning

If your custom widget plugin contains QVariant properties, be aware that only the following types 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 the QDesignerCustomWidgetInterface class, see the Custom Widget Example . The example shows how to create a custom widget plugin for Qt Widgets Designer.

See also

QDesignerCustomWidgetCollectionInterface Creating Custom Widgets for Qt Widgets Designer

codeTemplate()
Return type:

str

This function is reserved for future use by Qt Widgets Designer.

abstract createWidget(parent)
Parameters:

parent – QWidget

Return type:

QWidget

Returns a new instance of the custom widget, with the given parent.

domXml()
Return type:

str

Returns the XML that is used to describe the custom widget’s properties to Qt Widgets Designer.

abstract group()
Return type:

str

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

abstract icon()
Return type:

QIcon

Returns the icon used to represent the custom widget in Qt Widgets Designer’s widget box.

abstract includeFile()
Return type:

str

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

initialize(core)
Parameters:

core – QDesignerFormEditorInterface

Initializes the widget for use with the specified formEditor interface.

See also

isInitialized()

abstract isContainer()
Return type:

bool

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 Qt Widgets Designer.

isInitialized()
Return type:

bool

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

See also

initialize()

abstract name()
Return type:

str

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

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

abstract toolTip()
Return type:

str

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

abstract whatsThis()
Return type:

str

Returns a description of the widget that can be used by Qt Widgets Designer in “What’s This?” help for the widget.