15.4.4 Callbacks

Callback functions can be associated with graphics objects and triggered after certain events occur. The basic structure of all callback function is

function mycallback (hsrc, evt)
…
endfunction

where hsrc is a handle to the source of the callback, and evt gives some event specific data.

The function can be provided as a function handle to a plain Octave function, as an anonymous function or as a string representing an Octvae command. The latter syntax is not recommended since syntax errors will only occur when the string is evaluated. See Function Handles section.

This can then be associated with an object either at the objects creation or later with the set function. For example,

plot (x, "DeleteFcn", @(h, e) disp ("Window Deleted"))

where at the moment that the plot is deleted, the message "Window Deleted" will be displayed.

Additional user arguments can be passed to callback functions, and will be passed after the 2 default arguments. For example:

plot (x, "DeleteFcn", {@mycallback, "1"})
…
function mycallback (h, e, a1)
  fprintf ("Closing plot %d\n", a1);
endfunction

The basic callback functions that are available for all graphics objects are

• CreateFcn: called at the moment of the objects creation. It is not called if the object is altered in any way, and so it only makes sense to define this callback in the function call that defines the object. Callbacks that are added to CreateFcn later with the set function will never be executed.
• DeleteFcn: called at the moment an object is deleted.
• ButtonDownFcn: called if a mouse button is pressed while the pointer is over this object. Note, that the gnuplot interface does not respect this callback.

Caution: the second evt argument in callback functions is only loosely implemented in the Qt graphics toolkit:

• Mouse click events: evt is a class double value, 1 for left, 2 for middle and 3 for right click.
• Key press events: evt is a structure with fields Key (string), Character (string) and Modifier (cell array of strings).
• Other events: evt is a class double empty matrix.

The object and figure that the event occurred in that resulted in the callback being called can be found with the gcbo and gcbf functions.

: h = gcbo ()

: [h, fig] = gcbo ()

Return a handle to the object whose callback is currently executing.

If no callback is executing, this function returns the empty matrix. This handle is obtained from the root object property "CallbackObject".

When called with a second output argument, return the handle of the figure containing the object whose callback is currently executing. If no callback is executing the second output is also set to the empty matrix.

See also: gcbf, gco, gca, gcf, get, set.

: fig = gcbf ()

Return a handle to the figure containing the object whose callback is currently executing.

If no callback is executing, this function returns the empty matrix. The handle returned by this function is the same as the second output argument of gcbo.

See also: gcbo, gcf, gco, gca, get, set.

Callbacks can equally be added to properties with the addlistener function described below.