changeset 24462:8ff3c13d14c1

groot.m: New function to return handle of graphics root object. * scripts/plot/util/groot.m: New function * scripts/plot/util/module.mk: Add function to build system. * NEWS: Announce new function * plot.txi: Add docstring to manual. Update instances of get/set (0) in this chapter to use groot. * gcf.m: Update example code in documentation to use groot. * genpropdoc.m, geometryimages.m, interpimages.m, plotimages.m, sparseimages.m, splineimages.m: Use groot rather than hardcoded constant of 0 in scripts to generate figures for manual.
author Rik <rik@octave.org>
date Mon, 25 Dec 2017 22:13:41 -0800
parents 0a034d34a686
children b1ae8fe2ee00
files NEWS doc/interpreter/genpropdoc.m doc/interpreter/geometryimages.m doc/interpreter/interpimages.m doc/interpreter/plot.txi doc/interpreter/plotimages.m doc/interpreter/sparseimages.m doc/interpreter/splineimages.m scripts/plot/util/gcf.m scripts/plot/util/groot.m scripts/plot/util/module.mk
diffstat 11 files changed, 113 insertions(+), 42 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS	Mon Dec 25 19:37:03 2017 -0800
+++ b/NEWS	Mon Dec 25 22:13:41 2017 -0800
@@ -92,6 +92,7 @@
       corrcoef
       erase
       getframe
+      groot
       gsvd
       hgtransform
       humps
--- a/doc/interpreter/genpropdoc.m	Mon Dec 25 19:37:03 2017 -0800
+++ b/doc/interpreter/genpropdoc.m	Mon Dec 25 22:13:41 2017 -0800
@@ -151,7 +151,7 @@
       case "createfcn"
         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\", \
+e.g., @code{set (groot, \"default__objname__createfcn\", \
 'disp (\"__objname__ created!\")')}.\n\n__fcnmsg__";
         s.valid = valid_fcn;
 
--- a/doc/interpreter/geometryimages.m	Mon Dec 25 19:37:03 2017 -0800
+++ b/doc/interpreter/geometryimages.m	Mon Dec 25 22:13:41 2017 -0800
@@ -22,7 +22,7 @@
   hide_output ();
   outfile = fullfile (d, [nm "." typ]);
   if (strcmp (typ, "png"))
-    set (0, "defaulttextfontname", "*");
+    set (groot, "defaulttextfontname", "*");
   endif
   if (strcmp (typ, "eps"))
     d_typ = "-depsc2";
@@ -155,12 +155,12 @@
 function set_print_size ()
   image_size = [8.0, 6.0]; # in inches, 4:3 format
   border = 0;              # For postscript use 50/72
-  set (0, "defaultfigurepapertype", "<custom>");
-  set (0, "defaultfigurepaperorientation", "landscape");
-  set (0, "defaultfigurepapersize", image_size + 2*border);
-  set (0, "defaultfigurepaperposition", [border, border, image_size]);
+  set (groot, "defaultfigurepapertype", "<custom>");
+  set (groot, "defaultfigurepaperorientation", "landscape");
+  set (groot, "defaultfigurepapersize", image_size + 2*border);
+  set (groot, "defaultfigurepaperposition", [border, border, image_size]);
   ## FIXME: Required until listener for legend exists (bug #39697)
-  set (0, "defaultfigureposition", [ 72*[border, border, image_size] ]);
+  set (groot, "defaultfigureposition", [ 72*[border, border, image_size] ]);
 endfunction
 
 ## Use this function before plotting commands and after every call to print
--- a/doc/interpreter/interpimages.m	Mon Dec 25 19:37:03 2017 -0800
+++ b/doc/interpreter/interpimages.m	Mon Dec 25 22:13:41 2017 -0800
@@ -22,7 +22,7 @@
   hide_output ();
   outfile = fullfile (d, [nm "." typ]);
   if (strcmp (typ, "png"))
