YUI recommends YUI 3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

Yahoo! UI Library

Button  2.3.0

Yahoo! UI Library > button > YAHOO.widget.Button

Show Private Show Protected

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

The Button class creates a rich, graphical button.

Constructor

YAHOO.widget.Button ( p_oElement , p_oAttributes )
Parameters:
p_oElement <String> String specifying the id attribute of the <input>, <button>, <a>, or <span> element to be used to create the button.
p_oElement <HTMLInputElement| HTMLButtonElement|HTMLElement> Object reference for the <input>, <button>, <a>, or <span> element to be used to create the button.
p_oElement <Object> Object literal specifying a set of configuration attributes used to create the button.
p_oAttributes <Object> Optional. Object literal specifying a set of configuration attributes used to create the button.

Properties

_activationButtonPressed - protected Boolean

Boolean indicating if the mouse button that toggles the button's "active" state has been pressed.
Default Value: false

_activationKeyPressed - protected Boolean

Boolean indicating if the key(s) that toggle the button's "active" state have been pressed.
Default Value: false

_button - protected HTMLAnchorElement|HTMLButtonElement

Object reference to the button's internal <a> or <button> element.
Default Value: null

_hasKeyEventHandlers - protected Boolean

Boolean indicating if the button's "blur", "keydown" and "keyup" event handlers are assigned
Default Value: false

_hasMouseEventHandlers - protected Boolean

Boolean indicating if the button's "mouseout," "mousedown," and "mouseup" event handlers are assigned
Default Value: false

_hiddenFields - protected HTMLInputElement|Array

Object reference to the <input> element, or array of HTML form elements used to represent the button when its parent form is submitted.
Default Value: null

_menu - protected {YAHOO.widget.Overlay| YAHOO.widget.Menu}

Object reference to the button's menu.
Default Value: null

_onclickAttributeValue - protected Object

Object reference to the button's current value for the "onclick" configuration attribute.
Default Value: null

ACTIVATION_KEYS - final Array

Array of numbers representing keys that (when presed) toggle the button's "active" state.
Default Value: [13, 32]

CHECK_ACTIVATION_KEYS - final Array

Array of numbers representing keys that (when pressed) toggle the button's "checked" attribute.
Default Value: [32]

CHECKBOX_CHECKED_TITLE - final String

String representing the title applied to buttons of type "checkbox" when checked.
Default Value: "Checked. Click to uncheck."

CHECKBOX_DEFAULT_TITLE - final String

String representing the default title applied to buttons of type "checkbox."
Default Value: "Unchecked. Click to check."

CSS_CLASS_NAME - final String

String representing the CSS class(es) to be applied to the button's root element.
Default Value: "yui-button"

MENUBUTTON_DEFAULT_TITLE - final String

String representing the default title applied to buttons of type "menu."
Default Value: "Menu collapsed. Click to expand."

MENUBUTTON_MENU_VISIBLE_TITLE - final String

String representing the title applied to buttons of type "menu" when the button's menu is visible.
Default Value: "Menu expanded. Click or press Esc to collapse."

NODE_NAME - final String

The name of the node to be used for the button's root element.
Default Value: "SPAN"

OPTION_AREA_WIDTH - final Number

Width (in pixels) of the area of a split button that when pressed will display a menu.
Default Value: 20

RADIO_CHECKED_TITLE - final String

String representing the title applied to buttons of type "radio" when checked.
Default Value: "Checked. Click to uncheck."

RADIO_DEFAULT_TITLE - final String

String representing the default title applied to buttons of type "radio."
Default Value: "Unchecked. Click to check."

SPLITBUTTON_DEFAULT_TITLE - final String

String representing the default title applied to buttons of type "split."
Default Value: "Menu collapsed. Click inside option region or press Ctrl + Shift + M to show the menu."

SPLITBUTTON_OPTION_VISIBLE_TITLE - final String

String representing the title applied to buttons of type "split" when the button's menu is visible.
Default Value: "Menu expanded. Press Esc or Ctrl + Shift + M to hide the menu."

