Displays a tooltip-sized waitbar beneath uicontrols, and is animated. Inspired by "About Face", similarly to my other tooltip submission.
toolTipWaitBarHandle = tooltipwaitbar(hObject)
Generates a waitbar below a uicontrol (hObject). Returns a 4 element array for the static text boxes which make up the waitbar. (1) is the progress bar itself, (2) is the background to the waitbar, (3) is the border, and (4) is a UIContextMenu (right-click menu) that can be used which can hide the waitbar, and also gives information on the steps going through (it logs changes of the message using updatetooltipwaitbar). All can be modified using standard set/get notation. For example, change the colours with:
Progress bar: set(toolTipWaitBarHandle(1), 'BackgroundColor', 'red')
Progress background: set(toolTipWaitBarHandle(2), 'BackgroundColor', 'white')
Border: set(toolTipWaitBarHandle(3), 'BackgroundColor', 'black')
... = tooltipwaitbar(hObject, progress)
Pre-defines a progress level of the waitbar, where the progress is any number from 0 to 1, or, from 0 to 100 (whichever it is is dynamically selected). If left empty, the default is 0.
... = tooltipwaitbar(hObject, progress, message)
Also supplies a message which appears in the ToolTip for the text box. This can be empty (the default), or a string.
... = tooltipwaitbar(hObject, progress, message, useContextMenu)
If useContextMenu evaluates to false (the default is true), the context menu is disabled. If useContextMenu is the handle to a uicontext menu object, then this can be used instead. CAUTION: This will error if you accidentally supply the number to a uicontrol that is not a uicontextmenu. It is recommended this is converted to a logical beforehand if possible.
... = tooltipwaitbar(hObject, progress, message, useContextMenu, usePercentLabel)
If usePercentLabel evaluates to true (the default is false), the
percent label is used. This is a % label at the right alignment of the
progress bar, in white.
... = tooltipwaitbar(hObject, progress, message, useContextMenu, usePercentLabel, abortAction)
AbortAction specifies what to do when the user clicks on abort.
Because of the way it works, the process can only be aborted the next time a callback tries to update the waitbar (e.g. in a loop). It can be true, 'error', or false. If true, an abort status flag (retrieved later, see how to update the waitbar) is changed. If 'error', then the waitbar will deliberately error after the waitbar has been redrawn as normal. If false (the default), nothing happens.
To change the label colour:
set(toolTipWaitBarHandle(1), 'ForegroundColor', 'yellow')
To change the label alignment:
set(toolTipWaitBarHandle(1), 'HorizontalAlignment', 'left')
To change the font size (8 is the default in MATLAB):
set(toolTipWaitBarHandle(1), 'FontSize', 10)
abortStatus = tooltipwaitbar(toolTipWaitBarHandle, progress);
Updates the progress of the waitbar generated using tooltipwaitbar. If an output argument is supplied, the current abort status is given.
tooltipwaitbar(toolTipWaitBarHandle, progress, message)
Updates the waitbar, as well as the status message in the UIToolTip, and if the context menu is on, updates that too. If you only want to change the message, progress can also be empty ().
Removes the waitbar from the figure.
More than one tooltip can be used on the same uicontrol without issue, as long the handles are stored properly (the most recent one will be on top of the stack. No other data is stored. The waitbars stack rather nicely too when a tooltipwaitbar is slaved to another tooltipwaitbar, which makes for some quite interesting visual effects. The tooltipwaitbar is implemented as a series of overlapping text boxes rather than axes/patch objects because axes are always on the bottom of the UI element stack; if there are any other uicontrols nearby, the text object is obscured. The context menu to hide the waitbar merely makes it invisible; it may cause problems later otherwise when other functions attempt to clear up.
The test GUI I use for new features is also bundled.
% create a dummy GUI
hObject = uicontrol('Style', 'pushbutton');
% create waitbar
ttwb = tooltipwaitbar(hObject, 0, 'Starting...');
n = 1;
x = 3;
% simple loop
for m = 1:10 ^ x
n = n + m;
% update waitbar
tooltipwaitbar(ttwb, m / 10 ^ x);
% finish at end
% clear up
clear('ttwb', 'n', 'm', 'x', 'hObject')