Slicer3:Developers:Projects:QtSlicer/Tutorials/WidgetWriting - Revision history

Finetjul: Move from Slicer3 to Slicer4

2011-01-16T07:02:22Z

Move from Slicer3 to Slicer4

Finetjul: /* Step by step */

2010-06-17T03:53:42Z

Step by step

Finetjul: /* Step by step */

2010-06-17T03:53:10Z

Step by step

Finetjul: /* Step by step */

2010-06-17T03:52:57Z

Step by step

Finetjul at 20:52, 16 June 2010

2010-06-16T20:52:58Z

Show changes

Finetjul: /* Step by step */

2009-11-24T14:26:17Z

Step by step

Finetjul: /* Step by step */

2009-11-24T14:25:34Z

Step by step

Finetjul: /* Step by step */

2009-11-24T14:24:45Z

Step by step

Finetjul: /* Step by step */

2009-11-24T14:18:17Z

Step by step

Finetjul: /* Load the widget from the designer */

2009-11-24T14:17:01Z

Load the widget from the designer

← Older revision		Revision as of 07:02, 16 January 2011
Line 1:		Line 1:
−	[[~~Slicer3~~:Developers:Projects:QtSlicer~~\|QtSlicer]]~~/~~[[Slicer3:Developers:Projects:QtSlicer~~/~~Tutorials~~\|~~Tutorials]]←~~	+	This page has moved to [[Slicer4:Developers:Projects:QtSlicer/Tutorials/WidgetWriting\|Slicer4 Widget Writing]]
−	~~=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.<br>~~
−	~~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:~~
−	*<i>CTK</i>: Qt and/or VTK only
−	*<i>Slicer3/Libs/qMRMLWidgets</i>: 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.<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>
−
−	~~==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 <i>Lib/qMRMLWidgets</i> directory.
−	**If you use a <i>.ui</i> file, add it in the <i>Libs/qMRMLWidgets/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
−	*Update the <i>Libs/qMRMLWidgets/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
−	** if any, add the <i>.ui</i> 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.<br>~~
−	~~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 <i>Libs/qMRMLWidgets/Plugins</i> 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 <i>qMRML[name of your widget]Plugin.h</i>~~
−	\|}
−	*Replace <i>CustomWidget</i> with the name of your widget
−	*Copy-paste the following template in the <i>Libs/qMRMLWidgets/Plugins</i> 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 <i>CustomWidget</i> 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 <i>Libs/qMRMLWidgets/Plugins/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>
−	*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>.~~

@@ Line 42: / Line 42: @@
 *Copy paste this template in the <i>Libs/qMRMLWidgets/Plugins</i> directory.
 {|
 |<pre>
 #ifndef __qMRMLCustomWidgetPlugin_h
@@ Line 74: / Line 72: @@
 *Copy-paste the following template in the <i>Libs/qMRMLWidgets/Plugins</i> directory.
 {|
 |<pre>#include "qMRMLCustomWidgetPlugin.h"
 #include "qMRMLCustomWidget.h"

@@ Line 43: / Line 43: @@
 {|
 !qMRMLWidgets
 |<pre>
 #ifndef __qMRMLCustomWidgetPlugin_h

@@ Line 32: / Line 32: @@
 ** 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
-** if any, add the <i>.ui</i> file in the <code>qMRMLWidgets_UI_SRCS</code variable
+** if any, add the <i>.ui</i> 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.<br>

@@ Line 98: / Line 98: @@
 </pre>
-Rename the file qMRML[name of your widget]Plugin.h
+Rename the file <i>qMRML[name of your widget]Plugin.h</i>
 |}
 *Replace <i>CustomWidget</i> with the name of your widget

@@ Line 193: / Line 193: @@
 *Finally add your widget in the method <code>q***WidgetsPlugins::customWidgets()</code> of the file <i>Libs/q***Widgets/Plugins/q***WidgetsPlugins.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.
+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 visibility, make sure you respect the alphabetical order in the <i>CMakeLists.txt</i> when you add your files in the CMake variables.<br>
+For a better code readability, make sure you respect the alphabetical order of the files in <i>CMakeLists.txt</i>.

@@ Line 72: / Line 72: @@
 </pre>
-Name the file <i>qCTK[name of your widget]Plugin.h</i>
+Rename the file <i>qCTK[name of your widget]Plugin.h</i>
 |<pre>
 #ifndef __qMRMLCustomWidgetPlugin_h
@@ Line 98: / Line 98: @@
 </pre>
-Name the file qMRML[name of your widget]Plugin.h
+Rename the file qMRML[name of your widget]Plugin.h
 |}
-*Replace <i>CustomWidget</i> by the name of your widget
+*Replace <i>CustomWidget</i> with the name of your widget
-*Copy paste this template in the <i>Libs/q***Widgets/Plugins</i> directory.
+*Copy-paste the following template in the <i>Libs/q***Widgets/Plugins</i> directory.
 {|
 !qCTKWidgets
@@ Line 144: / Line 144: @@
+}
 </pre>
-Name the file <i>qCTK[name of your widget]Plugin.cxx</i>
+Rename the file <i>qCTK[name of your widget]Plugin.cxx</i>
 |<pre>#include "qMRMLCustomWidgetPlugin.h"
 #include "qMRMLCustomWidget.h"
@@ Line 182: / Line 182: @@
 }</pre>