-    set (0, "defaulttextfontname", "*");
+    set (groot, "defaulttextfontname", "*");
   endif
   if (strcmp (typ, "eps"))
     d_typ = "-depsc2";
@@ -98,12 +98,12 @@
 function set_print_size ()
   image_size = [8.0, 6.0]; # in inches, 4:3 format
   border = 0;              # For postscript use 50/72
-  set (0, "defaultfigurepapertype", "<custom>");
-  set (0, "defaultfigurepaperorientation", "landscape");
-  set (0, "defaultfigurepapersize", image_size + 2*border);
-  set (0, "defaultfigurepaperposition", [border, border, image_size]);
+  set (groot, "defaultfigurepapertype", "<custom>");
+  set (groot, "defaultfigurepaperorientation", "landscape");
+  set (groot, "defaultfigurepapersize", image_size + 2*border);
+  set (groot, "defaultfigurepaperposition", [border, border, image_size]);
   ## FIXME: Required until listener for legend exists (bug #39697)
-  set (0, "defaultfigureposition", [ 72*[border, border, image_size] ]);
+  set (groot, "defaultfigureposition", [ 72*[border, border, image_size] ]);
 endfunction
 
 ## Use this function before plotting commands and after every call to print
--- a/doc/interpreter/plot.txi	Mon Dec 25 19:37:03 2017 -0800
+++ b/doc/interpreter/plot.txi	Mon Dec 25 22:13:41 2017 -0800
@@ -1171,12 +1171,13 @@
 
 The graphics objects are arranged in a hierarchy:
 
-1. The root is at 0.  In other words, @code{get (0)} returns the properties of
+1. The root object is returned by @code{groot} (historically, equivalent to
+the handle 0).  In other words, @code{get (groot)} returns the properties of
 the root object.
 
 2. Below the root are @code{figure} objects.
 
-3. Below the @code{figure} objects are @code{axes} objects.
+3. Below the @code{figure} objects are @code{axes} or @code{hggroup} objects.
 
 4. Below the @code{axes} objects are @code{line}, @code{text}, @code{patch},
 @code{surface}, @code{image}, and @code{light} objects.
@@ -1252,8 +1253,8 @@
 deletefcn              position
 @end smallexample
 
-The root figure has index 0.  Its properties may be displayed by:
-@code{get (0, "")}.
+The properties of the root figure may be displayed by:
+@code{get (groot, "")}.
 
 The uses of @code{get} and @code{set} are further explained in
 @ref{XREFget,,get}, @ref{XREFset,,set}.
@@ -1276,8 +1277,8 @@
 @item root figure
 @cindex root figure graphics object
 @cindex graphics object, root figure
-the top level of the hierarchy and the parent of all figure objects.
-The handle index of the root figure is 0.
+The top level of the hierarchy and the parent of all figure objects.
+Use @code{groot} to obtain the handle of the root graphics object.
 
 @item figure
 @cindex figure graphics object
@@ -1331,7 +1332,7 @@
 @code{light} functions.  These fundamental graphic objects automatically become
 children of the current axes object as if @code{hold on} was in place.
 Separately, axes will automatically become children of the current figure
-object and figures will become children of the root object 0.
+object and figures will become children of the root object.
 
 If this auto-joining feature is not desired then it is important to call
 @code{newplot} first to prepare a new figure and axes for plotting.
@@ -1372,6 +1373,8 @@
 current axes object, or creates one (and its parent figure object) if
 none exists.
 
+@DOCSTRING(groot)
+
 @DOCSTRING(gcf)
 
 @DOCSTRING(gca)
@@ -1383,7 +1386,7 @@
 
 @example
 @group