SUBMIT_TITLE - final String

String representing the title applied to buttons of type "submit."
Default Value: "Click to submit form."

Properties inherited from YAHOO.util.Element:

Properties inherited from YAHOO.util.AttributeProvider:

Methods

_addListenersToForm

protected void _addListenersToForm ( )
Adds event handlers to the button's form.
Returns: void

_hideMenu

protected void _hideMenu ( )
Hides the button's menu.
Returns: void

_isActivationKey

protected Boolean _isActivationKey ( p_nKeyCode )
Determines if the specified keycode is one that toggles the button's "active" state.
Parameters:
p_nKeyCode <Number> Number representing the keycode to be evaluated.
Returns: Boolean

_isSplitButtonOptionKey

protected Boolean _isSplitButtonOptionKey ( p_oEvent )
Determines if the specified keycode is one that toggles the display of the split button's menu.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: Boolean

_onAppendTo

protected void _onAppendTo ( p_oEvent )
"appendTo" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onBlur

protected void _onBlur ( p_oEvent )
"blur" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onClick

protected void _onClick ( p_oEvent )
"click" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onDocumentKeyUp

protected void _onDocumentKeyUp ( p_oEvent )
"keyup" event handler for the document.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onDocumentMouseDown

protected void _onDocumentMouseDown ( p_oEvent )
"mousedown" event handler for the document.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onDocumentMouseUp

protected void _onDocumentMouseUp ( p_oEvent )
"mouseup" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onFocus

protected void _onFocus ( p_oEvent )
"focus" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onFormReset

protected void _onFormReset ( p_oEvent )
"reset" event handler for the button's form.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onKeyDown

protected void _onKeyDown ( p_oEvent )
"keydown" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onKeyUp

protected void _onKeyUp ( p_oEvent )
"keyup" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onMenuClick

private void _onMenuClick ( p_sType , p_aArgs )
"click" event handler for the button's menu.
Parameters:
p_sType <String> String representing the name of the event that was fired.
p_aArgs <Array> Array of arguments sent when the event was fired.
Returns: void

_onMenuHide

private void _onMenuHide ( p_sType )
"hide" event handler for the button's menu.
Parameters:
p_sType <String> String representing the name of the event that was fired.
Returns: void

_onMenuItemAdded

private void _onMenuItemAdded ( p_sType , p_aArgs , p_oItem )
"itemadded" event handler for the button's menu.
Parameters:
p_sType <String> String representing the name of the event that was fired.
p_aArgs <Array> Array of arguments sent when the event was fired.
p_oItem < YAHOO.widget.MenuItem> Object representing the menu item that subscribed to the event.
Returns: void

_onMenuItemSelected

private void _onMenuItemSelected ( p_sType , p_aArgs , p_nItem )
"selectedchange" event handler for each item in the button's menu.
Parameters:
p_sType <String> String representing the name of the event that was fired.
p_aArgs <Array> Array of arguments sent when the event was fired.
p_nItem <Number> Number representing the index of the menu item that subscribed to the event.
Returns: void

_onMenuKeyDown

private void _onMenuKeyDown ( p_sType , p_aArgs )
"keydown" event handler for the button's menu.
Parameters:
p_sType <String> String representing the name of the event that was fired.
p_aArgs <Array> Array of arguments sent when the event was fired.
Returns: void

_onMenuRender

private void _onMenuRender ( p_sType )
"render" event handler for the button's menu.
Parameters:
p_sType <String> String representing the name of the event thatwas fired.
Returns: void

_onMenuShow

private void _onMenuShow ( p_sType )
"show" event handler for the button's menu.
Parameters:
p_sType <String> String representing the name of the event that was fired.
Returns: void

_onMouseDown

protected void _onMouseDown ( p_oEvent )
"mousedown" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onMouseOut

protected void _onMouseOut ( p_oEvent )
"mouseout" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onMouseOver

protected void _onMouseOver ( p_oEvent )
"mouseover" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onMouseUp

