final Queue<String> queue = new ConcurrentLinkedQueue<String>(); final Gauge<Integer> queueDepth = new Gauge<Integer>() { public Integer getValue() { return queue.size(); } }; Gauge contains a current value that lies between zero and the maximum value, inclusive. The application can control the current value and maximum value. The range of values specified by the application may be larger than the number of distinct visual states possible on the device, so more than one value may have the same visual representation. For example, consider a Gauge object that has a range of values from zero to 99, running on a device that displays the Gauge's approximate value using a set of one to ten bars. The device might show one bar for values zero through nine, two bars for values ten through 19, three bars for values 20 through 29, and so forth.
A Gauge may be interactive or non-interactive. Applications may set or retrieve the Gauge's value at any time regardless of the interaction mode. The implementation may change the visual appearance of the bar graph depending on whether the object is created in interactive mode.
In interactive mode, the user is allowed to modify the value. The user will always have the means to change the value up or down by one and may also have the means to change the value in greater increments. The user is prohibited from moving the value outside the established range. The expected behavior is that the application sets the initial value and then allows the user to modify the value thereafter. However, the application is not prohibited from modifying the value even while the user is interacting with it.
In many cases the only means for the user to modify the value will be to press a button to increase or decrease the value by one unit at a time. Therefore, applications should specify a range of no more than a few dozen values.
In non-interactive mode, the user is prohibited from modifying the value. Non-interactive mode is used to provide feedback to the user on the state of a long-running operation. One expected use of the non-interactive mode is as a "progress indicator" or "activity indicator" to give the user some feedback during a long-running operation. The application may update the value periodically using the setValue() method.
A non-interactive Gauge can have a definite or indefinite range. If a Gauge has definite range, it will have an integer value between zero and the maximum value set by the application, inclusive. The implementation will provide a graphical representation of this value such as described above.
A non-interactive Gauge that has indefinite range will exist in one of four states: continuous-idle, incremental-idle, continuous-running, or incremental-updating. These states are intended to indicate to the user that some level of activity is occurring. With incremental-updating, progress can be indicated to the user even though there is no known endpoint to the activity. With continuous-running, there is no progress that gets reported to the user and there is no known endpoint; continuous-running is merely a busy state indicator. The implementation should use a graphical display that shows this appropriately. The implementation may use different graphics for indefinite continuous gauges and indefinite incremental gauges. Because of this, separate idle states exist for each mode. For example, the implementation might show an hourglass or spinning watch in the continuous-running state, but show an animation with different states, like a beach ball or candy-striped bar, in the incremental-updating state.
In the continuous-idle or incremental-idle state, the Gauge indicates that no activity is occurring. In the incremental-updating state, the Gauge indicates activity, but its graphical representation should be updated only when the application requests an update with a call to setValue(). In the continuous-running state, the Gauge indicates activity by showing an animation that runs continuously, without update requests from the application.
The values CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, and INCREMENTAL_UPDATING have their special meaning only when the Gauge is non-interactive and has been set to have indefinite range. They are treated as ordinary values if the Gauge is interactive or if it has been set to have a definite range.
An application using the Gauge as a progress indicator should typically also attach a {@link Command#STOP STOP}command to the container containing the Gauge to allow the user to halt the operation in progress.
As mentioned above, a non-interactive Gauge may be used to give user feedback during a long-running operation. If the application can observe the progress of the operation as it proceeds to an endpoint known in advance, then the application should use a non-interactive Gauge with a definite range. For example, consider an application that is downloading a file known to be 20 kilobytes in size. The application could set the Gauge's maximum value to be 20 and set its value to the number of kilobytes downloaded so far. The user will be presented with a Gauge that shows the portion of the task completed at any given time.
If, on the other hand, the application is downloading a file of unknown size, it should use a non-interactive Gauge with indefinite range. Ideally, the application should call setValue(INCREMENTAL_UPDATING) periodically, perhaps each time its input buffer has filled. This will give the user an indication of the rate at which progress is occurring.
Finally, if the application is performing an operation but has no means of detecting progress, it should set a non-interactive Gauge to have indefinite range and set its value to CONTINUOUS_RUNNING or CONTINUOUS_IDLE as appropriate. For example, if the application has issued a request to a network server and is about to block waiting for the server to respond, it should set the Gauge's state to CONTINUOUS_RUNNING before awaiting the response, and it should set the state to CONTINUOUS_IDLE after it has received the response.
| |
| |
| |
| |
| |