Yahoo! UI Library

ProgressBar Widget  2.8.0r4

Yahoo! UI Library > progressbar > YAHOO.widget.ProgressBar
Search:
 
Filters

Class YAHOO.widget.ProgressBar - extends YAHOO.util.Element

The ProgressBar widget provides an easy way to draw a bar depicting progress of an operation, a level meter, rating or any such simple linear measure. It allows for highly customized styles including animation, vertical or horizontal and forward or reverse.

Constructor

YAHOO.widget.ProgressBar ( oConfigs )
Parameters:
oConfigs <object> An object containing any configuration attributes to be set

Properties

_barSizeFunction - private {function}

Function to be used to calculate bar size. It is picked from _barSizeFunctions depending on direction and whether animation is active.
Default Value: null

_barSizeFunctions - private {collection of functions}

Collection of functions used by to calculate the size of the bar. One of this will be used depending on direction and whether animation is active.

_barSpace - private Number

The actual space (in pixels) available for the bar within the mask (excludes margins)
Default Value: 100

_previousValue - private Number

The previous value setting for the bar. Used mostly as information to event listeners
Default Value: 0

_rendered - private boolean

A flag to signal that rendering has already happened
Default Value: false

ProgressBar.MARKUP - static final String

String containing the HTML string which is the basis for the Progress Bar.
Default Value: (too long)

Properties inherited from YAHOO.util.Element:

Properties inherited from YAHOO.util.AttributeProvider:

Methods

_animSetter

private _animSetter ( )
Called in response to a change in the anim attribute. It creates and sets up or destroys the instance of the animation utility that will move the bar

_fixEdges

private _fixEdges ( )
Due to rounding differences, some browsers fail to cover the whole area with the mask quadrants when the width or height is odd. This method stretches the lower and/or right quadrants to make the difference.

_heightChange

private _heightChange ( value )
Method called when the height attribute is changed
Parameters:
value <int or string> New height, in pixels if int or string including units

_init

protected void _init ( oConfigs )
Initialization code for the widget, separate from the constructor to allow for overriding/patching. It is called after initAttributes
Parameters:
oConfigs <Object> (Optional) Object literal definition of configuration values.
Returns: void

_recalculateConstants

private _recalculateConstants ( )
Calculates some auxiliary values to make the rendering faster

_setAriaText

private _setAriaText ( )
Utility method to set the ARIA value attributes

_valueChange

private _valueChange ( )
Called in response to a change in the value attribute. Moves the bar to reflect the new value

_widthChange

private _widthChange ( value )
Method called when the height attribute is changed
Parameters:
value <int or string> New width, in pixels if int or string including units

destroy

destroy ( )
Destroys the ProgressBar, related objects and unsubscribes from all events

initAttributes

private void initAttributes ( oConfigs )
Implementation of Element's abstract method. Sets up config values.
Parameters:
oConfigs <Object> (Optional) Object literal definition of configuration values.
Returns: void

redraw

redraw ( )
Recalculates the bar size and position and redraws it

render

YAHOO.widget.ProgressBar render ( el , before )
Renders the ProgressBar into the given container. If the container has other content, the ProgressBar will be appended to it. If the second argument is provided, the ProgressBar will be inserted before the given child. The method is chainable since it returns a reference to this instance.
Parameters:
el <HTML Element> HTML element that will contain the ProgressBar
before <HTML Element> (optional) If present, the ProgressBar will be inserted before this element.
Returns: YAHOO.widget.ProgressBar
Chainable: This method is chainable.

Events

animChange

animChange ( event )
Fires when the value for the configuration attribute 'anim' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

ariaTextTemplateChange

ariaTextTemplateChange ( event )
Fires when the value for the configuration attribute 'ariaTextTemplate' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

barElChange

barElChange ( event )
Fires when the value for the configuration attribute 'barEl' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeAnimChange

beforeAnimChange ( event )
Fires before the value for the configuration attribute 'anim' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeAriaTextTemplateChange

beforeAriaTextTemplateChange ( event )
Fires before the value for the configuration attribute 'ariaTextTemplate' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeBarElChange

