View source for 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 {{qt|QObject}} and to implement the interface {{qt|QDesignerCustomWidgetInterface}}, as given by example for the widget MyWidget in the "mywidgetdesignerfactory.h":

<code cppqt n>
#ifndef MYWIDGETDESIGNERFACTORY_H
#define MYWIDGETDESIGNERFACTORY_H

// Qt
#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;
};

#endif
</code>

=== Creating the data as needed by the interface  ===

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

<code cppqt n>
#include "mywidgetdesignerfactory.h"

// my lib
#include <mywidget.h>
// Qt
#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 )

</code>

=== 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 <tt>MyWidgetDesignerFactory::name()</tt>) in the group "Some group (KDE)" (as defined by <tt>MyWidgetDesignerFactory::group()</tt>). Now drag and drop the entry to the currently edited view in Qt Designer, and voilà, it should be added to the view.