Documentation/4.1/Developers/Tutorials/WidgetWriting - Revision history

UpdateBot: Prepend documentation/versioncheck template. See http://na-mic.org/Mantis/view.php?id=2887

2013-06-14T07:24:11Z

Prepend documentation/versioncheck template. See http://na-mic.org/Mantis/view.php?id=2887

Dmwelch: /* Coding style */

2012-07-11T17:47:26Z

Coding style

Dmwelch: Added link to Qt webpage

2012-06-28T14:30:38Z

Added link to Qt webpage

Dmwelch: Fixed QtDesigner tutorial link

2012-06-28T14:27:25Z

Fixed QtDesigner tutorial link

Dmwelch: Updated directories for Slicer4

2012-06-28T14:23:05Z

Updated directories for Slicer4

JChris.FillionR at 01:45, 5 June 2012

2012-06-05T01:45:37Z

JChris.FillionR: 4.0 -> 4.1

2012-04-12T04:41:43Z

4.0 -> 4.1

New page

Back to [[Documentation/{{documentation/version}}/Developers|Developers Information]]←

=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 locations where custom widgets can be. You first have to decide where your custom widget should go:
*CTK: Qt and/or VTK only
*Slicer3/Libs/qMRMLWidgets: MRML-aware widgets
A good practice is to split (as possible) your custom widget in 2: a QT-only widget and a MRML-aware widget where the MRML-aware widgets inherits from the Qt-only widget. An intermediate level can be added for Qt and VTK widgets. 
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: <code>qMRML[customName][baseQtWidget]</code>, where <code>[baseQtWidget]</code> is the name of the qt widget your custom widget inherits from (i.e. <code>ComboBox</code>, <code>Slider</code>, <code>Dialog</code>, <code>Widget</code>...), and <code>[customName]</code> is a descriptive name. Examples:
*<code>qMRMLLinearTransformSlider</code>
*<code><s>qMRMLMatrix</s></code><code>qMRMLMatrixWidget</code>

