Module Programming
Almost any functionality can be added to SweepMe! on the Module level.
Requirements
Modules are written in Python and use Qt for Python for their user interface: PySide6 (Qt 6) in SweepMe! 1.6.1 and later, and PySide2 (Qt 5) in SweepMe! 1.5.x. Modules built for SweepMe! 1.5 do not work with SweepMe! 1.6.1 and must be rebuilt (see Migration guide). A module can define the class attribute REQUIRED_SWEEPME_VERSION with the minimum SweepMe! version it needs.
To program own modules, you need a license key. Modules can deeply interact with the entire program so that specific knowledge is needed. Please contact us (contact@sweep-me.net) to speak about possible approaches.
Philosophy
Modules are modular pieces. They have to be designed in a way to be able to work with all other modules. It is not recommended to put a final end user application into a module, even though it would be possible. It would be better to embed functionalities into a module that are useful for many different things. At the same time, tasks that belong to each other, should be grouped and incorporated to the module. Figuring out where to split functions is something we can help you with.
Basic steps
Create the GUI
GUI elements are arranged in a layout which is loaded into the Tab that comes with every Module. You can create such a layout independent from SweepMe! by:
- creating a python script
- importing PySide using "from PySide6 import QtWidgets, QtCore, QtGui" (SweepMe! 1.6.1 and later) or "from PySide2 import QtWidgets, QtCore, QtGui" (SweepMe! 1.5.x). This way you ensure to call each object of PySide the way we are doing it.
- creating a QWidget, QDialog, or QMainWindow as your main widget
- creating a function that returns a layout. This function could have the name "create_MainLayout"
- setting your layout to your corresponding main widget
- running everything using QApplication
- testing the look and feel
If everything is nice, you can copy the function "create_MainLayout" to a module.
To automatically save the user configuration of your module to the sequence (called "setting" in SweepMe! 1.5), you can define a dictionary that must be named 'self.GUIwidget'. Connect string keys with the GUI objects such as QLineEdit, QComboBox, QCheckBox etc. SweepMe! will save the content of each basic GUI object to the sequence whenever a user saves a sequence. When a sequence is loaded, SweepMe! restores the content of each basic GUI object. Caution: There are some keys that are reserved, e.g. "Label", "Port", "Device" that should not be used to link them to any GUI object that has a different purpose.
Define actions
There are some events where SweepMe! calls certain functions of a module:
- onVisibilityChanged(self, state): The tab of the module toggles visibility.
- onSettingLoaded(self): Loading a sequence (setting) is completed.
- onStartup(self): SweepMe! has started.
- onLayoutCreated(self): The layout of the module has been loaded after creation of the module.
- onAdded(self): The module has been created.
- onRemoved(self): The module has been removed.
You can add these functions to your module and fill them with the code that should be executed.
Link functions
If a measurement is started, SweepMe! will run a well-defined set of functions (sequencer functions). In this step, you have to tell SweepMe! what should be done.
Saving to sequences
How the user configures the module must be saved to and loaded from the sequence file. One possibility is to link GUI widgets to the dictionary 'self.GUIwidget' and SweepMe! will automatically save and load information for basic widgets such as QLineEdit, QComboBox, QCheckBox, etc. as described above.
However, it might be that you create complex widgets and functionalities that make it necessary to additionally save and load your own properties.
In SweepMe! 1.6.1 and later, sequences are saved as JSON-based .seq files (see Sequence file format). Use the following two functions:
- get_dynamic_parameters(self): returns a dictionary with the additional properties of the module. The values must be JSON-serializable (str, int, float, bool, list, dict, or None), and the keys must not collide with the keys of 'self.GUIwidget'.
- set_dynamic_parameters(self, parameters): This function is called when a sequence is loaded or a module is pasted. The dictionary 'parameters' contains the saved properties. Pick the keys that your module creates in get_dynamic_parameters.
For the setting format (.set) of SweepMe! 1.5, there are two further functions:
- get_CustomSetting(self): returns a list of strings. You get these strings back by the function set_CustomSetting when the setting is loaded.
- set_CustomSetting(self, content): This function is called when the setting is loaded and a custom entry is found. The function hands over an object called 'content' which is a list of strings separated by tabs, according to one item you added using get_CustomSetting.
Both functions of each pair have to be used pairwise. What you return in get_CustomSetting is what you get back in set_CustomSetting.
Test your module
Try to combine it with other modules and see whether it nicely interacts.