changeset 23208:8fd8ed1e3aa2

maint: merge of stable to default.
author Rik <rik@octave.org>
date Sun, 19 Feb 2017 21:10:03 -0800
parents 75515a7b1b4b (current diff) 9b0a2bc07545 (diff)
children 5d9d756724cc
files doc/interpreter/genpropdoc.m doc/interpreter/plot.txi liboctave/system/file-ops.cc liboctave/system/file-stat.cc liboctave/system/file-stat.h
diffstat 5 files changed, 74 insertions(+), 36 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/genpropdoc.m	Sun Feb 19 12:06:23 2017 +0100
+++ b/doc/interpreter/genpropdoc.m	Sun Feb 19 21:10:03 2017 -0800
@@ -126,6 +126,7 @@
       case "beingdeleted"
       case "busyaction"
       case "buttondownfcn"
+        s.doc = "__fcnmsg__";
         s.valid = valid_fcn;
 
       case "children"
@@ -140,12 +141,12 @@
         s.doc = "Callback function executed immediately after __objname__ \
 has been created.  Function is set by using default property on root object, \
 e.g., @code{set (0, \"default__objname__createfcn\", \
-'disp (\"__objname__ created!\")')}.";
+'disp (\"__objname__ created!\")')}.\n\n__fcnmsg__";
         s.valid = valid_fcn;
 
       case "deletefcn"
         s.doc = "Callback function executed immediately before __objname__ \
-is deleted.";
+is deleted.\n\n__fcnmsg__";
         s.valid = valid_fcn;
 
       case "handlevisibility"
@@ -290,7 +291,7 @@
 
       case "closerequestfcn"
         s.doc = "Function that is executed when a figure is deleted.  \
-@xref{XREFclosereq, , closereq function}."
+@xref{XREFclosereq, , closereq function}.\n\n__fcnmsg__";
         s.valid = valid_fcn;
 
       case "color"
@@ -346,6 +347,9 @@
         s.doc = "Replace the figure and axes background color with white when printing.";
 
       case "keypressfcn"
+        s.doc = "Callback function executed when a keystroke event \
+happens while the figure has focus. The actual key that was pressed \
+can be retrieved using the second argument 'evt' of the function.  __fcnmsg__";
         s.valid = valid_fcn;
 
       case "keyreleasefcn"
@@ -362,7 +366,8 @@
 @item Modifier:\n\
 A cell array containing strings representing the modifiers pressed with the \
 key.\n\
-@end table";
+@end table\
+\n\n__fcnmsg__";
         s.valid = valid_fcn;
 
       case "menubar"
@@ -473,7 +478,8 @@
         ## FIXME: docstring explaining what "{normal}|open|alt|extend" mean.
 
       case "sizechangedfcn"
-        s.doc = "Callback triggered when the figure window size is changed.";
+        s.doc = "Callback triggered when the figure window size is changed.\
+\n\n__fcnmsg__";
         s.valid = valid_fcn;
 
       case "toolbar"
@@ -499,20 +505,22 @@
 @code{windowbuttonmotionfcn}, the mouse callback functions.  These \
 callback functions are called when a mouse button is pressed, dragged, or \
 released respectively.  When these callback functions are executed, the \
-@code{currentpoint} property holds the current coordinates of the cursor.";
+@code{currentpoint} property holds the current coordinates of the cursor.\
+\n\n__fcnmsg__";
         s.valid = valid_fcn;
 
       case "windowkeypressfcn"
         s.doc = "Function that is executed when a key is pressed and \
-the figure has focus.";
+the figure has focus.\n\n__fcnmsg__";
         s.valid = valid_fcn;
 
       case "windowkeyreleasefcn"
         s.doc = "Function that is executed when a key is released and \
-the figure has focus.";
+the figure has focus.\n\n__fcnmsg__";
         s.valid = valid_fcn;
 
       case "windowscrollwheelfcn"
+        s.doc = doc_unused;
         s.valid = valid_fcn;
 
       case "windowstyle"
