# Yahoo! UI Library

### editor 2.3.1

Yahoo! UI Library > editor > YAHOO.widget.Toolbar

Show Private Show Protected

## Class YAHOO.widget.Toolbar

Creates a rich Toolbar widget based on Button. Primarily used with the Rich Text Editor

### Constructor

YAHOO.widget.Toolbar `( el , attrs )`

Parameters:
  `el <String/HTMLElement>` The element to turn into a toolbar.
  `attrs <Object>` Object liternal containing configuration parameters.

### Properties

#### _buttonGroupList `- protected Array`

Internal property list of current button groups in the toolbar

#### _buttonList `- protected Array`

Internal property list of current buttons in the toolbar

#### _colorData `- Object`

Object reference containing colors hex and text values.

#### _colorPicker `- HTMLElement`

The HTML Element containing the colorPicker

#### _disabled `- Object`

Object to track button status when enabling/disabling the toolbar

#### _sep `- protected HTMLElement`

Internal reference to the separator HTML Element for cloning

#### _sepCount `- protected Number`

Internal refernce for counting separators, so we can give them a useful class name for styling

#### _titlebar `- HTMLElement`

Object reference to the titlebar

#### _toolbarConfigs `- protected Object`

#### browser `- Object`

Standard browser detection

#### CLASS_CONTAINER `- protected String`

Default CSS class to apply to the toolbar container element

#### CLASS_DISABLED `- protected String`

Default CSS class to apply when the toolbar is disabled

#### CLASS_DRAGHANDLE `- protected String`

Default CSS class to apply to the toolbar's drag handle element

#### CLASS_PREFIX `- protected String`

Default prefix for dynamically created class names

#### CLASS_SEPARATOR `- protected String`

Default CSS class to apply to all separators in the toolbar

#### dd `- Object`

The DragDrop instance associated with the Toolbar

#### Dom `- private object`

#### draghandle `- protected HTMLElement`

#### STR_COLLAPSE `- String`

String for Toolbar Collapse Button

#### STR_SPIN_DOWN `- String`

String for spinbutton down

#### STR_SPIN_LABEL `- String`

String for spinbutton dynamic label. Note the {VALUE} will be replaced with YAHOO.lang.substitute

#### STR_SPIN_UP `- String`

String for spinbutton up

### Methods

#### _addMenuClasses

`private void _addMenuClasses ( ev , na , o )`
This method is called from Menu's renderEvent to add a few more classes to the menu items

Parameters:
  `ev <String>` The event that fired.
  `na <Array>` Array of event information.
  `o <Object>` Button config object.

Returns: `void`

#### _buttonClick

`protected void _buttonClick ( ev , info )`
Click handler for all buttons in the toolbar.

Parameters:
  `ev <String>` The event that was passed in.
  `info <Object>` Object literal of information about the button that was clicked.

Returns: `void`

#### _createColorPicker

`private void _createColorPicker ( id )`
Creates the core DOM reference to the color picker menu item.

Parameters:
  `id <String>` the id of the toolbar to prefix this DOM container with.

Returns: `void`

#### _makeColorButton

`private void _makeColorButton ( _oButton )`
Called to turn a "color" button into a menu button with an Overlay for the menu.

Parameters:
  `_oButton <Object>` YAHOO.widget.Button reference

Returns: `void`

#### _makeSpinButton

`private void _makeSpinButton ( _button , oButton )`
Create a button similar to an OS Spin button.. It has an up/down arrow combo to scroll through a range of int values.

Parameters:
  `_button <Object>` YAHOO.widget.Button reference
  `oButton <Object>` Object literal containing the buttons initial config

Returns: `void`

#### _resetColorPicker

`private void _resetColorPicker ( )`
Clears the currently selected color or mouseover color in the color picker.

Returns: `void`

#### addButton

`void addButton ( oButton , after )`
Add a new button to the toolbar. Buttons supported: push, split, menu, select, color, spin

Parameters:
  `oButton <Object>` Object literal reference to the Button's Config
  `after <HTMLElement>` Optional HTML element to insert this button after in the DOM.

Returns: `void`

#### addButtonGroup

`void addButtonGroup ( oGroup )`
Add a new button group to the toolbar. (uses addButton)

Parameters:
  `oGroup <Object>` Object literal reference to the Groups Config (contains an array of button configs)

Returns: `void`

