Guietta uses a grid layout (QGridLayout). Number of rows and columns is automatically calculated from the input. There is typically one widget per grid cell ( _ will result in an empty cell), but widgets may span multiple rows and/or columns as described below.


To create a layout, instantiate a guietta.Gui object and pass it a series of lists. Each list corresponds to a row of widgets. All lists must have the same length.

As a special case, if a list contains a single widget, the widget will be expanded to fill the whole row. This is useful for titles and horizontal separators.


Here is the complete widget set:

from guietta import Gui, B, E, L, HS, VS, HSeparator, VSeparator
from guietta import Yes, No, Ok, Cancel, Quit, _, ___, III

gui = Gui(

   [ '<center>A big GUI with all of Guietta''s widgets</center>'],
   [ HSeparator ],

  [ 'Label'    , 'imagelabel.jpeg' , L('another label')  , VS('slider1')],
  [  _         ,     ['button']    , B('another button') ,     III      ],
  [ '__edit__' ,  E('an edit box') , _                   ,   VSeparator ],
  [   Quit     ,        Ok         , Cancel              ,     III      ],
  [    Yes     ,        No         , _                   ,     III      ],
  [  HS('slider2'),    ___         , ___                 ,      _       ] )
Syntax Equivalent Qt widget Event name
_ nothing (empty layout cell) none
QLabel(‘text’) ‘text’
QLabel with QPixmap(‘image.jpg’) ‘image’
QPushButton(‘text’) ‘text’
QPushButton(QIcon(‘image.jpg’), ‘’) ‘image’
‘__name__’ QLineEdit(‘’), name set to ‘name’ ‘name’
E(‘text’) QLineEdit(‘text’) ‘text’
C(‘text’) QCheckBox(‘text’) ‘text’
R(‘text’) QRadioButton(‘text’) ‘text’
P(‘name’) QProgressBar() ‘name’
HS(‘name’) QSlider(Qt::Horizontal) ‘name’
VS(‘name’) QSlider(Qt::Horizontal) ‘name’
HSeparator Horizontal separator  
VSeparator Vertical separator  
M(‘name’) Matplotlib FigureCanvas*  
PG(‘name’) pyqtgraph PlotWidget*  
widget any valid QT widget none
(widget, ‘name’) any valid QT widget ‘name’
  • Matplotlib or pyqtraph will only be imported if the M() or PG() widgets are used. Matplotlib and pyqtgraph are not is not installed automatically together with guietta. If the M() widget is used, the user must install matplotlib manually, same for PG() and pyqtgraph.

Buttons support both images and texts at the same time:

Syntax Equivalent Qt widget Event name
[‘image.jpg’, ‘text’]
B(‘image.jpg’, ‘text’)
QPushButton() with image and text ‘text’


How to extend widgets over multiple rows and/or columns:

from guietta import Gui, HS, VS, _, ___, III

gui = Gui(

   [ 'Big label', ___ , ___ , 'xxx' , VS('s1') ],
   [    III     , III , III , 'xxx' ,   III    ],
   [    III     , III , III , 'xxx' ,   III    ],
   [     _      ,  _  ,  _  , 'xxx' ,   III    ],
   [  HS('s2')  , ___ , ___ ,  ___  ,    _     ])
Syntax Meaning
_ nothing (empty layout cell)
___ (three underscores) Horizontal widget span
III (three capital letters i) vertical widget span


  • all grid cells must contain either a widget, one of ___ or III, or _ if the cell is empty. Other values will cause a ValueError exception. Empty elements are not allowed by the Python list syntax and will cause a SyntaxError.
  • ___ can only be used to the right of a widget to extend it
  • III can only be used below a widget to extend it
  • ___ and III can be combined to form big rectangular widgets, with the widget to be extended in the top-left corner.


Signals can be connected with where each widget has:

Syntax Meaning
_ no connection
slot reference to Python callable, using the default widget signal (if pre-defined, otherwise ValueError)
(‘textEdited’, slot) tuple(signal name, Python callable)

Table of default signals:

Widget Signal
QPushButton clicked(bool)
QLineEdit returnPressed()
QCheckBox stateChanged(int)
QRadioButton toggled())
QAbstractSlider (QSlider, QDial, QScrollBar) QProgressBar valueChanged(int)
QListWidget currentTextChanged
QComboBox textActivated