@@ -1552,6 +1560,9 @@
 property to be set to @qcode{\"manual\"}";
   modemsg = sprintf (modemsg, field, field);
   strout = strrep (strout, "__modemsg__", modemsg);
+  fcnmsg = "For information on how to write graphics listener \
+functions see @ref{Callbacks, , @w{Callbacks section}}.";
+  strout = strrep (strout, "__fcnmsg__", fcnmsg);
 endfunction
 
 function s = getstructure (objname, base = [])
--- a/doc/interpreter/plot.txi	Sun Feb 19 12:06:23 2017 +0100
+++ b/doc/interpreter/plot.txi	Sun Feb 19 21:10:03 2017 -0800
@@ -1776,20 +1776,28 @@
 
 @example
 @group
-function mycallback (src, data)
+function mycallback (hsrc, evt)
 @dots{}
 endfunction
 @end group
 @end example
 
 @noindent
-where @code{src} gives a handle to the source of the callback, and
-@code{code} gives some event specific data.  This can then be associated
+where @code{hsrc} is a handle to the source of the callback, and @code{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.  
+@xref{Function Handles Anonymous Functions Inline Functions, , Function Handles section}.
+
+This can then be associated
 with an object either at the objects creation or later with the
 @code{set} function.  For example,
 
 @example
-plot (x, "DeleteFcn", @@(s, e) disp ("Window Deleted"))
+plot (x, "DeleteFcn", @@(h, e) disp ("Window Deleted"))
 @end example
 
 @noindent
@@ -1803,7 +1811,7 @@
 @group
 plot (x, "DeleteFcn", @{@@mycallback, "1"@})
 @dots{}
-function mycallback (src, data, a1)
+function mycallback (h, e, a1)
   fprintf ("Closing plot %d\n", a1);
 endfunction
 @end group
@@ -1813,22 +1821,33 @@
 are
 
 @itemize @bullet
-@item CreateFcn
-This is the callback that is 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} later with
-the @code{set} function will never be executed.
-
-@item DeleteFcn
-This is the callback that is called at the moment an object is deleted.
-
-@item ButtonDownFcn
-This is the callback that is called if a mouse button is pressed while
-the pointer is over this object.  Note, that the gnuplot interface does
-not respect this callback.
+@item 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} later with the @code{set} function will never be executed.
+
+@item DeleteFcn: 
+called at the moment an object is deleted.
+
+@item 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.
 @end itemize
 
+@strong{Caution:} the second @code{evt} argument in callback functions is only 
+loosely implemented in the Qt graphics toolkit:
+
+@itemize @bullet
+@item Mouse click events:
+@code{evt} is a class @code{double} value, 1 for left, 2 for middle and 3 
+for right click.
+
+@item Key press events:
+@code{evt} is a structure with fields @code{Key} (string), @code{Character} 
+(string) and @code{Modifier} (cell array of strings).
+
+@item Other events:
+@code{evt} is a class @code{double} empty matrix.
+@end itemize
+
+
 The object and figure that the event occurred in that resulted in the
 callback being called can be found with the @code{gcbo} and @code{gcbf}
 functions.
--- a/liboctave/system/file-ops.cc	Sun Feb 19 12:06:23 2017 +0100
+++ b/liboctave/system/file-ops.cc	Sun Feb 19 21:10:03 2017 -0800
@@ -227,7 +227,7 @@
       size_t f_len = filename.length ();
 
       if (f_len == 0 || filename[0] != '~')
-        return filename;
+        return std::string (filename);
 
       // A leading '~/' or a bare '~' is *always* translated to the value
       // of $HOME or the home directory of the current user, regardless of
@@ -301,7 +301,7 @@
     octave::sys::file_ops::tilde_expand (const std::string& name)
     {
       if (name.find ('~') == std::string::npos)
-        return name;
+        return std::string (name);
       else
         {
           std::string result;
--- a/liboctave/system/file-stat.cc	Sun Feb 19 12:06:23 2017 +0100
+++ b/liboctave/system/file-stat.cc	Sun Feb 19 21:10:03 2017 -0800
@@ -167,6 +167,15 @@
 
     // Private stuff:
 
+    file_stat::file_stat (const std::string& n, bool fl)
+        : base_file_stat (), file_name (n), follow_links (fl)
+      {
+        if (! file_name.empty ())
+          update_internal ();
+      }
+
+    inline file_stat::~file_stat () { }
+
     void
     file_stat::update_internal (bool force)
     {
--- a/liboctave/system/file-stat.h	Sun Feb 19 12:06:23 2017 +0100
+++ b/liboctave/system/file-stat.h	Sun Feb 19 21:10:03 2017 -0800
@@ -211,12 +211,9 @@
     {
     public:
 
-      file_stat (const std::string& n = "", bool fl = true)
-        : base_file_stat (), file_name (n), follow_links (fl)
-      {
-        if (! file_name.empty ())
-          update_internal ();
-      }
+      // This constructor must remain defined in the cpp file rather than in
+      // the header file (bug #50234).
+      file_stat (const std::string& n = "", bool fl = true);
 
       file_stat (const file_stat& fs)
         : base_file_stat (fs), file_name (fs.file_name),
@@ -235,7 +232,9 @@
         return *this;
       }
 
-      ~file_stat (void) = default;
+      // This destructor must remain as an empty destructor defined in the
+      // cpp file rather than in the header file (bug #50234).
+      ~file_stat (void);
 
       void get_stats (bool force = false)
       {