10.18. ui-elements (ui, uiItem)

10.18.1. uiItem-Class

class itom.uiItem(objectID, objName, widgetClassName, parentObj=None)
class itom.uiItem(parentObj, objName) uiItem

Base class that represents any widget or layout of an user interface.

This class represents any widget (graphical, interactive element like a button or checkbox) on a graphical user interface. An object 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 this object.

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 object 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 uiItem.info(). For more information about creating customized user interfaces, reference widgets and layouts etc, see the section Creating customized dialogs, windows and dock widgets.

Parameters
objectIDint

is the itom internal identifier number for the widget or layout to be wrapped.

objNamestr

is the objectName property of the wrapped widget or layout.

widgetClassNamestr

is the Qt class name of the wrapped widget or layout (see getClassName()).

parentObjuiItem

is the parent uiItem of this wrapped widget or layout.

Returns
uiItem

is the new uiItem object that wraps the indicated widget or layout.

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(publicSlotName, *args)

Calls any public slot or other accessible public method of the widget or layout, referenced by this uiItem.

This method calls a public or a ‘wrapped’ slot (see section Special (wrapped) slots) of the widget or layout, that is referenced by this uiItem.

If only one slot with the given publicSlotName is available, all arguments *args are tried to be cast to the requested types and the slot is called then. If the designated slot has multiple possible overloads, at first, it is intended to find the overload where all arguments can be strictly cast from Python types to the indicated C-types. If this fails, the next overload with a successful, non-strict conversion is chosen.

Information about all possible slots of this uiItem can be obtained by the official Qt help or the method uiItem.info().

Parameters
publicSlotNamestr

name of the public slot or a specially wrapped slot of the widget or layout.

*argsAny, optional

Variable length argument list, that is passed to the called slot. The type of each value must be convertible to the requested C++ based argument type of the slot (see section Supported data types).

See also

info
children(recursive=False) Dict[str, str]

Returns a dict with all child items of the referenced widget.

Each widget in an user interface can have multiple child items, like radio buttons within a group box or widgets within a layout. This method returns information about all child items of this uiItem. A dictionary is returned with key-value pairs, where the key is the objectName of the child item, and the value its Qt class name (see getClassName()).

Child items without valid objectName are not contained in the returned dict.

Parameters
recursivebool

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

Returns
dict

All child items of this item are returned.

connect(signalSignature, callableMethod, minRepeatInterval=0)

Connects a signal of this widget or layout with the given Python callback method.

The widget or layout class, referenced by an uiItem object, can emit different signals whenever a certain event occurs. See the official Qt help about a list of all possible signals or use the method info() to get a print-out of a list of possible signals. This method is used to connect a certain callable Python callback method or function to a specific signal. The callable function can be bounded as well as unbounded.

The connection is described by the string signature of the signal (hence the source of the connection). Such a signature is the name of the signal, followed by the types of its arguments (the original C++ types). An example is clicked(bool), emitted if a button has been clicked. This signal can be connected to a callback function with one argument, that will then contain the boolean click state of this signal. In case of a bounded method, the self argument must be given in any case.

If the signal should have further arguments with specific datatypes, they are transformed into corresponding Python data types. A table of supported conversions is given in section Supported data types. In general, a callableMethod must be a method or function with the same number of parameters than the signal has (besides the self argument).

If a signal is emitted very often, it can be necessary to limit the call of the callback function to a certain minimum time interval. This can be given by the minRepeatInterval parameter.

Parameters
signalSignaturestr

This must be the valid signature, known from the Qt-method connect (e.g. targetChanged(QVector<double>))

callableMethodcallable()

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

minRepeatIntervalint, 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.

Notes

The Python callback method can only be executed if Python is in an idle state. Else, the trigger is postponed to the next possible time. However, if you want for instance to have a button that interrupts a long Python operation, it is not possible to use this connect() method to bind the click signal of this button with any Python script interruption, since the callback method will only be called if the long operation has finished. For these cases it is recommenden to connect the triggering signal (e.g. clicked()) by the invokeKeyboardInterrupt() method.

