Modules

A module is a small standalone user interface that allows you to add custom features to Symphony. A module may be opened from the Modules menu at the top of the main Symphony window.

Writing a new module

To write a new module you need to create a sub-class of the Module class.

Your sub-class should:

1. Uniquely identify the module.
2. Define a constructor method.

Identifying the module

Identify the module using a constant property of the Module sub-class.

properties (Constant)
    displayName = 'My Module'
end

Add user interface controls

Add user interface controls to a module by defining a constructor method and creating controls on the main module figure handle. The constructor must take a single argument (the main SymphonyUI application) and call the Module superclass constructor before adding ui controls:

function obj = MyModule(symphonyUI)
    obj@Module(symphonyUI);
    
    % Create ui controls on the main figure handle.
    uicontrol('Style', 'pushbutton', 'String', 'Hello World!')
end

Add listeners

Symphony fires events when it changes state. For instance, it fires an event when the user changes the current rig configuration or protocol. Your module can listen for these events and perform an action in response. To listen for a particular event add an event listener to the symphonyUI object and define a function to run when the event occurs:

properties
    rigConfigChanged
end

function obj = MyModule(symphonyUI)
    obj@Module(symphonyUI);
    
    % Add a listener to call the update() method when the rig config changes.
    obj.rigConfigChanged = addlistener(symphonyUI, 'ChangedRigConfig', @(src,evt)obj.update());
end

function update(obj)
    disp('The rig config was changed! I better update my UI.');
end

function delete(obj)
    % If you add a listener you must explicitly delete it!
    delete(obj.rigConfigChanged);
end

Saving modules

Symphony will search for modules in the directory defined by the config.modulesDir variable in your symphonyrc.m script. All modules must be at the top level of the modules directory.

A simple module

The following class implements a simple module which displays the current protocol name.

classdef SimpleModule < Module
    
    properties (Constant)
        displayName = 'Simple Module'        
    end
    
    properties
        label
        protocolChanged
    end
    
    methods
        
        function obj = SimpleModule(symphonyUI)
            obj@Module(symphonyUI);
            
            obj.label = uicontrol(obj.figureHandle, ...
                'Position', [0, 0, 1000, 40], ...
                'FontSize', 40, ...
                'HorizontalAlignment', 'left', ...
                'Style', 'text');
            
            obj.protocolChanged = addlistener(symphonyUI, 'ChangedProtocol', @(src,evt)obj.updateLabel());
            
            obj.updateLabel();
        end
        
        function delete(obj)
            delete(obj.protocolChanged);
        end
        
        function updateLabel(obj)
            protocolName = obj.symphonyUI.protocol.displayName;
            set(obj.label, 'String', ['Current protocol: ' protocolName]);
        end
        
    end
    
end