User Functions (r3.7)

This page contains macros or features from a plugin which requires a valid license.

You will need to contact your administrator.

USER FUNCTIONS Dialog

• : List of events to which user functions (event listeners) can be bound. These are pre-defined by ScanImage, but custom events can be readily added, if required, as discussed below.
• : Name of user-specified function to execute when event occurs. Generally these are specified by , but they can also be entered directly if the user function is a Matlab built-in function.
• : User functions can take optional arguments, specified here. This allows behavior of function to be modulated. A single value can be entered if only one argument is expected. If more than one argument is required, it should be entered as a cell array, e.g. {<Arg1Value> <Arg2Value> ...}.
• : Checkbox enables/disables execution of specified user function for particular event.

• : Up to 10 user functions can be bound to each listener. There are then 10 tables of event/user function configuration. This value adjusts which of these is currently displayed and available for editing.

• : Enables or disables all of the user functions specified for events with user function specified, at current .

The / operations act on the currently selected event. To select event, the mouse/cursor should be placed in one of the editable controls for given event.

• : Launches file browser dialog allowing selection of user function for currently selected event (and current ). The file selected need not be on the Matlab search path.
• : Removes user function, if any, bound to currently selected event (at current .

All settings in the USER FUNCTIONS... dialog are Configuration settings, i.e. saved/loaded as part of CFG files.

The ability to specify optional arguments to user functions is useful, for instance, to specify channels on which to apply custom computation, to provide parameters to an algorithm implemented by the user function, etc.

User Function Signature

User functions, except when a Matlab built-in (rare), should have the following signature:

This signature should be used even if the eventName or eventData arguments passed to the user function are not needed. These arguments are supplied by ScanImage. Optional arguments, if any, are passed starting from the third argument – these arguments are supplied by the User Functions dialog.

Using the eventName argument allows, for instance, using the same function bound to multiple events, with a different action occurring based on the particular event – this is readily implemented in the user function with a statement. This architecture can be used to make a fairly complex 'Plugins'.

The eventData argument can contain a single value (possibly a structure of multiple values) that is specified by ScanImage at the time of the event. The value passed – if any – depends on the event. See the ScanImage.EventManager class for information about what data is passed with each event.

The ScanImage.EventManager Class

The list of events generated by ScanImage are specified in the ScanImage.EventManager class – see the +ScanImage folder in the ScanImage 3.7 distribution.

The documentation for each event in this class file provides information about the event, and also specifies what, if any, eventData is passed to user functions for particular events.

End users are encouraged to simply add events to the ScanImage.EventManager class file. These changes should be made to the file when ScanImage is not running and Matlab should typically be restarted following the addition. Then on subsequent ScanImage startup, the added event will appear in the User Functions dialog.

To 'fire' the event at appropriate location(s) in ScanImage code, the following syntax should be used:

where eventName specifies the event to 'fire', and the optional eventData argument passes value to the user functions invoked by this event.