disconnect(signalSignature, callableMethod)

Disconnects a connection which must have been established before with exactly the same parameters.

Parameters
signalSignaturestr

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

callableMethodcallable()

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

See also

connect, info
exists() bool

Returns True if the widget or layout still exists, otherwise False.

Returns
bool

True if the referenced widget or layout still exists, otherwise False.

getAttribute(attributeNumber) bool

Returns if a specific WidgetAttribute is set for the referenced widget.

Widgets have specific attributes that influence their behaviour. These attributes are contained in the Qt-enumeration Qt::WidgetAttribute. Use this method to query if the requested attributeNumber is set / enabled for the referenced widget.

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
attributeNumberint

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

Returns
bool

True if attribute is set (enabled), otherwise False.

See also

setAttribute
getChild(widgetName) uiItem

Returns the uiItem of the child widget with the given widgetName.

This call is equal to self.widgetName, where self is this uiItem.

Parameters
widgetNamestr

objectName of the requested child widget or layout.

Returns
itemuiItem

The reference to the searched sub-widget (or layout).

Raises
AttributeError

if no widget / layout with widgetName as objectName exists.

getClassName() str

Returns the Qt class name of this uiItem (widget or layout).

Every uiItem wraps a widget or layout of the user interface. This method returns the class name of this item, as it is given by the Qt framework.

New in itom 4.1.

Returns
classNamestr

The class name of this uiItem.

getLayout() Optional[uiItem]

Returns the uiItem of the layout item of this widget (or None).

Container widgets, like group boxes, tab widgets etc. as well as top level widgets of a custom user interface can have layouts, that are responsible to arrange possible child widgets.

If this uiItem has such a layout, its reference is returned as uiItem, too. Else None is returned.

Returns
layoutNone or uiItem

The reference to the searched layout, or None if no such a layout exists.

getProperty(propertyName) Union[Any, List[Any]]

nReturns the requested property or a list of values for a sequence of requested properties.

Use this method or the operator [] in order to get the value of one specific property of this widget or layout 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 list of same size is returned with the corresponding values.

Parameters
propertyNamestr or list of str or tuple of str

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

Returns
valueAny or list of Any

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

See also

setProperty
getPropertyInfo(propertyName=None) Union[dict, List[str]]

Returns a list of all available property names or a dict of meta information of one given propertyName.

if propertyName is None, a list of all property names is returned. Else, a Dict[str, Any] is returned with meta information about this property. The structure of this dictionary is as follows:

  • name: Name of the property (str).

  • valid: True if this property is valid (readable), otherwise False.

  • readable: True if this property is readable, otherwise False.

  • writable: True if this property can be set to another value, otherwise False.

  • resettable: True if this property can be reset to a default value; otherwise returns False.

  • final: True if this property is final and cannot be overwritten in derived classes, otherwise False.

  • constant: True if this property is constant, otherwise False.

Parameters
propertyNamestr, optional

The name of the property whose detailed information should be returned or None, if a list of all property names should be returned.

Returns
nameslist of str

A list of all available property names.

informationdict

The dictionary with meta information about this property (see above).

getWindowFlags() int

Gets the window flags of the referenced widget.

The returned flags value is an or-combination, hence bitmask, of enumeration values of the Qt enumeration Qt::WindowType.

Returns
flagsint

or-combination of Qt::WindowType describing the type and further hints of the referenced widget.

See also

setWindowFlags
info(verbose=0)

Prints information about properties, public accessible slots and signals of the wrapped widget.

Parameters
verboseint
  • 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 the immediate invokation of a Python interrupt signal.

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.

Parameters
signalSignaturestr

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

invokeProgressObserverCancellation(signalSignature, observer)

Connects the given signal to a slot immediately setting the cancellation flag of this object.

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

For more information about the class requestCancellation, see also this section: Interruptible filters and progress information.

