Library of Common GUI Controls

gui is a library of functions which allow constructing a control (like check box, line edit or a combo), inserting it into the parent’s layout, setting tooltips, callbacks and so forth, establishing synchronization with a Python object’s attribute (including saving and retrieving when the widgets is closed and reopened) ... in a single call.

Almost all functions need three arguments:

  • the widget into which the control is inserted,
  • the master widget with one whose attributes the control’s value is synchronized,
  • the name of that attribute (value).

All other arguments should be given as keyword arguments for clarity and also for allowing the potential future compatibility-breaking changes in the module. Several arguments that are common to all functions must always be given as keyword arguments.

Common options

All controls accept the following arguments that can only be given as keyword arguments.

tooltip:A string for a tooltip that appears when mouse is over the control.
disabled:Tells whether the control be disabled upon the initialization.
addSpace:Gives the amount of space that is inserted after the control (or the box that encloses it). If True, a space of 8 pixels is inserted. Default is 0.
addToLayout:The control is added to the parent’s layout unless this flag is set to False.
stretch:The stretch factor for this widget, used when adding to the layout. Default is 0.
sizePolicy:The size policy for the box or the control.

Common Arguments

Many functions share common arguments.

widget:Widget on which control will be drawn.
master:Object which includes the attribute that is used to store the control’s value; most often the self of the widget into which the control is inserted.
value:String with the name of the master’s attribute that synchronizes with the the control’s value..
box:Indicates if there should be a box that around the control. If box is False (default), no box is drawn; if it is a string, it is also used as the label for the box’s name; if box is any other true value (such as True :), an unlabeled box is drawn.
callback:A function that is called when the state of the control is changed. This can be a single function or a list of functions that will be called in the given order. The callback function should not change the value of the controlled attribute (the one given as the value argument described above) to avoid a cycle (a workaround is shown in the description of listBox function.
label:A string that is displayed as control’s label.
labelWidth:The width of the label. This is useful for aligning the controls.
orientation:When the label is given used, this argument determines the relative placement of the label and the control. Label can be above the control, (“vertical” or True - this is the default) or in the same line with control, (“horizontal” or False). Orientation can also be an instance of QLayout.

Properties

PyQt support settings of properties using keyword arguments. Functions in this module mimic this functionality. For instance, calling

cb = gui.comboBox(..., editable=True)

has the same effect as

cb = gui.comboBox(...) cb.setEditable(True)

Any properties that have the corresponding setter in the underlying Qt control can be set by using keyword arguments.

Common Attributes

box:If the constructed widget is enclosed into a box, the attribute box refers to the box.

Widgets

This section describes the wrappers for controls like check boxes, buttons and similar. Using them is preferred over calling Qt directly, for convenience, readability, ease of porting to newer versions of Qt and, in particular, because they set up a lot of things that happen in behind.

Orange.widgets.gui.checkBox(widget, master, value, label, box=None, callback=None, getwidget=False, id_=None, labelWidth=None, disables=None, **misc)[source]

A simple checkbox.

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • master (OWWidget or OWComponent) – master widget
  • value (str) – the master’s attribute with which the value is synchronized
  • label (str) – label
  • box (int or str or None) – tells whether the widget has a border, and its label
  • callback (function) – a function that is called when the check box state is changed
  • getwidget (bool) – If set True, the callback function will get a keyword argument widget referencing the check box
  • id (any) – If present, the callback function will get a keyword argument id with this value
  • labelWidth (int) – the width of the label
  • disables (list or QWidget or None) – a list of widgets that are disabled if the check box is unchecked
Returns:

constructed check box; if is is placed within a box, the box is return in the attribute box

Return type:

QCheckBox

Orange.widgets.gui.lineEdit(widget, master, value, label=None, labelWidth=None, orientation=2, box=None, callback=None, valueType=<class 'str'>, validator=None, controlWidth=None, callbackOnType=False, focusInCallback=None, **misc)[source]

Insert a line edit.

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • master (OWWidget or OWComponent) – master widget
  • value (str) – the master’s attribute with which the value is synchronized
  • label (str) – label
  • labelWidth (int) – the width of the label
  • orientation (Qt.Vertical (default) or Qt.Horizontal) – tells whether to put the label above or to the left
  • box (int or str or None) – tells whether the widget has a border, and its label
  • callback (function) – a function that is called when the check box state is changed
  • valueType (type) – the type into which the entered string is converted when synchronizing to value
  • validator (QValidator) – the validator for the input
  • controlWidth (int) – the width of the line edit
  • callbackOnType (bool) – if set to True, the callback is called at each key press (default: False)
  • focusInCallback (function) – a function that is called when the line edit receives focus
Return type:

QLineEdit or a box

Orange.widgets.gui.listBox(widget, master, value=None, labels=None, box=None, callback=None, selectionMode=1, enableDragDrop=False, dragDropCallback=None, dataValidityCallback=None, sizeHint=None, **misc)[source]

Insert a list box.

The value with which the box’s value synchronizes (master.<value>) is a list of indices of selected items.

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • master (OWWidget or OWComponent) – master widget
  • value (str) – the name of the master’s attribute with which the value is synchronized (list of ints - indices of selected items)
  • labels (str) – the name of the master’s attribute with the list of items (as strings or tuples with icon and string)
  • box (int or str or None) – tells whether the widget has a border, and its label
  • callback (function) – a function that is called when the selection state is changed
  • selectionMode (QAbstractItemView.SelectionMode) – selection mode - single, multiple etc
  • enableDragDrop (bool) – flag telling whether drag and drop is available
  • dragDropCallback (function) – callback function on drop event
  • dataValidityCallback (function) – function that check the validity on enter and move event; it should return either ev.accept() or ev.ignore().
  • sizeHint (QSize) – size hint
Return type:

OrangeListBox

Orange.widgets.gui.comboBox(widget, master, value, box=None, label=None, labelWidth=None, orientation=2, items=(), callback=None, sendSelectedValue=False, valueType=<class 'str'>, emptyString=None, editable=False, contentsLength=None, maximumContentsLength=25, **misc)[source]

Construct a combo box.

The value attribute of the master contains either the index of the selected row (if sendSelected is left at default, False) or a value converted to valueType (str by default).

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • master (OWWidget or OWComponent) – master widget
  • value (str) – the master’s attribute with which the value is synchronized
  • box (int or str or None) – tells whether the widget has a border, and its label
  • orientation (Qt.Horizontal (default), Qt.Vertical or instance of QLayout) – tells whether to put the label above or to the left
  • label (str) – a label that is inserted into the box
  • labelWidth (int) – the width of the label
  • callback (function) – a function that is called when the value is changed
  • items (tuple of str or tuples) – items (optionally with data) that are put into the box
  • sendSelectedValue (bool) – flag telling whether to store/retrieve indices or string values from value
  • valueType (type) – the type into which the selected value is converted if sentSelectedValue is False
  • emptyString (str) – the string value in the combo box that gets stored as an empty string in value
  • editable (bool) – a flag telling whether the combo is editable
  • contentsLength (int) –

    Contents character length to use as a fixed size hint. When not None, equivalent to:

    combo.setSizeAdjustPolicy(
        QComboBox.AdjustToMinimumContentsLengthWithIcon)
    combo.setMinimumContentsLength(contentsLength)
    
  • maximumContentsLength (int) – Specifies the upper bound on the sizeHint and minimumSizeHint width specified in character length (default: 25, use 0 to disable)
Return type:

QComboBox

Orange.widgets.gui.radioButtonsInBox(widget, master, value, btnLabels=(), tooltips=None, box=None, label=None, orientation=2, callback=None, **misc)

Construct a button group and add radio buttons, if they are given. The value with which the buttons synchronize is the index of selected button.

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • master (OWWidget or OWComponent) – master widget
  • value (str) – the master’s attribute with which the value is synchronized
  • btnLabels (list of str or pixmaps) – a list of labels or icons for radio buttons
  • tooltips (list of str) – a list of tool tips of the same length as btnLabels
  • box (int or str or None) – tells whether the widget has a border, and its label
  • label (str) – a label that is inserted into the box
  • callback (function) – a function that is called when the selection is changed
  • orientation (Qt.Vertical (default), Qt.Horizontal or an instance of QLayout) – orientation of the box
Return type:

QButtonGroup

Orange.widgets.gui.appendRadioButton(group, label, insertInto=None, disabled=False, tooltip=None, sizePolicy=None, addToLayout=True, stretch=0, addSpace=False, id=None)[source]

Construct a radio button and add it to the group. The group must be constructed with radioButtons since it adds additional attributes need for the call backs.

The radio button is inserted into insertInto or, if omitted, into the button group. This is useful for more complex groups, like those that have radio buttons in several groups, divided by labels and inside indented boxes.

Parameters:
  • group (QButtonGroup) – the button group
  • label (str or QPixmap) – string label or a pixmap for the button
  • insertInto (QWidget) – the widget into which the radio button is inserted
Return type:

QRadioButton

Orange.widgets.gui.spin(widget, master, value, minv, maxv, step=1, box=None, label=None, labelWidth=None, orientation=1, callback=None, controlWidth=None, callbackOnReturn=False, checked=None, checkCallback=None, posttext=None, disabled=False, alignment=1, keyboardTracking=True, decimals=None, spinType=<class 'int'>, **misc)[source]

A spinbox with lots of bells and whistles, such as a checkbox and various callbacks. It constructs a control of type SpinBoxWFocusOut or DoubleSpinBoxWFocusOut.

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • master (OWWidget or OWComponent) – master widget
  • value (str) – the master’s attribute with which the value is synchronized
  • minv (int or float) – minimal value
  • maxv (int or float) – maximal value
  • step (int or float) – step (default: 1)
  • box (int or str or None) – tells whether the widget has a border, and its label
  • label (str) – label that is put in above or to the left of the spin box
  • labelWidth (int) – optional label width (default: None)
  • orientation (Qt.Horizontal (default), Qt.Vertical or instance of QLayout) – tells whether to put the label above or to the left
  • callback (function) – a function that is called when the value is entered; if callbackOnReturn is True, the function is called when the user commits the value by pressing Enter or clicking the icon
  • controlWidth (int) – the width of the spin box
  • callbackOnReturn (bool) – if True, the spin box has an associated icon that must be clicked to confirm the value (default: False)
  • checked (str) – if not None, a check box is put in front of the spin box; when unchecked, the spin box is disabled. Argument checked gives the name of the master’s attribute given whose value is synchronized with the check box’s state (default: None).
  • checkCallback (function) – a callback function that is called when the check box’s state is changed
  • posttext (str) – a text that is put to the right of the spin box
  • alignment (Qt.Alignment) – alignment of the spin box (e.g. Qt.AlignLeft)
  • keyboardTracking (bool) – If True, the valueChanged signal is emitted when the user is typing (default: True)
  • spinType (type) – determines whether to use QSpinBox (int) or QDoubleSpinBox (float)
  • decimals (int) – number of decimals (if spinType is float)
Returns:

Tuple (spin box, check box) if `checked is True, otherwise the spin box

Return type:

tuple or gui.SpinBoxWFocusOut

Orange.widgets.gui.doubleSpin(widget, master, value, minv, maxv, step=1, box=None, label=None, labelWidth=None, orientation=1, callback=None, controlWidth=None, callbackOnReturn=False, checked=None, checkCallback=None, posttext=None, alignment=1, keyboardTracking=True, decimals=None, **misc)[source]

Backward compatilibity function: calls spin with spinType=float.

Orange.widgets.gui.hSlider(widget, master, value, box=None, minValue=0, maxValue=10, step=1, callback=None, label=None, labelFormat=' %d', ticks=False, divideFactor=1.0, vertical=False, createLabel=True, width=None, intOnly=True, **misc)[source]

Construct a slider.

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • master (OWWidget or OWComponent) – master widget
  • value (str) – the master’s attribute with which the value is synchronized
  • box (int or str or None) – tells whether the widget has a border, and its label
  • label (str) – a label that is inserted into the box
  • callback (function) – a function that is called when the value is changed
  • minValue (int or float) – minimal value
  • maxValue (int or float) – maximal value
  • step (int or float) – step size
  • labelFormat (str) – the label format; default is ” %d”
  • ticks (bool) – if set to True, ticks are added below the slider
  • divideFactor (float) – a factor with which the displayed value is divided
  • vertical (bool) – if set to True, the slider is vertical
  • createLabel (bool) – unless set to False, labels for minimal, maximal and the current value are added to the widget
  • width (int) – the width of the slider
  • intOnly (bool) – if True, the slider value is integer (the slider is of type QSlider) otherwise it is float (FloatSlider, derived in turn from QSlider).
Return type:

QSlider or FloatSlider

Orange.widgets.gui.button(widget, master, label, callback=None, width=None, height=None, toggleButton=False, value='', default=False, autoDefault=True, buttonType=<class 'PyQt5.QtWidgets.QPushButton'>, **misc)[source]

Insert a button (QPushButton, by default)

Parameters:
  • widget (QWidget or None) – the widget into which the button is inserted
  • master (OWWidget or OWComponent) – master widget
  • label (str) – label
  • callback (function) – a function that is called when the button is pressed
  • width (int) – the width of the button
  • height (int) – the height of the button
  • toggleButton (bool) – if set to True, the button is checkable, but it is not synchronized with any attribute unless the value is given
  • value (str) – the master’s attribute with which the value is synchronized (the argument is optional; if present, it makes the button “checkable”, even if toggleButton is not set)
  • default (bool) – if True it makes the button the default button; this is the button that is activated when the user presses Enter unless some auto default button has current focus
  • autoDefault (bool) – all buttons are auto default: they are activated if they have focus (or are the next in the focus chain) when the user presses enter. By setting autoDefault to False, the button is not activated on pressing Return.
  • buttonType (QPushButton) – the button type (default: QPushButton)
Return type:

QPushButton

Orange.widgets.gui.toolButton(widget, master, label='', callback=None, width=None, height=None, tooltip=None)[source]

Insert a tool button. Calls button

Parameters:
  • widget (QWidget or None) – the widget into which the button is inserted
  • master (OWWidget or OWComponent) – master widget
  • label (str) – label
  • callback (function) – a function that is called when the button is pressed
  • width (int) – the width of the button
  • height (int) – the height of the button
Return type:

QToolButton

Orange.widgets.gui.widgetLabel(widget, label='', labelWidth=None, **misc)[source]

Construct a simple, constant label.

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • label (str) – The text of the label (default: None)
  • labelWidth (int) – The width of the label (default: None)
Returns:

Constructed label

Return type:

QLabel

Orange.widgets.gui.label(widget, master, label, labelWidth=None, box=None, orientation=2, **misc)[source]

Construct a label that contains references to the master widget’s attributes; when their values change, the label is updated.

Argument label is a format string following Python’s syntax (see the corresponding Python documentation): the label’s content is rendered as label % master.__dict__. For instance, if the label is given as “There are %(mm)i monkeys”, the value of master.mm (which must be an integer) will be inserted in place of %(mm)i.

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • master (OWWidget or OWComponent) – master widget
  • label (str) – The text of the label, including attribute names
  • labelWidth (int) – The width of the label (default: None)
  • orientation (Qt.Vertical (default), Qt.Horizontal or instance of QLayout) – layout of the inserted box
Returns:

label

Return type:

QLabel

Other widgets

Orange.widgets.gui.widgetBox(widget, box=None, orientation=2, margin=None, spacing=4, **misc)[source]

Construct a box with vertical or horizontal layout, and optionally, a border with an optional label.

If the widget has a frame, the space after the widget is added unless explicitly disabled.

Parameters:
  • widget (QWidget or None) – the widget into which the box is inserted
  • box (int or str or None) – tells whether the widget has a border, and its label
  • orientation (Qt.Horizontal, Qt.Vertical or instance of QLayout) – orientation of the box
  • sizePolicy (QSizePolicy) – The size policy for the widget (default: None)
  • margin (int) – The margin for the layout. Default is 7 if the widget has a border, and 0 if not.
  • spacing (int) – Spacing within the layout (default: 4)
Returns:

Constructed box

Return type:

QGroupBox or QWidget

Orange.widgets.gui.indentedBox(widget, sep=20, orientation=2, **misc)[source]

Creates an indented box. The function can also be used “on the fly”:

gui.checkBox(gui.indentedBox(box), self, "spam", "Enable spam")

To align the control with a check box, use checkButtonOffsetHint:

gui.hSlider(gui.indentedBox(self.interBox), self, "intervals")
Parameters:
  • widget (QWidget) – the widget into which the box is inserted
  • sep (int) – Indent size (default: 20)
  • orientation (Qt.Vertical (default), Qt.Horizontal or instance of QLayout) – orientation of the inserted box
Returns:

Constructed box

Return type:

QGroupBox or QWidget

Orange.widgets.gui.separator(widget, width=4, height=4)[source]

Add a separator of the given size into the widget.

Parameters:
  • widget (QWidget) – the widget into whose layout the separator is added
  • width (int) – width of the separator
  • height (int) – height of the separator
Returns:

separator

Return type:

QWidget

Orange.widgets.gui.rubber(widget)[source]

Insert a stretch 100 into the widget’s layout

Utility functions

Orange.widgets.gui.attributeIconDict = {}

A dict that returns icons for different attribute types. The dict is constructed on first use since icons cannot be created before initializing the application.

Accepted keys are variable type codes and instances of Orange.data.variable: attributeIconDict[var] will give the appropriate icon for variable var or a question mark if the type is not recognized

Orange.widgets.gui.attributeItem(var)[source]

Construct a pair (icon, name) for inserting a variable into a combo or list box

Parameters:var (Orange.data.Variable) – variable
Return type:tuple with QIcon and str

Internal functions and classes

This part of documentation describes some classes and functions that are used internally. The classes will likely maintain compatibility in the future, while the functions may be changed.

Wrappers for Qt classes

class Orange.widgets.gui.SpinBoxWFocusOut(minv, maxv, step, parent=None)[source]

A class derived from QSpinBox, which postpones the synchronization of the control’s value with the master’s attribute until the control looses focus or user presses Tab when the value has changed.

The class overloads onChange event handler to show the commit button, and onEnter to commit the change when enter is pressed.

class Orange.widgets.gui.DoubleSpinBoxWFocusOut(minv, maxv, step, parent)[source]

Same as SpinBoxWFocusOut, except that it is derived from QDoubleSpinBox

class Orange.widgets.gui.LineEditWFocusOut(parent, callback, focusInCallback=None)[source]

A class derived from QLineEdit, which postpones the synchronization of the control’s value with the master’s attribute until the user leaves the line edit or presses Tab when the value is changed.

The class also allows specifying a callback function for focus-in event.

callback

Callback that is called when the change is confirmed

focusInCallback

Callback that is called on the focus-in event

class Orange.widgets.gui.OrangeListBox(master, enableDragDrop=False, dragDropCallback=None, dataValidityCallback=None, sizeHint=None, *args)[source]

List box with drag and drop functionality. Function listBox constructs instances of this class; do not use the class directly.

master

The widget into which the listbox is inserted.

ogLabels

The name of the master’s attribute that holds the strings with items in the list box.

ogValue

The name of the master’s attribute that holds the indices of selected items.

enableDragDrop

A flag telling whether drag-and-drop is enabled.

dragDropCallback

A callback that is called at the end of drop event.

dataValidityCallback

A callback that is called on dragEnter and dragMove events and returns either ev.accept() or ev.ignore().

defaultSizeHint

The size returned by the sizeHint method.

Wrappers for Python classes

class Orange.widgets.gui.ControlledList(content, listBox=None)[source]

A class derived from a list that is connected to a QListBox: the list contains indices of items that are selected in the list box. Changing the list content changes the selection in the list box.

Other functions

Orange.widgets.gui.miscellanea(control, box, parent, addToLayout=True, stretch=0, sizePolicy=None, addSpace=False, disabled=False, tooltip=None, **kwargs)[source]

Helper function that sets various properties of the widget using a common set of arguments.

The function - sets the control‘s attribute box, if box is given and control.box is not yet set, - attaches a tool tip to the control if specified, - disables the control, if disabled is set to True, - adds the box to the parent‘s layout unless addToLayout is set to False; the stretch factor can be specified, - adds the control into the box’s layout if the box is given (regardless of addToLayout!) - sets the size policy for the box or the control, if the policy is given, - adds space in the parent‘s layout after the box if addSpace is set and addToLayout is not False.

If box is the same as parent it is set to None; this is convenient because of the way complex controls are inserted.

Unused keyword arguments are assumed to be properties; with this gui function mimic the behaviour of PyQt’s constructors. For instance, if gui.lineEdit is called with keyword argument sizePolicy=some_policy, miscallenea will call control.setSizePolicy(some_policy).

Parameters:
  • control (QWidget) – the control, e.g. a QCheckBox
  • box (QWidget or None) – the box into which the widget was inserted
  • parent (QWidget) – the parent into whose layout the box or the control will be inserted
  • addSpace (bool or int) – the amount of space to add after the widget
  • disabled (bool) – If set to True, the widget is initially disabled
  • addToLayout (bool) – If set to False the widget is not added to the layout
  • stretch (int) – the stretch factor for this widget, used when adding to the layout (default: 0)
  • tooltip (str or None) – tooltip that is attached to the widget
  • sizePolicy (QSizePolicy) – the size policy for the box or the control
Orange.widgets.gui.setLayout(widget, layout)[source]

Set the layout of the widget.

If layout is given as Qt.Vertical or Qt.Horizontal, the function sets the layout to QVBoxLayout or QVBoxLayout.

Parameters:
  • widget (QWidget) – the widget for which the layout is being set
  • layout (Qt.Horizontal, Qt.Vertical or instance of QLayout) – layout
Orange.widgets.gui._addSpace(widget, space)[source]

A helper function that adds space into the widget, if requested. The function is called by functions that have the addSpace argument.

Parameters:
  • widget (QWidget) – Widget into which to insert the space
  • space (bool or int) – Amount of space to insert. If False, the function does nothing. If the argument is an int, the specified space is inserted. Otherwise, the default space is inserted by calling a separator.
Orange.widgets.gui.createAttributePixmap(char, background=2, color=3)[source]

Create a QIcon with a given character. The icon is 13 pixels high and wide.

Parameters:
  • char (str) – The character that is printed in the icon
  • background (QColor) – the background color (default: black)
  • color (QColor) – the character color (default: white)
Return type:

QIcon