protected void _onMouseUp ( p_oEvent )
"mouseup" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onOption

protected void _onOption ( p_oEvent )
"option" event handler for the button.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

_onOverlayBeforeShow

private void _onOverlayBeforeShow ( p_sType )
"beforeshow" event handler for the YAHOO.widget.Overlay instance serving as the button's menu.
Parameters:
p_sType <String> String representing the name of the event that was fired.
Returns: void

_setChecked

protected void _setChecked ( p_bChecked )
Sets the value of the button's "target" attribute.
Parameters:
p_bChecked <Boolean> Boolean indicating the value for the button's "checked" attribute.
Returns: void

_setDisabled

protected void _setDisabled ( p_bDisabled )
Sets the value of the button's "disabled" attribute.
Parameters:
p_bDisabled <Boolean> Boolean indicating the value for the button's "disabled" attribute.
Returns: void

_setHref

protected void _setHref ( p_sHref )
Sets the value of the button's "href" attribute.
Parameters:
p_sHref <String> String indicating the value for the button's "href" attribute.
Returns: void

_setLabel

protected void _setLabel ( p_sLabel )
Sets the value of the button's "label" attribute.
Parameters:
p_sLabel <String> String indicating the value for the button's "label" attribute.
Returns: void

_setMenu

protected void _setMenu ( p_oMenu )
Sets the value of the button's "menu" attribute.
Parameters:
p_oMenu <Object> Object indicating the value for the button's "menu" attribute.
Returns: void

_setOnClick

protected void _setOnClick ( p_oObject )
Sets the value of the button's "onclick" attribute.
Parameters:
p_oObject <Object> Object indicating the value for the button's "onclick" attribute.
Returns: void

_setSelectedMenuItem

protected void _setSelectedMenuItem ( p_nIndex )
Sets the value of the button's "selectedMenuItem" attribute.
Parameters:
p_nIndex <Number> Number representing the index of the item in the button's menu that is currently selected.
Returns: void

_setTabIndex

protected void _setTabIndex ( p_nTabIndex )
Sets the value of the button's "tabindex" attribute.
Parameters:
p_nTabIndex <Number> Number indicating the value for the button's "tabindex" attribute.
Returns: void

_setTarget

protected void _setTarget ( p_sTarget )
Sets the value of the button's "target" attribute.
Parameters:
p_sTarget <String> String indicating the value for the button's "target" attribute.
Returns: void

_setTitle

protected void _setTitle ( p_nTabIndex )
Sets the value of the button's "title" attribute.
Parameters:
p_nTabIndex <String> Number indicating the value for the button's "title" attribute.
Returns: void

_setType

protected void _setType ( p_sType )
Sets the value of the button's "type" attribute.
Parameters:
p_sType <String> String indicating the value for the button's "type" attribute.
Returns: void

_showMenu

protected void _showMenu ( p_oEvent )
Shows the button's menu.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event) that triggered the display of the menu.
Returns: void

addHiddenFieldsToForm

void addHiddenFieldsToForm ( p_oForm )
Searches the specified form and adds hidden fields for instances of YAHOO.widget.Button that are of type "radio," "checkbox," "menu," and "split."
Parameters:
p_oForm <HTMLFormElement> Object reference for the form to search.
Returns: void

addStateCSSClasses

void addStateCSSClasses ( )
Appends state-specific CSS classes to the button's root DOM element.
Returns: void

blur

void blur ( )
Causes the button to lose focus and fires the button's "blur" event.
Returns: void

createButtonElement

HTMLElement createButtonElement ( p_sType )
Creates the button's HTML elements.
Parameters:
p_sType <String> String indicating the type of element to create.
Returns: HTMLElement

createHiddenFields

HTMLInputElement|Array createHiddenFields ( )
Creates the button's hidden form field and appends it to its parent form.
Returns: HTMLInputElement|Array

createInputElement

