(octave.info)Callbacks

---

Next: Application-defined Data Prev: Marker Styles Up: Advanced Plotting

---

Enter node , (file) or (file)node

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
Octave command.  The latter syntax is not recommended since syntax
errors will only occur when the string is evaluated.  Note: Function
Handles section.

   This can then be associated with an object either at the object’s
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 two default arguments.  For example:

     plot (x, "DeleteFcn", {@mycallback, "1"})
     ...
     function mycallback (h, evt, arg1)
       fprintf ("Closing plot %d\n", arg1);
     endfunction

   *Caution:* The second argument in callback functions—‘evt’—is only
partially 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 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 implement this callback.

   By default callback functions are queued (they are executed one after
the other in the event queue) unless the ‘drawnow’, ‘figure’, ‘waitfor’,
‘getframe’, or ‘pause’ functions are used.  If an executing callback
invokes one of those functions, it causes Octave to flush the event
queue, which results in the executing callback being interrupted.

   It is possible to specify that an object’s callbacks should not be
interrupted by setting the object’s ‘interruptible’ property to "off".
In this case, Octave decides what to do based on the ‘busyaction’
property of the *interrupting* callback object:

‘queue’ (the default)
     The interrupting callback is executed after the executing callback
     has returned.

‘cancel’
     The interrupting callback is discarded.

   The ‘interruptible’ property has no effect when the interrupting
callback is a ‘deletefcn’, or a figure ‘resizefcn’ or ‘closerequestfcn’.
Those callbacks always interrupt the executing callback.

   The handle to the object that holds the callback being executed can
be obtained with the ‘gcbo’ function.  The handle to the ancestor figure
of this object may be obtained using the ‘gcbf’ function.

 -- : 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: Note: gcbf, Note: gco, *note gca:
     XREFgca, Note: gcf, Note: get, *note 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’.

     See also: Note: gcbo, Note: gcf, *note gco:
     XREFgco, Note: gca, Note: get, *note set:
     XREFset.

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