Widgets not listed in this table must be connected using the tuple syntax.


Table of properties created for each widget type:

Widget Read property type Write property type
QLabel, QLineEdit str str
QAbstractButton (QPushButton, QCheckBox, QRadioButton) widget instance callable
QAbstractSlider (QSlider, QDial, QScrollBar) QProgressBar int int
QAbstractItemView (QListWidget) list of str list of str
QComboBox dict{str: any} dict{str: any}
Everything else widget instance raises an exception

Exception catching in slots

When a slot is called, they will be enclosed in a “try - except Exception” block. What happens in the except clause depends on the “exceptions” keyword parameter of the GUI constructor, which accepts the following enums:

Enum Exception handling
Exceptions.OFF nothing, exception is re-raised
Exceptions.POPUP (default) popup a QMessageBox.warning with the exception string
Exceptions.PRINT exception string printed on stdout
Exceptions.SILENT nothing, exception is “swallowed”

Gui class

class guietta.Gui(*lists, images_dir='.', create_properties=True, exceptions=<Exceptions.POPUP: 3>, persistence=1, title='')

Main GUI class.

The GUI is defined passing to the initializer a set of QT widgets organized in rows of equal length. All other methods that expect lists (like events() or names()) will expect a series of list with the same length.

Every widget will be added as an attribute to this instance, using the widget text as the attribute name (removing all special characters and only keeping letters, numbers and underscores.)


Make sure that any and all widgets have a property


Auto-connection decorator.

Analyzes a function and auto-connects the function as a slot for all widgets that are accessed in the function itself.


Closes the window


Defines the column stretches

Arguments are lists as in the initializer. Since typically all rows have the same stretch, it is allowed to define just one or only a few rows in this method.

Every element must be a number, that will be passed to the setColumnStretch() QT function, or _ if no particular stretch is desired.

enable_drag_and_drop(from_, to)

Enable drag and drop between the two widgets


Defines the GUI events.

Arguments are lists as in the initializer. It is allowed to define just one or only a few rows in this method, if for example the last rows do not contain widgets with associated events.

Every element is a tuple with:

(‘signal_name’, slot)

where ‘signal_name’ is the name of the QT signal to be connected, and slot is any Python callable. Use _ for widgets that do not need to be connected to a slot.

If just the default signal is wanted, ‘signal_name’ can be omitted and just the callable slot is required (without using a tuple).

Bound methods are called without arguments. Functions and unbound methods will get a single argument with a reference to this Gui instance.

execute_in_background(func, args=(), callback=None)

Executes func in a background thread and updates GUI with a callback.

When func is done, the callback is called in the GUI thread. The callback receives a reference to this Gui instance as the first argument, plus whatever was returned by func as additional arguments.

get(block=True, timeout=None)

Runs the GUI in queue mode

In queue mode, no callbacks are used. Instead, the user should call gui.get() in a loop to get the events and process them. The QT event loop will stop in between calls to gui.get(), so event processing should be quick.

Every time an event happens, get() will return a tuple:

name, event = gui.get()

where name is widget name that generated the event, and event is a namedtuple with members signal (the PyQT signal) and args which is a list of signal arguments, which may be empty for signals without arguments.

get() will return (None, None) after the gui is closed.


Returns the selected items in widget name. Raises TypeError if the widget does not support selection.


Add all widgets to obj.

Adds all this Gui’s widget to obj as new attributes. Typically used in classes as an alternative from deriving from Gui. Duplicate attributes will raise an AttributeError.


Returns the GUI layout, containing all the widgets


Overrides the default widget names.

Arguments are lists as in the initializer. It is allowed to define just one or only a few rows in this method, if for example the last rows do not contain widgets that must be renamed.

Every element is a string with the new name for the widget in that position. Use _ for widgets that do not need to be renamed.


Defines the row stretches

Arguments are lists as in the initializer. Since typically all rows have the same stretch, it is allowed to define just one or only a few rows in this method.

Every element in the lists must be a number, that will be passed to the setRowStretch() QT function, or _ if no particular stretch is desired.


Display the Gui and start the event loop.

This call is blocking and will return when the window is closed. Any user interaction must be done with callbacks.


Shows the GUI. This call is non-blocking


Sets the window title


Read-only property with the widgets dictionary


Returns the window containing the GUI (an instance of QWidget). If the window had not been built before, it will be now.