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:
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
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).
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; jObj.setBusyText('All done!');
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:
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 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
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. Also, the
BusyAffordance spin direction is reversed compared to the spinner icon. From this we learn that
BusyAffordance probably creates its spinner image on-the-fly (programmatically), rather than use spinner.gif.
For additional information on
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 syntax-highlighted labels and text panes that can be embedded in our Matlab 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.