Clear Up
SharpKit Reference

Button Class

Create simple buttons with this component. Customisations include alignedicons, dropdown menus, tooltips and sizing options. Specify a handler to run code when a user clicks the button, or use listeners for other events such as mouseover. Example usage:

  
    Ext.create('Ext.Button', {
            text: 'Click me',
            renderTo: Ext.getBody(),
            handler: function() {
            alert('You clicked the button!');
            }
            });
            

The handler configuration can also be updated dynamically using the setHandler method. Example usage:

  
    Ext.create('Ext.Button', {
            text    : 'Dynamic Handler Button',
            renderTo: Ext.getBody(),
            handler : function() {
            // this button will spit out a different number every time you click it.
            // so firstly we must check if that number is already set:
            if (this.clickCount) {
            // looks like the property is already set, so lets just add 1 to that number and alert the user
            this.clickCount++;
            alert('You have clicked the button "' + this.clickCount + '" times.\n\nTry clicking it again..');
            } else {
            // if the clickCount property is not set, we will set it and alert the user
            this.clickCount = 1;
            alert('You just clicked the button for the first time!\n\nTry pressing it again..');
            }
            }
            });
            

A button within a container:

  
    Ext.create('Ext.Container', {
            renderTo: Ext.getBody(),
            items   : [
            {
            xtype: 'button',
            text : 'My Button'
            }
            ]
            });
            

A useful option of Button is the scale configuration. This configuration has three different options:

  • 'small'
  • 'medium'
  • 'large'

Example usage:

  
    Ext.create('Ext.Button', {
            renderTo: document.body,
            text    : 'Click me',
            scale   : 'large'
            });
            

Buttons can also be toggled. To enable this, you simple set the enableToggle property to true. Example usage:

  
    Ext.create('Ext.Button', {
            renderTo: Ext.getBody(),
            text: 'Click Me',
            enableToggle: true
            });
            

You can assign a menu to a button by using the menu configuration. This standard configuration can either be a reference to a menu object, a menu id or a menu config blob. When assigning a menu to a button, an arrow is automatically added to the button. You can change the alignment of the arrow using the arrowAlign configuration on button. Example usage:

  
    Ext.create('Ext.Button', {
            text      : 'Menu button',
            renderTo  : Ext.getBody(),
            arrowAlign: 'bottom',
            menu      : [
            {text: 'Item 1'},
            {text: 'Item 2'},
            {text: 'Item 3'},
            {text: 'Item 4'}
            ]
            });
            

Using listeners, you can easily listen to events fired by any component, using the listeners configuration or using the addListener method. Button has a variety of different listeners:

  • click
  • toggle
  • mouseover
  • mouseout
  • mouseshow
  • menuhide
  • menutriggerover
  • menutriggerout

Example usage:

  
    Ext.create('Ext.Button', {
            text     : 'Button',
            renderTo : Ext.getBody(),
            listeners: {
            click: function() {
            // this == the button, as we are in the local scope
            this.setText('I was clicked!');
            },
            mouseover: function() {
            // set a new config which says we moused over, if not already set
            if (!this.mousedOver) {
            this.mousedOver = true;
            alert('You moused over a button!\n\nI wont do this again.');
            }
            }
            }
            });
            

Namespace: Ext.button

Constructors

Fields