private HTMLInputElement createInputElement ( p_sType , p_sName , p_sValue , p_bChecked )
Creates an <input> element of the specified type.
Parameters:
p_sType <String> String specifying the type of <input> element to create.
p_sName <String> String specifying the name of <input> element to create.
p_sValue <String> String specifying the value of <input> element to create.
p_bChecked <String> Boolean specifying if the <input> element is to be checked.
Returns: HTMLInputElement

destroy

void destroy ( )
Removes the button's element from its parent element and removes all event handlers.
Returns: void

focus

void focus ( )
Causes the button to receive the focus and fires the button's "focus" event.
Returns: void

getForm

HTMLFormElement getForm ( )
Returns a reference to the button's parent form.
Returns: HTMLFormElement

getHiddenFields

HTMLInputElement|Array getHiddenFields ( )
Returns an <input> element or array of form elements used to represent the button when its parent form is submitted.
Returns: HTMLInputElement|Array

getMenu

YAHOO.widget.Overlay|YAHOO.widget.Menu getMenu ( )
Returns a reference to the button's menu.

hasFocus

Boolean hasFocus ( )
Returns a boolean indicating whether or not the button has focus.
Returns: Boolean

init

void init ( p_oElement , p_oAttributes )
The Button class's initialization method.
Parameters:
p_oElement <String> String specifying the id attribute of the <input>, <button>, <a>, or <span> element to be used to create the button.
p_oElement <HTMLInputElement|HTMLButtonElement| HTMLElement> Object reference for the <input>, <button>, <a>, or <span> element to be used to create the button.
p_oElement <Object> Object literal specifying a set of configuration attributes used to create the button.
p_oAttributes <Object> Optional. Object literal specifying a set of configuration attributes used to create the button.
Returns: void

initAttributes

void initAttributes ( p_oAttributes )
Initializes all of the configuration attributes used to create the button.
Parameters:
p_oAttributes <Object> Object literal specifying a set of configuration attributes used to create the button.
Returns: void

initConfig

private void initConfig ( Object )
Initializes the set of configuration attributes that are used to instantiate the button.
Parameters:
Object <Object> representing the button's set of configuration attributes.
Returns: void

isActive

Boolean isActive ( )
Returns a boolean indicating whether or not the button is active.
Returns: Boolean

removeHiddenFields

void removeHiddenFields ( )
Removes the button's hidden form field(s) from its parent form.
Returns: void

removeStateCSSClasses

void removeStateCSSClasses ( )
Removes state-specific CSS classes to the button's root DOM element.
Returns: void

setAttributeFromDOMAttribute

private void setAttributeFromDOMAttribute ( p_sAttribute )
Gets the value of the specified DOM attribute and sets it into the collection of configuration attributes used to configure the button.
Parameters:
p_sAttribute <String> String representing the name of the attribute to retrieve from the DOM element.
Returns: void

setAttributesFromSrcElement

private void setAttributesFromSrcElement ( p_oElement , p_oAttributes )
Gets the values for all the attributes of the source element (either <input> or <a>) that map to Button configuration attributes and sets them into a collection that is passed to the Button constructor.
Parameters:
p_oElement <HTMLInputElement|HTMLAnchorElement> Object reference to the HTML element (either <input> or <span> ) used to create the button.
p_oAttributes <Object> Object reference for the collection of configuration attributes used to create the button.
Returns: void

setFormElementProperties

private void setFormElementProperties ( )
Gets the value of the attributes from the form element and sets them into the collection of configuration attributes used to configure the button.
Returns: void

submitForm

protected Boolean submitForm ( )
Submits the form to which the button belongs. Returns true if the form was submitted successfully, false if the submission was cancelled.
Returns: Boolean

toString

String toString ( )
Returns a string representing the button.
Returns: String

YAHOO.widget.Button.onFormKeyPress

void YAHOO.widget.Button.onFormKeyPress ( p_oEvent )
"keypress" event handler for the button's form.
Parameters:
p_oEvent <Event> Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).
Returns: void

Events

blur

blur ( )
Fires when the menu item loses the input focus. Passes back a single object representing the original DOM event object passed back by the event utility (YAHOO.util.Event) when the event was fired. See Element.addListener for more information on listening for this event.

