OWGUIEx: Library of Advanced GUI Controls

OWGUIEx library contains a set of more advanced GUI components. We didn't simply put them in the OWGUI module since these components typically take tens or hundreds of lines of code and are less frequently used in widgets.


Common Attributes

Since this file is basically an extension of the OWGUI library, many of the attributes that can be specified when constructing a control are described in the "Common attributes" section in the documentation on OWGUI. It is highly recomended that you are familiar with those attributes.

Controls

This section describes the OWGUI wrappers for controls that are defined in OWGUIEx.

Line Edit with Filter

A modification of the OWGUI.lineEdit control. It can be used to filter content of a list box based on the text in this control.

lineEditFilter(widget, master, value [, label, labelWidth, orientation, box, tooltip, valueType, validator, controlWidth, caseSensitive, useRE, matchAnywhere, callback, emptyText])

The meaning of attributes label, labelWidth, orientation, box, tooltip, valueType, validator and controlWidth are described in the OWGUI.lineEdit documentation.
caseSensitive (default: 1)
Determines whether the filtering of items in the list box will be case sensitive or not.
useRE (default: 0)
Determines whether use of regular expressions is allowed or not. If regular expressions are allowed then certain characters have different meaning, e.g. typing ".a" in the line edit will keep all those list box items that have letter a as the second character (no matter what the first character is).
matchAnywhere (default: 0)
Do we want to match only those list box items that start with the text in the line edit control or can the text appear anywhere in the item's text. matchAnywhere attribute is relevant only when we don't use regular expressions (useRe = 0).
callback (default: None)
The specified callback function will be called each time the line edit control is changed (edited).
emptyText (default: "")
When the text in the control will be empty and the control will be out of focus, the specified emptyText will be displayed in gray color. This attribute can be used to make it easier for the user to know what is the function of the control. For example, by setting emptyText="Filter attributes..." we can let user know that he can use the control to filter out the attributes.
Along with the described attributes there are also some important methods that can/have to be used:
setListBox(listbox)
Using this method we can specify which list box instance we would like to control using the line edit.
setAllListItems(items)
Using this method we tell the line edit control what is the complete (unfiltered) content of the list box. The list of items can be a list of strings or QListWidgetItem instances.
updateListBoxItems(callCallback=1)
We can call this function if we want manually to cause the update of the associated list box based on the content of the line edit. The value of callCallback argument determines whether we would like to call the callback function after this update or not.
Show Example Download example (gui_lineeditFilter.py)

In the following code we create a lineEditFilter and a list box component. We add to the list box 10.000 randomly generated strings of length 10 and also tell the line edit control that these are all of the items. By typing in the line edit we can then keep only those list box items that match the text.

self.filter = "" self.listboxValue = "" lineEdit = OWGUIEx.lineEditFilter(self.controlArea, self, "filter", "Filter:", useRE = 1, emptyText = "filter...") listbox = OWGUI.listBox(self.controlArea, self, "listboxValue") lineEdit.setListBox(listbox) names = [] for i in range(10000): names.append("".join([string.ascii_lowercase[random.randint(0, len(string.ascii_lowercase)-1)] for c in range(10)])) lineEdit.listbox.addItems(names) lineEdit.setAllListItems(names)

Line Edit with Hint

A modification of the OWGUI.lineEdit control. It helps the user to enter the text by showing a drop-down list of items that match the current text.

lineEditHint(widget, master, value [, label, labelWidth, orientation, box, tooltip, valueType, validator, controlWidth, caseSensitive, useRE, matchAnywhere, callback, listUpdateCallback, nrOfSuggestions, autoSizeListWidget, delimiters])

The meaning of attributes label, labelWidth, orientation, box, tooltip, valueType, validator and controlWidth are described in the OWGUI.lineEdit documentation.
caseSensitive (default: 1)
Determines whether the filtering of items in the list box will be case sensitive or not.
useRE (default: 0)
Determines whether use of regular expressions is allowed or not. If regular expressions are allowed then certain characters have different meaning, e.g. typing ".a" in the line edit will show in the suggestion-list all those items that have letter a as the second character (no matter what the first character is).
matchAnywhere (default: 0)
Do we want to match only those items that start with the text in the line edit control or can the text appear anywhere in the item's text. matchAnywhere attribute is relevant only when we don't use regular expressions (useRe = 0).
callback (default: None)
The specified callback function will be called each time some suggested item is selected.
listUpdateCallback (default: None)
The specified function will be called each time the list of suggested items is updated.
nrOfSuggestions (default: 10)
This attribute determines the height of the list of suggested items. By default, the height is determined so that the list will show maximum 10 items. If more items match the criteria, a vertical scrollbar will be shown.
autoSizeListWidget (default: 0)
If autoSizeListWidget is 1 then the width of the suggestions list will be adjusted automatically based on the width of the items in the list. The width of the list will be at least as wide as the line edit control.
delimiters (default: None)
Sometimes we would like to have more than one item in the line edit. To be able to show the suggestions when entering the second, third, ... item, we have to specify which characters are delimiters that separate items. For example, let's assume we would like to use the line edit to specify a list of our favourite colors, which are red, blue and yellow. If we'd like to get a list of suggestions when we start typing the second color name (blue) we have to set delimiters=', ' (notice that the string also contains SPACE besides the comma).
Along with the described attributes there is also an important methods that has to be used:
setItems(items)
Using this method we tell the line edit control what are the possible items that can be suggested when user is entering text. The list of items can be a list of strings or QListWidgetItem instances.
Show Example Download example (gui_lineeditHint.py)

In the following example we create a lineEditHint and set a short list of items. By typing in the line edit we can then keep only those list box items that match the text.

s = OWGUIEx.lineEditHint(self.controlArea, self, "text", useRE = 0, caseSensitive = 0, matchAnywhere = 0, delimiters = "., ") s.listWidget.setSpacing(2) items = ["janez", "joza", "danica", "jani", "jok", "jure"] s.setItems(items)