26. gui.widgets — A collection of custom widgets used in the pyFormex GUI

The widgets in this module were primarily created in function of the pyFormex GUI. The user can apply them to change the GUI or to add interactive widgets to his scripts. Of course he can also use all the Qt widgets directly.

26.1. Classes defined in module gui.widgets

class gui.widgets.InputItem(name, *args, **kargs)

A single input item.

This is the base class for widgets holding a single input item. A single input item is any item that is treated as a unit and refered to by a single name.

This base class is rarely used directly. Most of the components of an InputDialog are subclasses of hereof, each specialized in some form of input data or representation. There is e.g. an InputInteger class to input an integer number and an InputString for the input of a string. The base class groups the functionality that is common to the different input widgets.

The InputItem widget holds a horizontal layout box (QHBoxLayout) to group its its components. In most cases there are just two components: a label with the name of the field, and the actual input field. Other components, such as buttons or sliders, may be added. This is often done in subclasses.

The constructor has one required argument: name. Other (optional) positional parameters are passed to the QtWidgets.QWidget constructor. The remaining keyword parameters are options that somehow change the default behavior of the InputItem class.

Parameters:

• name: the name used to identify the item. It should be unique for all InputItems in the same InputDialog. It will be used as a key in the dictionary that returns all the input values in the dialog. It will also be used as the label to display in front of the input field, in case no text value was specified.
• text: if specified, this text will be displayed in the label in front of the input field. This allows for showing descriptive texts for the input fields in the dialog, while keeping short and simple names for the items in the programming. text can be set to an empty string to suppress the creation of a label in front of the input field. This is useful if the input field widget itself already provides a label (see e.g. InputBool). text can also be a QPixmap, allowing for icons to be used as labels.
• buttons: a list of (label,function) tuples. For each tuple a button will be added after the input field. The button displays the text and when pressed, the specified function will be executed. The function takes no arguments.
• data: any extra data that you want to be stored into the widget. These data are not displayed, but can be useful in the functioning of the widget.
• enabled: boolean. If False, the InputItem will not be enabled, meaning that the user can not enter any values there. Disabled fields are usually displayed in a greyed-out fashion.
• readonly: boolean. If True, the data are read-only and can not be changed by the user. Unlike disabled items, they are displayed in a normal fashion.
• tooltip: A descriptive text which is only shown when the user pauses the cursor for some time on the widget. It can be used to give more comprehensive explanation to first time users.
• spacer: string. Only the characters ‘l’, ‘r’ and ‘c’ are relevant. If the string contains an ‘l’, a spacer in inserted before the label. If the string contains an ‘r’, a spacer in inserted after the input field. If the string contains a ‘c’, a spacer in inserted between the label and the input filed.

Subclasses should have an __init__() method which first constructs a proper widget for the input field, and stores it in the attribute self.input. Then the baseclass should be properly initialized, passing any optional parameters:

self.input = SomeInputWidget()
InputItem.__init__(self,name,*args,**kargs)

Subclasses should also override the following default methods of the InputItem base class:

• text(): if the subclass calls the superclass __init__() method with a value text=''. This method should return the value of the displayed text.
• value(): if the value of the input field is not given by self.input.text(), i.e. in most cases. This method should return the value of the input field.
• setValue(val): always, unless the field is readonly. This method should change the value of the input widget to the specified value.

Subclasses are allowed to NOT have a self.input attribute, IFF they redefine both the value() and the setValue() methods.

Subclasses can set validators on the input, like:

self.input.setValidator(QtGui.QIntValidator(self.input))

Subclasses can define a show() method e.g. to select the data in the input field on display of the dialog.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputInfo(name, value, *args, **kargs)

An unchangeable input field with a label in front.

It is just like an InputString, but the text can not be edited. The value should be a simple string without newlines.

There are no specific options.

value()

Return the widget’s value.

class gui.widgets.InputLabel(name, value, *args, **kargs)

An unchangeable information field.

The value is displayed as a string, but may contain more complex texts.

By default, the text format will be guessed to be either plain text, ReStructuredText ot html. Specify plain=True to display in plain text.

setValue(val)

Change the widget’s value.

class gui.widgets.InputString(name, value, max=None, *args, **kargs)

A string input field with a label in front.

If the type of value is not a string, the input string will be eval’ed before returning.

Options:

• max: the maximum number of characters in the string.

show(*args)

