9.18. ui-elements (ui, uiItem)

9.18.1. uiItem-Class

class itom.uiItem(...) → base class representing any widget of a graphical user interface

This class represents any widget (graphical, interactive element like a button or checkbox) on a graphical user interface. An instance of this class provides many functionalities given by the underlying Qt system. For instance, it is posible to call a public slot of the corresponding widget, connect signals to specific python methods or functions or change properties of the widget represeted by the instance.

The overall dialog or window as main element of a graphical user interface itself are instances of the class ui. However, they are derived from uiItem, since dialogs or windows internally are widgets as well.

Widgets placed at a user interface using the Qt Designer can be referenced by an uiItem instance by their specific objectName, assigned in the Qt Designer as well. As an example, a simple dialog with one button is created and the text of the button (objectName: btn) is set to OK:

dialog = ui('filename.ui', type=ui.TYPEDIALOG) 
button = dialog.btn #here the reference to the button is obtained 
button["text"] = "OK" #set the property text of the button 

Information about available properties, signals and slots can be obtained using the method info() of uiItem.

Notes

It is not intended to directly instantiate this class. Either create a user interface using the class ui or obtain a reference to an existing widget (this is then an instance of uiItem) using the dot-operator of a parent widget or the entire user interface.

call(slotOrPublicMethod, *args) → calls any public slot of this widget or any accessible public method.

This method invokes (calls) a method of the underlying widget that is marked as public slot. Besides slots there are some public methods of specific widget classes that are wrapped by itom and therefore are callable by this method, too.

If only method is available, all arguments are tried to be cast to the requested types and the slot is called on conversion success. If the method has multiple overloaded possibilities in the underlying C++ classes, at first, it is intended to find the variant where all arguments can be strictly casted from Python types to the necessary C-types. If this fails, the next variant with a non-strict conversion is chosen.

Parameters

slotOrPublicMethod : {str}

name of the slot or method

*args : {various types}, optional

Variable length argument list, that is passed to the called slot or method. The type of each value must be convertible to the requested C++ based argument type of the slot.

See also

info

Notes

If you want to know all possible slots of a specific widget, see the Qt help or call the member info() of the widget.

children(recursive=False) → returns dict with widget-based child items of this uiItem.

Each key -> value pair is object-name -> class-name). Objects with no object-name are omitted.

Parameters

recursive : {bool}

True: all objects including sub-widgets of widgets are returned, False: only children of this uiItem are returned (default)

connect(signalSignature, callableMethod, minRepeatInterval=0) → connects the signal of the widget with the given callable python method

This instance of uiItem wraps a widget, that is defined by a C++-class, that is finally derived from QWidget. See Qt-help for more information about the capabilities of every specific widget. Every widget can send various signals. Use this method to connect any signal to any callable python method (bounded or unbounded). This method must have the same number of arguments than the signal and the types of the signal definition must be convertable into a python object.

Parameters

signalSignature : {str}

This must be the valid signature, known from the Qt-method connect (e.g. ‘clicked(bool)’)

callableMethod : {python method or function}

valid method or function that is called if the signal is emitted.

minRepeatInterval : {int}, optional