-Name the file qMRML[name of your widget]Plugin.cxx
+Rename the file qMRML[name of your widget]Plugin.cxx
 |}
 *Replace <i>CustomWidget</i> by the name of your widget
-*If the widget is a container, return true in the method <code>isContainer()</code>. See <i>qCTKCollapsibleWidgetPlugin.cxx</i> for more information.
+*If the widget is a container, return <code>true</code in the method <code>isContainer()</code>. See <i>qCTKCollapsibleGroupBoxPlugin.cxx</i> for an example.
-*You can customize how the widget look in the designer by modifying the <code>domxml()</code> method.
+*You can customize how the widget is instantiated in the designer by reimplementing the method <code>domxml()</code>.
-*Update the <i>Libs/q***Widgets/Plugins/CMakeLists.txt</i> file with your widget files.
+*Update <i>Libs/q***Widgets/Plugins/CMakeLists.txt</i> by adding your widget plugin files.
-** add the <i>.h</i> and <i>.cxx</i> files in the <code>q***WidgetsPlugin_SRCS</code> variable
+** add the files <i>qMRMLCustomWidgetPlugin.h</i> and <i>qMRMLCustomWidgetPlugin.cxx</i> in the variable <code>q***WidgetsPlugin_SRCS</code>
-** add the <i>.h</i> file in the <code>q***WidgetsPlugin_MOC_SRCS</code> variable
+** add the file <i>qMRMLCustomWidgetPlugin.h</i> in the variable <code>q***WidgetsPlugin_MOC_SRCS</code>
 ** if any, add the extension files as well. i.e. <i>qCTKCollapsibleWidgetContainerExtension.cxx</i>
-*Add your widget in the <code>q***WidgetsPlugins::customWidgets()</code> method in the <i>Libs/q***Widgets/Plugins/q***WidgetsPlugins.h</i> file
+*Finally add your widget in the method <code>q***WidgetsPlugins::customWidgets()</code> of the file <i>Libs/q***Widgets/Plugins/q***WidgetsPlugins.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.
 '''Coding style:'''
-For a better code visibility, make sure you respect the alphabetical order in the <i>CMakeLists.txt</i> files when you add your files in the CMake variables.<br>
+For a better code visibility, make sure you respect the alphabetical order in the <i>CMakeLists.txt</i> when you add your files in the CMake variables.<br>

@@ Line 44: / Line 44: @@
 *Copy paste this template in the <i>Libs/q***Widgets/Plugins</i> directory.
 {|
-!qCTKWidget
+!qCTKWidgets
-!qMRMLWidget
+!qMRMLWidgets
 |-
 |<pre>
@@ Line 51: / Line 51: @@
 #define __qCTKCustomWidgetPlugin_h
-#include "qCTKWidgetsBasePlugin.h"
+#include "qCTKWidgetsAbstractPlugin.h"
 class QCTK_WIDGETS_PLUGIN_EXPORT qCTKCustomWidgetPlugin : public QObject,
-                                                           public qCTKWidgetsBasePlugin
+                                                           public qCTKWidgetsAbstractPlugin
+{
    Q_OBJECT
@@ Line 78: / Line 77: @@
 #define __qMRMLCustomWidgetPlugin_h
-#include "qMRMLWidgetsBasePlugin.h"
+#include "qMRMLWidgetsAbstractPlugin.h"
 class QMRML_WIDGETS_PLUGIN_EXPORT qMRMLCustomWidgetPlugin : public QObject,
-                                 public qMRMLWidgetsBasePlugin
+                                 public qMRMLWidgetsAbstractPlugin
+{
    Q_OBJECT

@@ Line 39: / Line 39: @@
 However the widget doesn't show up in QDesigner, let's create the custom widget plugin for QDesigner.
-=Load the widget from the designer=
+=Create a widget for the designer=
-For a presentation of creating custom widgets for Qt Designer, see http://doc.trolltech.com/designer-creating-custom-widgets.html
+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/q***Widgets/Plugins</i> directory.