Select all text on first display.

value()

Return the widget’s value.

class gui.widgets.InputText(name, value, *args, **kargs)

A scrollable text input field with a label in front.

By default, the text format will be guessed to be either plain text, ReStructuredText ot html.

Specify plain=True to display in plain text.

If the type of value is not a string, the input text will be eval’ed before returning.

show(*args)

Select all text on first display.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputBool(name, value, *args, **kargs)

A boolean input item.

Creates a new checkbox for the input of a boolean value.

Displays the name next to a checkbox, which will initially be set if value evaluates to True. (Does not use the label) The value is either True or False,depending on the setting of the checkbox.

Options:

• func: an optional function to be called whenever the value is changed. The function receives the input field as argument. With this argument, the fields attributes like name, value, text, can be retrieved.

text()

Return the displayed text.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputList(name, default=[], choices=[], sort=False, single=False, check=False, fast_sel=False, maxh=-1, *args, **kargs)

A list selection InputItem.

A list selection is a widget allowing the selection of zero, one or more items from a list.

choices is a list/tuple of possible values. default is the initial/default list of selected items. Values in default that are not in the choices list, are ignored. If default is None or an empty list, nothing is selected initially.

By default, the user can select multiple items and the return value is a list of all currently selected items. If single is True, only a single item can be selected.

If maxh==-1, the widget gets a fixed height to precisely take the number of items in the list. If maxh>=0, the widget will get scrollbars when the height is not sufficient to show all items. With maxh>0, the item will get the specified height (in pixels), while maxh==0 will try to give the widget the required height to show all items

If check is True, all items have a checkbox and only the checked items are returned. This option sets single==False.

setSelected(selected, flag=True)

Mark the specified items as selected or not.

setChecked(selected, flag=True)

Mark the specified items as checked or not.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

setAll()

Mark all items as selected/checked.

setNone()

Mark all items as not selected/checked.

class gui.widgets.InputCombo(name, value, choices=[], onselect=None, func=None, *args, **kargs)

A combobox InputItem.

A combobox is a widget allowing the selection of an item from a drop down list.

choices is a list/tuple of possible values. value is the initial/default choice. If value is not in the choices list, it is prepended.

The choices are presented to the user as a combobox, which will initially be set to the default value.

An optional onselect function may be specified, which will be called whenever the current selection changes. The function is passed the selected option string

value()

Return the widget’s value.

setValue(val)

Change the widget’s current value.

setChoices(choices)

Change the widget’s choices.

This also sets the current value to the first in the list.

class gui.widgets.InputRadio(name, value, choices=[], direction='h', *args, **kargs)

A radiobuttons InputItem.

Radio buttons are a set of buttons used to select a value from a list.

choices is a list/tuple of possible values. value is the initial/default choice. If value is not in the choices list, it is prepended. If value is None, the first item of choices is taken as the default.

The choices are presented to the user as a hbox with radio buttons, of which the default will initially be pressed. If direction == ‘v’, the options are in a vbox.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputPush(name, value=None, choices=[], direction='h', count=0, icon=None, iconsonly=False, func=None, *args, **kargs)

A pushbuttons InputItem.

Creates pushbuttons for the selection of a value from a list.

choices is a list/tuple of possible values. value is the initial/default choice. If value is not in the choices list, it is prepended. If value is None, the first item of choices is taken as the default.

The choices are presented to the user as a hbox with push buttons, of which the default will initially be selected. If direction == ‘v’, the options are in a vbox.

Extra parameters:

• func: the function to call when the button is clicked. The function receives the input field as argument. From this argument, the fields attributes like name, value, text, can be retrieved. The function should return the value to be set, or None if it is to be unchanged. If no function is specified, the value can not be changed.

setText(text, index=0)

Change the text on button index.

setIcon(icon, index=0)

Change the icon on button index.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

doFunc()

Set the value by calling the button’s func

class gui.widgets.InputInteger(name, value, *args, **kargs)

An integer input item.

Options:

• min, max: range of the scale (integer)

show()

Select all text on first display.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputFloat(name, value, *args, **kargs)

A float input item.

show()

Select all text on first display.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputTable(name, value, chead=None, rhead=None, celltype=None, rowtype=None, coltype=None, edit=True, resize=None, autowidth=True, *args, **kargs)

An input item for tabular data.

