1 ## Copyright (C) 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 {Function File} {@var{h} =} waitbar (@var{frac})
21 ## @deftypefnx {Function File} {@var{h} =} waitbar (@var{frac}, @var{msg})
22 ## @deftypefnx {Function File} {@var{h} =} waitbar (@dots{}, "FigureProperty", "Value", @dots{})
23 ## @deftypefnx {Function File} {} waitbar (@var{frac})
24 ## @deftypefnx {Function File} {} waitbar (@var{frac}, @var{hwbar})
25 ## @deftypefnx {Function File} {} waitbar (@var{frac}, @var{hwbar}, @var{msg})
26 ## Return a handle @var{h} to a new waitbar object. The waitbar is
27 ## filled to fraction @var{frac} which must be in the range [0, 1]. The
28 ## optional message @var{msg} is centered and displayed above the waitbar.
29 ## The appearance of the waitbar figure window can be configured by passing
30 ## property/value pairs to the function.
32 ## When called with a single input the current waitbar, if it exists, is
33 ## updated to the new value @var{frac}. If there are multiple outstanding
34 ## waitbars they can be updated individually by passing the handle @var{hwbar}
35 ## of the specific waitbar to modify.
40 function retval = waitbar (varargin)
42 persistent curr_waitbar;
51 if (! (isnumeric (frac) && isscalar (frac) && frac >= 0 && frac <= 1))
52 error ("waitbar: FRAC must be between 0 and 1");
55 ## Use existing waitbar if it still points to a valid graphics handle.
56 if (nargin == 1 && ishandle (curr_waitbar))
62 if (! isempty (varargin) && isnumeric (varargin{1}))
63 if (! ishandle (varargin{1}))
64 error ("waitbar: H must be a handle to a waitbar object");
68 if (! isfigure (h) || ! strcmp (get (h, "tag"), "waitbar"))
69 error ("waitbar: H must be a handle to a waitbar object");
76 if (! isempty (varargin))
79 if (! (ischar (msg) || iscellstr (msg)))
80 error ("waitbar: MSG must be a character string or cell array of strings");
84 if (rem (numel (varargin), 2) != 0)
85 error ("waitbar: invalid number of property-value pairs");
89 p = findobj (h, "type", "patch");
90 set (p, "xdata", [0; frac; frac; 0]);
91 ax = findobj (h, "type", "axes");
92 if (ischar (msg) || iscellstr (msg))
93 th = get (ax, "title");
94 curr_msg = get (th, "string");
95 ## graphics handles always store data as column vectors
99 cmp = strcmp (msg, curr_msg);
101 set (th, "string", msg);
105 h = __go_figure__ (NaN, "position", [250, 500, 400, 100],
106 "numbertitle", "off",
107 "toolbar", "none", "menubar", "none",
108 "integerhandle", "off",
109 "handlevisibility", "callback",
113 ax = axes ("parent", h, "xtick", [], "ytick", [],
114 "xlim", [0, 1], "ylim", [0, 1],
115 "xlimmode", "manual", "ylimmode", "manual",
116 "position", [0.1, 0.3, 0.8, 0.2]);
118 patch (ax, [0; frac; frac; 0], [0; 0; 1; 1], [0, 0.35, 0.75]);
120 if (! (ischar (msg) || iscellstr (msg)))
121 msg = "Please wait...";
132 ## If there were no errors, update current waitbar.
139 %! h = waitbar (0, "0.00%");
141 %! waitbar (i, h, sprintf ("%.2f%%", 100*i));
146 %! h = waitbar (0, "please wait...");
147 %! for i = 0:0.01:0.6
151 %! waitbar (i, h, "don't you hate taking a step backward?")
153 %! for i = i:0.005:0.7
156 %! waitbar (i, h, "or stalling?")
158 %! for i = i:0.003:0.8
159 %! waitbar (i, h, "just a little longer now")
162 %! waitbar (i, h, "please don't be impatient")
167 %! h1 = waitbar (0, "Waitbar #1");
168 %! h2 = waitbar (0, "Waitbar #2");
169 %! h2pos = get (h2, "position");
170 %! h2pos(1) += h2pos(3) + 50;
171 %! set (h2, "position", h2pos);
174 %! waitbar (i/4, h1);
176 %! waitbar (i/4, h2);
183 %% Test input validation
184 %!error <FRAC must be between 0 and 1> waitbar (-0.5)
185 %!error <FRAC must be between 0 and 1> waitbar (1.5)
186 %!error <MSG must be a character string> waitbar (0.5, struct ())
187 %!error <invalid number of property-value pairs> waitbar (0.5, "msg", "Name")