Function: multiwaitbar

CALL:

HWIN = multiwaitbar(bartag, x, wbtext, varargin) HWIN = multiwaitbar(bartag, x, wbtext, 'stopb', 'abort', varargin) HWIN = multiwaitbar(bartag, x, wbtext, 'suspb', 'abort', varargin) HWIN = multiwaitbar(bartag, x, wbtext, 'message', 'msg', varargin) HWIN = multiwaitbar(bartag, x) HWIN = multiwaitbar(bartag, -1) (kill waitbar identified with "bartag") HWIN = multiwaitbar(-1) (kill figure, including waitbars)

DESCRIPTION:

Plot one or more waitbars in a unique figure

INPUT:

bartag any
string, signature of waitbar
x any
double, progress (in % ==> range = 0-100)
    Note: set x to NaN for indefinite waitbar
wbtext any
string, text above waitbar
    Note: the space reserve for this text is determined at startup
    of waitbar
varargin any
properties to be passed on to the "figure" command (has no effect
when figure already exists)

SPECIAL KEYWORDS:
    'alignfigure',FIGHANDLE
        Waitbar will be alligned with figure FIGHANDLE. Default
        behavior: waitbar will align woth current figure. Note:
        when working with hidden figures; define this property to
        avoid waitbar from being hidden.
    'stepsize',VALUE
        changes default stepsize to VALUE. All calls will be
        ignored, unless rem(x,VALUE)==0.
    'stopb','abort'
        adds a stopbutton with text 'abort'
    'suspb','abort'
        adds a suspend button with text 'abort' this works
        together with function "stopwaitbar"

OUTPUT:

HWIN any
handle of the figure with the waitbar(s)

EXAMPLE:

    multiwaitbar('uniqueTag',10,'10%','name','example')
 
  EXAMPLE 1:
  multiwaitbar('loop1',0,'Initialising...','name','Check');
  tmp1=onCleanup(@()multiwaitbar('loop1',-1))
  tmp2=onCleanup(@()multiwaitbar('loop2',-1))
      for k=1:(5)
          multiwaitbar('loop1',100*(k-.5)/5,sprintf('k=%d',k));
          for r=1:5:100
               if stopwaitbar(hwait),return;end
              multiwaitbar('loop2',r,sprintf('r=%d',r));
              pause(0.01)
          end
      end
 
  EXAMPLE 2:
  % (display remaining waiting time):
  hwait=multiwaitbar('loop1',0,'Initialising...','name','Check');
  tmp1=onCleanup(@()multiwaitbar('loop1',-1))
  t0=clock;
  tm=t0;
  for k=1:length(vl)
      %<do task k>
      pause(0.1);
      if rem(k,100)==0&&etime(clock,tm)>1 %etime(clock) is CPU hungry
          if stopwaitbar(hwait),return;end
          %- k tasks done;
          %- etime(clock,t0) time spent;
          %- length(vl)-k tasks due;
          %- expected remaining time: (length(vl)-k)*etime(clock,t0)/k
          multiwaitbar('loop1',100*(k)/length(vl),...
              sprintf('About %.0f seconds remaining',(length(vl)-k)* etime(clock,t0)/k));
          tm=clock; %store "tm" for timing next message
      end
  end
 
  EXAMPLE 3:
  only display when progress is at least 1 %. In this way the total number
  of calls to multiwaitbar is limited. There may be a long time between
  consecutive updates multiwaitbar. Use example 2 when this is a problem.
  (Example 2 displays remaining expected time.)
      vl=1:1000;
      tmp1=onCleanup(@()multiwaitbar('loop1',-1));
      P=0; %progress percentage
      hwait=multiwaitbar('loop1',P,'Initialising...','name','Check');
      t0=clock;
      tm=t0;
      for k=1:length(vl)
          Pnew=round(100*(k)/length(vl));
          if Pnew~=P
              P=Pnew;
              multiwaitbar('loop1',P,...
                  sprintf('Progress = %d%%',P));
              pause(.01)
          end
      end