Integrating Custom Widgets with Qt Designer

Before we can use custom widgets in Qt Designer, we must make Qt Designer aware of them. There are two techniques for doing this: the "simple custom widget" approach and the plugin approach.

The "simple custom widget" approach consists of filling in a dialog box in Qt Designer with some information about the custom widget. The widget can then be used in forms developed using Qt Designer, but the widget is only represented by an icon and a dark gray rectangle while the form is edited or previewed. Here's how to integrate the HexSpinBox widget using this approach:

1. Click Tools|Custom|Edit Custom Widget. This will launch Qt Designer's custom widget editor.
2. Click New Widget.
3. Change the class name from MyCustomWidget to HexSpinBox and the header file from mycustomwidget.h to hexspinbox.h.
4. Change the size hint to (60, 20).
5. Change the size policy to (Minimum, Fixed).

The widget will then be available in the "Custom Widgets" section of Qt Designer's toolbox.

Figure 5.6. Qt Designer's custom widget editor

The plugin approach requires the creation of a plugin library that Qt Designer can load at run-time and use to create instances of the widget. The real widget is then used by Qt Designer when editing the form and for previewing. We will integrate the IconEditor as a plugin to demonstrate how to do it.

First, we must subclass QWidgetPlugin and reimplement some virtual functions. We can do everything in the same source file. We will assume that the plugin source code is located in a directory called iconeditorplugin and that the IconEditor source code is located in a parallel directory called iconeditor.

Here's the header file:

#include 

#include "../iconeditor/iconeditor.h"

class IconEditorPlugin : public QWidgetPlugin
{
public:
 QStringList keys() const;
 QWidget *create(const QString &key, QWidget *parent,
 const char *name);
 QString includeFile(const QString &key) const;
 QString group(const QString &key) const;
 QIconSet iconSet(const QString &key) const;
 QString toolTip(const QString &key) const;
 QString whatsThis(const QString &key) const;
 bool isContainer(const QString &key) const;
};

The IconEditorPlugin subclass is a factory class that encapsulates the IconEditor widget. The functions are used by Qt Designer to create instances of the class and to obtain information about it.

QStringList IconEditorPlugin::keys() const
{
 return QStringList() << "IconEditor";
}

The keys() function returns a list of widgets provided by the plugin. The example plugin only provides the IconEditor widget.

QWidget *IconEditorPlugin::create(const QString &, QWidget *parent,
 const char *name)
{
 return new IconEditor(parent, name);
}

The create() function is called by Qt Designer to create an instance of a widget class. The first argument is the widget's class name. We can ignore it in this example, because we only provide one class. All the other functions also take a class name as their first argument.

QString IconEditorPlugin::includeFile(const QString &) const
{
 return "iconeditor.h";
}

The includeFile() function returns the name of the header file for the specified widget encapsulated by the plugin. The header file is included in the code generated by the uic tool.

bool IconEditorPlugin::isContainer(const QString &) const
{
 return false;
}

The isContainer() function returns true if the widget can contain other widgets; otherwise, it returns false. For example, QFrame is a widget that can contain other widgets. We return false for the IconEditor, since it doesn't make sense for it to contain other widgets. Strictly speaking, any widget can contain other widgets, but Qt Designer disallows this when isContainer() returns false.

QString IconEditorPlugin::group(const QString &) const
{
 return "Plugin Widgets";
}

The group() function returns the name of the toolbox group this custom widget should belong to. If the name isn't already in use, Qt Designer automatically creates a new group for the widget.

QIconSet IconEditorPlugin::iconSet(const QString &) const
{
 return QIconSet(QPixmap::fromMimeSource("iconeditor.png"));
}

The iconSet() function returns the icon to use to represent the custom widget in Qt Designer's toolbox.

QString IconEditorPlugin::toolTip(const QString &) const
{
 return "Icon Editor";
}

The toolTip() function returns the tooltip to show when the mouse hovers over the custom widget in Qt Designer's toolbox.

QString IconEditorPlugin::whatsThis(const QString &) const
{
 return "Widget for creating and editing icons";
}

The whatsThis() function returns the "What's This?" text for Qt Designer to display.

Q_EXPORT_PLUGIN(IconEditorPlugin)

At the end of the source file that implements the plugin class, we must use the Q_EXPORT_PLUGIN() macro to make the plugin available to Qt Designer.

The .pro file for building the plugin looks like this:

TEMPLATE = lib
CONFIG += plugin
HEADERS = ../iconeditor/iconeditor.h
SOURCES = iconeditorplugin.cpp 
 ../iconeditor/iconeditor.cpp
IMAGES = images/iconeditor.png
DESTDIR = $(QTDIR)/plugins/designer

The .pro file assumes that the QTDIR environment variable is set to the directory where Qt is installed. When you type make or nmake to build the plugin, it will automatically install itself in Qt Designer's plugins directory.

Once the plugin is built, the IconEditor widget can be used in Qt Designer in the same way as any of Qt's built-in widgets.