If > 0, the same signal only invokes a slot once within the given interval (in ms). Default: 0 (all signals will invoke the callable python method.

disconnect(signalSignature, callableMethod) → disconnects a connection which must have been established with exactly the same parameters.
Parameters

signalSignature : {str}

This must be the valid signature, known from the Qt-method connect (e.g. ‘clicked(bool)’)

callableMethod : {python method or function}

valid method or function, that should not be called any more, if the given signal is emitted.

See also

connect

exists() → returns true if widget still exists, else false.
getAttribute(attributeNumber) → returns specified attribute of corresponding widget.

Widgets have specific attributes that influence their behaviour. These attributes are contained in the Qt-enumeration Qt::WidgetAttribute. Use this method to query the current status of one specific attributes.

Important attributes are:

  • Qt::WA_DeleteOnClose (55) -> deletes the widget when it is closed, else it is only hidden [default]

  • Qt::WA_MouseTracking (2) -> indicates that the widget has mouse tracking enabled

Parameters

attributeNumber : {int}

Number of the attribute of the widget to query (enum Qt::WidgetAttribute)

Returns

out : {bool}

True if attribute is set, else False

See also

setAttribute

getChild(widgetName) → returns the uiItem of the child widget with the given widgetName.

This call is equal to self.__attributes__[widgetName] or self.widgetName

Parameters

widgetName : {str}

Object name of the desired child widget.

getProperty(propertyName) -> returns tuple of requested properties (single property or tuple of properties)

Use this method or the operator [] in order to get the value of one specific property of this widget or of multiple properties. Multiple properties are given by a tuple or list of property names. For one single property, its value is returned as it is. If the property names are passed as sequence, a sequence of same size is returned with the corresponding values.

Parameters

property : {str, sequence of str}

Name of one property or sequence (tuple,list…) of property names

Returns

out : {variant, sequence of variants}

the value of one single property of a list of values, if a sequence of names is given as parameter.

See also

setProperty

getPropertyInfo(propertyName=None) → returns information about the property ‘propertyName’ of this widget or all properties, if None or no name indicated.
Parameters

propertyName : {tuple}, optional

The name of the property whose detailed information should be returned or None, if a list of all property names should be returned. Instead of None, the method can also be called without any arguments.

Returns

A list of all available property names, if None or no argument is given. :

OR: :

A read-only dictionary with further settings of the requested property. This dictionary contains :

of the following entries: :

name, valid, readable, writeable, resettable, final, constant :

getWindowFlags(flags) → gets window flags of corresponding widget.

The flags-value is an or-combination of the enumeration Qt::WindowType. See Qt documentation for more information.

Returns

flags {int}: :

or-combination of Qt::WindowType describing the type and further hints of the user interface

See also

setWindowFlags

info(verbose=0) → prints information about properties, public accessible slots and signals of the wrapped widget.
Parameters

verbose : {int}

0: only properties, slots and signals that do not come from Qt-classes are printed (default) 1: properties, slots and signals are printed up to Qt GUI base classes 2: all properties, slots and signals are printed

invokeKeyboardInterrupt(signalSignature) → connects the given signal with a slot immediately invoking a python interrupt signal.
Parameters

signalSignature : {str}

This must be the valid signature, known from the Qt-method connect (e.g. ‘clicked(bool)’)

Notes

If you use the connect method to link a signal with a python method or function, this method can only be executed if python is in an idle status. However, if you want to immediately raise the python interrupt signal, use this method to establish the connection instead of the uiItem.connect command.

invokeProgressObserverCancellation(signalSignature: str, observer: itom.progressObserver) → connects the given signal with a slot immediately setting the cancellation flag of the given progressObserver.

This method immediately calls the ‘requestCancellation’ slot of the given observer if the given signal is emitted (independent on the current state of the Python script execution).

Parameters

signalSignature : {str}

This must be the valid signature, known from the Qt-method connect (e.g. ‘clicked(bool)’)

observer : {itom.progressObserver}

This must be an itom.progressObserver object. The given signal is connected to the slot ‘requestCancellation’ of this progressObserver.

setAttribute(attributeNumber, value) → sets attribute of corresponding widget.

Widgets have specific attributes that influence their behaviour. These attributes are contained in the Qt-enumeration Qt::WidgetAttribute. Use this method to enable/disable one specific attribute.

Important attributes are:

  • Qt::WA_DeleteOnClose (55) -> deletes the widget when it is closed, else it is only hidden [default]

  • Qt::WA_MouseTracking (2) -> indicates that the widget has mouse tracking enabled

Parameters

attributeNumber : {int}

Number of the attribute of the widget to set (enum Qt::WidgetAttribute)

value : {bool}

True if attribute should be enabled, else False

See also

getAttribute

setProperty(propertyDict) → each property in the parameter dictionary is set to the dictionaries value.
Parameters

propertyDict : {dict}

Dictionary with properties (keyword) and the values that should be set.

See also

getProperty

setWindowFlags(flags) → set window flags of corresponding widget.

The window flags are used to set the type of a widget, dialog or window including further hints to the window system. This method is used to set the entire or-combination of all flags, contained in the Qt-enumeration Qt::WindowType.

The most important types are:

  • Qt::Widget (0) -> default type for widgets

  • Qt::Window (1) -> the widget looks and behaves like a windows (title bar, window frame…)

  • Qt::Dialog (3) -> window decorated as dialog (no minimize or maximize button…)

Further hints can be (among others):

  • Qt::FramelessWindowHint (0x00000800) -> borderless window (user cannot move or resize the window)

  • Qt::WindowTitleBar (0x00001000) -> gives the window a title bar

  • Qt::WindowMinimizeButtonHint (0x00004000) -> adds a minimize button to the title bar

  • Qt::WindowMaximizeButtonHint (0x00008000) -> adds a maximize button to the title bar

  • Qt::WindowCloseButtonHint (0x00010000) -> adds a close button.

  • Qt::WindowStaysOnTopHint (0x00040000) -> this ui element always stays on top of other windows

  • Qt::WindowCloseButtonHint (0x08000000) -> remove this flag in order to disable the close button

If you simply want to change one hint, get the current set of flags using getWindowFlags, change the necessary bitmask and set it again using this method.

Parameters

flags : {int}

window flags to set (or-combination, see Qt::WindowFlags)

See also

getWindowFlags

9.18.2. ui-Class

class itom.ui(filename[, type, dialogButtonBar, dialogButtons, childOfMainWindow, deleteOnClose, dockWidgetArea]) → instance of user interface

Bases: itom.uiItem

The class ui wraps a user interface, externally designed and given by a ui-file. If your user interface is a dialog or window, chose ui.TYPEWINDOW as type, if the user interface is a widget (simplest case), chose ui.TYPEDIALOG and your widget will be embedded in a dialog, provided by itom. This dialog can be equiped with a button bar, whose buttons are already connected to itom internal methods. If you then show your dialog in a modal mode, itom knows which button has been clicked in order to accept or reject the dialog.

Parameters

filename : {str}

path to user interface file (*.ui), absolute or relative to current directory

type : {int}, optional

display type:

  • 0 (ui.TYPEDIALOG): ui-file is embedded in auto-created dialog (default),

  • 1 (ui.TYPEWINDOW): ui-file is handled as main window,

  • 2 (ui.TYPEDOCKWIDGET): ui-file is handled as dock-widget and appended to the main-window dock area,

  • 3 (ui.TYPECENTRALWIDGET): ui-file must be a widget or mainWindow and is included in the central area of itom, above the command line

dialogButtonBar : {int}, optional

Only for type ui.TYPEDIALOG (0). Indicates whether buttons should automatically be added to the dialog:

  • 0 (ui.BUTTONBAR_NO): do not add any buttons (default)

  • 1 (ui.BUTTONBAR_HORIZONTAL): add horizontal button bar

  • 2 (ui.BUTTONBAR_VERTICAL): add vertical button bar

dialogButtons : {dict}, optional

every dictionary-entry is one button. key is the role, value is the button text

childOfMainWindow : {bool}, optional

for type TYPEDIALOG and TYPEWINDOW only. Indicates whether window should be a child of itom main window (default: True)

deleteOnClose : {bool}, optional

Indicates whether window should be deleted if user closes it or if it is hidden (default: Hidden, False)

dockWidgetArea : {int}, optional

Only for type ui.TYPEDOCKWIDGET (2). Indicates the position where the dock widget should be placed:

  • 1 (ui.LEFTDOCKWIDGETAREA)

  • 2 (ui.RIGHTDOCKWIDGETAREA)

  • 4 (ui.TOPDOCKWIDGETAREA): default

  • 8 (ui.BOTTOMDOCKWIDGETAREA)

static availableWidgets() -> return a list of currently available widgets (that can be directly loaded in ui-files at runtime)
static createNewPluginWidget(widgetName[, mandparams, optparams]) → creates widget defined by any algorithm plugin and returns the instance of type ‘ui’

This static class method initializes an instance of class ui from a widget, window, dialog or dockWidget that is implemented in an algorithm plugin. Compared to the more detailed method ‘createNewPluginWidget2’, this method uses the following defaults for the windows appearance:

  • the type of the widget is derived from the widget itself and cannot be adjusted

  • deleteOnClose = false, the widget or windows will only be hidden if the user clicks the close button

  • childOfMainWindow = true, the widget or windows is a child of the main window without own symbol in the task bar

  • dockWidgetArea = ui.TOPDOCKWIDGETAREA, if the widget is derived from QDockWidget, the dock widget is docked at that location

  • buttonBarType = ui.BUTTONBAR_NO, if a dialog is created (if the plugin delivers a widget and no windows, dialog or dock widget), the dialog has no automatically generated OK, Cancel, … buttons

If you want to have other default parameters than these ones, call ‘createNewPluginWidget2’.

Parameters

widgetName : {str}

name of algorithm widget

mandparams, optparams : {arbitrary}

parameters to pass to the plugin. The parameters are parsed and unnamed parameters are used in their incoming order to fill first mandatory parameters and afterwards optional parameters. Parameters may be passed with name as well but after the first named parameter no more unnamed parameters are allowed.

Returns

instance of type ‘ui’. The type of the ui is mainly defined by the type of the widget. If it is derived from QMainWindow, a window is opened; if :

it is derived from QDockWidget a dock widget at the top dock widget area is created, in all other cases a dialog is created. :

Notes

Unlike it is the case at the creation of ui’s from ui files, you can not directly parameterize behaviours like the deleteOnClose flag. This can however be done using setAttribute.

static createNewPluginWidget2(widgetName [, paramsArgs, paramsDict, type = -1, dialogButtonBar, dialogButtons, childOfMainWindow, deleteOnClose, dockWidgetArea) → creates widget defined by any algorithm plugin and returns the instance of type ‘ui’
Parameters

widgetName : {str}

name of algorithm widget

paramsArgs : {tuple of arbitrary parameters}

see paramsDict

paramsDict : {dict of arbitrary parameters}

The widget creation method in the plugin can depend on several mandatory or optional parameters. For their initialization, the mandatory and optional parameters are considered to be stacked together. At first, the paramsArgs sequence is used to assign a certain number of parameters beginning at the mandatory ones. If all paramsArgs values are assigned, the keyword-based values in paramsDict are tried to be assigned to not yet used mandatory or optional parameters. All mandatory parameters must be given (use widgetHelp(widgetName) to obtain information about all required parameters.

type : {int}, optional

display type:

  • 255 (default) : type is derived from type of widget,

  • 0 (ui.TYPEDIALOG): ui-file is embedded in auto-created dialog (default),

  • 1 (ui.TYPEWINDOW): ui-file is handled as main window,

  • 2 (ui.TYPEDOCKWIDGET): ui-file is handled as dock-widget and appended to the main-window dock area

  • 3 (ui.TYPECENTRALWIDGET): ui-file must be a widget or mainWindow and is included in the central area of itom, above the command line

dialogButtonBar : {int}, optional

Only for type ui.TYPEDIALOG (0). Indicates whether buttons should automatically be added to the dialog:

  • 0 (ui.BUTTONBAR_NO): do not add any buttons (default)

  • 1 (ui.BUTTONBAR_HORIZONTAL): add horizontal button bar

  • 2 (ui.BUTTONBAR_VERTICAL): add vertical button bar

dialogButtons : {dict}, optional every dictionary-entry is one button. key is the role, value is the button text

childOfMainWindow : {bool}, optional

for type TYPEDIALOG and TYPEWINDOW only. Indicates whether window should be a child of itom main window (default: True)

deleteOnClose : {bool}, optional

Indicates whether window should be deleted if user closes it or if it is hidden (default: Hidden, False)

dockWidgetArea : {int}, optional

Only for type ui.TYPEDOCKWIDGET (2). Indicates the position where the dock widget should be placed:

  • 1 (ui.LEFTDOCKWIDGETAREA)

  • 2 (ui.RIGHTDOCKWIDGETAREA)

  • 4 (ui.TOPDOCKWIDGETAREA): default

  • 8 (ui.BOTTOMDOCKWIDGETAREA)

Returns

instance of type ‘ui’. The type of the ui is mainly defined by the type of the widget. If it is derived from QMainWindow, a window is opened; if :

it is derived from QDockWidget a dock widget at the top dock widget area is created, in all other cases a dialog is created. :

Notes

Unlike it is the case at the creation of ui’s from ui files, you can not directly parameterize behaviours like the deleteOnClose flag. This can however be done using setAttribute.

static getDouble(title, label, defaultValue[, min, max, decimals=3, parent]) → shows a dialog to get a double value from the user
Parameters

title : {str}

is the dialog title

label : {str}

is the label above the spin box

defaultValue : {double}, optional

is the default value in the spin box

min : {double}, optional

default = -2147483647.0 is the allowed minimal value

max : {double}, optional

default = 2147483647.0 is the allowed maximal value

decimals : {int}, optional

the maximum number of decimal places (default: 1)

parent : {uiItem or derived classes}, optional

is a parent dialog or window, this dialog becomes modal.

Returns

out : {tuple (double, bool)}

A tuple where the first value contains the current double value. The second value is True if the dialog has been accepted, else False.

See also

getInt, getText, getItem

static getExistingDirectory(caption, startDirectory[, options, parent]) → opens a dialog to choose an existing directory
Parameters

caption : {str}

is the caption of this dialog

startDirectory : {str}

is the start directory

options : {int}, optional

is an or-combination of the following options (see ‘QFileDialog::Option’):

  • 1: ShowDirsOnly [default]

  • 2: DontResolveSymlinks

  • … (for others see Qt-Help)

parent : {uiItem or derived classes}, optional

is a parent dialog or window, this dialog becomes modal.

Returns

out : {str, None}

The selected directory is returned as absolute path or None if the dialog has been rejected.

static getInt(title, label, defaultValue[, min, max, step=1, parent]) → shows a dialog to get an integer value from the user
Parameters

title : {str}

is the dialog title

label : {str}

is the label above the spinbox

defaultValue : {int}, optional

is the default value in the spinbox

min : {int}, optional

is the allowed minimal value (default: -2147483647)

max : {int}, optional

is the allowed maximal value (default: 2147483647)

step : {int}, optional

is the step size if user presses the up/down arrow (default: 1)

parent : {uiItem or derived classes}, optional

is a parent dialog or window, this dialog becomes modal.

Returns

out : {tuple (int, bool)}

A tuple where the first value contains the current integer value. The second value is True if the dialog has been accepted, else False.

static getItem(title, label, stringList[, currentIndex=0, editable=True, parent]) → shows a dialog to let the user select an item from a string list
Parameters

title : {str}

is the dialog title

label : {str}

is the label above the text box

stringList : {tuple or list}, optional

is a list or tuple of possible string values

currentIndex : {int}, optional

defines the preselected value index (default: 0)

editable : {bool}, optional

defines whether new entries can be added (True) or not (False, default)

parent : {uiItem or derived classes}, optional

is the parent dialog of the message box.

Returns

out : {tuple (str, bool)}

A tuple where the first value contains the current active or typed string value. The second value is True if the dialog has been accepted, else False.

See also

getInt, getDouble, getText

static getOpenFileName([caption, startDirectory, filters, selectedFilterIndex, options, parent]) → opens dialog for chosing an existing file.
Parameters

caption : {str}, optional

This is the optional title of the dialog, default: no title

startDirectory {str}, optional :

optional, if not indicated currentDirectory will be taken

filters : {str}, optional

default = 0 possible filter list, entries should be separated by ;; , e.g. ‘Images (.png *.jpg);;Text files (.txt)’

selectedFilterIndex : {int}, optional

is the index of filters which is set by default (0 is first entry)

options : {int}, optional

default = 0 or-combination of enum values QFileDialog::Options

parent : {uiItem or derived classes}, optional

is the parent widget of this dialog

Returns

out : {str, None}

filename as string or None if dialog has been aborted.

static getOpenFileNames([caption, startDirectory, filters, selectedFilterIndex, options, parent]) → opens dialog for chosing existing files.
Parameters

caption : {str}, optional

This is the optional title of the dialog, default: no title

startDirectory {str}, optional :

optional, if not indicated currentDirectory will be taken

filters : {str}, optional

default = 0 possible filter list, entries should be separated by ;; , e.g. ‘Images (.png *.jpg);;Text files (.txt)’ selectedFilterIndex : {int}, optional is the index of filters which is set by default (0 is first entry)

options : {int}, optional

default = 0 or-combination of enum values QFileDialog::Options

parent : {uiItem or derived classes}, optional

is the parent widget of this dialog

Returns

out : {strlist, None}

filenames as stringList or None if dialog has been aborted.

static getSaveFileName([caption, startDirectory, filters, selectedFilterIndex, options, parent]) → opens dialog for chosing a file to save.

This method creates a modal file dialog to let the user select a file name used for saving a file.

Parameters

caption : {str}, optional

This is the title of the dialog

startDirectory : {String}, optional

if not indicated, the current working directory will be taken

filters : {str}, optional

possible filter list, entries should be separated by ;; , e.g. ‘Images (.png *.jpg);;Text files (.txt)’

selectedFilterIndex : {int}, optional

default = 0 is the index of filters which is set by default (0 is first entry)

options : {int}, optional

default = 0 or-combination of enum values QFileDialog::Options

parent : {uiItem or derived classes}, optional

is the parent widget of this dialog

Returns

out : {str, None}

filename as string or None if dialog has been aborted.

See also

getOpenFileName

static getText(title, label, defaultString[, parent]) → opens a dialog in order to ask the user for a string
Parameters

title : {str}

is the dialog title

label : {str}

is the label above the text box

defaultString : {str}

is the default string in the text box

parent : {uiItem or derived classes}, optional

is the parent dialog of the message box.

Returns

out : {tuple (str, bool)}

A tuple where the first value contains the current string value. The second value is True if the dialog has been accepted, else False.

See also

getInt, getDouble, getItem

hide() → hides initialized user interface

See also

show

isVisible() → returns true if dialog is still visible
Returns

visibility : {bool}

True if user interface is visible, False if it is hidden

static msgCritical(title, text[, buttons, defaultButton, parent]) → opens a critical message box
Parameters

title : {str}

is the message box title

text : {str}

is the message text

buttons : {int}, optional

is an or-combination of ui.MsgBox[…]-constants indicating the buttons to display. Use | for the or-combination.

defaultButton : {int}, optional

is a value of ui.MsgBox[…] which indicates the default button

parent : {uiItem or derived classes}, optional

is the parent dialog of the message box.

static msgInformation(title, text[, buttons, defaultButton, parent]) → opens an information message box
Parameters

title : {str}

is the message box title

text : {str}

is the message text

buttons : {int}, optional

is an or-combination of ui.MsgBox[…]-constants indicating the buttons to display. Use | for the or-combination.

defaultButton : {int}, optional

is a value of ui.MsgBox[…] which indicates the default button

parent : {uiItem or derived classes}, optional

is the parent dialog of the message box.

static msgQuestion(title, text[, buttons, defaultButton, parent]) → opens a question message box
Parameters

title : {str}

is the message box title

text : {str}

is the message text

buttons : {int}, optional

is an or-combination of ui.MsgBox[…]-constants indicating the buttons to display. Use | for the or-combination.

defaultButton : {int}, optional

is a value of ui.MsgBox[…] which indicates the default button

parent : {uiItem or derived classes}, optional

is the parent dialog of the message box.

static msgWarning(title, text[, buttons, defaultButton, parent]) → opens a warning message box
Parameters

title : {str}

is the message box title

text : {str}

is the message text

buttons : {int}, optional

is an or-combination of ui.MsgBox[…]-constants indicating the buttons to display. Use | for the or-combination.

defaultButton : {int}, optional

is a value of ui.MsgBox[…] which indicates the default button

parent : {uiItem or derived classes}, optional

is the parent dialog of the message box.

show([modal=0]) → shows initialized UI-Dialog
Parameters

modal : {int}, optional

  • 0: non-modal (default)

  • 1: modal (python waits until dialog is hidden)

  • 2: modal (python returns immediately)

See also

hide