6.1. Common to all kind of widgets

6.1.1. Widget Class Declaration

It is required that the widgets uses Signal, Slots and Properties as interface. GUIs should consider it their design the Qt event oriented paradigm. This paradigm is best suited when using Qt intended interfaces. This means:

Properties

Properties are members of a widget class definition that express a configuration. Later, when using the Qt Designer, properties are automatically displayed by the designer in the Property Editor tab.

Properties should use basic datatypes, such as int, unsigned int, float, bool, str.

A Property has normally a related signal that acts as a change notification, and a related slot that allows to set the property.

Signals

Signals are send by a widget when a property changes, or when an event of significance has happened, and the developer of the widget wants other GUI elements to react to this significant event.

Signals can be typeless, or can carry arguments. For example, when a QPushButton_ is `pushed`_, a typeless signals is send. When a QCheckBox_ has its stateChanged_, the signals carries the new state value.

Note

Signals require no implementation, only declaration.

Slots

Slots are normally a setter for a property, or allow to perform an action on the widget.

It is usefull to create Slots for Properties: then the developer may connect one signal that provides the value, and the slot that sets the value to the widget.

Tip

Declaring signals and slots is cheap and imposes no penalty in performance. Using connections in the same thread is a direct function call.

Warning

Connecting a signal to a slot in different threads is slow. Qt will by default create an event of with the arguments of the signal, and pass it to the appropiate Event Pump.

The definition of Properties in Python should be done as in this example:

#include <QWidget>

class AWidget : public QWidget
{
    Q_OBJECT

    /**
     * @brief Altitude coordinate of the current position in radians.
     * @accessors getCurrentAlt(), setCurrentAlt(double)
     */
    Q_PROPERTY(double currentAlt MEMBER m_currentAlt READ getCurrentAlt WRITE setCurrentAlt NOTIFY currentAltChanged )

public :
    AWidget(QWidget* parent = Q_NULLPTR): QWidget(parent){
    }
    double getCurrentAlt(){
        return this->m_currentAlt;
    };

public slots:
    double setCurrentAlt(double newValue){
        if( this->m_currentAlt != newValue ){
            this->m_currentAlt = newValue;
            emit currentAltChanged(this->m_currentAlt);
        }
    };

signals:
    void currentAltChanged(double newValue);

private:
    double m_currentAlt = 0.0;
}

The comments over the Q_PROPERTY macro are doxygen compatible. Doxygen can be configured to process and understand Qt Properties, Signals and Slots.

Note that the signal has no implementation.

from PySide2.QtCore import QWidget, Signal, Property, Slot

class AWidget(QWidget):

    def __init__(self):
        self._current_alt = 0.0

    def get_current_alt(self) -> double:
        """Gets the value of the current altitude
        :returns: double with value of the current altitude in radians.
        :rtype: double
        """
        return self._current_alt

    @Slot(double)
    def set_current_alt(self, new_value: double):
        """Sets the current altitude to new_value.
        :param[in]: new_value double with value of the current altitude in radians.
        """
        if( self._current_alt != new_value ):
            self._current_alt = new_value
            self.current_alt_changed.emit(self._current_alt)

    ## Signal that indicates tha the current altitude has changed.
    current_alt_changed = Signal(double)

    ## Property that holds the current altitude to be rendered.
    #  It uses radians as units
    current_alt = Property(double, get_current_alt, set_current_alt, notify=current_alt_changed)

Error

Do not use QStringList as a bug in Qt 5.15 (https://jira.eso.org/browse/ETCS-1036, https://bugreports.qt.io/browse/PYSIDE-1942) does not make it usable under python. As a workaround until we port to Qt 6, please use QString with a separator.

6.1. Common to all kind of widgets

6.1.1. Widget Class Declaration

6.1.2. WAF project/module for the Widget