<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Callbacks (GNU Octave (version 5.1.0))</title>
<meta name="description" content="Callbacks (GNU Octave (version 5.1.0))">
<meta name="keywords" content="Callbacks (GNU Octave (version 5.1.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Advanced-Plotting.html#Advanced-Plotting" rel="up" title="Advanced Plotting">
<link href="Application_002ddefined-Data.html#Application_002ddefined-Data" rel="next" title="Application-defined Data">
<link href="Marker-Styles.html#Marker-Styles" rel="prev" title="Marker Styles">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<a name="Callbacks"></a>
<div class="header">
<p>
Next: <a href="Application_002ddefined-Data.html#Application_002ddefined-Data" accesskey="n" rel="next">Application-defined Data</a>, Previous: <a href="Marker-Styles.html#Marker-Styles" accesskey="p" rel="prev">Marker Styles</a>, Up: <a href="Advanced-Plotting.html#Advanced-Plotting" accesskey="u" rel="up">Advanced Plotting</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Callbacks-1"></a>
<h4 class="subsection">15.4.4 Callbacks</h4>
<a name="index-callbacks"></a>
<p>Callback functions can be associated with graphics objects and triggered
after certain events occur. The basic structure of all callback function
is
</p>
<div class="example">
<pre class="example">function mycallback (hsrc, evt)
…
endfunction
</pre></div>
<p>where <code>hsrc</code> is a handle to the source of the callback, and <code>evt</code>
gives some event specific data.
</p>
<p>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.
See <a href="Function-Handles-Anonymous-Functions-Inline-Functions.html#Function-Handles-Anonymous-Functions-Inline-Functions">Function Handles section</a>.
</p>
<p>This can then be associated with an object either at the object’s creation, or
later with the <code>set</code> function. For example,
</p>
<div class="example">
<pre class="example">plot (x, "DeleteFcn", @(h, e) disp ("Window Deleted"))
</pre></div>
<p>where at the moment that the plot is deleted, the message
<code>"Window Deleted"</code> will be displayed.
</p>
<p>Additional user arguments can be passed to callback functions, and will be
passed after the two default arguments. For example:
</p>
<div class="example">
<pre class="example">plot (x, "DeleteFcn", {@mycallback, "1"})
…
function mycallback (h, evt, arg1)
fprintf ("Closing plot %d\n", arg1);
endfunction
</pre></div>
<p><strong>Caution:</strong> The second argument in callback functions—<code>evt</code>—is
only partially implemented in the Qt graphics toolkit:
</p>
<ul>
<li> Mouse click events:
<code>evt</code> is a class <code>double</code> value: 1 for left, 2 for middle, and 3 for
right click.
</li><li> Key press events:
<code>evt</code> is a structure with fields <code>Key</code> (string), <code>Character</code>
(string), and <code>Modifier</code> (cell array of strings).
</li><li> Other events:
<code>evt</code> is a class <code>double</code> empty matrix.
</li></ul>
<p>The basic callback functions that are available for all graphics objects are
</p>
<ul>
<li> 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 <code>CreateFcn</code> later with the <code>set</code> function will
never be executed.
</li><li> DeleteFcn:
called at the moment an object is deleted.
</li><li> 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.
</li></ul>
<p>By default callback functions are queued (they are executed one after the other
in the event queue) unless the <code>drawnow</code>, <code>figure</code>, <code>waitfor</code>,
<code>getframe</code>, or <code>pause</code> 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.
</p>
<p>It is possible to specify that an object’s callbacks should not be interrupted
by setting the object’s <code>interruptible</code> property to <code>"off"</code>. In
this case, Octave decides what to do based on the <code>busyaction</code> property of
the <strong>interrupting</strong> callback object:
</p>
<dl compact="compact">
<dt><code>queue</code> (the default)</dt>
<dd><p>The interrupting callback is executed after the executing callback has
returned.
</p>
</dd>
<dt><code>cancel</code></dt>
<dd><p>The interrupting callback is discarded.
</p></dd>
</dl>
<p>The <code>interruptible</code> property has no effect when the interrupting callback
is a <code>deletefcn</code>, or a figure <code>resizefcn</code> or <code>closerequestfcn</code>.
Those callbacks always interrupt the executing callback.
</p>
<p>The handle to the object that holds the callback being executed can be
obtained with the <code>gcbo</code> function. The handle to the ancestor figure
of this object may be obtained using the <code>gcbf</code> function.
</p>
<a name="XREFgcbo"></a><dl>
<dt><a name="index-gcbo"></a><em><var>h</var> =</em> <strong>gcbo</strong> <em>()</em></dt>
<dt><a name="index-gcbo-1"></a><em>[<var>h</var>, <var>fig</var>] =</em> <strong>gcbo</strong> <em>()</em></dt>
<dd><p>Return a handle to the object whose callback is currently executing.
</p>
<p>If no callback is executing, this function returns the empty matrix. This
handle is obtained from the root object property <code>"CallbackObject"</code>.
</p>
<p>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.
</p>
<p><strong>See also:</strong> <a href="#XREFgcbf">gcbf</a>, <a href="Graphics-Objects.html#XREFgco">gco</a>, <a href="Graphics-Objects.html#XREFgca">gca</a>, <a href="Graphics-Objects.html#XREFgcf">gcf</a>, <a href="Graphics-Objects.html#XREFget">get</a>, <a href="Graphics-Objects.html#XREFset">set</a>.
</p></dd></dl>
<a name="XREFgcbf"></a><dl>
<dt><a name="index-gcbf"></a><em><var>fig</var> =</em> <strong>gcbf</strong> <em>()</em></dt>
<dd><p>Return a handle to the figure containing the object whose callback is
currently executing.
</p>
<p>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 <code>gcbo</code>.
</p>
<p><strong>See also:</strong> <a href="#XREFgcbo">gcbo</a>, <a href="Graphics-Objects.html#XREFgcf">gcf</a>, <a href="Graphics-Objects.html#XREFgco">gco</a>, <a href="Graphics-Objects.html#XREFgca">gca</a>, <a href="Graphics-Objects.html#XREFget">get</a>, <a href="Graphics-Objects.html#XREFset">set</a>.
</p></dd></dl>
<p>Callbacks can equally be added to properties with the <code>addlistener</code>
function described below.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Application_002ddefined-Data.html#Application_002ddefined-Data" accesskey="n" rel="next">Application-defined Data</a>, Previous: <a href="Marker-Styles.html#Marker-Styles" accesskey="p" rel="prev">Marker Styles</a>, Up: <a href="Advanced-Plotting.html#Advanced-Plotting" accesskey="u" rel="up">Advanced Plotting</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