• value: a 2-D array of items, with nrow rows and ncol columns.

  If value is an numpy array, the Table will use the ArrayModel: editing the data will directly change the input data array; all items are of the same type; the size of the table can not be changed.

  Else a TableModel is used. Rows and columns can be added to or removed from the table. Item type can be set per row or per column or for the whole table.

• autowidth:

• additionally, all keyword parameters of the TableModel or ArrayModel may be passed

value()

Return the widget’s value.

class gui.widgets.InputSlider(name, value, *args, **kargs)

An integer input item using a slider.

Options:

• min, max: range of the scale (integer)
• ticks: step for the tick marks (default range length / 10)
• func: an optional function to be called whenever the value is changed. The function receives the input field as argument. With this argument, the fields attributes like name, value, text, can be retrieved.
• tracking: bool. If True (default), func is called repeatedly while the slider is being dragged. If False, func is only called when the user releases the slider.

class gui.widgets.InputFSlider(name, value, *args, **kargs)

A float input item using a slider.

Options:

• min, max: range of the scale (integer)
• scale: scale factor to compute the float value
• ticks: step for the tick marks (default range length / 10)
• func: an optional function to be called whenever the value is changed. The function receives the input field as argument. With this argument, the fields attributes like name, value, text, can be retrieved.
• tracking: bool. If True (default), func is called repeatedly while the slider is being dragged. If False, func is only called when the user releases the slider.

class gui.widgets.InputPoint(name, value, ndim=3, *args, **kargs)

A 2D/3D point/vector input item.

The default gives fields x, y and z. With ndim=2, only x and y.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputIVector(name, value, *args, **kargs)

A vector of int values.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputButton(name, value, *args, **kargs)

A button input item.

The button input field is a button displaying the current value. Clicking on the button executes a function responsible for changing the value.

Extra parameters:

• func: the function to call when the button is clicked. The function receives the input field as argument. From this argument, the fields attributes like name, value, text, can be retrieved. The function should return the value to be set, or None if it is to be unchanged. If no function is specified, the value can not be changed.

doFunc()

Set the value by calling the button’s func

class gui.widgets.InputColor(name, value, *args, **kargs)

A color input item. Creates a new color input field with a label in front.

The color input field is a button displaying the current color. Clicking on the button opens a color dialog, and the returned value is set in the button.

Options:

• func: an optional function to be called whenever the value is changed. The function receives the input field as argument. With this argument, the fields attributes like name, value, text, can be retrieved.

setValue(value)

Change the widget’s value.

class gui.widgets.InputFont(name, value, *args, **kargs)

An input item to select a font.

class gui.widgets.InputFilename(name, value, filter='*', exist=False, preview=None, **kargs)

A filename input item.

This is a button input field displaying a file name. Clicking on the button pops up a file dialog.

Extra parameters:

• filter: the filter for the filenames to accept. See askFilename.
• exist: boolean. Specifies whether the file should exist, or a new one can be created (default).
• preview: an ImageView widget, or another widget having a showImage method. This can be used with image files to show a preview of the selected file. In most cases the preview widget is inserted in a dialog directly below the InputFilename field.

changeFilename()

Pop up a FileDialog to change the filename

class gui.widgets.InputFile(name, value, pattern='*', exist=False, multi=False, dir=False, compr=False, *args, **kargs)

An input item to select a file.

The following arguments are passed to the FileDialog widget: value,pattern,exist,multi,dir,compr.

value()

Return the widget’s value.

setValue(value)

Change the widget’s value.

class gui.widgets.InputWidget(name, value, *args, **kargs)

An input item containing any other widget.

The widget should have:

• a results attribute that is set to a dict with the resulting input values when the widget’s acceptData() is called.
• an acceptData() method, that sets the widgets results dict.
• a setValue(dict) method that sets the widgets values to those specified in the dict.

The return value of this item is an OrderedDict.

text()

Return the displayed text.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputGroup(name, *args, **kargs)

A boxed group of InputItems.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class gui.widgets.InputHBox(name, hbox, *args, **kargs)

A column in a hbox input form.

class gui.widgets.InputTab(name, tab, *args, **kargs)

A tab page in an input form.

class gui.widgets.InputForm

An input form.

The input form is a layout box in which the items are layed out vertically. The layout can also contain any number of tab widgets in which items can be layed out using tab pages.

