Yahoo! UI Library

ProgressBar Widget  2.9.0

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

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

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.

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.