1 ## Copyright (C) 2005-2012 John W. Eaton
3 ## This file is part of Octave.
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.
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.
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/>.
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
29 ## Retain plot data and settings so that subsequent plot commands are displayed
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
38 ## Clear plot and restore default graphics settings before each new plot
39 ## command. (default).
42 ## Toggle the current 'hold' state.
45 ## When given the additional argument @var{hax}, the hold state is modified
46 ## only for the given axis handle.
48 ## To query the current 'hold' state use the @code{ishold} function.
49 ## @seealso{ishold, cla, newplot, clf}
52 function hold (varargin)
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}))
63 nargs = numel (varargin);
68 turn_hold_off = ishold (ax);
72 if (strcmpi (state, "off"))
74 elseif (strcmpi (state, "all"))
75 turn_hold_off = false;
77 elseif (strcmpi (state, "on"))
78 turn_hold_off = false;
80 error ("hold: invalid hold STATE");
88 set (ax, "nextplot", "replace");
90 set (ax, "nextplot", "add");
91 set (fig, "nextplot", "add");
93 set (ax, "__hold_all__", hold_all);
100 %! [X, Y] = find (A > 0.9);
109 %! imagesc(1./hilb(4));
116 %! imagesc(1./hilb(2));
117 %! imagesc(1./hilb(4));
124 %! imagesc(1./hilb(4));
130 %! t = linspace (-3, 3, 50);
131 %! [x, y] = meshgrid (t, t);
133 %! contourf (x, y, z, 10);
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");
144 %! hf = figure ("visible", "off");
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
156 %! end_unwind_protect
160 %! hf = figure ("visible", "off");
166 %! p1 = fill ([0 1 1], [0 0 1],"black");
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
173 %! end_unwind_protect