class gui.widgets.InputDialog(items, caption=None, parent=None, flags=None, actions=None, default=None, store=None, prefix='', autoprefix=False, flat=None, modal=None, enablers=[], scroll=False, buttonsattop=False, size=None, align_right=False)

A dialog widget to interactively set the value of one or more items.

Overview

The pyFormex user has full access to the Qt4 framework on which the GUI was built. Therefore he can built input dialogs as complex and powerful as he can imagine. However, directly dealing with the Qt4 libraries requires some skills and, for simple input widgets, more effort than needed.

The InputDialog class presents a unified system for quick and easy creation of common dialog types. The provided dialog can become quite sophisticated with tabbed pages, groupboxes and custom widgets. Both modal and modeless (non-modal) dialogs can be created.

Items

Each basic input item is a dictionary, where the fields have the following meaning:

• name: the name of the field,
• value: the initial or default value of the field,
• itemtype: the type of values the field can accept,
• options: a dict with options for the field.
• text: if specified, the text value will be displayed instead of the name. The name value will remain the key in the return dict. Use this field to display a more descriptive text for the user, while using a short name for handling the value in your script.
• buttons:
• tooltip:
• min:
• max:
• scale:
• func:

For convenience, simple items can also be specified as a tuple. A tuple (key,value) will be transformed to a dict {‘key’:key, ‘value’:value}.

Other arguments

• caption: the window title to be shown in the window decoration
• actions: a list of action buttons to be added at the bottom of the input form. By default, a Cancel and Ok button will be added, to either reject or accept the input values.
• default: the default action
• parent: the parent widget (by default, this is the pyFormex main window)
• autoprefix: if True, the names of items inside tabs and group boxes will get prefixed with the tab and group names, separated with a ‘/’.
• flat: if True, the results are returned in a single (flat) dictionary, with keys being the specified or autoprefixed ones. If False, the results will be structured: the value of a tab or a group is a dictionary with the results of its fields. The default value is equal to the value of autoprefix.
• flags:
• modal:
• enablers: a list of tuples (key,value,key1,…) where the first two items indicate the key and value of the enabler, and the next items are keys of fields that are enabled when the field key has the specified value. Currentley, key should be a field of type boolean, [radio], combo or group. Also, any input field should only have one enabler!

add_items(items, form, prefix='')

Add input items to form.

items is a list of input item data layout is the widget layout where the input widgets will be added

add_group(form, prefix, name, items, **extra)

Add a group of input items.

add_hbox(form, prefix, name, items, **extra)

Add a hbox of input items.

add_tab(form, prefix, name, items, **extra)

Add a Tab page of input items.

add_input(form, prefix, **item)

Add a single input item to the form.

timeout()

Hide the dialog and set the result code to TIMEOUT

timedOut()

Returns True if the result code was set to TIMEOUT

show(timeout=None, timeoutfunc=None, modal=False)

Show the dialog.

For a non-modal dialog, the user has to call this function to display the dialog. For a modal dialog, this is implicitely executed by getResults().

If a timeout is given, start the timeout timer.

acceptData(result=PySide2.QtWidgets.QDialog.DialogCode.Accepted)

Update the dialog’s return value from the field values.

This function is connected to the ‘accepted()’ signal. Modal dialogs should normally not need to call it. In non-modal dialogs however, you can call it to update the results without having to raise the accepted() signal (which would close the dialog).

updateData(d)

Update a dialog from the data in given dictionary.

d is a dictionary where the keys are field names in the dialog. The values will be set in the corresponding input items.

getResults(timeout=None)

Get the results from the input dialog.

