4.2.5. Implementation of the User Interface

In this section, the developer will use the UI designed in the previous section, and implement basic functionality for them. Every function needed will be implemented in the PythonApplication/src/paegui/applicationwindow.py file.

All the entry points for missing functionality are already defined through the Actions in the UI file, we just need to connect the missing pieces. We will begin explaining the imports.

import time

from taurus.external.qt.QtCore import QObject
from taurus.external.qt.QtCore import Slot
from taurus.external.qt.QtCore import Signal
from taurus.external.qt.QtCore import QMetaObject
from taurus.external.qt.QtWidgets import QApplication
from taurus.external.qt.QtWidgets import QMainWindow
from taurus.external.qt.QtWidgets import QWhatsThis

from taurus.core.util.log import Logger, TraceIt
from elt.cut.task.task import Task
from CutColor import QePalettesModel

from python_application_example.mainwindow import Ui_MainWindow  # WAF will automatically generated this
from python_application_example.applicationconfiguration import ApplicationConfiguration

Most classes in the Qt library inherit from QObject. This is true also for widgets. QObject is the base class that provides Signal/Slot connection capabilities to the Qt Toolkit. We will use them plenty through the design and implementation of GUIs. If you are not familiar with them, we suggest you to read:

The QMainWindow import is present, as this class is the implementation of a QMainWindow. At the beginning of the design section, a Main Window was selected. Therefore, the implementation class must match the top level UI element.

The taurus.Logger class is from the taurus module and it allows to enhance a class with logging capabilities.

Finally, the Ui_MainWindow import is the python code generated by the pyside6-uic compiler. The compiler is automatically invoked by WAF, so no extra instructions are to be given. It is important that the UI file is inside of the Python Package name paegui, as from this directory is where WAF will look for any UI file, and automatically compile them.

Important

To determine both the name of the Python Module and the Class Name, the name of the first element of the UI file is used:

The Python module name will be lowercased name of the top level element of the UI file (in our case mainwindow.py).

The resulting Class Name will be Ui_<name of top level element>, in this case Ui_MainWindow.

You can see the first element name in the the Designer; Object Inspector Tab; the first element. You can also change it in the same place.

The resulting import show how the Python Module and the Class Name are used:

from python_application_example.mainwindow import Ui_MainWindow

We will now proceed to examine the Class definition:

class ApplicationWindow(QMainWindow, Logger):
    '''
    Implementation of the mainwindow.ui file.

    Since the UI file indicates that its root is a QMainWindow, then
    this class should also inherit from it.
    We should also call explicitly its parent constructors.

    The implementation for this class also includes slots for 
    actions, and management of the closeEvent.
    '''

    ###########################################################################
    #                Initialization and QMainWindow Methods                   #
    ###########################################################################

    def __init__(self, configuration: ApplicationConfiguration):
        QMainWindow.__init__(self)
        Logger.__init__(self, name=QApplication.instance().applicationName())
        # Construction of UI
        self.ui = Ui_MainWindow()
        self.ui.setupUi(self)
        self._init_gui()
        self._configuration = configuration

Line 28 declares a new class called ApplicationWindow, which inherits from QMainWindow. QMainWindow already inherits from QObject, so we can use signal and slots from this class definition.

The __init__() manually calls both its parent classes __init__() method. This is very important, as Python does not make implicit calls to these.

In line 46, the taurus.Logger parent class is initialized, but we use as name keyworded argument, QApplication.instance().applicationName(). QApplication.instance() is a static reference to the QApplication or taurus.qt.qtgui.application.TaurusApplication of this process. Qt forbids running two or more QApplications in the same process, and in Python, they offer a quick manner to obtain a reference to the QApplication object. Developers may use the QApplication.instance() reference to access the running QApplication.

In line 48 is where we create an instance of the UI definition we have in the mainwindow.ui file. It is assigned to self.ui. Then, in the next line, we invoke its setupUi() method, passing as argument the self reference to the QMainWindow object being initialized. The setupUi() method in the Ui_MainWindow() class will create every element as defined in the Designer for us. It is actually Python code that was translated from the XML. When the method finishes, every widget, action and layout will be available for the developer at self.ui.

