Slicer3:Developers:Projects:QtSlicer/Tutorials/WidgetWriting

QtSlicer/Tutorials←

Creating a custom widget in Slicer

Intro

A custom widget is a specialization of another widget or a group of widgets working together. Custom widgets are usually created when you need to add new functionality to existing widgets or groups of widgets. If you simply want a collection of widgets in a special configuration it can be easily done in QtDesigner and probably doesn't require to be a custom widget.

In the following we will assume you are familiar with Qt.
Here are some useful links:

• http://doc.trolltech.com/how-to-learn-qt.html
• http://doc.trolltech.com/object.html
• http://doc.trolltech.com/properties.html

Before starting

There are 2 directories where custom widgets can be. You first have to decide in what directory your custom widget should go:

• Slicer3/Libs/qCTKWidgets: Qt only widget
• Slicer3/Libs/qMRMLWidgets: MRML-aware widgets

A good practice is to split (if possible) your custom widget in 2 widgets, a QT-only widget, and a MRML-aware widget. The MRML widget inherits from the Qt only widget.
It is important to keep the widgets basic. If you think someone else can use your custom widget differently, or if someone would need less features than the custom widget currently have, it is probably a good idea to split the widget in 2 widgets linked with an IS-A relationship.

Coding style

The name of the custom widgets must follow the pattern: q[CTK|MRML][customName][baseQtWidget], where baseQtWidget is the name of the qt widget your custom widget inherits from (i.e. ComboBox, Slider, Dialog, Widget...), and customName is a descriptive name. Examples:

• qCTKCollapsibleGroupBox
• qMRMLLinearTransformSlider
• qCTKColorPickerqCTKColorPickerButton, qCTKColorPickerDialog

Note

• When you create your widget, make sure you highly use the Qt property system, it let you customize your widgets from the Qt Designer.
• The process to create a custom widget is similar for qCTKWidgets and qMRMLWidgets, this is why we will use the notation q***Widgets to describe either qCTKWidgets or qMRMLWidgets.

Step by step

• Create your widget files (.h and .cxx) in the Lib/q***Widgets directory.
  • If you use a .ui file, add it in the Libs/q***Widgets/Resources/UI directory
  • If you use icon files, add them in the Libs/q***Widgets/Resources/Icons directory and update the Libs/q***Widgets/Resources/q***Widgets.qrc file accordingly
• Update the Libs/q***Widgets/CMakeLists.txt file with your widget files.
  • add the .h and .cxx files in the q***Widgets_SRCS variable
  • add the .h file in the q***Widgets_MOC_SRCS variable
  • if any, add the .ui file in the q***Widgets_UI_SRCS</code variable
• compile with your favorite compiler.

Congratulations, you just added a custom widget in Slicer. The widget can now be used anywhere in Slicer.
However the widget doesn't show up in QDesigner, let's create the custom widget plugin for QDesigner.

Create a widget for the designer

For a general presentation to create custom widgets for Qt Designer, see http://doc.trolltech.com/designer-creating-custom-widgets.html

Step by step

• Copy paste this template in the Libs/q***Widgets/Plugins directory.

qCTKWidgets

qMRMLWidgets

#ifndef __qCTKCustomWidgetPlugin_h #define __qCTKCustomWidgetPlugin_h #include "qCTKWidgetsAbstractPlugin.h" class QCTK_WIDGETS_PLUGIN_EXPORT qCTKCustomWidgetPlugin : public QObject, public qCTKWidgetsAbstractPlugin { Q_OBJECT public: qCTKCustomWidgetPlugin(QObject *_parent = 0); QWidget *createWidget(QWidget *_parent); QString domXml() const; QString includeFile() const; bool isContainer() const; QString name() const; }; #endif Rename the file qCTK[name of your widget]Plugin.h

#ifndef __qMRMLCustomWidgetPlugin_h #define __qMRMLCustomWidgetPlugin_h #include "qMRMLWidgetsAbstractPlugin.h" class QMRML_WIDGETS_PLUGIN_EXPORT qMRMLCustomWidgetPlugin : public QObject, public qMRMLWidgetsAbstractPlugin { Q_OBJECT public: qMRMLCustomWidgetPlugin(QObject *_parent = 0); QWidget *createWidget(QWidget *_parent); QString domXml() const; QString includeFile() const; bool isContainer() const; QString name() const; }; #endif Rename the file qMRML[name of your widget]Plugin.h

• Replace CustomWidget with the name of your widget
• Copy-paste the following template in the Libs/q***Widgets/Plugins directory.

qCTKWidgets

qMRMLWidgets

#include "qCTKCustomWidgetPlugin.h" #include "qCTKCustomWidget.h" qCTKCustomWidgetPlugin::qCTKCustomWidgetPlugin(QObject *_parent) : QObject(_parent) { } QWidget *qCTKCustomWidgetPlugin::createWidget(QWidget *_parent) { qCTKCustomWidget* _widget = new qCTKCustomWidget(_parent); return _widget; } QString qCTKCustomWidgetPlugin::domXml() const { return "<widget class=\"qCTKCustomWidget\" \ name=\"CTKCustomWidget\">\n" "</widget>\n"; } QString qCTKCustomWidgetPlugin::includeFile() const { return "qCTKCustomWidget.h"; } bool qCTKCustomWidgetPlugin::isContainer() const { return false; } QString qCTKCustomWidgetPlugin::name() const { return "qCTKCustomWidget"; } Rename the file qCTK[name of your widget]Plugin.cxx

#include "qMRMLCustomWidgetPlugin.h" #include "qMRMLCustomWidget.h" qMRMLCustomWidgetPlugin::qMRMLCustomWidgetPlugin(QObject *_parent) : QObject(_parent) { } QWidget *qMRMLCustomWidgetPlugin::createWidget(QWidget *_parent) { qMRMLCustomWidget* _widget = new qMRMLCustomWidget(_parent); return _widget; } QString qMRMLCustomWidgetPlugin::domXml() const { return "<widget class=\"qMRMLCustomWidget\" \ name=\"MRMLCustomWidget\">\n" "</widget>\n"; } QString qMRMLCustomWidgetPlugin::includeFile() const { return "qMRMLCustomWidget.h"; } bool qMRMLCustomWidgetPlugin::isContainer() const { return false; } QString qMRMLCustomWidgetPlugin::name() const { return "qMRMLCustomWidget"; } Rename the file qMRML[name of your widget]Plugin.cxx

• Replace CustomWidget by the name of your widget
• If the widget is a container, return true</code in the method isContainer(). See qCTKCollapsibleGroupBoxPlugin.cxx for an example.
• You can customize how the widget is instantiated in the designer by reimplementing the method domxml().
• Update Libs/q***Widgets/Plugins/CMakeLists.txt by adding your widget plugin files.
  • add the files qMRMLCustomWidgetPlugin.h and qMRMLCustomWidgetPlugin.cxx in the variable q***WidgetsPlugin_SRCS
  • add the file qMRMLCustomWidgetPlugin.h in the variable q***WidgetsPlugin_MOC_SRCS
  • if any, add the extension files as well. i.e. qCTKCollapsibleWidgetContainerExtension.cxx
• Finally add your widget in the method q***WidgetsPlugins::customWidgets() of the file Libs/q***Widgets/Plugins/q***WidgetsPlugins.h
• compile

Congratulations, you just added a custom widget in a plugin that can be read by QDesigner. Read the next tutorial to learn how you can use the widget into Qt Designer.
Coding style: For a better code readability, make sure you respect the alphabetical order of the files in CMakeLists.txt.