==Note==
*When you create your widget, make sure you use the [http://doc.trolltech.com/4.5/properties.html Qt property system], it allow the customization of the widgets in [http://doc.trolltech.com/4.6/designer-manual.html Qt Designer].

==Step by step==
*Create your widget files (.h and .cxx) in the Lib/qMRMLWidgets directory.
**If you use a .ui file, add it in the Libs/qMRMLWidgets/Resources/UI directory
**If you use icon files, add them in the Libs/qMRMLWidgets/Resources/Icons directory and update the Libs/qMRMLWidgets/Resources/qMRMLWidgets.qrc file accordingly
*Update the Libs/qMRMLWidgets/CMakeLists.txt file with your widget files.
** add the .h and .cxx files in the <code>qMRMLWidgets_SRCS</code> variable
** add the .h file in the <code>qMRMLWidgets_MOC_SRCS</code> variable
** if any, add the .ui file in the <code>qMRMLWidgets_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 associated 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/qMRMLWidgets/Plugins directory.
{|
|<pre>
#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

</pre>
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/qMRMLWidgets/Plugins directory.
{|
|<pre>#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";
}</pre>

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 <code>true</code in the method <code>isContainer()</code>.
*You can customize how the widget is instantiated in the designer by reimplementing the method <code>domxml()</code>.
*Update Libs/qMRMLWidgets/Plugins/CMakeLists.txt by adding your widget plugin files.
** add the files qMRMLCustomWidgetPlugin.h and qMRMLCustomWidgetPlugin.cxx in the variable <code>qMRMLWidgetsPlugin_SRCS</code>
** add the file qMRMLCustomWidgetPlugin.h in the variable <code>qMRMLWidgetsPlugin_MOC_SRCS</code>
*Finally add your widget in the method <code>qMRMLWidgetsPlugins::customWidgets()</code> of the file Libs/qMRMLWidgets/Plugins/qMRMLWidgetsPlugins.h
*compile
Congratulations, you just added a custom widget in a plugin that can be read by QDesigner. Read the [[Slicer3:Developers:Projects:QtSlicer:Tutorials:QtDesigner|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.

← Older revision		Revision as of 07:24, 14 June 2013
Line 1:		Line 1:
		+	<noinclude>{{documentation/versioncheck}}</noinclude>
	=Creating a custom widget in Slicer=		=Creating a custom widget in Slicer=
	==Intro==		==Intro==

@@ Line 125: / Line 125: @@
 *Finally add your widget in the method <code>qMRMLWidgetsPlugins::customWidgets()</code> of the file <i>Libs/MRML/Widgets/DesignerPlugins/qMRMLWidgetsPlugins.h</i>
 *compile
-Congratulations, you just added a custom widget in a plugin that can be read by QDesigner. Read the [[Documentation/4.1/Developers/Tutorials/QtDesigner |next tutorial]] to learn how you can use the widget into Qt Designer.<br>
+Congratulations, you just added a custom widget in a plugin that can be read by QDesigner. Read the [[Documentation/4.1/Developers/Tutorials/QtDesigner |QtDesigner tutorial]] to learn how you can use the widget in [http://qt.nokia.com/products/developer-tools/ Qt Designer].<br>
 '''Coding style:'''
 For a better code readability, make sure you respect the alphabetical order of the files in <i>CMakeLists.txt</i>.

@@ Line 125: / Line 125: @@
 *Finally add your widget in the method <code>qMRMLWidgetsPlugins::customWidgets()</code> of the file <i>Libs/MRML/Widgets/DesignerPlugins/qMRMLWidgetsPlugins.h</i>
 *compile
-Congratulations, you just added a custom widget in a plugin that can be read by QDesigner. Read the [[Slicer3:Developers:Projects:QtSlicer:Tutorials:QtDesigner|next tutorial]] to learn how you can use the widget into Qt Designer.<br>
+Congratulations, you just added a custom widget in a plugin that can be read by QDesigner. Read the [[Documentation/4.1/Developers/Tutorials/QtDesigner |next tutorial]] to learn how you can use the widget into Qt Designer.<br>
 '''Coding style:'''
 For a better code readability, make sure you respect the alphabetical order of the files in <i>CMakeLists.txt</i>.

@@ Line 12: / Line 12: @@
 There are 2 locations where custom widgets can be. You first have to decide where your custom widget should go:
 *<i>CTK</i>: Qt and/or VTK only
-*<i>Slicer3/Libs/qMRMLWidgets</i>: MRML-aware widgets
+*<i>Slicer3/Libs/qMRMLWidgets</i>: MRML-aware widgets (Slicer3)
 A good practice is to split (as possible) your custom widget in 2: a QT-only widget and a MRML-aware widget where the MRML-aware widgets inherits from the Qt-only widget. An intermediate level can be added for Qt and VTK widgets.<br>
 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.<br>
@@ Line 25: / Line 26: @@
 ==Step by step==
-*Create your widget files (.h and .cxx) in the <i>Lib/qMRMLWidgets</i> directory.
+*Create your widget files (.h and .cxx) in the <i>Libs/MRML/Widgets</i> directory.
-**If you use a <i>.ui</i> file, add it in the <i>Libs/qMRMLWidgets/Resources/UI</i> directory
+**If you use a <i>.ui</i> file, add it in the <i>Libs/MRML/Widgets/Resources/UI</i> directory
-**If you use icon files, add them in the <i>Libs/qMRMLWidgets/Resources/Icons</i> directory and update the <i>Libs/qMRMLWidgets/Resources/qMRMLWidgets.qrc</i> file accordingly
+**If you use icon files, add them in the <i>Libs/MRML/Widgets/Resources/Icons</i> directory and update the <i>Libs/MRML/Widgets/Resources/qMRMLWidgets.qrc</i> file accordingly
-*Update the <i>Libs/qMRMLWidgets/CMakeLists.txt</i> file with your widget files.
+*Update the <i>Libs/MRML/Widgets/CMakeLists.txt</i> file with your widget files.
 ** add the <i>.h</i> and <i>.cxx</i> files in the <code>qMRMLWidgets_SRCS</code> variable
 ** add the <i>.h</i> file in the <code>qMRMLWidgets_MOC_SRCS</code> variable
@@ Line 39: / Line 40: @@
 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 <i>Libs/qMRMLWidgets/Plugins</i> directory.
+*Copy paste this template in the <i>Libs/MRML/Widgets/Plugins</i> directory.
 {|
 |<pre>
@@ Line 69: / Line 70: @@
 |}
 *Replace <i>CustomWidget</i> with the name of your widget
-*Copy-paste the following template in the <i>Libs/qMRMLWidgets/Plugins</i> directory.
+*Copy-paste the following template in the <i>Libs/MRML/Widgets/DesignerPlugins</i> directory.
 {|
 |<pre>#include "qMRMLCustomWidgetPlugin.h"
@@ Line 119: / Line 120: @@
 *If the widget is a container, return <code>true</code in the method <code>isContainer()</code>.
 *You can customize how the widget is instantiated in the designer by reimplementing the method <code>domxml()</code>.
-*Update <i>Libs/qMRMLWidgets/Plugins/CMakeLists.txt</i> by adding your widget plugin files.
+*Update <i>Libs/MRML/Widgets/DesignerPlugins/CMakeLists.txt</i> by adding your widget plugin files.
 ** add the files <i>qMRMLCustomWidgetPlugin.h</i> and <i>qMRMLCustomWidgetPlugin.cxx</i> in the variable <code>qMRMLWidgetsPlugin_SRCS</code>
 ** add the file <i>qMRMLCustomWidgetPlugin.h</i> in the variable <code>qMRMLWidgetsPlugin_MOC_SRCS</code>
-*Finally add your widget in the method <code>qMRMLWidgetsPlugins::customWidgets()</code> of the file <i>Libs/qMRMLWidgets/Plugins/qMRMLWidgetsPlugins.h</i>
+*Finally add your widget in the method <code>qMRMLWidgetsPlugins::customWidgets()</code> of the file <i>Libs/MRML/Widgets/DesignerPlugins/qMRMLWidgetsPlugins.h</i>
 *compile
 Congratulations, you just added a custom widget in a plugin that can be read by QDesigner. Read the [[Slicer3:Developers:Projects:QtSlicer:Tutorials:QtDesigner|next tutorial]] to learn how you can use the widget into Qt Designer.<br>
 '''Coding style:'''
 For a better code readability, make sure you respect the alphabetical order of the files in <i>CMakeLists.txt</i>.

← Older revision		Revision as of 01:45, 5 June 2012
Line 1:		Line 1:
−	~~Back to [[Documentation/{{documentation/version}}/Developers\|Developers Information]]←~~
−
	=Creating a custom widget in Slicer=		=Creating a custom widget in Slicer=
	==Intro==		==Intro==

@@ Line 20: / Line 20: @@
 The name of the custom widgets must follow the pattern: <code>qMRML[customName][baseQtWidget]</code>, where <code>[baseQtWidget]</code> is the name of the qt widget your custom widget inherits from (i.e. <code>ComboBox</code>, <code>Slider</code>, <code>Dialog</code>, <code>Widget</code>...), and <code>[customName]</code> is a descriptive name. Examples:
 *<code>qMRMLLinearTransformSlider</code>
-*<code><s>qMRMLMatrix</s></code><code>qMRMLMatrixWidget</code>
+*<code><s>qMRMLMatrix</s></code> vs. <code>qMRMLMatrixWidget</code>
 ==Note==