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.


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.


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.

Other widgets

Utility functions

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 Python classes

Other functions