Get Involved/development/Tutorials/Writing Qt Designer Plugins

Abstract

This tutorial shows how to add support for custom GUI elements to Qt Designer. It starts by showing how to add a simple custom widget.

Creating a simple factory for a custom widget

We assume you have written a nice widget which you also want to be able to use in Qt Designer and the ui files. For this to achieve you have to write a plugin module for Qt Designer. It consists of just a single object of a class you have to write.

The interface to the plugin

The class, a factory, needs to be subclassed from QObject and to implement the interface QDesignerCustomWidgetInterface, as given by example for the widget MyWidget in the "mywidgetdesignerfactory.h":

1. ifndef MYWIDGETDESIGNERFACTORY_H
2. define MYWIDGETDESIGNERFACTORY_H

// Qt

1. include <QtDesigner/QDesignerCustomWidgetInterface>

class MyWidgetDesignerFactory : public QObject, public QDesignerCustomWidgetInterface {

 Q_OBJECT
 Q_INTERFACES( QDesignerCustomWidgetInterface )

 public:
   explicit MyWidgetDesignerFactory : QObject* parent = 0 );

 public: // QDesignerCustomWidgetInterface API
   virtual QWidget* createWidget( QWidget* parent );
   virtual QString group() const;
   virtual QIcon icon() const;
   virtual QString includeFile() const;
   virtual bool isContainer() const;
   virtual QString name() const;
   virtual QString toolTip() const;
   virtual QString whatsThis() const;

};

1. endif

Creating the data as needed by the interface

The definition of the methods is done as shown in the file "mywidgetdesignerfactory.cpp":

1. include "mywidgetdesignerfactory.h"

// my lib

1. include <mywidget.h>

// Qt

1. include <QtCore/QtPlugin>

MyWidgetDesignerFactory::MyWidgetDesignerFactory( QObject* parent )

 : QObject( parent )

{ }

QWidget* MyWidgetDesignerFactory::createWidget( QWidget* parent ) {

   MyNamespace::MyWidget* widget = new MyNamespace::MyWidget( parent );
   // init with some example data useful in the preview inside Qt Designer
   // this data will be only used there, not in the resulting view in the program.
   return widget;

}

QString MyWidgetDesignerFactory::group() const {

   return QString::fromLatin1("Some group (KDE)");

}

QIcon MyWidgetDesignerFactory::icon() const {

   return QIcon();

}

QString MyWidgetDesignerFactory::includeFile() const {

   return QString::fromLatin1("neededincludepathprefix/mywidget.h");

}

QString MyWidgetDesignerFactory::toolTip() const {

   return QString::fromLatin1("Useful Widget of Mine");

}

QString MyWidgetDesignerFactory::whatsThis() const {

   return QString::fromLatin1("Some description of my widget.");

}

bool MyWidgetDesignerFactory::isContainer() const {

   return false;

}

QString MyWidgetDesignerFactory::name() const {

   return QString::fromLatin1("MyNamespace::MyWidget");

}

// export macro, takes the name of the plugin module and the class name Q_EXPORT_PLUGIN2( mydesignerplugin, MyWidgetDesignerFactory )

Adding to the Buildsystem

After you created the two files above you need to tell the buildsystem how to create the Qt Designer plugin and where to install it. This needs a CMakeLists.txt file in the same directory with such content:

set( mydesignerplugin_SRCS
  mywidgetdesignerfactory.cpp
)

# the name of the plugin module is the same name as used in the macro Q_EXPORT_PLUGIN2 in the mywidgetdesignerfactory.cpp file
kde4_add_plugin( mydesignerplugin  ${mydesignerplugin_SRCS} )

target_link_libraries( mydesignerplugin
  mylib
  # other needed libs
)

install( TARGETS mydesignerplugin  DESTINATION ${PLUGIN_INSTALL_DIR}/plugins/designer )

Finding your widget in Qt Designer

If you successfully compiled and installed your plugin, (re-)start Qt Designer and have a look in the Widgetbox (on the left side by default). If everything worked perfectly you will see a new entry "MyNamespace::MyWidget" (as defined by MyWidgetDesignerFactory::name()) in the group "Some group (KDE)" (as defined by MyWidgetDesignerFactory::group()). Now drag and drop the entry to the currently edited view in Qt Designer, and voilà, it should be added to the view.