changeset 24510:a2569d574ae5

Add a help entry and documentation for @ character (bug #52771). expr.txi: Add sub-node "Access via Handle" to the "Calling Functions" node. Don't indent a paragraph that refers to the previous example. Provide the body for the "Access via Handle" node and include an '@' opindex entry qualified by "function handle". Mention that '@' is also used for class methods and reference the "Object Oriented Programming" chapter. oop.txi: Add an opindex reference to '@' qualified by "class methods" so a quick index link is created. op-kw-docs: Create an operator index entry for '@'. Mention that '@' is also used for class methods and suggest seeing the "Object Oriented Programming" chapter of the manual. octave.texi: Add sub-node "Access via Handle" to sub-menu list.
author Daniel J Sebald <daniel.sebald@ieee.org>
date Tue, 02 Jan 2018 15:29:10 -0600
parents d8ed90ecd4fd
children 3fc1c8ebe5c3
files doc/interpreter/expr.txi doc/interpreter/octave.texi doc/interpreter/oop.txi libinterp/op-kw-docs
diffstat 4 files changed, 70 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/expr.txi	Wed Jan 03 22:30:54 2018 -0800
+++ b/doc/interpreter/expr.txi	Tue Jan 02 15:29:10 2018 -0600
@@ -388,6 +388,7 @@
 @menu
 * Call by Value::
 * Recursion::
+* Access via Handle::
 @end menu
 
 @node Call by Value
@@ -483,6 +484,7 @@
 @end group
 @end example
 
+@noindent
 This function is recursive because it calls itself directly.  It
 eventually terminates because each time it calls itself, it uses an
 argument that is one less than was used for the previous call.  Once the
@@ -494,6 +496,52 @@
 
 @DOCSTRING(max_recursion_depth)
 
+@node Access via Handle
+@subsection Access via Handle
+@cindex function handle
+@cindex indirect function call
+
+@opindex @@ function handle
+A function may be abstracted and referenced via a function handle acquired
+using the special operator @samp{@@}.  For example,
+
+@example
+@group
+f = @@plus;
+f (2, 2)
+@result{}  4
+@end group
+@end example
+
+@noindent
+is equivalent to calling @code{plus (2, 2)} directly.  Beyond abstraction for
+general programming, function handles find use in callback methods for figures
+and graphics by adding listeners to properties or assigning pre-existing
+actions, such as in the following example:
+
+@cindex figure deletefcn
+@example
+@group
+function mydeletefcn (h, ~, msg)
+  printf (msg);
+endfunction
+sombrero;
+set (gcf, "deletefcn", @{@@mydeletefcn, "Bye!\n"@});
+close;
+@end group
+@end example
+
+@noindent
+The above will print "Bye!" to the terminal upon the closing (deleting) of the
+figure.  There are many graphics property actions for which a callback function
+may be assigned, including, @code{buttondownfcn}, @code{windowscrollwheelfcn},
+@code{createfcn}, @code{deletefcn}, @code{keypressfcn}, etc.
+
+Note that the @samp{@@} character also plays a role in defining class
+functions, i.e., methods, but not as a syntactical element.  Rather it begins a
+directory name containing methods for a class that shares the directory name
+sans the @samp{@@} character.  See @ref{Object Oriented Programming}.
+
 @node Arithmetic Ops
 @section Arithmetic Operators
 @cindex arithmetic operators
--- a/doc/interpreter/octave.texi	Wed Jan 03 22:30:54 2018 -0800
+++ b/doc/interpreter/octave.texi	Tue Jan 02 15:29:10 2018 -0600
@@ -359,6 +359,7 @@
 
 * Call by Value::
 * Recursion::
+* Access via Handle::
 
 Boolean Expressions
 
--- a/doc/interpreter/oop.txi	Wed Jan 03 22:30:54 2018 -0800
+++ b/doc/interpreter/oop.txi	Tue Jan 02 15:29:10 2018 -0600
@@ -81,6 +81,7 @@
 a = [a0, a1, a2, @dots{}, an];
 @end example
 
+@opindex @@ class methods
 This is a sufficient specification to begin writing the constructor for the
 polynomial class.  All object oriented classes in Octave must be located in a
 directory that is the name of the class prepended with the @samp{@@} symbol.
--- a/libinterp/op-kw-docs	Wed Jan 03 22:30:54 2018 -0800
+++ b/libinterp/op-kw-docs	Tue Jan 02 15:29:10 2018 -0600
@@ -383,6 +383,26 @@
 Logical 'or' (with short-circuit evaluation) operator.
 @seealso{|, or}
 @end deftypefn
+@
+@c libinterp/parse-tree/oct-parse.in.yy
+-*- texinfo -*-
+@deftypefn {} {} @@
+Return handle to a function.
+
+Example:
+
+@example
+@group
+f = @@plus;
+f (2, 2)
+@result{}  4
+@end group
+@end example
+
+(Note: @@ also finds use in creating classes.  See manual chapter titled
+Object Oriented Programming for detailed description.)
+@seealso{function, functions, func2str, str2func}
+@end deftypefn
 break
 @c libinterp/parse-tree/oct-parse.in.yy
 -*- texinfo -*-