This fuction is used to present a modal dialog to the user (i.e. a dialog that must be ended before the user can continue with the program. The dialog is shown and user interaction is processed. The user ends the interaction either by accepting the data (e.g. by pressing the OK button or the ENTER key) or by rejecting them (CANCEL button or ESC key). On accept, a dictionary with all the fields and their values is returned. On reject, an empty dictionary is returned.

If a timeout (in seconds) is given, a timer will be started and if no user input is detected during this period, the input dialog returns with the default values set. A value 0 will timeout immediately, a negative value will never timeout. The default is to use the global variable input_timeout.

The result() method can be used to find out how the dialog was ended. Its value will be one of ACCEPTED, REJECTED ot TIMEOUT.

class gui.widgets.ListWidget(maxh=0)

A customized QListWidget with ability to compute its required size.

class gui.widgets.TableModel(data, chead=None, rhead=None, celltype=None, rowtype=None, coltype=None, edit=True, resize=None)

A model representing a two-dimensional array of items.

• data: any tabular data organized in a fixed number of rows and colums. This means that an item at row i and column j can be addressed as data[i][j]. Thus it can be a list of lists, or a list of tuples or a 2D numpy array. The data will always be returned as a list of lists though. Unless otherwise specified by the use of a celltype, coltype or rowtype argument, all items are converted to strings and will be returned as strings. Item storage order is row by row.
• chead: optional list of (ncols) column headers
• rhead: optional list of (nrows) row headers
• celltype: callable: if specified, it is used to map all items. This is only used if neither rowtype nor coltype are specified. If unspecified, it will be set to ‘str’, unless data is a numpy array, in which case it will be set to the datatype of the array.
• rowtype: list of nrows callables: if specified, the items of each row are mapped by the corresponding callable. This overrides celltype and is only used if coltype ais not specified.
• coltype: list of ncols callables: if specified, the items of each column are mapped by the corresponding callable. This overrides celltype and rowtype.
• edit: bool: if True (default), the table is editable. Set to False to make the data readonly.
• resize: bool: if True, the table can be resized: rows and columns can be added or removed. If False, the size of the table can not be changed. The default value is equal to the value of edit. If coltype is specified, the number of columns can not be changed. If rowtype is specified, the number of rows can not be changed.

makeEditable(edit=True, resize=None)

Make the table editable or not.

• edit: bool: makes the items in the table editable or not.
• resize: bool: makes the table resizable or not. If unspecified, it is set equal to the edit.

rowCount(parent=None)

Return number of rows in the table

columnCount(parent=None)

Return number of columns in the table

data(index, role)

Return the data at the specified index

cellType(r, c)

Return the type of the item at the specified position

setCellData(r, c, value)

Set the value of an individual table element.

This changes the stored data, not the interface.

setData(index, value, role=PySide2.QtCore.Qt.ItemDataRole.EditRole)

Set the value of an individual table element.

headerData(col, orientation, role)

Return the header data for the sepcified row or column

insertRows(row=None, count=None)

Insert row(s) in table

removeRows(row=None, count=None)

Remove row(s) from table

flags(index)

Return the TableModel flags.

class gui.widgets.ArrayModel(data, chead=None, rhead=None, edit=True)

A model representing a two-dimensional numpy array.

• data: a numpy array with two dimensions.
• chead, rhead: column and row headers. The default will show column and row numbers.
• edit: if True (default), the data can be edited. Set to False to make the data readonly.

makeEditable(edit=True)

Make the table editable or not.

• edit: bool: makes the items in the table editable or not.

rowCount(parent=None)

Return number of rows in the table

columnCount(parent=None)

Return number of columns in the table

cellType(r, c)

Return the type of the item at the specified position

setData(index, value, role=PySide2.QtCore.Qt.ItemDataRole.EditRole)

Set the value of an individual table element.

headerData(col, orientation, role)

Return the header data for the sepcified row or column

flags(index)

Return the TableModel flags.

class gui.widgets.Table(data, chead=None, rhead=None, label=None, celltype=None, rowtype=None, coltype=None, edit=True, resize=None, parent=None, autowidth=True)

A widget to show/edit a two-dimensional array of items.

• data: a 2-D array of items, with nrow rows and ncol columns.

  If data is an numpy array, the Table will use the ArrayModel: editing the data will directly change the input data array; all items are of the same type; the size of the table can not be changed.

  Else a TableModel is used. Rows and columns can be added to or removed from the table. Item type can be set per row or per column or for the whole table.

• label: currently unused (intended to display an optional label in the upper left corner if both chead and rhead are specified.

• parent:

• autowidth:

• additionally, all other parameters for the initialization of the TableModel or ArrayModel may be passed

colWidths()

Return the width of the columns in the table

rowHeights()

Return the height of the rows in the table

update()

Update the table.

This method should be called to update the widget when the data of the table have changed. If autowidth is True, this will also adjust the column widths.

value()

Return the Table’s value.

class gui.widgets.FileDialog(path='.', pattern='*', exist=False, multi=False, dir=False, compr=False, button=None, sidebar=None, caption=None, native=False, **kargs)

A file selection dialog.

The FileDialog dialog is a special purpose complex dialog widget that allows to interactively select a file or directory from the file system, possibly even multiple files, create new files or directories.

Parameters:

• path: the path shown on initial display of the dialog. It should be an existing path in the file system. The default is ‘.’ for the current directory.

• pattern: a string or a list of strings: specifies one or more UNIX glob patterns, used to limit the set of displayed filenames to those matching the glob. Each string can contain multiple globs, and an explanation string can be place in front:

  'Image files (*.png *.jpg)'
  

  The pattern argument is passed to the utils.fileDescription() function, together with the compr argument, to generate the actual pattern set. This allows the creation of filters for common file types with a minimal input.

  If a list of multiple strings is given, a combo box will allow the user to select between one of them.

• exist: bool: if True, the filename must exist. The default will allow any new filename to be created.

• multi: bool: if True, multiple files can be selected. The default is to allow only a single file.

• dir: bool: if True, only directories can be selected. If dir evaluates to True, but is not the value True, either a directory or a filename can be selected.

• compr: bool: if True, compressed files of the specified type will be selectable as well. This is passed together with the pattern argument to the utils.fileDescription() to generate the actual patterns.

• button: string: the label to be displayed on the accept button. The default is set to ‘Save’ if new files are allowed or ‘Open’ if only existing files can be selected.

setFilters(patterns)

Set filter based on name patterns.

Parameters:patterns (list of str) – Each string has the format ‘DESCRIPTION (PATTERNS)’ where DESCRIPTION is a text describing the file type and PATTERNS is one or more filename matching patterns, separated by blanks.

See also

utils.fileDescriptions()

predefined patterns for most common file types.

value()

Return the selected value

getResults(timeout=None)

Ask the user to fill in the dialog.

Returns a dict. If the user accepts the results, the dict has a single entry with key ‘fn’ and the selected filename(s) as value. If the user hits CANCEL or ESC, an empty dict is returned.

getFilename(timeout=None)

Ask for filename(s) by user interaction.

Returns:Path | list of Paths | None – The filename(s) selected by the user if the user accepts the selection. Returns None if the user hits CANCEL or ESC.

class gui.widgets.GeometryFileDialog(path=None, pattern=None, exist=False, mode='binary', compression=4, access=None, default=None, convert=True, **kargs)

A file selection dialog specialized for opening pgf files.

getResults(timeout=None)

Ask the user to fill in the dialog.

Returns a Dict or dict. If the user accepts the results, a Dict with the following entries is returned: fn, acc, and optional mod, cpr, cvt If the user hits CANCEL or ESC, an empty dict is returned.

class gui.widgets.ProjectSelection(path=None, pattern=None, exist=False, compression=4, protocol=None, access=None, default=None, convert=True)

A file selection dialog specialized for opening projects.

getResults()

Ask the user to fill in the dialog.

Returns a dict. If the user accepts the results, the dict has a single entry with key ‘fn’ and the selected filename(s) as value. If the user hits CANCEL or ESC, an empty dict is returned.

class gui.widgets.SaveImageDialog(path=None, pattern=None, exist=False, multi=False)

A dialog for saving to an image file.

The dialog contains the normal file selection widget plus some extra fields to set the Save Image parameters:

• Grab Screen: If checked, the image will be cropped from the screen video buffers. This is implied by the ‘Whole Window’ and ‘Add Border’ options
• Whole Window: If checked, the whole pyFormex main window will be saved. If unchecked, only the current OpenGL viewport is saved.

getResults()

Ask the user to fill in the dialog.

Returns a dict. If the user accepts the results, the dict has a single entry with key ‘fn’ and the selected filename(s) as value. If the user hits CANCEL or ESC, an empty dict is returned.

class gui.widgets.ListSelection(choices, caption='ListSelection', default=[], single=False, check=False, sort=False, *args, **kargs)

A dialog for selecting one or more items from a list.

This is a convenient class which constructs an input dialog with a single input item: an InputList. It allows the user to select one or more items from a list. The constructor supports all arguments of the InputDialog and the InputList classes. The return value is the value of the InputList, not the result of the InputDialog.

setValue(selected)

Mark the specified items as selected.

value()

Return the selected items.

getResults()

Show the modal dialog and return the list of selected values.

If the user cancels the selection operation, the return value is None. Else, the result is always a list, possibly empty or with a single value.

class gui.widgets.GenericDialog(widgets, title=None, parent=None, actions=[('OK',)], default='OK')

A generic dialog widget.

The dialog is formed by a number of widgets stacked in a vertical box layout. At the bottom is a horizontal button box with possible actions.

• widgets: a list of widgets to include in the dialog
• title: the window title for the dialog
• parent: the parent widget. If None, it is set to pf.GUI.
• actions: the actions to include in the bottom button box. By default, an ‘OK’ button is displayed to close the dialog. Can be set to None to avoid creation of a button box.
• default: the default action, ‘OK’ by default.

class gui.widgets.MessageBox(text, format='', level='info', actions=['OK'], default=None, timeout=None, modal=None, parent=None, check=None)

A message box is a widget displaying a short text for the user.

The message box displays a text, an optional icon depending on the level and a number of push buttons.

• text: the text to be shown. This can be either plain text or html or reStructuredText.
• format: the text format: either ‘plain’, ‘html’ or ‘rest’. Any other value will try automatic recognition. Recognition of plain text and html is automatic. A text is autorecognized to be reStructuredText if its first line starts with ‘..’ and is followed by a blank line.
• level: defines the icon that will be shown together with the text. If one of ‘question’, ‘info’, ‘warning’ or ‘error’, a matching icon will be shown to hint the user about the type of message. Any other value will suppress the icon.
• actions: a list of strings. For each string a pushbutton will be created which can be used to exit the dialog and remove the message. By default there is a single button labeled ‘OK’.

When the MessageBox is displayed with the getResults() method, a modal dialog is created, i.e. the user will have to click a button or hit the ESC key before he can continue.

If you want a modeless dialog, allowing the user to continue while the message stays open, use the show() method to display it.

addCheck(text)

Add a check field at the bottom of the layout.

getResults()

Display the message box and wait for user to click a button.

This will show the message box as a modal dialog, so that the user has to click a button (or hit the ESC key) before he can continue. Returns the text of the button that was clicked or an empty string if ESC was hit.

class gui.widgets.TextBox(text, format=None, actions=[('OK',)], modal=None, parent=None, caption=None, mono=False, timeout=None, flags=None)

Display a text and wait for user response.

Possible choices are ‘OK’ and ‘CANCEL’. The function returns True if the OK button was clicked or ‘ENTER’ was pressed, False if the ‘CANCEL’ button was pressed or ESC was pressed.

class gui.widgets.ButtonBox(name='', actions=None, default=None, parent=None, spacer=False, stretch=[-1, -1], cmargin=(2, 2, 2, 2))

A box with action buttons.

• name: a label to be displayed in front of the button box. An empty string will suppress it.
• actions: a list of (button label, button function) tuples. The button function can be a normal callable function, or one of the values widgets.ACCEPTED or widgets.REJECTED. In the latter case, parent should be specified.
• default: name of the action to set as the default. If no default is given, it will be set to the LAST button.
• parent: the parent dialog holding this button box. It should be specified if one of the buttons actions is not specified or is widgets.ACCEPTED or widgets.REJECTED.

setText(text, index=0)

Change the text on button index.

setIcon(icon, index=0)

Change the icon on button index.

class gui.widgets.CoordsBox(ndim=3, readonly=False, *args)

A widget displaying the coordinates of a point.

getValues()

Return the current x,y,z values as a list of floats.

setValues(values)

Set the three values of the widget.

class gui.widgets.ImageView(image=None, maxheight=None, parent=None)

A widget displaying an image.

showImage(image, maxheight=None)

Show an image in the viewer.

image: either a filename or an existing QImage instance. If a filename, it should be an image file that can be read by the QImage constructor. Most image formats are understood by QImage. The variable gui.image.image_formats_qtr provides a list.

26.2. Functions defined in module gui.widgets

gui.widgets.pyformexIcon(icon)

Create a pyFormex icon.

Returns a QIcon with an image taken from the pyFormex icons directory. icon is the basename of the image file (.xpm or .png).

gui.widgets.objSize(object)

Return the width and height of an object.

Returns a tuple w,h for any object that has width and height methods.

gui.widgets.maxWinSize()

Return the maximum widget size.

The maximum widget size is the maximum size for a window on the screen. The available size may be smaller than the physical screen size (e.g. it may exclude the space for docking panels).

gui.widgets.addTimeOut(widget, timeout=None, timeoutfunc=None)

Add a timeout to a widget.

This enables calling a function or a widget method after a specified time has elapsed.

Parameters:

• widget (QWidget) – The widget to set the timeout function for.
• timeoutfunc (callable, optional) – Function to be called after the widget times out. If None, and the widget has a timeout method, that will be used.
• timeout (float, optional) – The time in seconds to wait before calling the timeout function. If None, it will be set to to the global widgets.input_timeout.

Notes

If timeout is positive, a timer is installed into the widget which will call the timeoutfunc after timeout seconds have elapsed. The timeoutfunc can be any callable, but usually will emit a signal to make the widget accept or reject the input. The timeoutfunc will not be called if the widget is destructed before the timer has finished.

gui.widgets.defaultItemType(item)

Guess the InputItem type from the value

gui.widgets.simpleInputItem(name, value=None, itemtype=None, **kargs)

A convenience function to create an InputItem dictionary

gui.widgets.groupInputItem(name, items=[], **kargs)

A convenience function to create an InputItem dictionary

gui.widgets.hboxInputItem(name, items=[], **kargs)

A convenience function to create an InputItem dictionary

gui.widgets.tabInputItem(name, items=[], **kargs)

A convenience function to create an InputItem dictionary

gui.widgets.convertInputItem(item)

Convert InputItem item to a dict or a widget.

This function tries to convert some old style or sloppy InputItem item to a proper InputItem item dict.

The conversion does the following:

• if item is a dict, it is considered a proper item and returned as is.
• if item is a QWidget, it is also returned as is.
• if item is a tuple or a list, conversion with simpleInputItem is tried, using the item items as arguments.
• if neither succeeds, an error is raised.

gui.widgets.inputAny(name, value, itemtype, **options)

Create an InputItem of any type, depending on the arguments.

Arguments: only name, value and itemtype are required

• name: name of the item, also the key for the return value
• value: initial value,
• itemtype: one of the available itemtypes

gui.widgets.updateDialogItems(data, newdata)

Update the input data fields with new data values

• data: a list of dialog items, as required by an InputDialog.
• newdata: a dictionary with new values for (some of) the items.

The data items with a name occurring as a key in newdata will have their value replaced with the corresponding value in newdata, unless this value is None.

The user should make sure to set only values of the proper type!

gui.widgets.fileUrls(files)

Transform a list of local file names to urls

gui.widgets.selectFont()

Ask the user to select a font.

A font selection dialog widget is displayed and the user is requested to select a font. Returns a font if the user exited the dialog with the OK button. Returns None if the user clicked CANCEL.

gui.widgets.getColor(col=None, caption=None)

Create a color selection dialog and return the selected color.

col is the initial selection. If a valid color is selected, its string name is returned, usually as a hex #RRGGBB string. If the dialog is canceled, None is returned.

gui.widgets.updateText(widget, text, format='')

Update the text of a text display widget.

• widget: a widget that has the setText(), setPlainText() and setHtml() methods to set the widget’s text. Examples are QMessageBox and QTextEdit.
• text: a multiline string with the text to be displayed.
• format: the format of the text. If empty, autorecognition will be tried. Currently available formats are: plain, html and rest (reStructuredText).

This function allows to display other text formats besides the plain text and html supported by the widget. Any format other than plain or html will be converted to one of these before sending it to the widget. Currently, we convert the following formats:

• rest (reStructuredText): If the :mod:docutils is available, rest text is converted to html, otherwise it will be displayed as plain text. A text is autorecognized as reStructuredText if its first line starts with ‘..’. Note: If you add a ‘..’ line to your text to have it autorecognized as reST, be sure to have it followed with a blank line, or your first paragraph could be turned into comments.

gui.widgets.addActionButtons(layout, actions=[('Cancel',), ('OK',)], default=None, parent=None)

Add a set of action buttons to a layout

layout is a QLayout

actions is a list of tuples (name,) or (name,function). If a function is specified, it will be executed on pressing the button. If no function is specified, and name is one of ‘ok’ or ‘cancel’ (case is ignored), the button will be bound to the dialog’s ‘accept’ or ‘reject’ slot. If actions is None (default), it will be set to the default [('Cancel',),('OK',)].

default is the name of the action to set as the default. If no default is given, it is set to the LAST button.

Returns a list of QPushButtons.

gui.widgets.setCustomColors(col)

Set QColorDialog Custom colors.

col is a list of max. 16 color values (any values accepted by colors.RGBcolor