focus

focus ( )
Fires when the menu item receives focus. Passes back a single object representing the original DOM event object passed back by the event utility (YAHOO.util.Event) when the event was fired. See Element.addListener for more information on listening for this event.

option

option ( )
Fires when the user invokes the button's option. Passes back a single object representing the original DOM event (either "mousedown" or "keydown") that caused the "option" event to fire. See Element.addListener for more information on listening for this event.

Events inherited from YAHOO.util.Element:

Configuration Attributes

checked - Boolean

Boolean indicating if the button is checked. Applies only to buttons of type "radio" and "checkbox."
Default Value: false

container - HTMLElement|String

HTML element reference or string specifying the id attribute of the HTML element that the button's markup should be rendered into.
Default Value: null

disabled - Boolean

Boolean indicating if the button should be disabled. (Disabled buttons are dimmed and will not respond to user input or fire events. Does not apply to button's of type "link.")
Default Value: false

focusmenu - Boolean

Boolean indicating whether or not the button's menu should be focused when it is made visible.
Default Value: true

href - String

String specifying the href for the button. Applies only to buttons of type "link."

label - String

String specifying the button's text label or innerHTML.
Default Value: null

lazyloadmenu - Boolean

Boolean indicating the value to set for the "lazyload" configuration property of the button's menu. Setting "lazyloadmenu" to true will defer rendering of the button's menu until the first time it is made visible. If "lazyloadmenu" is set to false, the button's menu will be rendered immediately if the button is in the document, or in response to the button's "appendTo" event if the button is not yet in the document. In either case, the menu is rendered into the button's parent HTML element. This attribute does not apply if a YAHOO.widget.Menu or YAHOO.widget.Overlay instance is passed as the value of the button's "menu" configuration attribute. YAHOO.widget.Menu or YAHOO.widget.Overlay instances should be rendered before being set as the value for the "menu" configuration attribute.
Default Value: true

menu - YAHOO.widget.Menu|YAHOO.widget.Overlay|HTMLElement|String|Array

Object specifying the menu for the button. The value can be one of the following:
  • Object specifying a YAHOO.widget.Menu instance.
  • Object specifying a YAHOO.widget.Overlay instance.
  • String specifying the id attribute of the <div> element used to create the menu. By default the menu will be created as an instance of YAHOO.widget.Overlay. If the default CSS class name for YAHOO.widget.Menu is applied to the <div> element, it will be created as an instance of YAHOO.widget.Menu .
  • String specifying the id attribute of the <select> element used to create the menu.
  • Object specifying the <div> element used to create the menu.
  • Object specifying the <select> element used to create the menu.
  • Array of object literals, each representing a set of YAHOO.widget.MenuItem configuration attributes.
  • Array of strings representing the text labels for each menu item in the menu.
Default Value: null

menuclassname - String

String representing the CSS class name to be applied to the root element of the button's menu.
Default Value: "yui-button-menu"

name - String

String specifying the name for the button.
Default Value: null

onclick - Object

Object literal representing the code to be executed when the button is clicked. Format:
{
fn: Function, // The handler to call when the event fires.
obj: Object, // An object to pass back to the handler.
scope: Object // The object to use for the scope of the handler.
}
Default Value: null

selectedMenuItem - Number

Number representing the index of the item in the button's menu that is currently selected.
Default Value: null

srcelement - HTMLElement|String

Object reference to the HTML element (either <input> or <span>) used to create the button.
Default Value: null

tabindex - Number

Number specifying the tabindex for the button.
Default Value: null

target - String

String specifying the target for the button. Applies only to buttons of type "link."

title - String

String specifying the title for the button.
Default Value: null

type - String

String specifying the button's type. Possible values are: "push," "link," "submit," "reset," "checkbox," "radio," "menu," and "split."
Default Value: "push"

value - Object

Object specifying the value for the button.
Default Value: null

Configuration attributes inherited from YAHOO.util.Element:


Copyright © 2007 Yahoo! Inc. All rights reserved.