# 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