ScanImage often requires customization for end user needs, e.g. to coordinate imaging with stimulus, to perform on-line analysis, etc. This often can be accomplished by binding User Functions (M files written for the end user needs) to one or more ScanImage events.
Events are a relatively new concept in the Matlab language. ScanImage defines several events in its main ScanImage.SI3 class – see the +scanImage folder in the ScanImage distribution. These include events like acquisitionStart, focusStart, focusAborted, etc.
User function bindings to these events can be made in the User Functions panel. Bindings can be made which are saved with either the Configuration (CFG) or the User Settings (USR) file. Bindings to the User Settings (USR) file should be made when the user function should always execute on the specified event, including for the special USR-only events, appOpen and appClose. Bindings to the Configuration (CFG) file should be made when the user function is only needed for particular acquisitions, i.e. those with a desired stimulus or other custom behavior.
User Function Signature
User functions, except when a Matlab built-in (rare), should have the following signature:
function myUserFunc(eventName, eventData, optArg1, optArg2,...)
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 switch statement. This architecture can be used to make a fairly complex 'Plugins' (see below).
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. The scanImage.SI3 class contains a documentation string for each event, which provides information about any data passed with each event.
Plugins
Adding Custom Events
The list of events generated by ScanImage are specified in the scanimage.SI3 class – see the +scanimage folder in the ScanImage 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.
If needed, end users are encouraged to simply add events to the scanImage.SI3 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:
state.userFcns.hEventManager.notify(eventName)
state.userFcns.hEventManager.notify(eventName,eventData)
where eventName specifies the event to 'fire', and the optional eventData argument passes value to the user functions invoked by this event.