7.5. Implement a more complex GUI in a plugin (C/C++)

It is already possible to implement many different types of user-defined interfaces by the QtDesigner combined with some Python scripting (see section Creating customized dialogs, windows and dock widgets). However this approach is limited with respect to the usage of external libraries or widgets that are currently not supported or available as designer plugin in the QtDesigner application.

Nevertheless, it is possible to implement arbitrary GUIs in an algorithm plugin (written in C++ and Qt). Then, an instance the Python class itom.ui can also be created from this widget and the standard interaction like connecting to signals or calling slots of this widget is possible.

One or multiple of those widgets can be implemented in one itom plugin of type algorithm. For more detailed information about the programming, read the documentation about the algo plugin class.

The following part of the documentation mainly describes how to show the widget and interact with it using Python.

A list of available widgets can be obtained by the following command:

widgetHelp()
#this command prints a list of all widgets into the command line

In order to create a desired widget, the initialization function might require a set of mandatory or optional parameters, like it is the case for calling filters or instantiating dataIO or actuator instances. If you want to get the list of parameters, call itom.widgetHelp() with the name of the widget as parameter (in difference to the argument-less call above). You will then see a printed list in the command line (comparable to itom.filterHelp()).

If the widget does not require any parameters, it is possible to simply open it via the GUI of itom. In the plugin toolbox, call Open Widget… from the context menu of the widget (child of the algorithm plugin entry where the widget is programmed).

In order to get an instance of the widget via Python (with or without mandatory or optional parameters), use the class-methods createNewPluginWidget() or createNewPluginWidget2(). The first provides an easy access to the widget initialization, the latter let you parameterize the obtained widget, similar to the constructor of the class ui. In both cases, the methods return an instance of itom.ui that can be used like the user-defined user interfaces, described in section Creating customized dialogs, windows and dock widgets.

An example for the easy widget generation is as follows:

#we assume that a widget (created as main window) with the name 'my_window' is available.
#it has one mandatory integer parameter (name: index)

#the window is then created with deleteOnClose = False, childOfMainWindow = True and
#a window type that is derived from the class of the widget (here: ui.TYPEWINDOW).
easy_widget = ui.createNewPluginWidget("my_window", index = 5)
easy_widget.show()

The default parameterizations have the same meaning than the parameters of the constructor of the class itom.ui. If you want to further changes these parameters, use the following form:

window = ui.createNewPluginWidget2("my_window", (), {"index":5}, type = ui.TYPEDOCKWIDGET, dockWidgetArea = ui.BOTTOMDOCKWIDGETAREA)
window.show()

In the case of a GUI based initialization, the widget is always opened with the deleteOnClose flag set to True, such that the widget is destroyed if the user closes it. In the script base approach, this value is False per default. It is closed and destroyed if the variable referencing to the corresponding itom.ui instance is deleted.