Important

self.ui is very important for UI development using Qt. We suggest the reader to familiarize themselves with this manner of accessing the UI declared in the UI file. Developers should never copy and archive to repositories the result of pyside6-uic compiler. Instead, they should archive the UI file, and WAF automatically will produce an updated version of the UI.

We also encourage to use an editor capable of Python introspection/code completion. This will make the navigation of self.ui much more easier.

The next section of the code has many entries like this one:

    @Slot()
    def on_actionNew_triggered(self):
        '''
        Slot that auto-connects to the actionExit.
        actionNew is not declared in the code, but in the mainwindow.ui.       
        See: https://doc.qt.io/qt-5/designer-using-a-ui-file.html#widgets-and-dialogs-with-auto-connect
        '''
        self.info('actionNew triggered')

Each of these method defined the implementation of an action. The developer may notice a pattern in the name of the method: It is a composite of an existing Action name, and a signal it has. Qt will automatically recognize this pattern, and connect that object’s signal, to this slot.

The on_actionNew_triggered() method has a special name. As the comment mentions, actionNew is defined in the UI, and make use of auto connection, which is a convention based manner to save lines of code.

The syntax is:

on_<ui_object_name>_<signal>(self, <same_arguments_as_signal>)

The last thing setupUi() method does is to execute the QMetaObject.connectSlotsByName(), a static method that will:

For every Slot declared in our implementation class (the ApplicationWindow class):

Check if the name starts with on_.

Check if the next section matches the name of an object in the UI definition.

Check if this object in the UI definition has a Signal called triggered.

If all three conditions are a true, then it will automatically connect the object’s Signal, against the implementation’s Slot.

The only entry that is different is the closeEvent() method.

    def closeEvent(self, event):
        '''
        Not to be confused with actionExit, this method is special. Instead
        of using signals to know when an application is closed, we can
        override the closeEvent method from the QApplication class, and
        determine here what will happen when the window is closed.
        In this case, we are just forwarding the event to its parent class.
        This is useful when disconnection from server or prevention of
        current work needs to be implemented.

        :param event: Event received from Qt event pump
        :type event: QtCore.QEvent

        '''
        self.info('Application shutting down...')
        QMainWindow.closeEvent(self, event)

Let’s remember that Qt is an event based library. It detect and translate many input performed by the user and internal system outcomes into Events. Example of these are mouse movement, click, keystrokes, closing minimizing, maximizing the application, among many more. When a user click on the close button of an application, this is translated into an event.

Each UI element in Qt has one main handleEvent() method, and many specialized Event methods: , like closeEvent():

handleEvent() is the main entry point for any event. The QApplication.handleEvent() method will process this event, clasify it accordingly, and then call a specialized method.
closeEvent() is the specialized method when a window or dialog is requested to close. In the case of our particular implementation, closing the application main window should exit the program. Qt does this by default, so we just call parent implementation using QMainWindow.closeEvent().

At this moment, we will not concern ourselves with other kinds of methods.

At this point, the implementation is ready, and will log every action that is triggered.

4.2.5.1. Long Running Jobs

Qt runs in one thread. The main thread of the process is used by the event pump to detect and conduct the necessary operations, and drawing the GUI. For example, resizing the application will create many resizeEvent, which will request redrawing the UI to the appropriate dimensions.

But for this to happen, the main thread needs to be free. The developer may implement short and quick methods, and connect them using signal/slot mechanism. Qt will insert in between signal/slot execution many of its own events, keeping the UI smooth. But long running jobs should not be conducted in the main thread.

For sake of simplicity, a long running job can be emulated with a time.sleep() call.

Warning

An example is given below. This will cause the GUI to freeze for 5 seconds, as no other event gets executed in between, including input detection, and GUI drawing instructions.

    @Slot()
    def on_actionSave_triggered(self):
        '''
        Slot that auto-connects to the actionSave.
        actionSave is not declared in the code, but in the mainwindow.ui.
        See: https://doc.qt.io/qt-5/designer-using-a-ui-file.html#widgets-and-dialogs-with-auto-connect
        '''
        self.info('actionSave triggered')
        time.sleep(5)
        self.info('actionSave finished')

