WProgressBar

WProgressBar is a component for creating progress bars (or progress bar emulators in non-HTML5 compliant user agents).

• When to use
• Creating WProgressBar
• Accessibility
  • Labelling
  • Setting a toolTip
  • Additional labelling text
• Appearance
• Small progress bars
• Current value
• Maximum value
• Hiding
• HTML output
• Further information

When to use

WProgressBar should be used to provide an indication of the state of progress through a linear process. From the HTML specification:

The progress element represents the completion progress of a task. The progress is either indeterminate, indicating that progress is being made but that it is not clear how much more work remains to be done before the task is complete (e.g. because the task is waiting for a remote host to respond), or the progress is a number in the range zero to a maximum, giving the fraction of work that has so far been completed.

If a process cannot be deemed to be a task through which one can logically progress then a WProgressBar may not be the most useful element. A progress bar is a rather blunt instrument and it cannot be used to provide a clear indication of the actual level of progress if a task has many steps. As an example, it would be difficult for most users to determine the difference between completion of 42 and 43 steps of a 100 step process. Then again, if your process has 100 steps is it one which is suited to being a web application?

Creating WProgressBar

WProgressBar has two useful constructors. The default constructor will create a normal WProgressBar.

WProgressBar bar = new WProgressBar();

A constructor taking a single int argument will create a normal WProgressBar with a maximum value.

// max of 10
WProgressBar barWithMax = new WProgressBar(10);

Accessibility

WProgressBar merely indicates progress but does not, in itself, indicate what is being measured. The context of the progress bar should be such that it is clear what the progress indicates, however, the progress element is a labelable element and so WProgressBar should be labelled.

Labelling

WProgressBar should be labelled. This may be done using (in order of preference):

• WLabel; or
• a toolTip; or
• additional labelling text.

Setting a toolTip

See toolTip.

// given WProgressBar `progress`
// to set the toolTip
progress.setToolTip("this is a toolTip");

Additional labelling text

WProgressBar may have accessible text applied as information additional to the visible label text. This should be used with care and restraint as it may result in less accessible applications.

// given WProgressBar `progress`
progress.setAccessibleText("Some further context to this progress indicator.");

Appearance

The progress element, where supported, is allowed to be styled by the browser so as to maximise usability. It is considered that the user of a particular browser will have maximum familiarity with the controls of that browser.

• Safari (OS X) (other browsers on OS X are very similar):

  

• Internet Explorer 11 / Windows 7:

  

• Firefox / Windows 7:

  

• Chrome / Windows 7:

  

Small progress bars

The size of a progress bar is generally determined by the user agent. A smaller bar may be created using setType(ProgressBarType). WProgressBar currently supports two sizes:

• NORMAL (default) uses the normal font size

  

• SMALL uses a smaller font size which renders a smaller progress bar

  

progressbar.setProgressBarType(ProgressBarType.SMALL);

Current value

The value indicates the current point in the progress and is most usually determined programmatically but may be specified explicitly. It must be greater than or equal to ZERO (0) and less than or equal to the value of the max property.

// if we are step 8 of n steps:
progressbar.setValue(8);

Maximum value

The max property indicates the total number of steps in the process to which the progress bar relates. It is commonly determined programmatically but may be specified. It can be set in a constructor or a standard accessor method. If defined it must be greater than ZERO (0).

// max of 10
WProgressBar barWithMax = new WProgressBar(10);

// or using accessor
barWithMax.setMax(20);

// to remove a previously set maximum set it to 0
barWithMax.setMax(0);

Hiding

A WProgressBar may be hidden on page load. When hidden the WProgressBar is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl. If a WProgressBar is hidden then a WLabel associated with it is also hidden.

HTML output

WProgressBar outputs a HTML progress element.

Further information

• JavaDoc;
• List of WComponents.