progressbar.m

GUI for Multivariate Image Analysis of 4-dimensional data (Matlab Code)

function [varargout] = progressbar(action, varargin)
%PROGRESSBAR Display, modify, and/or update a progress indicator
%   PROGRESSBAR is a comprehensive progress indicator for long or
%   repetitive calculations.  It allows the user to display any
%   title or message, the start time, the elapsed time, and an
%   estimate of the time remaining, as well as progress - all
%   while comsuming minimal execution time.
%
%   PROGRESSBAR is a multi-function fuction, where the first
%   argument is an action string specifying what function to
%   carry out:
%
%   H = PROGRESSBAR is the same as H = PROGRESSBAR('create').
%
%   H = PROGRESSBAR('create', ['TITLE'], ['MESSAGE']) creates
%   and initializes the progress indicator.  The figure name is 
%   given 'TITLE', and 'MESSAGE' is placed in the text field
%   above the bar.  The progress bar is placed at 0, the
%   refresh rate is set to .1 seconds, and the stop signal is
%   set to 0. In addition, the status string, containing start
%   time, elapsed time, estimated time left, and percent complete
%   are all initialized (NOTE: the elapsed time is set to
%   '??:??:??' since no estimate can be made yet).
%
%   For the remaining functions (except internal ones), the
%   figure handle H must be the second arguement passed, right
%   after the action string.
%
%   PROGRESSBAR('cancelbutton', H, ['CALLBACK']) creates a cancel
%   button that changes the stop signal (defined as the STATUS
%   field '.stop' - see below) to 1, when the cancel button is
%   pressed, as well as executing 'CALLBACK' if it is specified
%   (NOTE: pushing the cancel button does not prevent further
%   execution of calls to PROGRESSBAR, it simply sets the stop
%   signal to 1.  You can check on the status of the stop signal
%   with the action string 'status' - see definition below).
%
%   PROGRESSBAR('update', H, X) first checks to see if the last
%   update was over the refresh rate seconds ago.  If it was,
%   then the bar is set to X, where X is the fractional
%   completion (NOTE: X is forced to the interval [0, 1]).  In 
%   addition, the status string is updated to reflect changes in
%   the elapsed and estimated times, as well as the percent
%   complete.
%
%   PROGRESSBAR('message', H, 'MESSAGE') replaces the current
%   message text (the text field above the bar) with 'MESSAGE'
%   (NOTE: there is enough room for three to four lines of text
%   in the message field on most screen resolutions - use
%   SPRINTF with '\n' for newline).
%
%   PROGRESSBAR('title', H, 'TITLE') replaces the current title
%   text (the figure name) with 'TITLE' (NOTE: unlike the
%   message field, there is only room for one line of text).
%
%   PROGRESSBAR('refresh', H, NEWRATE) replaces the current
%   refresh rate (in seconds) with NEWRATE.  This value controls
%   how quickly the meter and status strings can be updated.
%   Setting a low value (such as .0001) provides very detailed
%   progress information, but can slow the execution loop because
%   too much time is spent updating PROGRESSBAR.  Setting a high
%   value (such as 5) minimizes PROGRESSBAR's execution time, but
%   may be too corse a measure of progress.  The default value of
%   .1 seems to be a fairly optimal balance, but this function is
%   provided so that the rate can be arbitrarily set.
%
%   PROGRESSBAR('kill', H) closes the progress indicator.  All
%   status information is lost (NOTE: If you want this
%   information before killing the indicator, use the action
%   string 'status' - see below).
%
%   STATUS = PROGRESSBAR('status', H) returns a structure
%   containing all information pertinent to the progress
%   indicator:
%       .winscale = the scale factor used to create all UI
%       objects so that they remain fairly consistant across
%       different screen resolutions.
%
%       .X = the fractional completion (between [0, 1])
%
%       .stop = stop signal (becomes 1 when cancel button is
%       pressed)
%
%       .refresh = refresh rate (in seconds)
%
%       .h = UI graphics handles:
%           .pbar = progress indicator figure handle (H)
%           .message = message text handle
%           .status = status string text handle
%           .axes = bar axes handle
%           .line = bar line handle
%           [.cancelbutton] = cancel button handle (if called)
%
%       .time = date vectors for status string (NOTE: some
%       date vectors have 0's for the yr/mo/day spots - this
%       function doesn't care about them, meaning that these
%       times become inaccurate if the calculations take longer
%       than 99:59:59):
%           .start = start time
%           .current = current time
%           .elapsed = elapsed time = etime(.current, .start)
%           .estimated = estimated time
%           
%   DATEVEC = PROGRESSBAR('sec2time', T) is an internal function
%   that returns a date vector DATEVEC corresponding T seconds.
%
%   TIMESTR = PROGRESSBAR('time2str', DATEVEC) is an internal
%   function that returns a 'HH:MM:SS' time string corresponding
%   to DATEVEC.  It tries to correct for min/sec overflows, and
%   returns '??:??:??' if the DATEVEC = [0 0 0 0 0 0] or it
%   contains negative values or is greater than 99:59:59.
%

