ui-elements (ui, uiItem)¶
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[, argument1, argument2, ...]) → 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
arguments : {various types}, optional
Here you must indicate every argument, that the definition of the slot indicates. The type must be convertable into the requested C++ based argument type.
See also
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) → 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.
See also
-
disconnect
(signalSignature, callableMethod) → disconnects a connection which must have been established with exactly the same parameters.¶ Parameters: signalSignature : {str}
callableMethod : {python method or function}
Notes
doctodo
-
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
-
getProperty
(propertyName | listOfPropertyNames) -> 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 : {string, string-list}
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
-
getPropertyInfo
([propertyName]) → returns information about the property 'propertyName' of this widget or all properties, if no name indicated.¶ Parameters: propertyName : {tuple}, optional
-
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
-
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)’)
See also
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 raise the python interrupt signal if a specific signal is emitted, this interruption should be immediately invoked. Therefore
-
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
-
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
-
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.
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
-
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
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
createNewPluginWidget
(widgetName[, mandparams, optparams]) → creates widget defined by any algorithm plugin and returns the instance of type 'ui'¶ Parameters: widgetName : {}
name algorithm widget 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.
Notes
doctodo
-
static
getDouble
(title, label, defaultValue[, min, max, decimals=3]) → 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)
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.
-
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 : {ui}, 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.
See also
-
static
getInt
(title, label, defaultValue[, min, max, step=1]) → 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)
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]) → 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)
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.
-
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 : {ui}, optional
is the parent widget of this dialog
Returns: out : {str, None}
filename as string or None if dialog has been aborted.
See also
-
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 : {ui}, optional
is the parent widget of this dialog
Returns: out : {str, None}
filename as string or None if dialog has been aborted.
See also
-
static
getText
(title, label, defaultString) → 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
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.
-
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 : {ui}, optional
is the parent dialog of the message box.
See also
-
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 : {ui}, optional
is the parent dialog of the message box.
See also
-
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 : {ui}, optional
is the parent dialog of the message box.
See also
-
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 : {ui}, optional
is the parent dialog of the message box.
See also