API: button YAHOO.widget.Button (YUI Library)

# Yahoo! UI Library

### Button 2.2.2

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

## 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>`, `<a>` or `<span>` element to be used to create the button.
  `p_oElement <HTMLInputElement|HTMLElement>` Object reference for the `<input>`, `<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" and "mousedown" and "mouseup" event handlers are assigned
Default Value: false

#### _hiddenField `- protected HTMLInputElement`

Object reference to the `<input>` element used when the button's parent form is submitted.
Default Value: null

#### _menu `- protected 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: "yuibutton"

#### MENUBUTTON_DEFAULT_TITLE `- final String`

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

#### MENUBUTTON_MENU_VISIBLE_TITLE `- final String`

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

#### 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 "splitebutton."
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 "splitbutton" 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."

#### TAG_NAME `- final String`

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

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

#### _addListenersToForm

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

Returns: `void`

#### _createButtonElement

`protected HTMLElement _createButtonElement ( p_sType )`
Creates the button's element.

Parameters:
  `p_sType <String>` String indicating the type of element to create.

Returns: `HTMLElement`

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

#### _onFormSubmit

`protected void _onFormSubmit ( p_oEvent )`
"submit" 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 , p_aArgs )`
"hide" 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`

#### _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_oItem )`
"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_oItem <YAHOO.widget.MenuItem>` Object representing 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 , p_aArgs )`
"render" 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`

#### _onMenuShow

`private void _onMenuShow ( p_sType , p_aArgs )`
"show" 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`

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

#### _setAccessKey

`protected void _setAccessKey ( p_sAccessKey )`
Sets the value of the button's "accesskey" attribute.

Parameters:
  `p_sAccessKey <String>` String indicating the value for the button's "accesskey" attribute.

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`

#### _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," "menubutton," and "splitbutton."

Parameters:
  `p_oForm <HTMLFormElement>` Object reference for the form to search.

Returns: `void`

#### blur

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

Returns: `void`

#### createHiddenField

`HTMLInputElement createHiddenField ( )`
Creates the button's hidden form field and appends it to its parent form.

Returns: `HTMLInputElement`

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

#### getFirstElement

`private HTMLElement getFirstElement ( p_oElement )`
Returns an HTML element's first HTML element node.

Parameters:
  `p_oElement <HTMLElement>` Object reference specifying the element to be evaluated.

Returns: `HTMLElement`

#### getForm

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

Returns: `HTMLFormElement`

#### getHiddenField

`HTMLInputElement getHiddenField ( )`
Returns a reference to the `<input>` element used when the button's parent form is submitted.

Returns: `HTMLInputElement`

#### getMenu

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

Returns: `YAHOO.widget.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>`, `<a>` or `<span>` element to be used to create the button.
  `p_oElement <HTMLInputElement|HTMLElement>` Object reference for the `<input>`, `<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`

#### onFormKeyDown

`void onFormKeyDown ( p_oEvent )`
"keydown" 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`

#### 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 void submitForm ( )`
Submits the form to which the button belongs.

Returns: `void`

#### toString

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

Returns: `String`

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

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

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

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

`available, contentReady`

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

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

#### menu `- 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.
- String specifying the id attribute of the `<div>` element used to create the 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

#### 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 `- YAHOO.widget.MenuItem`

Reference to 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: "button," "link," "submit," "reset," "checkbox," "radio," "menubutton," and "splitbutton."
Default Value: "button"

#### value `- Object`

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

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

`element`

Copyright © 2007 Yahoo! Inc. All rights reserved.