Name Description
allowDepress False to not allow a pressed Button to be depressed. Only valid when enableToggle is true. Defaults to: true
arrowAlign The side of the Button box to render the arrow if the button has an associated menu. Two values are allowed:
  • 'right'
  • 'bottom'
  • Defaults to: "right"
    arrowCls The className used for the inner arrow element if the button has a menu. Defaults to: "arrow"
    baseParams An object literal of parameters to pass to the url when the href property is specified.
    clickEvent The DOM event that will fire the handler of the button. This can be any valid event name (dblclick, contextmenu). Defaults to: "click"
    enableToggle True to enable pressed/not pressed toggling. If a toggleGroup is specified, this option will be set to true. Defaults to: false
    focusCls The CSS class to add to a button when it is in the focussed state. Defaults to: "focus"
    handleMouseEvents False to disable visual cues on mouseover, mouseout and mousedown. Defaults to: true
    handler A function called when the button is clicked (can be used instead of click event).
    href The URL to open when the button is clicked. Specifying this config causes the Button to be rendered with an anchor (An <a> element) as its active element, referencing the specified URL. This is better than specifying a click handler of
    function() { window.location = "http://www.sencha.com" }
                
    because the UI will provide meaningful hints to the user as to what to expect upon clicking the button, and will also allow the user to open in a new tab or window, bookmark or drag the URL, or directly save the URL stream to disk. See also the hrefTarget config.
    hrefTarget The target attribute to use for the underlying anchor. Only used if the href property is specified. Defaults to: "_blank"
    icon The path to an image to display in the button.
    iconAlign The side of the Button box to render the icon. Four values are allowed:
  • 'top'
  • 'right'
  • 'bottom'
  • 'left'
  • Defaults to: "left"
    iconCls A css class which sets a background image to be used as the icon for this button.
    menuActiveCls The CSS class to add to a button when it's menu is active. Defaults to: "menu-active"
    menuAlign The position to align the menu to (see Ext.Element.alignTo for more details). Defaults to: "tl-bl?"
    overflowText If used in a Toolbar, the text to be used if this item is shown in the overflow menu. See also Ext.toolbar.Item.overflowText.
    params An object literal of parameters to pass to the url when the href property is specified. Any params override baseParams. New params can be set using the setParams method.
    pressedCls The CSS class to add to a button when it is in the pressed state. Defaults to: "pressed"
    preventDefault True to prevent the default action when the clickEvent is processed. Defaults to: true
    repeat True to repeat fire the click event while the mouse is down. This can also be a ClickRepeater config object. Defaults to: false
    scale The size of the Button. Three values are allowed:
  • 'small' - Results in the button element being 16px high.
  • 'medium' - Results in the button element being 24px high.
  • 'large' - Results in the button element being 32px high.
  • Defaults to: "small"
    scope The scope (this reference) in which the handler and toggleHandler is executed. Defaults to this Button.
    tabIndex Set a DOM tabIndex for this button.
    text The button text to be used as innerHTML (html tags are accepted).
    textAlign The text alignment for this button (center, left, right). Defaults to: "center"
    toggleGroup The group this toggle button is a member of (only 1 per group can be pressed). If a toggleGroup is specified, the enableToggle configuration will automatically be set to true.
    toggleHandler Function called when a Button with enableToggle set to true is clicked.
    tooltip The tooltip for the button - can be a string to be used as innerHTML (html tags are accepted) or QuickTips config object.
    tooltipType The type of tooltip to use. Either 'qtip' for QuickTips or 'title' for title attribute. Defaults to: "qtip"
    type The type of <input> to create: submit, reset or button. Defaults to: "button"

    Methods

    Name Description
    getTemplateArgs() This method returns an object which provides substitution parameters for the XTemplate used to create this Button's DOM structure. Instances or subclasses which use a different Template to create a different DOM structure may need to provide their own implementation of this method.
    getText() Gets the text for this Button
    hasVisibleMenu() Returns true if the button has a menu and it is visible
    hideMenu() Hides this button's menu (if it has one)
    setHandler(Delegate, object) Assigns this Button's click handler
    setIcon(JsString) Sets the background image (inline style) of the button. This method also changes the value of the icon config internally.
    setIconCls(JsString) Sets the CSS class that provides a background image to use as the button's icon. This method also changes the value of the iconCls config internally.
    setParams(object) Sets the href of the link dynamically according to the params passed, and any baseParams configured. Only valid if the Button was originally configured with a href
    setScale(JsString) Method to change the scale of the button. See scale for allowed configurations.
    setText(JsString) Sets this Button's text
    setTextAlign(JsString) Sets the text alignment for this button.
    setTooltip(object) Sets the tooltip for this Button.
    showMenu() Shows this button's menu (if it has one)
    toggle(object, object) If a state it passed, it becomes the pressed state otherwise the current state is toggled.

    Properties

    Name Description
    menu The Menu object associated with this Button when configured with the menu config option.
    pressed True if this button is pressed (only if enableToggle = true). Defaults to: false
    template A Template used to create the Button's DOM structure. Instances, or subclasses which need a different DOM structure may provide a different template layout in conjunction with an implementation of getTemplateArgs.
    © Copyright 2005-2011 SharpKit. All rights reserved.