# Throbber Demo

## What Is It

A throbber is an indeterminate (or asynchronous) progress indicator. Usually it's very small and circular.

## How To Use It

You can configure a throbber by calling:

    JThrobber throbber = new JThrobber();

That should get you a pretty good out-of-the-box experience. If you want you can further customize it:

    throbber.setUI(new ChasingArrowsThrobberUI());
    throbber.setPreferredSize(new Dimension(60,60));
    throbber.setForeground(Color.cyan);

## How It Works

As long as a `JThrobber` is showing the `ThrobberUI` repaints it on a timer. All the UI subclasses are lightweight and vector-based.

## Discussion

Wikipedia defines a throbber as:

> A throbber is a graphic found in a graphical user interface of a computer program that animates to show the user that the program is performing an action in the background (such as downloading content, conducting intensive calculations or communicating with an external device). In contrast to a progress bar, a throbber does not convey how much of the action has been completed.

> [...]

> Throbbers saw a resurgence with client-side applications (such as Ajax web apps) where an application within the web browser would wait for some operation to complete. Most of these throbbers were known as a "spinning wheel", which typically consist of 8, 10, or 12 part-radial lines or discs arranged in a circle, as if on a clock face, highlighted in turn as if a wave is moving clockwise around the circle.

If you're developing exclusively on Macs, Apple has their own unique implementation in Technical Note 2196 (as part of their ProgressBarUI). That's a great start, but:

- Why limit this solution to Macs? Windows needs this component too.
- It's ... just not a JProgressBar. It has no numeric value. The interdeterminate flag, the orientation, the ChangeListeners: they're all lies when you dress the slider up as a throbber. And off the top of my head I'm not sure if Voice Over correctly describes these "progress bars" as not-progress-bars.

(Speaking of progress bars, though, be sure to check out the CircularProgressBarUI if that's what you're looking for.)

Apple's guidelines used to refer to this as an "asynchronous progress indicator". They advised:

> An asynchronous progress indicator provides feedback on an ongoing process.

> Asynchronous progress indicators are available in Interface Builder. In the Attributes pane of the inspector, select Spinning for the style and be sure the Indeterminate checkbox is selected. To create an asynchronous progress indicator using AppKit programming interfaces, use the NSProgressIndicator class with style NSProgressIndicatorSpinningStyle.

> #### Appearance and Behavior

> The appearance of the asynchronous progress indicator is provided automatically. The asynchronous progress indicator always spins at the same rate.

> #### Guidelines

> Use an asynchronous progress indicator when space is very constrained, such as in a text field or near a control. Because this indicator is small and unobtrusive, it is especially useful for asynchronous events that take place in the background, such as retrieving messages from a server.

> If the process might change from indeterminate to determinate, start with an indeterminate progress bar. You don't want to start with an asynchronous progress indicator because the determinate progress bar is a different shape and takes up much more space. Similarly, if the process might change from indeterminate to determinate, use an indeterminate progress bar instead of an asynchronous progress indicator, because it is the same shape and size as the determinate progress bar.

> In general, avoid supplying a label. Because an asynchronous progress indicator typically appears when the user initiates a process, a label is not usually necessary. If you decide to provide a label that appears with the indicator, create a complete or partial sentence that briefly describes the process that is occurring. You should use sentence-style capitalization (for more information on this style, see "Capitalizing Labels and Text") and you can end the label with an ellipsis (...) to emphasize the ongoing nature of the processing.

Also if you have several tasks that a single throbber represents: the `ThrobberManager` class helps. Each task takes a token as it starts, and then it returns that token when its finished. Meanwhile the `ThrobberManager` can produces any number of `JThrobbers` that are automatically shown/hidden depending on whether any tasks are currently unfinished.