1
## Copyright (C) 2005-2013 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 {Function File} {} newplot ()
21
## @deftypefnx {Function File} {} newplot (@var{hfig})
22
## @deftypefnx {Function File} {} newplot (@var{hax})
23
## @deftypefnx {Function File} {@var{hax} =} newplot (@dots{})
24
## Prepare graphics engine to produce a new plot.
26
## This function is called at the beginning of all high-level plotting
27
## functions. It is not normally required in user programs. @code{newplot}
28
## queries the @qcode{"NextPlot"} field of the current figure and axis to
29
## determine what to do.
31
## @multitable @columnfractions .25 .75
32
## @headitem Figure NextPlot @tab Action
33
## @item @qcode{"new"} @tab Create a new figure and make it the current figure.
35
## @item @qcode{"add"} (default) @tab Add new graphic objects to the current figure.
37
## @item @qcode{"replacechildren"} @tab Delete child objects whose HandleVisibility is
38
## set to @qcode{"on"}. Set NextPlot property to @qcode{"add"}. This
39
## typically clears a figure, but leaves in place hidden objects such as
40
## menubars. This is equivalent to @code{clf}.
42
## @item @qcode{"replace"} @tab Delete all child objects of the figure and
43
## reset all figure properties to their defaults. However, the following
44
## four properties are not reset: Position, Units, PaperPosition, PaperUnits.
45
## This is equivalent to @code{clf reset}.
48
## @multitable @columnfractions .25 .75
49
## @headitem Axis NextPlot @tab Action
50
## @item @qcode{"add"} @tab Add new graphic objects to the current axes. This is
51
## equivalent to @code{hold on}.
53
## @item @qcode{"replacechildren"} @tab Delete child objects whose HandleVisibility is
54
## set to @qcode{"on"}, but leave axis properties unmodified. This typically
55
## clears a plot, but preserves special settings such as log scaling for
56
## axes. This is equivalent to @code{cla}.
58
## @item @qcode{"replace"} (default) @tab Delete all child objects of the
59
## axis and reset all axis properties to their defaults. However, the
60
## following properties are not reset: Position, Units. This is equivalent
61
## to @code{cla reset}.
64
## If the optional input @var{hfig} or @var{hax} is given then prepare the
65
## specified figure or axes rather than the current figure and axes.
67
## The optional return value @var{hax} is a graphics handle to the created
68
## axes object (not figure).
70
## @strong{Caution:} Calling @code{newplot} may change the current figure and
74
## FIXME: The Matlab function takes an optional list of file handles, hsave,
75
## which are not deleted when the figure and axes are prepared.
76
## I'm sure there is a good reason for that, but coding such
77
## compatibility is really tricky and doesn't serve much purpose since
78
## newplot is nearly exclusively used by Octave's internal plotting
79
## functions. In Octave's case the argument is almost always null,
80
## or occasionally the axis handle to plot into.
82
function hax = newplot (hsave = [])
91
if (! isempty (hsave))
92
## Find the first valid axes
93
ca = ancestor (hsave, "axes", "toplevel");
97
ca = ca(find (ca, 1));
98
hsave(hsave == ca) = [];
99
## Next, find the figure associated with any axis found
101
cf = ancestor (ca, "figure", "toplevel");
103
cf = ancestor (hsave, "figure", "toplevel");
107
cf = cf(find (cf, 1));
112
## get current figure, or create a new one if necessary
115
## switch to figure provided without causing other updates
116
set (0, "currentfigure", cf);
119
fnp = get (cf, "nextplot");
122
## Default case. Doesn't require action.
124
## Ordinarily, create a new figure to hold plot.
125
## But, if user has requested preparing a specific axis, then
126
## use the existing figure to hold the requested axis.
130
case "replacechildren"
131
kids = get (cf, "children");
133
kids(kids == ca) = [];
137
kids = allchild (cf);
139
kids(kids == ca) = [];
144
set (cf, "nextplot", "add"); # Matlab compatibility
150
set (cf, "currentaxes", ca);
154
## FIXME: Is this necessary anymore?
155
## It seems like a kluge that belongs somewhere else.
156
if (strcmp (get (ca, "__hold_all__"), "off"))
157
__next_line_color__ (true);
158
__next_line_style__ (true);
160
__next_line_color__ (false);
161
__next_line_style__ (false);
164
anp = get (ca, "nextplot");
167
## Default case. Doesn't require action.
168
case "replacechildren"
169
if (! deleteall && ca != hsave)
170
## preserve hsave and its parents, uncles, ...
171
kids = allchild (ca);
173
while (! any (hkid == kids))
174
hkid = get (hkid, "parent");
176
kids(kids == hkid) = [];
179
delete (get (ca, "children"));
182
if (! deleteall && ca != hsave)
183
## preserve hsave and its parents, uncles, ...
184
kids = allchild (ca);
186
while (! any (hkid == kids))
187
hkid = get (hkid, "parent");
189
kids(kids == hkid) = [];
192
__go_axes_init__ (ca, "replace");
193
__request_drawnow__ ();
195
## FIXME: The code above should perform the following:
196
###########################
197
## delete (allchild (ca));
199
###########################
200
## Actually, __go_axes_init__ does both less and more.
201
## It doesn't really remove all children since it re-instantiates
202
## xlabel, ylabel, zlabel, and title text objects.
203
## Also it preserves font properties like fontsize.
204
## For the time being, in order to have axis labels and title work,
205
## the above code is is required.
216
%! hf = figure ("visible", "off");
218
%! p = plot ([0, 1]);
220
%! assert (hax, gca);
221
%! assert (isempty (get (gca, "children")));
222
%! unwind_protect_cleanup
224
%! end_unwind_protect
227
%! hf = figure ("visible", "off");
232
%! hg2 = hggroup ("parent", hg1);
233
%! li0 = line (1:10, 1:10);
234
%! li1 = line (1:10, -1:-1:-10, "parent", hg1);
235
%! li2 = line (1:10, sin (1:10), "parent", hg2);
238
%! assert (ishandle (li0), false);
239
%! assert (get (hax, "children"), hg1);
241
%! ## kids are preserved for hggroups
242
%! kids = get (hg1, "children");
244
%! assert (get (hg1, "children"), kids);
246
%! ## preserve objects
248
%! assert (ishandle (li1));
250
%! ## kids are deleted for axes
252
%! assert (isempty (get (hax, "children")));
253
%! unwind_protect_cleanup
255
%! end_unwind_protect
added
removed
scripts/plot/util/newplot.m
