### Navigation

- index
- modules |
- next |
- previous |
- pyFormex v0.8.6 documentation >
- pyFormex reference manual >

# 14. `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.

  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.

  `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, *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 slected items. If single is True, only a single item can be selected.

  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, default, 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. default is the initial/default choice. If default is not in the choices list, it is prepended. If default is None, the first item of choices is taken as the default.

  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.

  `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.``InputRadio`(name, default, 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. default is the initial/default choice. If default is not in the choices list, it is prepended. If default 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, default=None, choices=[], direction='h', *args, **kargs)

  A pushbuttons InputItem.

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

  choices is a list/tuple of possible values. default is the initial/default choice. If default is not in the choices list, it is prepended. If default 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)

  An 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.``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 attirbutes 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.

  `setValue`(value)

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

  `setValue`(val)

    Change the widget’s value.

  `name`()

    Return the name of the InputItem.

  `value`()

    Return the widget’s value.

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.``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=[])

  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:

  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.

  `getResult`(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.``FileSelection`(path='.', pattern='*.*', exist=False, multi=False, dir=False)

  A file selection dialog.

  You can specify a default path/filename that will be suggested initially. If a pattern is specified, only matching files will be shown. A pattern can be something like `Images (*.png *.jpg)` or a list of such strings. Default mode is to accept any filename. You can specify exist=True to accept only existing files. Or set exist=True and multi=True to accept multiple files. If dir==True, a single existing directory is asked.

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

  `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.
  `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.``TableModel`(data, chead=None, rhead=None, edit=True)

  A table model that represent data as a two-dimensional array of items.

  data is 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]. Optional lists of column and row headers can be specified.

  `flags`(index)

    Return the TableModel flags.

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

  A TableModel specialized for represents 2D array data.

  - 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.
  `flags`(index)

    Return the TableModel flags.

class `widgets.``Table`(data, chead=None, rhead=None, label=None, edit=True, parent=None)

  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 ndarray instance, the Table will use an ArrayModel, else a TableModel. The difference is important when editing the table. Also, an ArrayModel has default row and column headers, while a TableModel doesn’t.
  - chead: an optional list of ncol column headers.
  - rhead: an optional list of nrow row headers.
  - label: currently unused (intended to display an optional label in the upper left corner if both chead and rhead are specified.

class `widgets.``Tabs`(items, parent=None)

  Present a list of widgets as a single tabbed widget.

  - items: a list of (header,widget) tuples.
  - caption:
  - parent:

class `widgets.``TableDialog`(data, chead=None, rhead=None, title=None, parent=None, actions=[('OK',)], default='OK')

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

  A convenience class representing a Table within a dialog.

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', None], 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=[], parent=None, stretch=[-1, -1])

  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.
  - parent: the parent dialog holding this button box. It should be specified if one of the buttons actions is widgets.ACCEPTED or widgets.REJECTED.
  `name`()

    Return the name of the InputItem.

  `text`()

    Return the displayed text of the InputItem.

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

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)

    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.``maxSize`()

  Return the maximum widget size.

  The maximum widget size is the (available) screen size. This may be smaller than the physical screen size (e.g. excluding 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.``compatInputItem`(name, value, itemtype=None, kargs={})

  A convenience function to create an InputItem dictionary

  This function accepts InputItem data in the old format:

      ( name, value, [ itemtype, [ optionsdict ] ] )

  and turns them into a dictionary as required by the new InputItem format.

`widgets.``convertInputItem`(data)

  Convert InputItem data to a proper dict.

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

  The conversion does the following:

  - if data is a dict, it is considered proper data and returned as is.
  - if data is a tuple or a list, first conversion with simpleInputItem is tried, then conversion with compatInputItem, using the data 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.``dialogButtons`(dialog, actions=None, default=None)

  Create a set of dialog buttons

  dia is a dialog widget

  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.

### Navigation

- index
- modules |
- next |
- previous |
- pyFormex v0.8.6 documentation >
- pyFormex reference manual >