Print Friendly

# Class Ext.MenuButton

Package: | Ext
Class: | MenuButton
Extends: | Button
Subclasses: | Toolbar.MenuButton
Defined In: | MenuButton.js

A split button that provides a built-in dropdown arrow that can fire an event separately from the default click event of the button. Typically this would be used to display a dropdown menu that provides additional options to the primary button action, but any custom handler can provide the arrowclick implementation.
Properties - Methods - Events - Config Options

## Public Properties

Property | Defined By
--- | ---
| disabled : Boolean | Button
Read-only. True if this button is disabled
| hidden : Boolean | Button
Read-only. True if this button is hidden
| pressed : Boolean | Button
Read-only. True if this button is pressed (only if enableToggle = true)

## Public Methods

Method | Defined By
--- | ---
| MenuButton(`String/HTMLElement/Element renderTo`, `Object config`) | MenuButton
Create a new menu button
| addEvents(`Object object`) : void | Observable
Copies any events from the passed object onto this object if they do not already exist. The passed object must also ...
| addListener(`String eventName`, `Function handler`, [`Object scope`], [`Object options`]) : void | Observable
Appends an event handler to this component
| destroy() : void | Button
Destroys this Button and removes any listeners.
| disable() : void | Button
Disable this button
| enable() : void | Button
Enable this button
| fireEvent(`String eventName`, `Object... args`) : Boolean | Observable
Fires the specified event with the passed parameters (minus the event name).
| focus() : void | MenuButton
Focus the button
| getEl() : Ext.Element | Button
Returns the button's underlying element
| getText() : String | Button
Gets the text for this button
| hasListener(`String eventName`) : Boolean | Observable
Checks to see if this object is currently listening for a specified event
| hide() : void | Button
Hide this button
| on(`String eventName`, `Function handler`, [`Object options`]) : void | Observable
Appends an event handler to this element (shorthand for addListener)
| purgeListeners() : void | Observable
Removes all listeners for this object
| removeListener(`String eventName`, `Function handler`, [`Object scope`]) : void | Observable
Removes a listener
| setArrowHandler(`Function handler`, [`Object scope`]) : void | MenuButton
Sets this button's arrow click handler
| setDisabled(`Boolean enabled`) : void | Button
Convenience function for boolean enable/disable
| setHandler(`Function handler`, [`Object scope`]) : void | MenuButton
Sets this button's click handler
| setText(`String text`) : void | Button
Sets this button's text
| setVisible(`Boolean visible`) : void | Button
Convenience function for boolean show/hide
| show() : void | Button
Show this button
| toggle([`Boolean state`]) : void | Button
If a state it passed, it becomes the pressed state otherwise the current state is toggled.
| un(`String eventName`, `Function handler`, [`Object scope`]) : void | Observable
Removes a listener (shorthand for removeListener)

## Public Events

Event | Defined By
--- | ---
| arrowclick : (`MenuButton this`, `EventObject e`) | MenuButton
Fires when this button's arrow is clicked
| click : (`Button this`, `EventObject e`) | Button
Fires when this button is clicked
| mouseout : (`Button this`, `Event e`) | Button
Fires when the mouse exits the button
| mouseover : (`Button this`, `Event e`) | Button
Fires when the mouse hovers over the button
| toggle : (`Button this`, `Boolean pressed`) | Button
Fires when the "pressed" state of this button changes (only if enableToggle = true)

## Config Options

