octave: Callbacks
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. Function Handles
section Function Handles Anonymous Functions Inline Functions.
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.
DONTPRINTYET See also: gcbf XREFgcbf, gco XREFgco, *notegca:
DONTPRINTYET DONTPRINTYET See also: gcbf XREFgcbf, gco XREFgco, gca
XREFgca, gcf XREFgcf, get XREFget, *noteset:
DONTPRINTYET DONTPRINTYET See also: gcbf XREFgcbf, gco XREFgco, gca
XREFgca, gcf XREFgcf, get XREFget, set
XREFset.
-- : 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’.
DONTPRINTYET See also: gcbo XREFgcbo, gcf XREFgcf, *notegco:
DONTPRINTYET DONTPRINTYET See also: gcbo XREFgcbo, gcf XREFgcf, gco
XREFgco, gca XREFgca, get XREFget, *noteset:
DONTPRINTYET DONTPRINTYET See also: gcbo XREFgcbo, gcf XREFgcf, gco
XREFgco, gca XREFgca, get XREFget, set
XREFset.
Callbacks can equally be added to properties with the ‘addlistener’
function described below.