Supported by Supported by Advertisement

Creating an extension

What is an OpenSesame extension?

Extensions add arbitrary functionality to the OpenSesame user interface. For example, an extension can add a new entry to the main toolbar or the menubar. To add functionality that you can use in experiments, you need a plugin:

Relevant files

Let's assume that your extension is called my_extension. In that case, your extension corresponds to a folder called my_extension, which contains at least the following 2 files:

my_extension/
    info.yaml
    my_extension.py

Extension information

Extension information is defined in info.yaml. This works the same way as for plugins, with the exception that you don't define any controls. For more information, see:

Writing the extension code

The main extension code is placed in my_extension.py. This file has one class, my_extension, which inherits libqtopensesame.extensions.base_extension.base_extension. So a basic (non-functional) extension class looks like this:

from libqtopensesame.extensions import base_extension

class my_extension(base_extension):

    pass

Activating an extension through the menu/ toolbar

An extension can appear in the menu or main toolbar of OpenSesame. This requires that you define several fields in info.yaml:

label: Example extension
icon: go-next
tooltip: Some tooltip
menu:
  index: 0
  separator_after: false
  separator_before: false
  submenu: Example
toolbar:
  index: -1
  separator_after: false
  separator_before: true

The label is the text that will appear in the menu. The icon is a freedesktop-compliant icon name that specifies the icon that will appear in the menu and/ or toolbar. The index gives the position of the extension in the menu/ toolbar, and works like a list index. That is, negative values are relative to the last entry, where -1 puts your extension at the end.

To have your extension respond to menu/ toolbar activation, implement the activate() method:

from libopensesame import debug
from libqtopensesame.extensions import base_extension

class my_extension(base_extension):

    def activate(self):

        debug.msg(u'My extension was activated!')

Listening for events

OpenSesame fires events whenever something important happens. For example, the save_experiment event is fired when an experiment is saved. To have your extension listen to an event, simply implement a method with the name event_[event name].

from libopensesame import debug
from libqtopensesame.extensions import base_extension

class my_extension(base_extension):

    def event_save_experiment(self, path):

        debug.msg(u'Event fired: save_experiment(path=%s)' % path)

Note that some events take keyword arguments, such as path in the case of save_experiment. The keyword signature of your function must match the expected keyword signature. A list of events can be found in the example extension.

Writing a setup.py and uploading to PyPi

See:

Examples

For a working example, see: