Get Involved/development/Tutorials/Writi

Get Involved/development/Tutorials/Writing Qt Designer Plugins - KDE Community Wiki
Jump to content
From KDE Community Wiki
Get Involved
development
Proposed for Deletion
This page has been proposed for deletion for the following reason:
Uses the website qt.nokia.com. The page
and its children should not exist.
Please use the discussion section of this page to voice your opinion on this.
Warning
This page needs a review and probably holds information that needs to be fixed.
Parts to be reviewed:
{{{1}}}
Abstract
This tutorial shows how to add support for custom GUI elements to Qt Designer. In the first section you learn how to write a Qt Designer plugin for a simple custom widget. The second section then presents how to support more than one widget in a plugin.
Creating a simple Plugin 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 file "mywidgetdesignerfactory.h":
#ifndef MYWIDGETDESIGNERFACTORY_H
#define MYWIDGETDESIGNERFACTORY_H
// Qt
#include

#include

class
MyWidgetDesignerFactory
public
QObject
public
QDesignerCustomWidgetInterface
Q_OBJECT
Q_INTERFACES
QDesignerCustomWidgetInterface
public
explicit
MyWidgetDesignerFactory
QObject
parent
);
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
Creating the Data as needed by the Interface
The definition of the methods is done as shown in the file "mywidgetdesignerfactory.cpp":
#include
"mywidgetdesignerfactory.h"
// my lib
#include

// Qt
#include

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
For detailed information about the purpose of all the methods of the API you might want to read
the related page
from the Qt documentation.
Adding to the Buildsystem
After you created the two files above you need to tell the buildsystem how to build the Qt Designer plugin from them 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 file mywidgetdesignerfactory.cpp
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à, your widget should be added to that view.
Creating a Bundle Plugin for several Widgets
You may have created not just one, but several widgets which you would like to enable support for in Qt Designer. Instead of writing a plugin for each widget you can collect the factories for all widgets in a single plugin, by using a helper class.
In the next subsections it is assumed you have already written factories for your two widgets
MyWidget
and
MyOtherWidget
as described in the previous section, namely
MyWidgetDesignerFactory
and
MyOtherWidgetDesignerFactory
, using the headers "mywidgetdesignerfactory.h" and "myotherwidgetdesignerfactory.h" and the implementation files "mywidgetdesignerfactory.cpp" and "myotherwidgetdesignerfactory.cpp".
The Interface to the Bundle
The helper class, which is used to hold all factories, needs to be subclassed from
QObject
and to implement the interface
QDesignerCustomWidgetCollectionInterface
, as in the following example MyWidgetDesignerFactoryCollection in the file "mywidgetdesignerfactorycollection.h":
#ifndef MYWIDGETDESIGNERFACTORYCOLLECTION_H
#define MYWIDGETDESIGNERFACTORYCOLLECTION_H
// Qt
#include

#include

class
MyWidgetDesignerFactoryCollection
public
QObject
public
QDesignerCustomWidgetCollectionInterface
Q_OBJECT
Q_INTERFACES
QDesignerCustomWidgetCollectionInterface
public
explicit
MyWidgetDesignerFactoryCollection
QObject
parent
);
public
// QDesignerCustomWidgetCollectionInterface API
virtual
QList
QDesignerCustomWidgetInterface
*>
customWidgets
()
const
private
QList
QDesignerCustomWidgetInterface
*>
mWidgetFactories
};
#endif
Putting the Factories into the Collection
The implementation of the helper class is pretty simple. You just have to create all widget factories in the constructor and add them to the list member. This list is then returned in the method
MyWidgetDesignerFactoryCollection::customWidgets()
. See the example code of the file "mywidgetdesignerfactorycollection.cpp":
#include
"mywidgetdesignerfactorycollection.h"
// plugin
#include
"mywidgetdesignerfactory.h"
#include
"myotherwidgetdesignerfactory.h"
// Qt
#include

MyWidgetDesignerFactoryCollection
::
MyWidgetDesignerFactoryCollection
QObject
parent
QObject
parent
mWidgetFactories
append
new
MyWidgetDesignerFactory
this
);
mWidgetFactories
append
new
MyOtherWidgetDesignerFactory
this
);
QList
QDesignerCustomWidgetInterface
*>
MyWidgetDesignerFactoryCollection
::
customWidgets
()
const
return
mWidgetFactories
Q_EXPORT_PLUGIN2
mydesignerplugin
MyWidgetDesignerFactoryCollection
Important: As the
MyWidgetDesignerFactoryCollection
is now the central class of the plugin and not any of the widget factories, the source files of the widget factories should no more contain the macro
Q_EXPORT_PLUGIN2
. Otherwise the build will fail.
Adapting the Buildsystem
The CMakeLists.txt content is similar to the one for the single widget factory plugin. The two differences are in the files listed for
mydesignerplugin_SRCS
, here you put all the source files of the factories and the one of the helper class, and the libraries listed in
target_link_libraries( ... )
, here you collect all libraries as needed by the single widget factories:
set
mydesignerplugin_SRCS
mywidgetdesignerfactory.cpp
myotherwidgetdesignerfactory.cpp
# and any other factory source file
mywidgetdesignerfactorycollection.cpp
# the name of the plugin module is the same name as used in the macro Q_EXPORT_PLUGIN2 in the file mywidgetdesignerfactorycollection.cpp
kde4_add_plugin
mydesignerplugin
${
mydesignerplugin_SRCS
target_link_libraries
mydesignerplugin
mylib
# other needed libs
install
TARGETS
mydesignerplugin
DESTINATION
${
PLUGIN_INSTALL_DIR
/plugins/designer
Now if you compile and install this new bundle plugin, after the (re-)start of Qt Designer you should find all your widgets in the Widgetbox. Make sure you have removed any previously installed plugins with a single widget factory for any of the widgets before to avoid conflicts.
Retrieved from "
Hidden category:
Proposed deletion