Animated busy (spinning) icon

Matlab includes a wide variety of internal widgets (GUI components) that could be very useful in our GUIs. One such widget is an animated spinning icon, which is often used by Matlab itself and numerous toolboxes to illustrate a running task:

Sample usage of an animated spinning icon

One of the internal widgets that are readily-available for use in our Matlab GUI and displays a similar (but not identical) spinning icon is BusyAffordance, which is included in the built-in com.mathworks.widgets package. BusyAffordance creates a visible panel with an animated spinning icon and optional text label as long as the panel’s object is in the “started” mode (the mode can be started/stopped numerous times).

Animated spinner icon

The usage is very simple:

try
    % R2010a and newer
    iconsClassName = 'com.mathworks.widgets.BusyAffordance$AffordanceSize';
    iconsSizeEnums = javaMethod('values',iconsClassName);
    SIZE_32x32 = iconsSizeEnums(2);  % (1) = 16x16,  (2) = 32x32
    jObj = com.mathworks.widgets.BusyAffordance(SIZE_32x32, 'testing...');  % icon, label
catch
    % R2009b and earlier
    redColor   = java.awt.Color(1,0,0);
    blackColor = java.awt.Color(0,0,0);
    jObj = com.mathworks.widgets.BusyAffordance(redColor, blackColor);
end
jObj.setPaintsWhenStopped(true);  % default = false
jObj.useWhiteDots(false);         % default = false (true is good for dark backgrounds)
javacomponent(jObj.getComponent, [10,10,80,80], gcf);
jObj.start;
    % do some long operation...
jObj.stop;

Note how I’ve used the javacomponent function to place the BusyAffordance object onscreen, at position 10,10 of the current Matlab figure, and gave it an initial size of 80×80 pixels.

When the object is stop()ed, the icon and label are removed by default, but can be displayed un-animated (non-spinning) via the PaintsWhenStopped property:

BusyAffordance started...
(animated spinning icon)

   

...stopped
(PaintsWhenStopped = false)

   

...stopped
(PaintsWhenStopped = true)

The small-icon (16×16) variant of the BusyAffordance control is used by another internal Matlab component, ProgressBarDialog. This control presents an animated progress-bar dialog window, similar to Matlab’s built-in waitbar function but with an animated circular busy icon:

d = com.mathworks.mlwidgets.dialog.ProgressBarDialog.createProgressBar('test...', []);
d.setValue(0.75);                        % default = 0
d.setProgressStatusLabel('testing...');  % default = 'Please Wait'
d.setSpinnerVisible(true);               % default = true
d.setCircularProgressBar(false);         % default = false  (true means an indeterminate (looping) progress bar)
d.setCancelButtonVisible(true);          % default = true
d.setVisible(true);                      % default = false

ProgressBarDialog with animated BusyAffordance

For those interested, the 16×16 animated GIF used here is spinner.gif, which can be found in %matlabroot%/java/jar/mlwidgets.jar (remember that JAR files are simply ZIP files, so they can be opened in WinZip/WinRar etc.). BusyAffordance also includes a 32×32 icon which is not available as a separate icon file. From this we learn that BusyAffordance probably creates this variant (and possibly also the 16×16 one) on-the-fly (programmatically).

For additional information on BusyAffordance, com.mathworks.widgets and other internal Matlab components, refer to chapter 5 in my Matlab-Java programming book.

As with other internal Matlab components, I categorized this feature as “High risk of breaking in a future release“. Still, BusyAffordance has existed in its present form since R2010a (and with a slightly different interface for years before then), so there’s a good chance that it will continue as-is in the foreseeable future. Then again, it might be removed as early as the next upcoming release, without prior warning…

More advanced animated busy indications, including automated percentage and time-remaining labels, can be specified using JBusyComponent, which is a JXLayer decorator that can be applied to any displayable component. In R2013b or newer that use Java7, we can also use the built-in JLayer class. We can also simply embed the animated GIF image directly in our GUI, as I explained here.

In the past I have already shown how to use other internal components in Matlab’s com.mathworks.widgets package, including a syntax-highlighted labels and text panes that can be embedded in our GUI.

Have you used BusyAffordance or some other internal Matlab component in a neat way in your GUI? if so, please do tell us about it in a comment below.

1. Displaying animated GIFs It is possible to easily display animated images in Matlab figure windows. ...
2. Uitable sorting Matlab's uitables can be sortable using simple undocumented features...
3. Customizing menu items part 3 Matlab menu items can easily display custom icons, using just a tiny bit of Java magic powder. ...
4. FindJObj GUI – display container hierarchy The FindJObj utility can be used to present a GUI that displays a Matlab container's internal Java components, properties and callbacks....