Mercurial > octave
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 \