API: progressbar YAHOO.widget.ProgressBar (YUI Library)

# Yahoo! UI Library

### ProgressBar Widget 2.9.0

Yahoo! UI Library > progressbar > YAHOO.widget.ProgressBar
Search:
Filters Show Private Show Protected Show Deprecated

## 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

#### _barSizeFunctions - `private static {collection of functions}`

Collection of functions used 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 HTML`

String containing the HTML string which is the basis for the Progress Bar. Value is inserted into the DOM with innerHTML.
Default Value: (too long)

#### Properties inherited from YAHOO.util.Element:

`DOM_EVENTS`

#### Properties inherited from YAHOO.util.AttributeProvider:

`_configs`

#### Properties inherited from YAHOO.util.EventProvider:

`__yui_events, __yui_subscribers`

### Methods

#### _animComplete

`private _animComplete ( )`
Called when the animation signals it has completed.

Returns: ``
  void

#### _animSetter

`private _animSetter ( value )`
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

Parameters:
  `value <boolean ,YAHOO.util.Anim>` Enable animation or set to specific instance

Returns: ``
  void

#### _fixAnim

`private _fixAnim ( anim , acc )`
Temporary solution until http://yuilibrary.com/projects/yui2/ticket/2528222 gets solved. Also fixes: http://yuilibrary.com/projects/yui2/ticket/2528919. It also handles moving the background as per the animAcceleration configuration attribute since it turned out to be the best place to handle it.

Parameters:
  `anim <YAHOO.util.Anim>` Instance of Animation to fix
  `acc <number>` Value of animAcceleration attribute

Returns: ``
  void

#### _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.

Returns: ``
  void

#### _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

Returns: ``
  void

#### _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.

#### _recalculateConstants

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

Returns: ``
  void

#### _setAriaText

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

Parameters:
  `value <number>` Value to be voiced

Returns: ``
  void

#### _valueChange

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

Parameters:
  `value <number>` New value to be set
  `noAnim <boolean>` Disable animation for this redraw

Returns: ``
  void

#### _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

Returns: ``
  void

#### destroy

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

Returns: ``
  void

#### 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.

#### redraw

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

Parameters:
  `noAnim <boolean>` Don't use animation to redraw

Returns: ``
  void

#### 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.

Chainable: This method is chainable.

#### Methods inherited from YAHOO.util.Element:

`_setHTMLAttrConfig, addClass, addListener, appendChild, appendTo, delegate, fireQueue, getElementsByClassName, getElementsByTagName, getStyle, hasChildNodes, hasClass, initAttributes, insertBefore, on, removeChild, removeClass, removeDelegate, removeListener, replaceChild, replaceClass, setStyle, subscribe`

#### Methods inherited from YAHOO.util.AttributeProvider:

`configureAttribute, fireBeforeChangeEvent, fireChangeEvent, get, getAttributeConfig, getAttributeKeys, refresh, register, resetAttributeConfig, resetValue, set, setAttributeConfig, setAttributes`

#### Methods inherited from YAHOO.util.EventProvider:

`createEvent, fireEvent, hasEvent, subscribe, unsubscribe, unsubscribeAll`

### Events

#### animAccelerationChange

`animAccelerationChange ( event )`
Fires when the value for the configuration attribute 'animAcceleration' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### 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.

#### beforeAnimAccelerationChange

`beforeAnimAccelerationChange ( event )`
Fires before the value for the configuration attribute 'animAcceleration' 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.

#### 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.

#### Events inherited from YAHOO.util.Element:

`appendTo, available, beforeAppendTo, beforeElementChange, contentReady, elementChange,`

### 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

#### animAcceleration `- {number} or {null}`

It accepts a number or null to cancel. If a number, it is how fast the background image for the bar will move in the opposite direction to the bar itself. null or 0 means the background won't move. Negative values will make the background move along the bar. Only valid with animation active and it requires a suitable background image to make it evident.
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 before rendering.
Default Value: 'ltr'

#### height `- Number or String`

Pixel height of the ProgressBar, i.e., 200 or "200px". 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`

Pixel width of the ProgressBar, i.e., 200 or "200px". It will always be returned as a string including units.
Default Value: "200px"

#### Configuration attributes inherited from YAHOO.util.Element:

`element`

Copyright © 2011 Yahoo! Inc. All rights reserved.