In this example application, we include a solution for this. In line 115, the actionSave() slot is queuing a long running job using the elt.cut.task module. This class manages a threadpool used for long running operations, pushing tasks into it. It also allows you connect a slot to receive the results of the job.

    @TraceIt()
    @Slot()
    def on_actionSave_triggered(self):
        '''
        Slot that auto-connects to the actionSave.
        actionSave is not declared in the code, but in the mainwindow.ui.       
        See: https://doc.qt.io/qt-5/designer-using-a-ui-file.html#widgets-and-dialogs-with-auto-connect
        '''
        self.info('actionSave triggered')
        self.info('actionSave launching new Task')
        task = Task(self.save_job)
        task.signals.result.connect(self.save_job_slot)
        task.start()
        self.info('actionSave finished')

Both methods save_job() and save_job_slot() are defined in the code shown below. save_job() is a method, and it is doing the long running job (in this case, sleeping for 5 seconds). When finished, the Taurus Manager will automatically invoke the callback save_job_slot(), passing as argument the return value of the save_job() method.

    def save_job(self):
        self.info('save_job sleeping for 5')
        time.sleep(5)
        return 'Slept for 5 seconds'
    
    def save_job_slot(self, arg):
        self.info('save_job_slot reporting %s' % (arg, ) )

There are also signals for progress, errors and finished conditions, to create more complete behaviors.

Now the reader may run the PaeGui using this command:

$ cutPaeGui

Logs from Taurus will appear in the console and the application will start. Please exercise the different Double Spin Boxes, and see how connections works with the Dart Boart. Also, if you press several times the save button (or its menu entry), you will see how each job request will get executed in its own separate thread:

$ cutPaeGui
MainThread     INFO     2024-10-29 13:50:31,914 TaurusRootLogger: Using PySide6 (v6.7.2 with Qt 6.7.2 and Python 3.12.6)
MainThread     INFO     2024-10-29 13:50:32,085 taurus.qt.qtgui.icon.icon: Setting breeze icon theme (from /usr/share/icons)
MainThread     INFO     2024-10-29 13:50:32,096 TaurusRootLogger: Plugin "taurus_pyqtgraph" lazy-loaded as "taurus.qt.qtgui.tpg"
MainThread     INFO     2024-10-29 13:51:00,771 Python Application Example GUI: Application shutting down...
MainThread     INFO     2024-10-29 13:51:00,785 TaurusRootLogger:

Taurus logs have the following syntaxt: Thread, Level, Timestamp, Logger Name, message.

If you need lower level logs, please start the application with the following command:

$ cutPaeGui --taurus-log-level Debug

Help is always present when using the taurus.qt.qtgui.application.TaurusApplication class:

$ cutPaeGui --help
MainThread     INFO     2024-10-29 14:17:53,358 TaurusRootLogger: Using PySide6 (v6.7.2 with Qt 6.7.2 and Python 3.12.6)
MainThread     INFO     2024-10-29 14:17:53,502 taurus.qt.qtgui.icon.icon: Setting breeze icon theme (from /usr/share/icons)
MainThread     INFO     2024-10-29 14:17:53,512 TaurusRootLogger: Plugin "taurus_pyqtgraph" lazy-loaded as "taurus.qt.qtgui.tpg"
Usage: cutPaeGui [OPTIONS]

  PythonApplicationExample GUI (or paegui), is part of a tutorial intended to
  introduce how to developed a simple GUI application for the E-ELT software

Options:
  --log-level [Critical|Error|Warning|Info|Debug|Trace]
                                  Show only logs with priority LEVEL or above
                                  [default: Info]
  -m, --memory-oldb               Uses in memory OLDB, disregarding remote
                                  OLDB.
  --help                          Show this message and exit.

If the parser was configured as in the start of the application, the taurus default options and the application options will all be handled by the same parser.

At this point, please save your work.