# HG changeset patch
# User Rik <octave@nomad.inbox5.com>
# Date 1320339297 25200
# Node ID b3cdef33ac0e469909736bce1711b73f4c82932c
# Parent  4f112bebd474ae4463c5a4de98255741aa08eff5
waitbar.m: Update docstring.  Only return output handle h if requested.

* waitbar.m: Update docstring.  Only return output handle h if requested.
Don't delete message from waitbar window when only FRAC is updated.
Add input validation tests.

diff --git a/scripts/plot/waitbar.m b/scripts/plot/waitbar.m
--- a/scripts/plot/waitbar.m
+++ b/scripts/plot/waitbar.m
@@ -17,83 +17,99 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {@var{h} =} waitbar (@var{frac}, @var{msg})
-## @deftypefnx {Function File} {@var{h} =} waitbar (@var{frac}, @var{h}, @var{msg})
-## Craete a waitbar and display an optional message.
+## @deftypefn  {Function File} {} waitbar (@var{frac})
+## @deftypefn  {Function File} {} waitbar (@var{frac}, @var{msg})
+## @deftypefnx {Function File} {} waitbar (@var{frac}, @var{h}, @dots{})
+## @deftypefnx {Function File} {} waitbar (@dots{}, "FigureProperty", "Value", @dots{})
+## @deftypefnx {Function File} {@var{h} = } waitbar (@dots{})
+## Create a waitbar filled to fraction @var{frac} and display an optional
+## message @var{msg}.  The waitbar fraction must be in the range [0, 1].  If
+## the optional input @var{h} is specified then update the waitbar in the
+## specified figure handle.  Otherwise, a new waitbar is created.
+##
+## The display of the waitbar window can be configured by passing 
+## property/value pairs to the function.
 ## @end deftypefn
 
 ## Author: jwe
 
-function h = waitbar (varargin)
+function retval = waitbar (varargin)
+
+  if (nargin < 1)
+    print_usage ();
+  endif
 
-  msg = " ";
+  frac = varargin{1};
+  varargin(1) = [];
 
+  if (! (isnumeric (frac) && isscalar (frac) && frac >= 0 && frac <= 1))
+    error ("waitbar: FRAC must be between 0 and 1");
+  endif
+
+  msg = false;
   h = 0;
 
-  if (nargin > 0)
-
-    frac = varargin{1};
+  if (! isempty (varargin) && ishandle (varargin{1}))
+    h = varargin{1};
     varargin(1) = [];
-
-    if (! (isnumeric (frac) && isscalar (frac) && frac >= 0 && frac <= 1))
-      error ("waitbar: frac must be in between 0 and 1");
+    ## FIXME -- also check that H is really a waitbar?
+    if (! isfigure (h))
+      error ("waitbar: H must be a handle to a waitbar object");
     endif
+  endif
 
-    if (numel (varargin) > 0 && ishandle (varargin{1}))
-      h = varargin{1};
-      varargin(1) = [];
-      ## FIXME -- also check that H is really a waitbar?
-      if (! isfigure (h))
-        error ("handle must be a waitbar object");
-      endif
+  if (! isempty (varargin))
+    msg = varargin{1};
+    varargin(1) = [];
+    if (! ischar (msg))
+      error ("waitbar: MSG must be a character string");
     endif
+  endif
 
-    if (numel (varargin) > 0)
-      msg = varargin{1};
-      varargin(1) = [];
-      if (! ischar (msg))
-        error ("waitbar: msg must be a character string");
-      endif
-    endif
+  if (rem (numel (varargin), 2) != 0)
+    error ("waitbar: invalid number of property-value pairs");
+  endif
 
-    if (rem (numel (varargin), 2) != 0)
-      error ("waitbar: invalid number of property-value pairs");
+  if (h)
+    p = findobj (h, "type", "patch");
+    if (p)
+      delete (p);
     endif
+    ax = findobj (h, "type", "axes");
+  else
+    h = __go_figure__ (Inf, "position", [250, 500, 400, 100],
+                       "numbertitle", "off",
+                       "handlevisibility", "callback",
+                       varargin{:});
 
-    if (h)
-      p = findobj (h, "type", "patch");
-      if (p)
-        delete (p);
-      endif
-      ax = findobj (h, "type", "axes");
-    else
-      h = __go_figure__ (Inf, "position", [250, 500, 400, 100],
-                         "numbertitle", "off",
-                         "handlevisibility", "callback",
-                         varargin{:});
+    ax = axes ("parent", h, "xtick", [], "ytick", [],
+               "xlim", [0, 1], "ylim", [0, 1],
+               "xlimmode", "manual", "ylimmode", "manual",
+               "position", [0.1, 0.3, 0.8, 0.2]);
+  endif
 
-      ax = axes ("parent", h, "xtick", [], "ytick", [],
-                 "xlim", [0, 1], "ylim", [0, 1],
-                 "xlimmode", "manual", "ylimmode", "manual",
-                 "position", [0.1, 0.3, 0.8, 0.2]);
-    endif
+  patch (ax, [0, frac, frac, 0], [0, 0, 1, 1], [0, 0.35, 0.75]);
+  if (ischar (msg))
+    title (ax, msg);
+  endif
+  drawnow ();
 
-    patch (ax, [0, frac, frac, 0], [0, 0, 1, 1], [0, 0.35, 0.75]);
-    title (ax, msg);
-    drawnow ();
-
-  else
-    print_usage ();
+  if (nargout > 0)
+    retval = h;
   endif
 
 endfunction
 
+
 %!demo
-%! h = 0;
+%! h = waitbar (0, "0.00%");
 %! for i = 0:0.01:1
-%!   if (h)
-%!     waitbar (i, h, sprintf ("%.2f%%", 100*i));
-%!   else
-%!     h = waitbar (i, sprintf ("%.2f%%", 100*i));
-%!   endif
+%!   waitbar (i, h, sprintf ("%.2f%%", 100*i));
 %! endfor
+
+%% Test input validation
+%!error <FRAC must be between 0 and 1> waitbar (-0.5)
+%!error <FRAC must be between 0 and 1> waitbar (1.5)
+%!error <MSG must be a character string> waitbar (0.5, 1)
+%!error <invalid number of property-value pairs> waitbar (0.5, "msg", "Name")
+