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:

string, signature of waitbar

double, progress (in % ==> range = 0-100)
    Note: set x to NaN for indefinite waitbar

string, text above waitbar
    Note: the space reserve for this text is determined at startup
    of waitbar

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:

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