%   Created 2/7/2004 by:
%   Ajay Nemani
%   Center for Magnetic Resonance Research
%   University of Illinois at Chicago
%   [e-mail]
%
%   This program is free software; you can redistribute it and/or
%   modify it under the terms of the GNU General Public License
%   as published by the Free Software Foundation; either version 2
%   of the License, or (at your option) any later version.
%
%   This program is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%   GNU General Public License for more details:
%
%         http://www.gnu.org/copyleft/gpl.html
%


%If no inputs given, assume create function
if nargin == 0
    action = 'create';
end

switch lower(action)
    
    
case 'create'
%Create and intialize display
%useage: h = progressbar('create', 'Title', 'Message')
    
    if nargin < 3
        varargin{2} = 'Default Message';
    end
    if nargin < 2
        varargin{1} = 'Default Title';
    end
    
    if ~ischar(varargin{1}) | ~ischar(varargin{2})
        error('2nd and/or 3rd inputs must be strings');
    end



    %Initialize UserData structure
    tmp = get(0, 'ScreenSize'); %This m-file was created on a 1600x1200 display,
    ud.winscale = tmp(3)/1600;  %so position vectors are scaled by winscale
    ud.time.start = clock;
    ud.time.current = clock;
    ud.time.elapsed = progressbar('sec2time', ...
                                  etime(ud.time.current, ud.time.start) ...
                                 );
    ud.time.estimated = [0 0 0 0 0 0];
    
    ud.X = 0;           %Fraction completed (forced to [0 1])
    ud.stop = 0;        %Stop signal
    ud.refresh = .1;    %Maximum refresh rate (in seconds)

    %Create figure
    ud.h.pbar = figure( ...
        'Tag',                  'Progress Bar', ...
        'Resize',               'off', ...
        'Color',                get(0, 'DefaultUicontrolBackgroundColor'), ...
        'DoubleBuffer',         'on', ...
        'Selected',             'off', ...
        'NumberTitle',          'off', ...
        'IntegerHandle',        'off', ...
        'MenuBar',              'none', ...
        'Units',                'pixels', ...
        'Position',             ([500 500 600 150] * ud.winscale), ...
        'Visible',              'on' ...
    );

    %Create message string
    ud.h.message = uicontrol( ...        
        'Tag',                  'Message Text', ...
        'Style',                'text', ...
        'TooltipString',        '', ...
        'Enable',               'on', ...
        'Callback',             [], ...
        'Units',                'pixels', ...
        'Position',             ([5 85 590 60] * ud.winscale), ...
        'Parent',               ud.h.pbar, ...
        'SelectionHighlight',   'off', ...
        'Selected',             'off', ...
        'FontName',             'FixedWidth', ...
        'FontSize',             get(0, 'DefaultUicontrolFontSize'), ...
        'FontUnits',            'pixels', ...
        'Visible',              'on' ...
    );

    %Create status string
    ud.h.status = uicontrol( ...        
        'Tag',                  'Status Text', ...
        'Style',                'text', ...
        'String',               [], ...
        'TooltipString',        '', ...
        'Enable',               'on', ...
        'Callback',             [], ...
        'Units',                'pixels', ...
        'Position',             ([5 5 590 50] * ud.winscale), ...
        'Parent',               ud.h.pbar, ...
        'SelectionHighlight',   'off', ...
        'Selected',             'off', ...
        'FontName',             'FixedWidth', ...
        'FontSize',             get(0, 'DefaultUicontrolFontSize'), ...
        'FontUnits',            'pixels', ...
        'Visible',              'on' ...
    );

    %Create progress bar axes
    ud.h.axes = axes( ...
        'Tag',                  'Progress Bar Axes', ...
        'Units',                'pixels', ...
        'Box',                  'on', ...
        'Color',                [1 1 1], ...
        'DrawMode',             'fast', ...
        'HitTest',              'off', ...
        'Layer',                'top', ...
        'NextPlot',             'ReplaceChildren', ...
        'Parent',               ud.h.pbar, ...
        'Position',             ([5 60 590 20] * ud.winscale), ...