#### addButtonToGroup

`void addButtonToGroup ( oButton , group , after )`
Add a new button to a toolbar group. Buttons supported: push, split, menu, select, color, spin

Parameters:
  `oButton <Object>` Object literal reference to the Button's Config
  `group <String>` The Group identifier passed into the initial config
  `after <HTMLElement>` Optional HTML element to insert this button after in the DOM.

Returns: `void`

#### addSeparator

`void addSeparator ( cont , after )`
Add a new button separator to the toolbar.

Parameters:
  `cont <HTMLElement>` Optional HTML element to insert this button into.
  `after <HTMLElement>` Optional HTML element to insert this button after in the DOM.

Returns: `void`

#### collapse

`void collapse ( collapse )`
Programatically collapse the toolbar.

Parameters:
  `collapse <Boolean>` True to collapse, false to expand.

Returns: `void`

#### deselectAllButtons

`Boolean deselectAllButtons ( )`
Deselects all buttons in the toolbar.

Returns: `Boolean`

#### deselectButton

`Boolean deselectButton ( id )`
Deselects a button in the toolbar.

Parameters:
  `id <String/Number>` Deselect a button by it's id, index or value.

Returns: `Boolean`

#### destroy

`Boolean destroy ( )`
Destroys the toolbar, all of it's elements and objects.

Returns: `Boolean`

#### destroyButton

`Boolean destroyButton ( id )`
Destroy a button in the toolbar.

Parameters:
  `id <String/Number>` Destroy a button by it's id or index.

Returns: `Boolean`

#### disableAllButtons

`Boolean disableAllButtons ( )`
Disables all buttons in the toolbar.

Returns: `Boolean`

#### disableButton

`Boolean disableButton ( id )`
Disables a button in the toolbar.

Parameters:
  `id <String/Number>` Disable a button by it's id, index or value.

Returns: `Boolean`

#### enableAllButtons

`Boolean enableAllButtons ( )`
Enables all buttons in the toolbar.

Returns: `Boolean`

#### enableButton

`Boolean enableButton ( id )`
Enables a button in the toolbar.

Parameters:
  `id <String/Number>` Enable a button by it's id, index or value.

Returns: `Boolean`

#### getButtonById

`YAHOO.widget.Button getButtonById ( id )`
Gets a button instance from the toolbar by is Dom id.

Parameters:
  `id <String>` The Dom id to query for.

Returns: `YAHOO.widget.Button`

#### getButtonByIndex

`YAHOO.widget.Button getButtonByIndex ( index )`
Gets a button instance from the toolbar by is index in _buttonList.

Parameters:
  `index <Number>` The index of the button in _buttonList.

Returns: `YAHOO.widget.Button`

#### getButtonByValue

`YAHOO.widget.Button or YAHOO.widget.MenuItem getButtonByValue ( value )`
Gets a button instance or a menuitem instance from the toolbar by it's value.

Parameters:
  `value <String>` The button value to query for.

Returns: `YAHOO.widget.Button or YAHOO.widget.MenuItem`

#### getButtons

`Array getButtons ( )`
Returns an array of buttons in the current toolbar

Returns: `Array`

#### init

`void init ( )`
The Toolbar class's initialization method

Returns: `void`

#### initAttributes

`void initAttributes ( attr )`
Initializes all of the configuration attributes used to create the toolbar.

Parameters:
  `attr <Object>` Object literal specifying a set of configuration attributes used to create the toolbar.

Returns: `void`

#### resetAllButtons

`Boolean resetAllButtons ( _ex )`
Resets all buttons to their initial state.

Parameters:
  `_ex <Object>` Except these buttons

Returns: `Boolean`

#### selectButton

`Boolean selectButton ( id )`
Selects a button in the toolbar.

Parameters:
  `id <String/Number>` Select a button by it's id, index or value.

Returns: `Boolean`

#### toString

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

Returns: `String`

### Events

#### beforeButtonsChangeEvent

`beforeButtonsChangeEvent ( eventInfo )`
Fires before the value for the configuration attribute 'buttons' changes. Return false to cancel the attribute change.

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

#### beforeCollapseChangeEvent

`beforeCollapseChangeEvent ( eventInfo )`
Fires before the value for the configuration attribute 'collapse' changes. Return false to cancel the attribute change.

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

#### beforeContChangeEvent