beforeBarElChange ( event )
Fires before the value for the configuration attribute 'barEl' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeDirectionChange

beforeDirectionChange ( event )
Fires before the value for the configuration attribute 'direction' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeHeightChange

beforeHeightChange ( event )
Fires before the value for the configuration attribute 'height' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeMaskElChange

beforeMaskElChange ( event )
Fires before the value for the configuration attribute 'maskEl' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeMaxValueChange

beforeMaxValueChange ( event )
Fires before the value for the configuration attribute 'maxValue' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeMinValueChange

beforeMinValueChange ( event )
Fires before the value for the configuration attribute 'minValue' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeValueChange

beforeValueChange ( event )
Fires before the value for the configuration attribute 'value' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

beforeWidthChange

beforeWidthChange ( event )
Fires before the value for the configuration attribute 'width' changes. Return false to cancel the attribute change.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

complete

complete ( value )
Fires at the end of the animation or immediately upon changing values if animation is not loaded
Parameters:
value <Number> the current (final) value

directionChange

directionChange ( event )
Fires when the value for the configuration attribute 'direction' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

heightChange

heightChange ( event )
Fires when the value for the configuration attribute 'height' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

maskElChange

maskElChange ( event )
Fires when the value for the configuration attribute 'maskEl' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

maxValueChange

maxValueChange ( event )
Fires when the value for the configuration attribute 'maxValue' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

minValueChange

minValueChange ( event )
Fires when the value for the configuration attribute 'minValue' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

progress

progress ( value )
If animation is active, it will trigger several times during the animation providing intermediate values If animation is not active, it will fire only once providing the end value
Parameters:
value <Number> the current, changing value

start

start ( value )
Fires when the value is about to change. It reports the starting value
Parameters:
value <Number> the current (initial) value

valueChange

valueChange ( event )
Fires when the value for the configuration attribute 'value' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

widthChange

widthChange ( event )
Fires when the value for the configuration attribute 'width' changes.
Parameters:
event <{oldValue: any, newValue: any}> An object containing the previous attribute value and the new value.

Configuration Attributes

anim - {boolean} or {instance of YAHOO.util.Anim}

it accepts either a boolean (recommended) or an instance of YAHOO.util.Anim. If a boolean, it will enable/disable animation creating its own instance of the animation utility. If given an instance of YAHOO.util.Anim it will use that instance. The animation utility needs to be loaded. When read, it returns the instance of the animation utility in use or null if none. It can be used to set the animation parameters such as easing methods or duration.
Default Value: null

ariaTextTemplate - String

Text to be voiced by screen readers. The text is processed by YAHOO.lang.substitute. It can use the placeholders {value}, {minValue} and {maxValue}
Default Value: "{value}"

barEl - HTMLElement (div)

Reference to the HTML object that makes the moving bar (read-only)

direction - String (any of "ltr", "rtl", "ttb" or "btt")

Direction of movement of the bar. It can be any of 'ltr' (left to right), 'rtl' (the reverse) , 'ttb' (top to bottom) or 'btt'. Can only be set once and only before rendering.
Default Value: 'ltr'

height - Number or String

Height of the ProgressBar. If a number, it will be assumed to be in pixels. If a string it should be a valid setting for the CSS height attribute. It will always be returned as a string including units.
Default Value: "20px"

maskEl - HTMLElement (table)

Reference to the HTML object that overlays the bar providing the mask. (read-only)

maxValue - Number

Represents the top value for the bar. The bar will be fully extended when reaching this value. Values higher than this will be ignored.
Default Value: 100

minValue - Number

Represents the lowest value for the bar. The bar will be totally collapsed when reaching this value. Values lower than this will be ignored.
Default Value: 0

value - Number

The value for the bar. Valid values are in between the minValue and maxValue attributes.
Default Value: 0

width - Number or String

Width of the ProgressBar. If a number, it will be assumed to be in pixels. If a string it should be a valid setting for the CSS width attribute. It will always be returned as a string including units.
Default Value: "200px"

Configuration attributes inherited from YAHOO.util.Element:


Copyright © 2009 Yahoo! Inc. All rights reserved.