-get (0)
+get (groot)
     @result{} ans =
        @{
          type = root
@@ -1681,7 +1684,7 @@
 value.
 
 @example
-set (0, "defaultlinecolor", "green");
+set (groot, "defaultlinecolor", "green");
 @end example
 
 @noindent
@@ -1696,7 +1699,7 @@
 @code{defaultlinelinewidth"} specifies the default @code{linewidth}
 property for @code{line} objects.
 
-The example above used the root figure object, 0, so the default
+The example above used the root figure object so the default
 property value will apply to all line objects.  However, default values
 are hierarchical, so defaults set in a figure objects override those
 set in the root figure object.  Likewise, defaults set in axes objects
@@ -1705,7 +1708,7 @@
 @example
 @group
 subplot (2, 1, 1);
-set (0, "defaultlinecolor", "red");
+set (groot, "defaultlinecolor", "red");
 set (1, "defaultlinecolor", "green");
 set (gca (), "defaultlinecolor", "blue");
 line (1:10, rand (1, 10));
@@ -1753,7 +1756,7 @@
 command
 
 @example
-get (0, "factory");
+get (groot, "factory");
 @end example
 
 @noindent
--- a/doc/interpreter/plotimages.m	Mon Dec 25 19:37:03 2017 -0800
+++ b/doc/interpreter/plotimages.m	Mon Dec 25 22:13:41 2017 -0800
@@ -22,7 +22,7 @@
   hide_output ();
   outfile = fullfile (d, [nm "." typ]);
   if (strcmp (typ, "png"))
-    set (0, "defaulttextfontname", "*");
+    set (groot, "defaulttextfontname", "*");
   endif
   if (strcmp (typ, "eps"))
     d_typ = "-depsc2";
@@ -136,10 +136,10 @@
 function set_print_size ()
   image_size = [5.0, 3.5]; # in inches, 16:9 format
   border = 0;              # For postscript use 50/72
-  set (0, "defaultfigurepapertype", "<custom>");
-  set (0, "defaultfigurepaperorientation", "landscape");
-  set (0, "defaultfigurepapersize", image_size + 2*border);
-  set (0, "defaultfigurepaperposition", [border, border, image_size]);
+  set (groot, "defaultfigurepapertype", "<custom>");
+  set (groot, "defaultfigurepaperorientation", "landscape");
+  set (groot, "defaultfigurepapersize", image_size + 2*border);
+  set (groot, "defaultfigurepaperposition", [border, border, image_size]);
 endfunction
 
 ## Use this function before plotting commands and after every call to print
--- a/doc/interpreter/sparseimages.m	Mon Dec 25 19:37:03 2017 -0800
+++ b/doc/interpreter/sparseimages.m	Mon Dec 25 22:13:41 2017 -0800
@@ -22,7 +22,7 @@
   hide_output ();
   outfile = fullfile (d, [nm "." typ]);
   if (strcmp (typ, "png"))
-    set (0, "defaulttextfontname", "*");
+    set (groot, "defaulttextfontname", "*");
   endif
   if (strcmp (typ, "eps"))
     d_typ = "-depsc2";
@@ -257,10 +257,10 @@
 function set_print_size ()
   image_size = [5.0, 3.5]; # in inches, 16:9 format
   border = 0;              # For postscript use 50/72
-  set (0, "defaultfigurepapertype", "<custom>");
-  set (0, "defaultfigurepaperorientation", "landscape");
-  set (0, "defaultfigurepapersize", image_size + 2*border);
-  set (0, "defaultfigurepaperposition", [border, border, image_size]);
+  set (groot, "defaultfigurepapertype", "<custom>");
+  set (groot, "defaultfigurepaperorientation", "landscape");
+  set (groot, "defaultfigurepapersize", image_size + 2*border);
+  set (groot, "defaultfigurepaperposition", [border, border, image_size]);
 endfunction
 
 ## Use this function before plotting commands and after every call to print
--- a/doc/interpreter/splineimages.m	Mon Dec 25 19:37:03 2017 -0800
+++ b/doc/interpreter/splineimages.m	Mon Dec 25 22:13:41 2017 -0800
@@ -22,7 +22,7 @@
   hide_output ();
   outfile = fullfile (d, [nm "." typ]);
   if (strcmp (typ, "png"))
-    set (0, "defaulttextfontname", "*");
+    set (groot, "defaulttextfontname", "*");
   endif
   if (strcmp (typ, "eps"))
     d_typ = "-depsc2";
@@ -188,12 +188,12 @@
 function set_print_size ()
   image_size = [8.0, 6.0]; # in inches, 4:3 format
   border = 0;              # For postscript use 50/72
-  set (0, "defaultfigurepapertype", "<custom>");
-  set (0, "defaultfigurepaperorientation", "landscape");
-  set (0, "defaultfigurepapersize", image_size + 2*border);
-  set (0, "defaultfigurepaperposition", [border, border, image_size]);
+  set (groot, "defaultfigurepapertype", "<custom>");
+  set (groot, "defaultfigurepaperorientation", "landscape");
+  set (groot, "defaultfigurepapersize", image_size + 2*border);
+  set (groot, "defaultfigurepaperposition", [border, border, image_size]);
   ## FIXME: Required until listener for legend exists (bug #39697)
-  set (0, "defaultfigureposition", [ 72*[border, border, image_size] ]);
+  set (groot, "defaultfigureposition", [ 72*[border, border, image_size] ]);
 endfunction
 
 ## Use this function before plotting commands and after every call to print
--- a/scripts/plot/util/gcf.m	Mon Dec 25 19:37:03 2017 -0800
+++ b/scripts/plot/util/gcf.m	Mon Dec 25 22:13:41 2017 -0800
@@ -45,7 +45,7 @@
 ## object.
 ##
 ## @example
-## get (0, "currentfigure");
+## get (groot, "currentfigure");
 ## @end example
 ##
 ## @seealso{gca, gco, gcbf, gcbo, get, set}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/util/groot.m	Mon Dec 25 22:13:41 2017 -0800
@@ -0,0 +1,66 @@
+## Copyright (C) 2017 Rik Wehbring
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {} {@var{h} =} groot ()
+## Return a handle to the root graphics object.
+##
+## The root graphics object is the ultimate parent of all graphics objects.
+##
+## In addition, the root object contains information about the graphics
+## system as a whole such as the @code{ScreenSize}.  Use @w{@code{get (groot)}}
+## to find out what information is available.
+##
+## Defaults for the graphic system as a whole are specified by setting
+## properties of the root graphics object that begin with @qcode{"Default"}.
+## For example, to set the default font for all text objects to FreeSans use
+##
+## @example
+## set (groot, "DefaultTextFontName", "FreeSans")
+## @end example
+##
+## Default properties can be deleted by using @code{set} with the special
+## property value of @qcode{"remove"}.  To undo the default font assignment
+## above use
+##
+## @example
+## set (groot, "DefaultTextFontName", "remove")
+## @end example
+##
+## Programming Note: The root graphics object is identified by the special
+## handle value of 0.  At some point this unique value may change, but code can
+## be made resistant to future changes by using @code{groot} which is
+## guaranteed to always return the root graphics object.
+## @seealso{gcf, gca, get, set}
+## @end deftypefn
+
+function h = groot ()
+
+  if (nargin != 0)
+    print_usage ();
+  endif
+
+  h = 0;
+
+endfunction
+
+
+%!assert (groot (), 0)
+
+## Test input validation
+%!error groot (1)
--- a/scripts/plot/util/module.mk	Mon Dec 25 19:37:03 2017 -0800
+++ b/scripts/plot/util/module.mk	Mon Dec 25 22:13:41 2017 -0800
@@ -52,6 +52,7 @@
   %reldir%/gco.m \
   %reldir%/ginput.m \
   %reldir%/graphics_toolkit.m \
+  %reldir%/groot.m \
   %reldir%/hdl2struct.m \
   %reldir%/hggroup.m \
   %reldir%/hgload.m \