octave_packages/m/plot/waitbar.m

   1 ## Copyright (C) 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  {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.
  31 ##
  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.
  36 ## @end deftypefn
  37
  38 ## Author: jwe
  39
  40 function retval = waitbar (varargin)
  41
  42   persistent curr_waitbar;
  43
  44   if (nargin < 1)
  45     print_usage ();
  46   endif
  47
  48   frac = varargin{1};
  49   varargin(1) = [];
  50
  51   if (! (isnumeric (frac) && isscalar (frac) && frac >= 0 && frac <= 1))
  52     error ("waitbar: FRAC must be between 0 and 1");
  53   endif
  54
  55   ## Use existing waitbar if it still points to a valid graphics handle.
  56   if (nargin == 1 && ishandle (curr_waitbar))
  57     h = curr_waitbar;
  58   else
  59     h = false;
  60   endif
  61
  62   if (! isempty (varargin) && isnumeric (varargin{1}))
  63     if (! ishandle (varargin{1}))
  64       error ("waitbar: H must be a handle to a waitbar object");
  65     else
  66       h = varargin{1};
  67       varargin(1) = [];
  68       if (! isfigure (h) || ! strcmp (get (h, "tag"), "waitbar"))
  69         error ("waitbar: H must be a handle to a waitbar object");
  70       endif
  71     endif
  72   endif
  73
  74   msg = false;
  75
  76   if (! isempty (varargin))
  77     msg = varargin{1};
  78     varargin(1) = [];
  79     if (! (ischar (msg) || iscellstr (msg)))
  80       error ("waitbar: MSG must be a character string or cell array of strings");
  81     endif
  82   endif
  83
  84   if (rem (numel (varargin), 2) != 0)
  85     error ("waitbar: invalid number of property-value pairs");
  86   endif
  87
  88   if (h)
  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
  96       if (iscellstr (msg))
  97         msg = msg(:);
  98       endif
  99       cmp = strcmp (msg, curr_msg);
 100       if (! all (cmp(:)))
 101         set (th, "string", msg);
 102       endif
 103     endif
 104   else
 105     h = __go_figure__ (NaN, "position", [250, 500, 400, 100],
 106                        "numbertitle", "off",
 107                        "toolbar", "none", "menubar", "none",
 108                        "integerhandle", "off",
 109                        "handlevisibility", "callback",
 110                        "tag", "waitbar",
 111                        varargin{:});
 112
 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]);
 117
 118     patch (ax, [0; frac; frac; 0], [0; 0; 1; 1], [0, 0.35, 0.75]);
 119
 120     if (! (ischar (msg) || iscellstr (msg)))
 121       msg = "Please wait...";
 122     endif
 123     title (ax, msg);
 124   endif
 125
 126   drawnow ();
 127
 128   if (nargout > 0)
 129     retval = h;
 130   endif
 131
 132   ## If there were no errors, update current waitbar.
 133   curr_waitbar = h;
 134
 135 endfunction
 136
 137
 138 %!demo
 139 %! h = waitbar (0, "0.00%");
 140 %! for i = 0:0.01:1
 141 %!   waitbar (i, h, sprintf ("%.2f%%", 100*i));
 142 %! endfor
 143 %! close (h);
 144
 145 %!demo
 146 %! h = waitbar (0, "please wait...");
 147 %! for i = 0:0.01:0.6
 148 %!   waitbar (i);
 149 %! endfor
 150 %! i = 0.3;
 151 %! waitbar (i, h, "don't you hate taking a step backward?")
 152 %! pause (0.5);
 153 %! for i = i:0.005:0.7
 154 %!   waitbar (i, h);
 155 %! endfor
 156 %! waitbar (i, h, "or stalling?")
 157 %! pause (1);
 158 %! for i = i:0.003:0.8
 159 %!   waitbar (i, h, "just a little longer now")
 160 %! endfor
 161 %! for i = i:0.001:1
 162 %!   waitbar (i, h, "please don't be impatient")
 163 %! endfor
 164 %! close (h);
 165
 166 %!demo
 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);
 172 %! pause (0.5);
 173 %! for i = 1:4
 174 %!   waitbar (i/4, h1);
 175 %!   pause (0.5);
 176 %!   waitbar (i/4, h2);
 177 %!   pause (0.5);
 178 %! endfor
 179 %! pause (0.5);
 180 %! close (h1);
 181 %! close (h2);
 182
 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")
 188