octave_packages/m/plot/hold.m

   1 ## Copyright (C) 2005-2012 John W. Eaton
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Command} {} hold
  21 ## @deftypefnx {Command} {} hold @var{state}
  22 ## @deftypefnx {Function File} {} hold (@var{hax}, @dots{})
  23 ## Toggle or set the 'hold' state of the plotting engine which determines
  24 ## whether new graphic objects are added to the plot or replace the existing
  25 ## objects.
  26 ##
  27 ## @table @code
  28 ## @item hold on
  29 ## Retain plot data and settings so that subsequent plot commands are displayed
  30 ## on a single graph.
  31 ##
  32 ## @item hold all
  33 ## Retain plot line color, line style, data and settings so that subsequent
  34 ## plot commands are displayed on a single graph with the next line color and
  35 ## style.
  36 ##
  37 ## @item hold off
  38 ## Clear plot and restore default graphics settings before each new plot
  39 ## command.  (default).
  40 ##
  41 ## @item hold
  42 ## Toggle the current 'hold' state.
  43 ## @end table
  44 ##
  45 ## When given the additional argument @var{hax}, the hold state is modified
  46 ## only for the given axis handle.
  47 ##
  48 ## To query the current 'hold' state use the @code{ishold} function.
  49 ## @seealso{ishold, cla, newplot, clf}
  50 ## @end deftypefn
  51
  52 function hold (varargin)
  53
  54   if (nargin > 0 && numel (varargin{1}) == 1 && ishandle (varargin{1})
  55       && strcmp (get (varargin{1}, "type"), "axes"))
  56     [ax, varargin, nargs] = __plt_get_axis_arg__ ("hold", varargin{:});
  57     fig = get (ax, "parent");
  58   elseif (nargin > 0 && numel (varargin{1}) > 1 && ishandle (varargin{1}))
  59     print_usage ();
  60   else
  61     ax = gca ();
  62     fig = gcf ();
  63     nargs = numel (varargin);
  64   endif
  65
  66   hold_all = false;
  67   if (nargs == 0)
  68     turn_hold_off = ishold (ax);
  69   elseif (nargs == 1)
  70     state = varargin{1};
  71     if (ischar (state))
  72       if (strcmpi (state, "off"))
  73         turn_hold_off = true;
  74       elseif (strcmpi (state, "all"))
  75         turn_hold_off = false;
  76         hold_all = true;
  77       elseif (strcmpi (state, "on"))
  78         turn_hold_off = false;
  79       else
  80         error ("hold: invalid hold STATE");
  81       endif
  82     endif
  83   else
  84     print_usage ();
  85   endif
  86
  87   if (turn_hold_off)
  88     set (ax, "nextplot", "replace");
  89   else
  90     set (ax, "nextplot", "add");
  91     set (fig, "nextplot", "add");
  92   endif
  93   set (ax, "__hold_all__", hold_all);
  94
  95 endfunction
  96
  97 %!demo
  98 %! clf
  99 %! A = rand (100);
 100 %! [X, Y] = find (A > 0.9);
 101 %! imshow (A)
 102 %! hold on
 103 %! plot (X, Y, 'o')
 104 %! hold off
 105
 106 %!demo
 107 %! clf
 108 %! hold on
 109 %! imagesc(1./hilb(4));
 110 %! plot (1:4, "-s")
 111 %! hold off
 112
 113 %!demo
 114 %! clf
 115 %! hold on
 116 %! imagesc(1./hilb(2));
 117 %! imagesc(1./hilb(4));
 118 %! hold off
 119
 120 %!demo
 121 %! clf
 122 %! hold on
 123 %! plot (1:4, "-s")
 124 %! imagesc(1./hilb(4));
 125 %! hold off
 126
 127 %!demo
 128 %! clf
 129 %! colormap (jet)
 130 %! t = linspace (-3, 3, 50);
 131 %! [x, y] = meshgrid (t, t);
 132 %! z = peaks (x, y);
 133 %! contourf (x, y, z, 10);
 134 %! hold ("on");
 135 %! plot (vec (x), vec (y), "^");
 136 %! patch ([-1.0 1.0 1.0 -1.0 -1.0], [-1.0 -1.0 1.0 1.0 -1.0], "red");
 137 %! xlim ([-2.0 2.0]);
 138 %! ylim ([-2.0 2.0]);
 139 %! colorbar ("SouthOutside");
 140 %! title ("Test script for some plot functions");
 141
 142 ##hold on
 143 %!test
 144 %! hf = figure ("visible", "off");
 145 %! unwind_protect
 146 %!   p = plot ([0 1]);
 147 %!   assert (!ishold);
 148 %!   hold on;
 149 %!   assert (ishold);
 150 %!   p1 = fill ([0 1 1], [0 0 1],"black");
 151 %!   p2 = fill ([0 1 0], [0 1 1], "red");
 152 %!   assert (length (get (hf, "children")), 1);
 153 %!   assert (length (get (gca, "children")), 3);
 154 %! unwind_protect_cleanup
 155 %!   close (hf);
 156 %! end_unwind_protect
 157
 158 ##hold off
 159 %!test
 160 %! hf = figure ("visible", "off");
 161 %! unwind_protect
 162 %!   p = plot ([0 1]);
 163 %!   assert (!ishold);
 164 %!   hold on;
 165 %!   assert (ishold);
 166 %!   p1 = fill ([0 1 1], [0 0 1],"black");
 167 %!   hold off
 168 %!   p2 = fill ([0 1 0], [0 1 1], "red");
 169 %!   assert (length (get (hf, "children")), 1);
 170 %!   assert (length (get (gca, "children")), 1);
 171 %! unwind_protect_cleanup
 172 %!   close (hf);
 173 %! end_unwind_protect