Creating Custom Widgets for Qt Designer

Notes on the domXml() Function

The domXml() function returns a UI file snippet that is used by Qt Designer's widget factory to create a custom widget and its applicable properties.

Since Qt 4.4, Qt Designer's widget box allows for a complete UI file to describe one custom widget. The UI file can be loaded using the <ui> tag. Specifying the <ui> tag allows for adding the <customwidget> element that contains additional information for custom widgets. The <widget> tag is sufficient if no additional information is required

If the custom widget does not provide a reasonable size hint, it is necessary to specify a default geometry in the string returned by the domXml() function in your subclass. For example, the AnalogClockPlugin provided by the Custom Widget Plugin example, defines a default widgetgeometry in the following way:

     ...
            "  <property name=\"geometry\">\n"
            "   <rect>\n"
            "    <x>0</x>\n"
            "    <y>0</y>\n"
            "    <width>100</width>\n"
            "    <height>100</height>\n"
            "   </rect>\n"
            "  </property>\n"
     ...

An additional feature of the domXml() function is that, if it returns an empty string, the widget will not be installed in Qt Designer's widget box. However, it can still be used by other widgets in the form. This feature is used to hide widgets that should not be explicitly created by the user, but are required by other widgets.

A complete custom widget specification looks like:

 <ui language="c++"> displayname="MyWidget">
     <widget class="widgets::MyWidget" name="mywidget"/>
     <customwidgets>
         <customwidget>
             <class>widgets::MyWidget</class>
             <addpagemethod>addPage</addpagemethod>
             <propertyspecifications>
                 <stringpropertyspecification name="fileName" notr="true" type="singleline"
                 <stringpropertyspecification name="text" type="richtext"
             </propertyspecifications>
         </customwidget>
     </customwidgets>
 </ui>

Attributes of the <ui> tag:

The <addpagemethod> tag tells Qt Designer and uic which method should be used to add pages to a container widget. This applies to container widgets that require calling a particular method to add a child rather than adding the child by passing the parent. In particular, this is relevant for containers that are not a a subclass of the containers provided in Qt Designer, but are based on the notion of Current Page. In addition, you need to provide a container extension for them.

The <propertyspecifications> element can contain a list of property meta information. Currently, properties of type string are supported. For these properties, the <stringpropertyspecification> tag can be used. This tag has the following attributes:

Values of the type attribute of the string property:

 CONFIG      += designer plugin
 TARGET      = $$qtLibraryTarget($$TARGET)
 TEMPLATE    = lib

 CONFIG += release

 target.path = $$[QT_INSTALL_PLUGINS]/designer
 INSTALLS += target