18. 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.

Classes defined in module widgets

class 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 QtGui.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 QtGui.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 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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

setValue(val)

Change the widget’s value.

class 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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

value()

Return the widget’s value.

class 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()

Select all text on first display.

value()

Return the widget’s value.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

setValue(val)

Change the widget’s value.

class 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()

Select all text on first display.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

class 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.

name()

Return the name of the InputItem.

class 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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

class 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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

class 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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

class widgets.InputPush(name, value=None, choices=[], direction='h', icon=None, iconsonly=False, *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 radio buttons, of which the default will initially be selected. If direction == ‘v’, the options are in a vbox.

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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

class 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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

class 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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

class 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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

setValue(val)

Change the widget’s value.

class 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 takes a float/integer argument.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

show()

Select all text on first display.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class 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.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

show()

Select all text on first display.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

class widgets.InputPoint(name, value, *args, **kargs)

A 3D point/vector input item.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

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

A vector of int values.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

class 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 current input value is passed as an argument. 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.

value()

Return the widget’s value.

doFunc()

Set the value by calling the button’s func

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

setValue(val)

Change the widget’s value.

class 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.

value()

Return the widget’s value.

setValue(value)

Change the widget’s value.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

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

An input item to select a font.

value()

Return the widget’s value.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

setValue(val)

Change the widget’s value.

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

An input item to select a file.

The following arguments are passed to the FileSelection widget: path,pattern,exist,multi,dir.

value()

Return the widget’s value.

name()

Return the name of the InputItem.

text()

Return the displayed text of the InputItem.

class 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 ODict.

text()

Return the displayed text.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

name()

Return the name of the InputItem.

class 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 widgets.ScrollForm

An scrolling 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 widgets.InputGroup(name, *args, **kargs)

A boxed group of InputItems.

value()

Return the widget’s value.

setValue(val)

Change the widget’s value.

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

A tab page in an input form.

class 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, 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_tab(form, prefix, name, items, **extra)

Add a Tab page of input items.

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

Add a group 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 getResult().

If a timeout is given, start the timeout timer.

acceptData(result=1)

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 widgets.ListWidget(maxh=0)

A customized QListWidget with ability to compute its required size.

class 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=2)

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 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=2)

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 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 widgets.FileSelection(path='.', pattern='*', exist=False, multi=False, dir=False, button=None, **kargs)

A file selection dialog.

The FileSelection 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 function utils.fileDescription() can be used to create some strings for common classes of files.

  As a convenience, if a string starts with a ‘.’, the remainder of the string will be used as a lookup key in utils.fileDescription to get the actual string to be used. Thus, pattern=’.png’ will filter all ‘.png’ files, and pattern=’.img’ will filter all image files in any of the supported formats.

  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.

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

value()

Return the selected value

getFilename(timeout=None)

Ask for a filename by user interaction.

Return the filename selected by the user. If the user hits CANCEL or ESC, None is returned.

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

A file selection dialog specialized for opening projects.

value()

Return the selected value

getFilename(timeout=None)

Ask for a filename by user interaction.

Return the filename selected by the user. If the user hits CANCEL or ESC, None is returned.

class 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:

• Whole Window: If checked, the whole pyFormex main window will be saved. If unchecked, only the current OpenGL viewport is saved.
• Crop Root: If checked, the window will be cropped from the root window. This mode is required if you want to include the window decorations.

value()

Return the selected value

getFilename(timeout=None)

Ask for a filename by user interaction.

Return the filename selected by the user. If the user hits CANCEL or ESC, None is returned.

class 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.

getResult()

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.

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_tab(form, prefix, name, items, **extra)

Add a Tab page of input items.

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

Add a group 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 getResult().

If a timeout is given, start the timeout timer.

acceptData(result=1)

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 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 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 getResult() 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() mehod to display it.

addCheck(text)

Add a check field at the bottom of the layout.

getResult()

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 widgets.WarningBox

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 getResult() 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() mehod to display it.

class 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 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 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 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.

Functions defined in module widgets

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).

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.

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).

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

Add a timeout to a widget.

• timeoutfunc is a callable. If None it will be set to the widget’s timeout method if one exists.
• timeout is a float value. If None, it will be set to to the global input_timeout.

If timeout is positive, a timer will be 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 is if the widget is destructed before the timer has finished.

widgets.defaultItemType(item)

Guess the InputItem type from the value

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

A convenience function to create an InputItem dictionary

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

A convenience function to create an InputItem dictionary

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

A convenience function to create an InputItem dictionary

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.

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

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!

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.

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.

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.

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==None (default), it will be set to the default [('Cancel',),('OK',)].

Specify actions=[] if you want an empty dialogDuttons. 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 horizontal box layout with the buttons.