Config Options | Defined By
--- | ---
| arrowHandler : Function | MenuButton
A function called when the arrow button is clicked (can be used instead of click event)
| arrowTooltip : String | MenuButton
The title attribute of the arrow
| disabled : Boolean | Button
True to start disabled (defaults to false)
| enableToggle : Boolean | Button
True to enable pressed/not pressed toggling (defaults to false)
| handler : Function | Button
A function called when the button is clicked (can be used instead of click event)
| hidden : Boolean | Button
True to start hidden (defaults to false)
| icon : String | Button
The path to an image to display in the button (the image will be set as the background-image CSS property of the butt...
| menu : Mixed | Button
Standard menu attribute consisting of a reference to a menu object, a menu id or a menu config blob
| menuAlign : String | Button
The position to align the menu to (see Ext.Element.alignTo for more details, defaults to 'tl-bl?').
| minWidth : Number | Button
The minimum width for this button (used to give a set of buttons a common width)
| pressed : Boolean | Button
True to start pressed (only if enableToggle = true)
| repeat : Boolean/Object | Button
True to repeat fire the click event while the mouse is down. This can also be an Ext.util.ClickRepeater config object...
| scope : Object | Button
The scope of the handler
| text : String | Button
The button text
| toggleGroup : String | Button
The group this toggle button is a member of (only 1 per group can be pressed, only applies if enableToggle = true)
| tooltip : String/Object | Button
The tooltip for the button - can be a string or QuickTips config object
| tooltipType : String | Button
The type of tooltip to use. Either "qtip" for QuickTips or "title" for title attribute.

## Property Details

### disabled

`public Boolean disabled`
Read-only. True if this button is disabled
This property is defined by Button.

### hidden

`public Boolean hidden`
Read-only. True if this button is hidden
This property is defined by Button.

### pressed

`public Boolean pressed`
Read-only. True if this button is pressed (only if enableToggle = true)
This property is defined by Button.

## Constructor Details

### MenuButton

`public function MenuButton(`String/HTMLElement/Element renderTo`, `Object config`)`
Create a new menu button
Parameters:

- `renderTo` : String/HTMLElement/Element
  The element to append the button to
- `config` : Object
  The config object

## Method Details

### addEvents

`public function addEvents(`Object object`)`
Copies any events from the passed object onto this object if they do not already exist. The passed object must also inherit from Observable for this method to have any effect.
Parameters:

- `object` : Object
  The object from which to copy events

Returns:

- `void`

This method is defined by Observable.

### addListener

`public function addListener(`String eventName`, `Function handler`, [`Object scope`], [`Object options`])`
Appends an event handler to this component
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The method the event invokes
- `scope` : Object
  (optional) The scope in which to execute the handler function. The handler function's "this" context.
- `options` : Object
  (optional) An object containing handler configuration properties. This may contain any of the following properties:
  - scope {Object} The scope in which to execute the handler function. The handler function's "this" context.
  - delegate {String} A simple selector to filter the target or look for a descendant of the target
  - stopEvent {Boolean} True to stop the event. That is stop propagation, and prevent the default action.
  - preventDefault {Boolean} True to prevent the default action
  - stopPropagation {Boolean} True to prevent event propagation
  - normalized {Boolean} False to pass a browser event to the handler function instead of an Ext.EventObject
  - delay {Number} The number of milliseconds to delay the invocation of the handler after te event fires.
  - single {Boolean} True to add a handler to handle just the next firing of the event, and then remove itself.
  - buffer {Number} Causes the handler to be scheduled to run in an Ext.util.DelayedTask delayed by the specified number of milliseconds. If the event fires again within that time, the original handler is not invoked, but the new handler is scheduled in its place.

  Combining Options
  Using the options argument, it is possible to combine different types of listeners:
  A normalized, delayed, one-time listener that auto stops the event and passes a custom argument (forumId)

  Code:

      el.on('click', this.onClick, this, { single: true, delay: 100, stopEvent : true, forumId: 4 });

  The method also allows for a single argument to be passed which is a config object containing properties which specify multiple handlers.

  Attaching multiple handlers in 1 call
  Code:

      el.on({ 'click' : { fn: this.onClick scope: this, delay: 100 }, 'mouseover' : { fn: this.onMouseOver scope: this }, 'mouseout' : { fn: this.onMouseOut scope: this } });

  Or a shorthand syntax:
  Code:

      el.on({ 'click' : this.onClick, 'mouseover' : this.onMouseOver, 'mouseout' : this.onMouseOut scope: this });

Returns:

- `void`

This method is defined by Observable.

### destroy

`public function destroy()`
Destroys this Button and removes any listeners.
Parameters:

- None.

Returns:

- `void`

This method is defined by Button.

### disable

`public function disable()`
Disable this button
Parameters:

- None.

Returns:

- `void`

This method is defined by Button.

### enable

`public function enable()`
Enable this button
Parameters:

- None.

Returns:

- `void`

This method is defined by Button.

### fireEvent

`public function fireEvent(`String eventName`, `Object... args`)`
Fires the specified event with the passed parameters (minus the event name).
Parameters:

- `eventName` : String
- `args` : Object...
  Variable number of parameters are passed to handlers

Returns:

- `Boolean`
  returns false if any of the handlers return false otherwise it returns true

This method is defined by Observable.

### focus

`public function focus()`
Focus the button
Parameters:

- None.

Returns:

- `void`

This method is defined by MenuButton.

### getEl

`public function getEl()`
Returns the button's underlying element
Parameters:

- None.

Returns:

- `Ext.Element`
  The element

This method is defined by Button.

### getText

`public function getText()`
Gets the text for this button
Parameters:

- None.

Returns:

- `String`
  The button text

This method is defined by Button.

### hasListener

`public function hasListener(`String eventName`)`
Checks to see if this object is currently listening for a specified event
Parameters:

- `eventName` : String
  The name of the event to check for

Returns:

- `Boolean`
  True if the event is being listened for, else false

This method is defined by Observable.

### hide

`public function hide()`
Hide this button
Parameters:

- None.

Returns:

- `void`

This method is defined by Button.

### on

`public function on(`String eventName`, `Function handler`, [`Object options`])`
Appends an event handler to this element (shorthand for addListener)
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The method the event invokes
- `options` : Object
  (optional)

Returns:

- `void`

This method is defined by Observable.

### purgeListeners

`public function purgeListeners()`
Removes all listeners for this object
Parameters:

- None.

Returns:

- `void`

This method is defined by Observable.

### removeListener

`public function removeListener(`String eventName`, `Function handler`, [`Object scope`])`
Removes a listener
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The handler to remove
- `scope` : Object
  (optional) The scope (this object) for the handler

Returns:

- `void`

This method is defined by Observable.

### setArrowHandler

`public function setArrowHandler(`Function handler`, [`Object scope`])`
Sets this button's arrow click handler
Parameters:

- `handler` : Function
  The function to call when the arrow is clicked
- `scope` : Object
  (optional) Scope for the function passed above

Returns:

- `void`

This method is defined by MenuButton.

### setDisabled

`public function setDisabled(`Boolean enabled`)`
Convenience function for boolean enable/disable
Parameters:

- `enabled` : Boolean
  True to enable, false to disable

Returns:

- `void`

This method is defined by Button.

### setHandler

`public function setHandler(`Function handler`, [`Object scope`])`
Sets this button's click handler
Parameters:

- `handler` : Function
  The function to call when the button is clicked
- `scope` : Object
  (optional) Scope for the function passed above

Returns:

- `void`

This method is defined by MenuButton.

### setText

`public function setText(`String text`)`
Sets this button's text
Parameters:

- `text` : String
  The button text

Returns:

- `void`

This method is defined by Button.

### setVisible

`public function setVisible(`Boolean visible`)`
Convenience function for boolean show/hide
Parameters:

- `visible` : Boolean
  True to show, false to hide

Returns:

- `void`

This method is defined by Button.

### show

`public function show()`
Show this button
Parameters:

- None.

Returns:

- `void`

This method is defined by Button.

### toggle

`public function toggle([`Boolean state`])`
If a state it passed, it becomes the pressed state otherwise the current state is toggled.
Parameters:

- `state` : Boolean
  (optional) Force a particular state

Returns:

- `void`

This method is defined by Button.

### un

`public function un(`String eventName`, `Function handler`, [`Object scope`])`
Removes a listener (shorthand for removeListener)
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The handler to remove
- `scope` : Object
  (optional) The scope (this object) for the handler

Returns:

- `void`

This method is defined by Observable.

## Event Details

### arrowclick

`public event arrowclick`
Fires when this button's arrow is clicked
Subscribers will be called with the following parameters:

- `this` : MenuButton
- `e` : EventObject
  The click event

This event is defined by MenuButton.

### click

`public event click`
Fires when this button is clicked
Subscribers will be called with the following parameters:

- `this` : Button
- `e` : EventObject
  The click event

This event is defined by Button.

### mouseout

`public event mouseout`
Fires when the mouse exits the button
Subscribers will be called with the following parameters:

- `this` : Button
- `e` : Event
  The event object

This event is defined by Button.

### mouseover

`public event mouseover`
Fires when the mouse hovers over the button
Subscribers will be called with the following parameters:

- `this` : Button
- `e` : Event
  The event object

This event is defined by Button.

### toggle

`public event toggle`
Fires when the "pressed" state of this button changes (only if enableToggle = true)
Subscribers will be called with the following parameters:

- `this` : Button
- `pressed` : Boolean

This event is defined by Button.

## Config Details

### arrowHandler

`arrowHandler : Function`
A function called when the arrow button is clicked (can be used instead of click event)
This config option is defined by MenuButton.

### arrowTooltip

`arrowTooltip : String`
The title attribute of the arrow
This config option is defined by MenuButton.

### disabled

`disabled : Boolean`
True to start disabled (defaults to false)
This config option is defined by Button.

### enableToggle

`enableToggle : Boolean`
True to enable pressed/not pressed toggling (defaults to false)
This config option is defined by Button.

### handler

`handler : Function`
A function called when the button is clicked (can be used instead of click event)
This config option is defined by Button.

### hidden

`hidden : Boolean`
True to start hidden (defaults to false)
This config option is defined by Button.

### icon

`icon : String`
The path to an image to display in the button (the image will be set as the background-image CSS property of the button by default, so if you want a mixed icon/text button, set cls:"x-btn-text-icon")
This config option is defined by Button.

### menu

`menu : Mixed`
Standard menu attribute consisting of a reference to a menu object, a menu id or a menu config blob
This config option is defined by Button.

### menuAlign

`menuAlign : String`
The position to align the menu to (see Ext.Element.alignTo for more details, defaults to 'tl-bl?').
This config option is defined by Button.

### minWidth

`minWidth : Number`
The minimum width for this button (used to give a set of buttons a common width)
This config option is defined by Button.

### pressed

`pressed : Boolean`
True to start pressed (only if enableToggle = true)
This config option is defined by Button.

### repeat

`repeat : Boolean/Object`
True to repeat fire the click event while the mouse is down. This can also be an Ext.util.ClickRepeater config object (defaults to false).
This config option is defined by Button.

### scope

`scope : Object`
The scope of the handler
This config option is defined by Button.

### text

`text : String`
The button text
This config option is defined by Button.

### toggleGroup

`toggleGroup : String`
The group this toggle button is a member of (only 1 per group can be pressed, only applies if enableToggle = true)
This config option is defined by Button.

### tooltip

`tooltip : String/Object`
The tooltip for the button - can be a string or QuickTips config object
This config option is defined by Button.

### tooltipType

`tooltipType : String`
The type of tooltip to use. Either "qtip" for QuickTips or "title" for title attribute.
This config option is defined by Button.

Ext - Copyright © 2006-2007 Ext JS, LLC
All rights reserved.