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 possible to call a public slot of the corresponding widget, connect signals to specific python methods or functions or change properties of the widget represented 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.

See also

disconnect, info, invokeKeyboardInterrupt

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() → uiItem | None#

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) → 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) → 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 invocation 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)’)

See also

connect, invokeProgressObserverCancellation

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.

See also

connect, invokeKeyboardInterrupt

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.

See also

createNewPluginWidget2, widgetHelp

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.

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

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.

See also

createNewPluginWidget, widgetHelp

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) → str | None#

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.

See also

getSaveFileName, getOpenFileName

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.

See also

getDouble, getText, getItem

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) → str | None#

Shows a dialog for choosing 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 initial 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

getOpenFileNames, getSaveFileName

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

Shows a dialog for choosing 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 initial 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 paths or None if the dialog has been aborted.

See also

getOpenFileName, getSaveFileName

static getSaveFileName(caption='', startDirectory='', filters='', selectedFilterIndex=0, options=0, parent=None) → str | None#

Shows a dialog for choosing 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 initial 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.

See also

msgWarning, msgQuestion, msgInformation

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.

See also

msgCritical, msgQuestion, msgWarning

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.

See also

msgCritical, msgWarning, msgInformation

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.

See also

msgCritical, msgQuestion, msgInformation

show(modal=0) → int | None#

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#