`beforeContChangeEvent ( eventInfo )`
Fires before the value for the configuration attribute 'cont' changes. Return false to cancel the attribute change.

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

#### beforeDisabledChangeEvent

`beforeDisabledChangeEvent ( eventInfo )`
Fires before the value for the configuration attribute 'disabled' changes. Return false to cancel the attribute change.

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

#### beforeDraggableChangeEvent

`beforeDraggableChangeEvent ( eventInfo )`
Fires before the value for the configuration attribute 'draggable' changes. Return false to cancel the attribute change.

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

#### beforeGrouplabelsChangeEvent

`beforeGrouplabelsChangeEvent ( eventInfo )`
Fires before the value for the configuration attribute 'grouplabels' changes. Return false to cancel the attribute change.

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

#### beforeTitlebarChangeEvent

`beforeTitlebarChangeEvent ( eventInfo )`
Fires before the value for the configuration attribute 'titlebar' changes. Return false to cancel the attribute change.

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

#### buttonClick

`buttonClick ( o )`
Fires when any botton receives a click event. Passes back a single object representing the buttons config object. See Element.addListener for more information on listening for this event.

Parameters:
  `o <Object>` The object passed to this handler is the button config used to create the button.

#### buttonsChangeEvent

`buttonsChangeEvent ( eventInfo )`
Fires when the value for the configuration attribute 'buttons' changes.

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

#### collapseChangeEvent

`collapseChangeEvent ( eventInfo )`
Fires when the value for the configuration attribute 'collapse' changes.

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

#### contChangeEvent

`contChangeEvent ( eventInfo )`
Fires when the value for the configuration attribute 'cont' changes.

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

#### disabledChangeEvent

`disabledChangeEvent ( eventInfo )`
Fires when the value for the configuration attribute 'disabled' changes.

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

#### draggableChangeEvent

`draggableChangeEvent ( eventInfo )`
Fires when the value for the configuration attribute 'draggable' changes.

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

#### grouplabelsChangeEvent

`grouplabelsChangeEvent ( eventInfo )`
Fires when the value for the configuration attribute 'grouplabels' changes.

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

#### titlebarChangeEvent

`titlebarChangeEvent ( eventInfo )`
Fires when the value for the configuration attribute 'titlebar' changes.

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

#### toolbarCollapsed

`toolbarCollapsed ( )`
Fires when the toolbar is collapsed via the collapse button. See Element.addListener for more information on listening for this event.

#### toolbarExpanded

`toolbarExpanded ( )`
Fires when the toolbar is expanded via the collapse button. See Element.addListener for more information on listening for this event.

#### valueClick

`valueClick ( o )`
This is a special dynamic event that is created and dispatched based on the value property of the button config. See Element.addListener for more information on listening for this event. Example: `

    buttons : [
    { type: 'button', value: 'test', value: 'testButton' }
    ]

` With the valueClick event you could subscribe to this buttons click event with this: tbar.in('testButtonClick', function() { alert('test button clicked'); })

Parameters:
  `o <Object>` The object passed to this handler is the button config used to create the button.

### Configuration Attributes

#### buttons `- Array`

Object specifying the buttons to include in the toolbar Example: `

    {
    { id: 'b3', type: 'button', label: 'Underline', value: 'underline' },
    { type: 'separator' },
    { id: 'b4', type: 'menu', label: 'Align', value: 'align',
    menu: [
    { text: "Left", value: 'alignleft' },
    { text: "Center", value: 'aligncenter' },
    { text: "Right", value: 'alignright' }
    ]
    }
    }

`

#### collapse `- Boolean`

Boolean indicating if the the titlebar should have a collapse button. The collapse button will not remove the toolbar, it will minimize it to the titlebar
Default Value: false

#### cont `- HTMLElement`

The container for the toolbar.

#### disabled `- Boolean`

Boolean indicating if the toolbar should be disabled. It will also disable the draggable attribute if it is on.
Default Value: false

#### draggable `- Boolean`

Boolean indicating if the toolbar should be draggable.
Default Value: false

#### grouplabels `- Boolean`

Boolean indicating if the toolbar should show the group label's text string.
Default Value: true

#### titlebar `- Boolean or String`

Boolean indicating if the toolbar should have a titlebar. If passed a string, it will use that as the titlebar text
Default Value: false

Copyright © 2007 Yahoo! Inc. All rights reserved.