Parameters
signalSignaturestr

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

observerprogressObserver

This must be a progressObserver object. The given signal is connected to the slot requestCancellation of this progressObserver.

setAttribute(attributeNumber, value)

Enables or disables the attribute of the referenced widget.

Widgets have specific attributes that influence their behaviour. These attributes are contained in the Qt-enumeration Qt::WidgetAttribute. Use this method to enable or disable the requested widget attribute, given by its attributeNumber.

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
attributeNumberint

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

valuebool

True if attribute should be enabled, else False.

See also

getAttribute
setProperty(propertyDict)

Each property in the propertyDict is set to the dictionaries value.

As an alternative, a single property can also be set using the operator [].

Parameters
propertyDictdict

Dictionary with properties (the keys are the property names) and the values that should be set.

See also

getProperty
setWindowFlags(flags)

Set the window flags of the referenced 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.

Please consider, that you have to set all values in flags, that should be active in the referenced widget. It is possible to get the current flags value of this widget using getWindowFlags`(), set or unset some enum values (bits) and set it again using this method.

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

Parameters
flagsint

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

See also

getWindowFlags

10.18.2. ui-Class

class itom.ui(filename, type=ui.TYPEDIALOG, dialogButtonBar=ui.BUTTONBAR_NO, dialogButtons={}, childOfMainWindow=True, deleteOnClose=False, dockWidgetArea=ui.TOPDOCKWIDGETAREA)

Bases: uiItem

Loads a user interface file (ui) and references this loaded interface by the new ui object.

If the ui file is created in the QtDesigner, you can choose from which base type you would like to create the user interface (e.g. from a dialog, a window or a widget). This together with the argument type will mainly define the kind of user interface that is actually displayed in itom.

If you want to add a customized user interface as toolbox or into the central part of the main window of itom, it is either recommended to design the interface from a widget or a main window. The latter has the advantage, that an individual menu or toolbar can be added.

If you want to create a standalone window, it is recommended to already design the user interface from a main window, such that menus, toolbars as well as access to the statusbar is possible (if desired).

For the creation of (modal) dialogs, where the user should configure settings or pass some inputs, it is recommended to either design the interface from a dialog on, or it is also possible to create a simple widget. In the latter case, itom will put this interface into a dialog (for type = ui.TYPEDIALOG) and add optional buttons (like the OK and Cancel button). These buttons are then already configured to work. If you design a dialog from a dialog as base element, you have to connect buttons for instance with the accept() or reject() slot of the dialog by hand.

For more information see also the section Creating customized dialogs, windows and dock widgets of the user documentation.

Parameters
filenamestr

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

typeint, optional

This type defines how the loaded user interface is displayed:

  • ui.TYPEDIALOG (0): The ui-file is the content of a dialog window or, if the file already defines a QDialog, this dialog is shown as it is. This is recommended for the creation of modal dialogs, like settings…

  • ui.TYPEWINDOW (1): The ui-file must be a QMainWindow or its outer widget is turned into a main window. This window is then shown. This is recommended for “standalone” windows, that should be able to be minimized, maximized, contain menus or toolbars etc.

  • ui.TYPEDOCKWIDGET (2): The loaded widget is the content of a dock widget (toolbox) and is added to the indicated dockWidgetArea of the main window of itom.

  • ui.TYPECENTRALWIDGET (3): The loaded ui-file must define a QWidget or QMainWindow and is then added to the central area of itom, above the command line. It is not allowed to choose this type if the user interface is created from a QDialog.

dialogButtonBarint, optional

This argument is only used if type == ui.TYPEDIALOG and defines if a button bar with buttons, given by dialogButtons should be automatically added to the dialog. If this is the case, the role of the buttons is considered, such that clicking the OK or Cancel button will automatically close the dialog and return the role to the show() method (if the dialog is displayed modal). Allowed values:

  • ui.BUTTONBAR_NO (0): do not add any button bar and buttons (default),

  • ui.BUTTONBAR_HORIZONTAL (1): add a horizontal button bar at the bottom,

  • ui.BUTTONBAR_VERTICAL (2): add vertical button bar on the right side.

dialogButtonsdict, optional

Only relevant if dialogButtonBar is not ui.BUTTONBAR_NO: This dictionary contains all buttons, that should be added to the button bar. For every entry, the key is the role name of the button (enum QDialogButtonBox::ButtonRole, e.g. ‘AcceptRole’, ‘RejectRole’, ‘ApplyRole’, ‘YesRole’, ‘NoRole’). The value is the text of the button.

childOfMainWindowbool, optional

For type ui.TYPEDIALOG and ui.TYPEWINDOW only: Indicates if the window should be a child of the itom main window. If False, this window has its own icon in the taskbar of the operating system.

deleteOnClosebool, optional

Indicates if the widget / window / dialog should be deleted if the user closes it or if it is hidden. If it is hidden, it can be shown again using show().

dockWidgetAreaint, 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

  • 8 : ui.BOTTOMDOCKWIDGETAREA

Returns
windowui

A ui object, that references the loaded ui-file.

static availableWidgets() List[str]

List of class names of all available widgets that can be directly loaded in an ui-file at runtime.

Returns
list of str

A list of the class names of all widgets, that can be directly loaded in an user interface at runtime. These widgets can be built-in widgets of Qt as well as additional widgets from designer plugins (like itom plots or other itom widgets.

static createNewPluginWidget(widgetName, *args, **kwds) ui

Loads a widget, defined in an itom algorithm plugin, and returns the ui object, that references this widget.

Itom algorithm plugins cannot only contain algorithms, callable by Python, but also methods, that return a customized user-interface, widget etc. Use this method to initialize such an user-interface and returns its corresponding ui object.

For a list of available widget methods, see widgetHelp(). 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 taskbar,

  • 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
widgetNamestr

Name of algorithm widget method.

*args

Further positional arguments, that are parsed and passed to the widget creation method. These arguments are used first to initialize all mandatory parameters, followed by the optional ones.

**kwds

Keyword-based arguments, that are parsed and passed together with the positional arguments to the widget creation method. If one argument is given by its keyword, no further positional arguments can follow. For this, the mandatory and optional parameters of the widget creation method can be considered to be in one list, where the optional parameters follow after the mandatory ones.

Returns
ui

ui object, that represents the loaded widget, dialog or window. 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 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 cannot directly parameterize behaviours like the deleteOnClose flag. This can however be done using setAttribute().

static createNewPluginWidget2(widgetName, paramsArgs=[], paramsDict={}, type=0xFF, dialogButtonBar=ui.BUTTONBAR_NO, dialogButtons={}, childOfMainWindow=True, deleteOnClose=False, dockWidgetArea=ui.TOPDOCKWIDGETAREA) ui

Loads a widget, defined in an itom algorithm plugin, and returns the ui object, that references this widget.

Itom algorithm plugins cannot only contain algorithms, callable by Python, but also methods, that return a customized user-interface, widget etc. Use this method to initialize such an user-interface and returns its corresponding ui object.

For a list of available widget methods, see widgetHelp().

Parameters
widgetNamestr

Name of algorithm widget method.

paramsArgstuple

See paramsDict.

paramsDictdict

The widget creation method in the algorithm plugin can depend on several mandatory and / 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 with 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 (see widgetHelp(widgetName) to obtain information about all required parameters.

typeint, optional

Desired type of the newly created widget (a widget can also be a standalone dialog, dockwidget or window):

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

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

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

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

    to the main-window dock area,

  • 3 (ui.TYPECENTRALWIDGET): the ui-file must be a widget or main window

    and is included in the central area of itom, above the command line.

dialogButtonBarint, optional

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

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

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

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

dialogButtonsdict, optional

Only relevant if dialogButtonBar is not ui.BUTTONBAR_NO: This dictionary contains all buttons, that should be added to the button bar. For every entry, the key is the role name of the button (enum QDialogButtonBox::ButtonRole, e.g. ‘AcceptRole’, ‘RejectRole’, ‘ApplyRole’, ‘YesRole’, ‘NoRole’). The value is the text of the button.

childOfMainWindowbool, optional

For type ui.TYPEDIALOG and ui.TYPEWINDOW only: Indicates if the window should be a child of the itom main window. If False, this window has its own icon in the taskbar of the operating system.

deleteOnClosebool, optional

Indicates if the widget / window / dialog should be deleted if the user closes it or if it is hidden. If it is hidden, it can be shown again using show().

dockWidgetAreaint, 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

  • 8 : ui.BOTTOMDOCKWIDGETAREA

Returns
ui

ui object, that represents the loaded widget, dialog or window. 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 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 cannot directly parameterize behaviours like the deleteOnClose flag. This can however be done using setAttribute().

static getDouble(title, label, defaultValue, min=- 2147483647.0, max=2147483647.0, decimals=1, parent=None) Tuple[float, bool]

Shows a dialog to get a float value from the user.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
titlestr

is the title of the dialog.

labelstr

is the label above the input box.

defaultValuefloat

is the default value in the input box.

minfloat, optional

is the allowed minimal value.

maxfloat, optional

is the allowed maximal value.

decimalsint, optional

the maximum number of decimal places.

parentuiItem, optional

the dialog is modal with respect to parent or with respect to the main window of itom, if None.

Returns
valuefloat

The entered float value.

successbool

True if the dialog has been accepted, otherwise False.

See also

getInt, getText, getItem
static getExistingDirectory(caption, startDirectory, options=0, parent=None) Optional[str]

Opens a dialog to choose an existing directory.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
captionstr

is the caption of this dialog.

startDirectorystr

is the start directory, visible in the dialog.

optionsint, optional

is a flag value (bitmask) of the following options (see QFileDialog::Option):

  • 1: ShowDirsOnly [default]

  • 2: DontResolveSymlinks

  • … (for others see Qt-Help)

parentuiItem, optional

If not None, the dialog will be shown modal to this parent window. Else, it is modal with respect to the main window of itom.

Returns
directoryNone or str

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

static getInt(title, label, defaultValue, min=- 2147483647, max=2147483647, step=1, parent=None) Tuple[int, bool]

Shows a dialog to get an integer value from the user.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
titlestr

is the title of the dialog.

labelstr

is the label above the input box.

defaultValueint

is the default value in the input box.

minint, optional

is the allowed minimal value.

maxint, optional

is the allowed maximal value.

stepint, optional

is the step size if user presses the up/down arrow.

parentuiItem, optional

the dialog is modal with respect to parent or with respect to the main window of itom, if None.

Returns
valueint

The entered integer value.

successbool

True if the dialog has been accepted, otherwise False.

static getItem(title, label, stringList, currentIndex=0, editable=False, parent=None) Tuple[str, bool]

Shows a dialog to let the user select an item from a string list.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
titlestr

is the title of the dialog.

labelstr

is the label above the text box.

stringListlist of str or tuple of str

is a list or tuple of possible string values.

currentIndexint, optional

defines the pre-selected value index from stringList.

editablebool, optional

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

parentuiItem, optional

the dialog is modal with respect to parent or with respect to the main window of itom, if None.

Returns
valuestr

The currently selected or entered string value.

successbool

True if the dialog has been accepted, otherwise False.

See also

getInt, getDouble, getText
static getOpenFileName(caption='', startDirectory='', filters='', selectedFilterIndex=0, options=0, parent=None) Optional[str]

Shows a dialog for chosing a file name. The selected file must exist.

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

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
captionstr, optional

This is the title of the dialog.

startDirectorystr, optional

The intial directory, shown in the dialog. If an empty string, the current working directory will be taken.

filtersstr, optional

Possible filter list or allowed file types / suffixes etc. The entries should be separated by ;;, for example Images (*.png *.jpg);;Text files (*.txt).

selectedFilterIndexint, optional

The index of the currently selected filter from filters.

optionsint, optional

This corresponds to the Qt flag QFileDialog::Options.

parentuiItem, optional

If not None, the dialog will be shown modal to this parent window. Else, it is modal with respect to the main window of itom.

Returns
selectedFileNameNone or str

The selected file path or None if the dialog has been aborted.

static getOpenFileNames(caption='', startDirectory='', filters='', selectedFilterIndex=0, options=0, parent=None) Optional[List[str]]

Shows a dialog for chosing one or multiple file names. The selected file(s) must exist.

This method creates a modal file dialog to let the user select one or multiple file names used for opening these files.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
captionstr, optional

This is the title of the dialog.

startDirectorystr, optional

The intial directory, shown in the dialog. If an empty string, the current working directory will be taken.

filtersstr, optional

Possible filter list or allowed file types / suffixes etc. The entries should be separated by ;;, for example Images (*.png *.jpg);;Text files (*.txt).

selectedFilterIndexint, optional

The index of the currently selected filter from filters.

optionsint, optional

This corresponds to the Qt flag QFileDialog::Options.

parentuiItem, optional

If not None, the dialog will be shown modal to this parent window. Else, it is modal with respect to the main window of itom.

Returns
selectedFileNamesNone or list of str

The selected file pathes or None if the dialog has been aborted.

static getSaveFileName(caption='', startDirectory='', filters='', selectedFilterIndex=0, options=0, parent=None) Optional[str]

Shows a dialog for chosing a file name. The selected file must not exist.

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

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
captionstr, optional

This is the title of the dialog.

startDirectorystr, optional

The intial directory, shown in the dialog. If an empty string, the current working directory will be taken.

filtersstr, optional

Possible filter list or allowed file types / suffixes etc. The entries should be separated by ;;, for example Images (*.png *.jpg);;Text files (*.txt).

selectedFilterIndexint, optional

The index of the currently selected filter from filters.

optionsint, optional

This corresponds to the Qt flag QFileDialog::Options.

parentuiItem, optional

If not None, the dialog will be shown modal to this parent window. Else, it is modal with respect to the main window of itom.

Returns
selectedFileNameNone or str

The selected file path or None if the dialog has been aborted.

See also

getOpenFileName
static getText(title, label, defaultString, parent=None) Tuple[str, bool]

Opens a dialog to ask the user for a string value.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
titlestr

is the title of the dialog.

labelstr

is the label above the text box.

defaultStringstr

is the default string in the text box.

parentuiItem, optional

the dialog is modal with respect to parent or with respect to the main window of itom, if None.

Returns
valuestr

The entered string value.

successbool

True if dialog has been accepted, otherwise False.

See also

getInt, getDouble, getItem
hide()

Hides the user interface reference by this ui object.

A hidden window or dialog can be shown again via the method show().

See also

show
isVisible() bool

Returns True if the referenced window or dialog is still visible.

Returns
visiblebool

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

static msgCritical(title, text, buttons=ui.MsgBoxOk, defaultButton=0, parent=None) Tuple[int, str]

Opens a critical message box.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
titlestr

is the title of the message box.

textstr

is the message text

buttonsint, optional

is a flag value (bitmask) of the constants ui.MsgBoxXYZ, where XYZ is a placeholder for different values. Each selected constant indicates the corresponding button to display (combine values be the | operator).

defaultButtonint, optional

is the button constant (see buttons, that should be set as default.

parentuiItem, optional

If not None, the dialog will be shown modal to this parent window. Else, it is modal with respect to the main window of itom.

Returns
buttonIDint

constant of the button that has been clicked to close the message box.

buttonTextstr

caption of the button that has been clicked to close the message box.

static msgInformation(title, text, buttons=ui.MsgBoxOk, defaultButton=0, parent=None) Tuple[int, str]

Opens an information message box.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
titlestr

is the title of the message box.

textstr

is the message text

buttonsint, optional

is a flag value (bitmask) of the constants ui.MsgBoxXYZ, where XYZ is a placeholder for different values. Each selected constant indicates the corresponding button to display (combine values be the | operator).

defaultButtonint, optional

is the button constant (see buttons, that should be set as default.

parentuiItem, optional

If not None, the dialog will be shown modal to this parent window. Else, it is modal with respect to the main window of itom.

Returns
buttonIDint

constant of the button that has been clicked to close the message box.

buttonTextstr

caption of the button that has been clicked to close the message box.

static msgQuestion(title, text, buttons=ui.MsgBoxOk, defaultButton=0, parent=None) Tuple[int, str]

Opens a question message box.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
titlestr

is the title of the message box.

textstr

is the message text

buttonsint, optional

is a flag value (bitmask) of the constants ui.MsgBoxXYZ, where XYZ is a placeholder for different values. Each selected constant indicates the corresponding button to display (combine values be the | operator).

defaultButtonint, optional

is the button constant (see buttons, that should be set as default.

parentuiItem, optional

If not None, the dialog will be shown modal to this parent window. Else, it is modal with respect to the main window of itom.

Returns
buttonIDint

constant of the button that has been clicked to close the message box.

buttonTextstr

caption of the button that has been clicked to close the message box.

static msgWarning(title, text, buttons=ui.MsgBoxOk, defaultButton=0, parent=None) Tuple[int, str]

Opens a warning message box.

For more information, see also the section Show messages, input boxes and default dialogs of the documentation.

Parameters
titlestr

is the title of the message box.

textstr

is the message text

buttonsint, optional

is a flag value (bitmask) of the constants ui.MsgBoxXYZ, where XYZ is a placeholder for different values. Each selected constant indicates the corresponding button to display (combine values be the | operator).

defaultButtonint, optional

is the button constant (see buttons, that should be set as default.

parentuiItem, optional

If not None, the dialog will be shown modal to this parent window. Else, it is modal with respect to the main window of itom.

Returns
buttonIDint

constant of the button that has been clicked to close the message box.

buttonTextstr

caption of the button that has been clicked to close the message box.

show(modal=0) Optional[int]

Shows the window or dialog.

Parameters
modalint, optional
  • 0: non-modal, the opened GUI does not block other windows of itom (default)

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

  • 2: modal (python returns immediately)

Returns
None or int

Usually the value -1 is returned. Only if a dialog is shown with modal = 1, the exit code of the shown dialog is returned, once this dialog is closed again. This code is: 1 if the dialog has been accepted (e.g. by closing it by an OK button or 0 if the dialog has been rejected (Cancel button or directly closing the dialog via the close icon in its title bar.

See also

hide
BOTTOMDOCKWIDGETAREA = 8
BUTTONBAR_HORIZONTAL = 1
BUTTONBAR_NO = 0
BUTTONBAR_VERTICAL = 2
LEFTDOCKWIDGETAREA = 1
MsgBoxAbort = 262144
MsgBoxApply = 33554432
MsgBoxCancel = 4194304
MsgBoxClose = 2097152
MsgBoxDiscard = 8388608
MsgBoxFirstButton = 1024
MsgBoxHelp = 16777216
MsgBoxIgnore = 1048576
MsgBoxLastButton = 134217728
MsgBoxNo = 65536
MsgBoxNoButton = 0
MsgBoxNoToAll = 131072
MsgBoxOk = 1024
MsgBoxOpen = 8192
MsgBoxReset = 67108864
MsgBoxRestoreDefaults = 134217728
MsgBoxRetry = 524288
MsgBoxSave = 2048
MsgBoxSaveAll = 4096
MsgBoxYes = 16384
MsgBoxYesToAll = 32768
RIGHTDOCKWIDGETAREA = 2
TOPDOCKWIDGETAREA = 4
TYPECENTRALWIDGET = 3
TYPEDIALOG = 0
TYPEDOCKWIDGET = 2
TYPEWINDOW = 1