Progress bar
Draws a progress bar which can be used to provide a visual cue indicating a task is being preformed and how much is left to do in the task.
Properties and All Attributes views
The Properties view for a component shows the most common set of attributes you can set on a component, and, depending on the component, you might also see options for adding controls, actions, or other components. To open the Properties view, click
Window | Show View | Properties.
These common attributes for the Progress bar component display on the hx:Progressbar tab in the Properties view. See the Progress bar attributes table for a complete list of attributes.
The All Attributes view shows a table of all the attributes you can set on a component, which includes those attributes you can access from the Properties view. To switch to the All Attributes view, click the
All Attributes icon 
in the upper right corner of the Properties
view.
|
Attribute name |
Description |
|---|---|
|
auto |
If true, the progress bar is self-timing and when started, it automatically updates itself on the specified interval. If omitted or false, the progress bar must be updated manually. It redraws the bar as a result of JavaScript™ calls that specify the current status. If auto is true, the bar does not display percent complete. If false, it displays percent complete. |
|
binding |
An expression that binds the component's instance (usually a user interface component) to a bean property (usually in the backing file). |
|
id |
Assigns a name to a component. Should be a unique name within a JSP. |
|
initHidden |
If true, the progress bar is hidden when the page is initially displayed. This should be used instead of setting "display:none" in the progress bar's style. |
|
initValue |
If auto is false or not set (optional, default is 0), the amount (percentage) the bar intially displays. For example, a value of 15 means that the bar shows the starting value as 15%. |
|
message |
The message to display above the bar. This may be changed via JavaScript as the bar is running. |
|
outward |
If true, the progress bar draws from the center outwards. If omitted or false, the bar draws from left to right. |
|
proportion |
If auto is true (optional, default is 5), the amount (percentage of the width of the progress bar) the bar increments each time it updates. For example, a value of 10 means each increment widens the bar by 10% of total width. If auto is false or not set (optional, default is 0), the amount (percentage) the bar intially displays. For example, a value of 15 means that the bar shows the starting value as 15%. |
|
rendered |
Can be set to true or false:
|
|
style |
Specifies CSS style information for the component (for example, style="font-size : 8pt ; color : red"). Defines the properties (such as font and color) of the selected component. This may be done manually, or by clicking the button and selecting the desired properties from within the window. |
|
styleClass |
Space-separated list of CSS style classes to be applied when this element is rendered. This value must be passed through as the class attribute on generated markup. Defines the classes (such as style sheets) of the selected component. This may be done manually, or by clicking the button and selecting the desired Classes from within the window. |
|
timeInterval |
If auto is true, interval (how often) the bar is updated. Specified in milliseconds, for example, a value of 5000 means the bar changes every 5 seconds. |
|
title |
Specifies the title text, shown in browser as a tooltip at runtime. Used by a browser as the alternative text of a component if the alternative text is not specified. |
CSS classes
|
CSS class name |
Description |
|---|---|
| progressBar | This is the style that gets applied to the entire progress bar control. |
| progressBar-Table | This is the style that gets applied to the table that makes up the progress bar. |
| progressBar-Message | This is the style that gets applied to the area holding the message text and the message text. |
| progressBar-Bar | This is the style that gets applied to the moving bar. |
| progressBar-Bar_container | This is the style that gets applied to the area containing both the moving bar and percentage text. |
| progressBar-Bar_text | This is the style that gets applied to the area containing the percentage text and the percentage text. |
API calls
|
API call |
Description |
|---|---|
| redraw() | Redraw the component taking into account any changes made to the attributes/properties of the base tag. |
| start(string) | Starts the progress bar running and changes the message text to the value of string. If you do not want a message, do not pass a parameter. This API call is used when the progress bar is in progress mode. |
| stop(string) | Stops the progress bar running and changes the message text to the value of string. If you do not want a message, do not pass a parameter. This API call is used when the progress bar is in progress mode. |
| reset() | Resets the bar displayed values to zero. |
| upDatePercentage(integer) | Update the progress bar to the value of integer. Integer value must be 0 and 100, values outside this range are rounded up and down respectively. This API call is used when the progress bar is in percentage mode. |
| UpdateMessage(string) | Used to change the message that is displayed. If you want to clear the message, leave this parameter blank. |
Description
Draws a progress bar which can be used to provide a visual cue indicating a task is being preformed and how much is left to do in the task.
The progress bar requires JavaScript be added to the page that controls the display of the bar. If the auto attribute is set to true, the JavaScript is used to start and stop the display of the bar (the bar draws itself using the specified timer interval). If the auto attribute is set to false, each update to the bar is made with a separate JavaScript call on the bar.
When the progress bar is set to auto, you start displaying the bar using the following script:
hX.getComponentById("id").start("message");
Where
"id" is the id of the component (for example, "form1:progressBar1")
and "message" is the message to display over the bar.
The advance of the bar is stopped by calling stop on the progress bar:
hX.getComponentById("id").stop();
Note
that if a bar is "started", it will continue to run (resetting itself
to zero as need be) until it is explicitly stopped.
When the progress bar is not set to auto, updates (advances) to the bar must be coded in JavaScript. Each change in the bar's size (percentage), is the result of the following script:
hX.getComponentById("id").upDatePercentage(value);
Where
"id" is the id of the component (for example, "form1:progressBar1")
and "value" is an integer representing the percent complete (for example,
10 means 10% complete.
Accessibility
The component is an "output" component so it is not in the tab order of the page. When reading the component, screen readers will report the title (if present) and the message. As a rule, screen readers will only read the message once so the presence/absence of the bar (whether it is hidden or shown) is more important to screen readers than the message.
Limitations and cautions
- The component renders as a block-level element.
- Hiding the progress bar does not reset it.
- Resetting the progress bar does not stop it nor does it change
the message.
- Once a progress bar is created, the value of the auto attribute
cannot be changed, except by reloading the page it is on.
- Calling the start function on a progress bar that does not have
auto set to true has no effect. Conversely, calling the upDatePercentage
function on a progress bar that does not have auto set to false has
no effect.
- Reset must be called between stop and (re)start in progress mode, otherwise it will not restart.
Example code
Define an "auto" progress bar that expands from left to right, increasing the size by 10% every second.
<hx:progressBar id="pb1" auto="true" styleClass="progressBar"
title="Progress bar" message="<b>hello</b>"
proportion="10" timeInterval="1000"/>
<input type="button" value="start" onclick="start1();"/>
<input type="button" value="stop" onclick="end1();"/>
<script>
function start1() {
hX.getComponentById("pb1").start();
}
function end1() {
hX.getComponentById("pb1").stop();
}
</script>
Define an "manual" progress bar that expands from left to right. The percentage of the bar is set manually by JavaScript calls. The initial percentage value is 15%.
<hx:progressBar id="pb3" auto="false" styleClass="progressBar" message="hello" initValue="15"/>
<input type="button" value="set to 20%" onclick="move1();" />
<input type="button" value="set to 72%" onclick="move2();" />
<script>
function move1() {
var obj = hX.getComponentById("pb3");
obj.upDatePercentage(20);
obj.redraw();
}
function move2() {
var obj = hX.getComponentById("pb3");
obj.upDatePercentage(72);
obj.upDateMessage("value is now set to 72 %");
obj.redraw();
}
</script>