X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/7a654f8d43fdb43d78b63d90528bed6e86b608cc..6746dc89c47ed01b165cc1152533605f97eb8e8d:/docs/source/Button.html diff --git a/docs/source/Button.html b/docs/source/Button.html index 9be1eb5a..3c1bda4b 100644 --- a/docs/source/Button.html +++ b/docs/source/Button.html @@ -1,12 +1,29 @@ -
+ +/** - * @class Ext.button.Button + + + + +\ No newline at end of file +The source code + + + + + + +/** + * @class Ext.button.Button * @extends Ext.Component -Create simple buttons with this component. Customisations include {@link #config-iconAlign aligned} -{@link #config-iconCls icons}, {@link #config-menu dropdown menus}, {@link #config-tooltip tooltips} -and {@link #config-scale sizing options}. Specify a {@link #config-handler handler} to run code when -a user clicks the button, or use {@link #config-listeners listeners} for other events such as -{@link #events-mouseover mouseover}. +Create simple buttons with this component. Customisations include {@link #iconAlign aligned} +{@link #iconCls icons}, {@link #menu dropdown menus}, {@link #tooltip tooltips} +and {@link #scale sizing options}. Specify a {@link #handler handler} to run code when +a user clicks the button, or use {@link #listeners listeners} for other events such as +{@link #mouseover mouseover}. {@img Ext.button.Button/Ext.button.Button1.png Ext.button.Button component} Example usage: @@ -125,10 +142,6 @@ Example usage: } }); - * @constructor - * Create a new button - * @param {Object} config The config object - * @xtype button * @markdown * @docauthor Robert Dougan <rob@sencha.com> */ @@ -152,34 +165,34 @@ Ext.define('Ext.button.Button', { isButton: true, componentLayout: 'button', - /** + /** * Read-only. True if this button is hidden * @type Boolean */ hidden: false, - /** + /** * Read-only. True if this button is disabled * @type Boolean */ disabled: false, - /** + /** * Read-only. True if this button is pressed (only if enableToggle = true) * @type Boolean */ pressed: false, - /** + /** * @cfg {String} text The button text to be used as innerHTML (html tags are accepted) */ - /** + /** * @cfg {String} icon 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') */ - /** + /** * @cfg {Function} handler A function called when the button is clicked (can be used instead of click event). * The handler is passed the following parameters:<div class="mdetail-params"><ul> * <li><code>b</code> : Button<div class="sub-desc">This Button.</div></li> @@ -187,52 +200,52 @@ Ext.define('Ext.button.Button', { * </ul></div> */ - /** + /** * @cfg {Number} minWidth The minimum width for this button (used to give a set of buttons a common width). * See also {@link Ext.panel.Panel}.<tt>{@link Ext.panel.Panel#minButtonWidth minButtonWidth}</tt>. */ - /** + /** * @cfg {String/Object} tooltip The tooltip for the button - can be a string to be used as innerHTML (html tags are accepted) or QuickTips config object */ - /** + /** * @cfg {Boolean} hidden True to start hidden (defaults to false) */ - /** + /** * @cfg {Boolean} disabled True to start disabled (defaults to false) */ - /** + /** * @cfg {Boolean} pressed True to start pressed (only if enableToggle = true) */ - /** + /** * @cfg {String} toggleGroup The group this toggle button is a member of (only 1 per group can be pressed) */ - /** + /** * @cfg {Boolean/Object} repeat True to repeat fire the click event while the mouse is down. This can also be * a {@link Ext.util.ClickRepeater ClickRepeater} config object (defaults to false). */ - /** + /** * @cfg {Number} tabIndex Set a DOM tabIndex for this button (defaults to undefined) */ - /** + /** * @cfg {Boolean} allowDepress * False to not allow a pressed Button to be depressed (defaults to undefined). Only valid when {@link #enableToggle} is true. */ - /** + /** * @cfg {Boolean} enableToggle * True to enable pressed/not pressed toggling (defaults to false) */ enableToggle: false, - /** + /** * @cfg {Function} toggleHandler * Function called when a Button with {@link #enableToggle} set to true is clicked. Two arguments are passed:<ul class="mdetail-params"> * <li><b>button</b> : Ext.button.Button<div class="sub-desc">this Button object</div></li> @@ -240,88 +253,99 @@ Ext.define('Ext.button.Button', { * </ul> */ - /** + /** * @cfg {Mixed} menu * Standard menu attribute consisting of a reference to a menu object, a menu id or a menu config blob (defaults to undefined). */ - /** + /** * @cfg {String} menuAlign * The position to align the menu to (see {@link Ext.core.Element#alignTo} for more details, defaults to 'tl-bl?'). */ menuAlign: 'tl-bl?', - /** + /** * @cfg {String} overflowText If used in a {@link Ext.toolbar.Toolbar Toolbar}, the * text to be used if this item is shown in the overflow menu. See also * {@link Ext.toolbar.Item}.<code>{@link Ext.toolbar.Item#overflowText overflowText}</code>. */ - /** + /** * @cfg {String} iconCls * A css class which sets a background image to be used as the icon for this button */ - /** + /** * @cfg {String} type * submit, reset or button - defaults to 'button' */ type: 'button', - /** + /** * @cfg {String} clickEvent * The DOM event that will fire the handler of the button. This can be any valid event name (dblclick, contextmenu). * Defaults to <tt>'click'</tt>. */ clickEvent: 'click', - /** + /** * @cfg {Boolean} preventDefault * True to prevent the default action when the {@link #clickEvent} is processed. Defaults to true. */ preventDefault: true, - /** + /** * @cfg {Boolean} handleMouseEvents * False to disable visual cues on mouseover, mouseout and mousedown (defaults to true) */ handleMouseEvents: true, - /** + /** * @cfg {String} tooltipType * The type of tooltip to use. Either 'qtip' (default) for QuickTips or 'title' for title attribute. */ tooltipType: 'qtip', - /** + /** * @cfg {String} baseCls * The base CSS class to add to all buttons. (Defaults to 'x-btn') */ baseCls: Ext.baseCSSPrefix + 'btn', - /** + /** * @cfg {String} pressedCls * The CSS class to add to a button when it is in the pressed state. (Defaults to 'x-btn-pressed') */ pressedCls: 'pressed', - /** + /** * @cfg {String} overCls * The CSS class to add to a button when it is in the over (hovered) state. (Defaults to 'x-btn-over') */ overCls: 'over', - /** + /** * @cfg {String} focusCls * The CSS class to add to a button when it is in the focussed state. (Defaults to 'x-btn-focus') */ focusCls: 'focus', - /** + /** * @cfg {String} menuActiveCls * The CSS class to add to a button when it's menu is active. (Defaults to 'x-btn-menu-active') */ menuActiveCls: 'menu-active', + + /** + * @cfg {Object} baseParams + * An object literal of parameters to pass to the url when the {@link #href} property is specified. + */ + + /** + * @cfg {Object} params + * An object literal of parameters to pass to the url when the {@link #href} property is specified. + * Any params override {@link #baseParams}. New params can be set using the {@link #setParams} method. + */ ariaRole: 'button', @@ -330,7 +354,10 @@ Ext.define('Ext.button.Button', { '<em class="{splitCls}">' + '<tpl if="href">' + '<a href="{href}" target="{target}"<tpl if="tabIndex"> tabIndex="{tabIndex}"</tpl> role="link">' + - '<span class="{baseCls}-inner">{text}</span>' + + '<span class="{baseCls}-inner">' + + '{text}' + + '</span>' + + '<span class="{baseCls}-icon"></span>' + '</a>' + '</tpl>' + '<tpl if="!href">' + @@ -338,12 +365,15 @@ Ext.define('Ext.button.Button', { // the autocomplete="off" is required to prevent Firefox from remembering // the button's disabled state between page reloads. '<tpl if="tabIndex"> tabIndex="{tabIndex}"</tpl> role="button" autocomplete="off">' + - '<span class="{baseCls}-inner" style="{innerSpanStyle}">{text}</span>' + + '<span class="{baseCls}-inner" style="{innerSpanStyle}">' + + '{text}' + + '</span>' + + '<span class="{baseCls}-icon"></span>' + '</button>' + '</tpl>' + '</em>' , - /** + /** * @cfg {String} scale * <p>(Optional) The size of the Button. Three values are allowed:</p> * <ul class="mdetail-params"> @@ -355,18 +385,18 @@ Ext.define('Ext.button.Button', { */ scale: 'small', - /** + /** * @private An array of allowed scales. */ allowedScales: ['small', 'medium', 'large'], - /** + /** * @cfg {Object} scope The scope (<tt><b>this</b></tt> reference) in which the * <code>{@link #handler}</code> and <code>{@link #toggleHandler}</code> is * executed. Defaults to this Button. */ - /** + /** * @cfg {String} iconAlign * <p>(Optional) The side of the Button box to render the icon. Four values are allowed:</p> * <ul class="mdetail-params"> @@ -379,7 +409,7 @@ Ext.define('Ext.button.Button', { */ iconAlign: 'left', - /** + /** * @cfg {String} arrowAlign * <p>(Optional) The side of the Button box to render the arrow if the button has an associated {@link #menu}. * Two values are allowed:</p> @@ -391,13 +421,13 @@ Ext.define('Ext.button.Button', { */ arrowAlign: 'right', - /** + /** * @cfg {String} arrowCls * <p>(Optional) The className used for the inner arrow element if the button has a menu.</p> */ arrowCls: 'arrow', - /** + /** * @cfg {Ext.Template} template (Optional) * <p>A {@link Ext.Template Template} used to create the Button's DOM structure.</p> * Instances, or subclasses which need a different DOM structure may provide a different @@ -406,18 +436,18 @@ Ext.define('Ext.button.Button', { * @property template */ - /** + /** * @cfg {String} cls * A CSS class string to apply to the button's main element. */ - /** + /** * @property menu * @type Menu * The {@link Ext.menu.Menu Menu} object associated with this Button when configured with the {@link #menu} config option. */ - /** + /** * @cfg {Boolean} autoWidth * By default, if a width is not specified the button will attempt to stretch horizontally to fit its content. * If the button is being managed by a width sizing layout (hbox, fit, anchor), set this to false to prevent @@ -433,7 +463,7 @@ Ext.define('Ext.button.Button', { me.callParent(arguments); me.addEvents( - /** + /** * @event click * Fires when this button is clicked * @param {Button} this @@ -441,7 +471,7 @@ Ext.define('Ext.button.Button', { */ 'click', - /** + /** * @event toggle * Fires when the 'pressed' state of this button changes (only if enableToggle = true) * @param {Button} this @@ -449,7 +479,7 @@ Ext.define('Ext.button.Button', { */ 'toggle', - /** + /** * @event mouseover * Fires when the mouse hovers over the button * @param {Button} this @@ -457,7 +487,7 @@ Ext.define('Ext.button.Button', { */ 'mouseover', - /** + /** * @event mouseout * Fires when the mouse exits the button * @param {Button} this @@ -465,7 +495,7 @@ Ext.define('Ext.button.Button', { */ 'mouseout', - /** + /** * @event menushow * If this button has a menu, this event fires when it is shown * @param {Button} this @@ -473,7 +503,7 @@ Ext.define('Ext.button.Button', { */ 'menushow', - /** + /** * @event menuhide * If this button has a menu, this event fires when it is hidden * @param {Button} this @@ -481,7 +511,7 @@ Ext.define('Ext.button.Button', { */ 'menuhide', - /** + /** * @event menutriggerover * If this button has a menu, this event fires when the mouse enters the menu triggering element * @param {Button} this @@ -490,7 +520,7 @@ Ext.define('Ext.button.Button', { */ 'menutriggerover', - /** + /** * @event menutriggerout * If this button has a menu, this event fires when the mouse leaves the menu triggering element * @param {Button} this @@ -586,7 +616,8 @@ Ext.define('Ext.button.Button', { Ext.applyIf(me.renderSelectors, { btnEl : me.href ? 'a' : 'button', btnWrap: 'em', - btnInnerEl: '.' + me.baseCls + '-inner' + btnInnerEl: '.' + me.baseCls + '-inner', + btnIconEl: '.'+ me.baseCls + '-icon' }); if (me.scale) { @@ -667,7 +698,7 @@ Ext.define('Ext.button.Button', { Ext.ButtonToggleManager.register(me); }, - /** + /** * <p>This method returns an object which provides substitution parameters for the {@link #renderTpl XTemplate} used * to create this Button's DOM structure.</p> * <p>Instances or subclasses which use a different Template to create a different DOM structure may need to provide their @@ -706,23 +737,27 @@ Ext.define('Ext.button.Button', { }; }, - /** + /** * @private * If there is a configured href for this Button, returns the href with parameters appended. * @returns The href string with parameters appended. */ getHref: function() { - var me = this; - return me.href ? Ext.urlAppend(me.href, me.params + Ext.Object.toQueryString(Ext.apply(Ext.apply({}, me.baseParams)))) : false; + var me = this, + params = Ext.apply({}, me.baseParams); + + // write baseParams first, then write any params + params = Ext.apply(params, me.params); + return me.href ? Ext.urlAppend(me.href, Ext.Object.toQueryString(params)) : false; }, - /** + /** * <p><b>Only valid if the Button was originally configured with a {@link #url}</b></p> * <p>Sets the href of the link dynamically according to the params passed, and any {@link #baseParams} configured.</p> - * @param {Object} Parameters to use in the href URL. + * @param {Object} params Parameters to use in the href URL. */ - setParams: function(p) { - this.params = p; + setParams: function(params) { + this.params = params; this.btnEl.dom.href = this.getHref(); }, @@ -740,7 +775,7 @@ Ext.define('Ext.button.Button', { this.callParent(arguments); }, - /** + /** * Sets the CSS class that provides a background image to use as the button's icon. This method also changes * the value of the {@link #iconCls} config internally. * @param {String} cls The CSS class providing the icon image @@ -748,18 +783,18 @@ Ext.define('Ext.button.Button', { */ setIconCls: function(cls) { var me = this, - btnInnerEl = me.btnInnerEl; - if (btnInnerEl) { + btnIconEl = me.btnIconEl; + if (btnIconEl) { // Remove the previous iconCls from the button - btnInnerEl.removeCls(me.iconCls); - btnInnerEl.addCls(cls || ''); + btnIconEl.removeCls(me.iconCls); + btnIconEl.addCls(cls || ''); me.setButtonCls(); } me.iconCls = cls; return me; }, - /** + /** * Sets the tooltip for this Button. * @param {String/Object} tooltip. This may be:<div class="mdesc-details"><ul> * <li><b>String</b> : A string to be used as innerHTML (html tags are accepted) to show in a tooltip</li> @@ -837,7 +872,7 @@ Ext.define('Ext.button.Button', { me.callParent(); }, - /** + /** * Assigns this Button's click handler * @param {Function} handler The function to call when the button is clicked * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the handler function is executed. @@ -850,7 +885,7 @@ Ext.define('Ext.button.Button', { return this; }, - /** + /** * Sets this Button's text * @param {String} text The button text * @return {Ext.button.Button} this @@ -866,7 +901,7 @@ Ext.define('Ext.button.Button', { return me; }, - /** + /** * Sets the background image (inline style) of the button. This method also changes * the value of the {@link #icon} config internally. * @param {String} icon The path to an image to display in the button @@ -883,7 +918,7 @@ Ext.define('Ext.button.Button', { return me; }, - /** + /** * Gets the text for this Button * @return {String} The button text */ @@ -891,7 +926,7 @@ Ext.define('Ext.button.Button', { return this.text; }, - /** + /** * If a state it passed, it becomes the pressed state otherwise the current state is toggled. * @param {Boolean} state (optional) Force a particular state * @param {Boolean} supressEvent (optional) True to stop events being fired when calling this method. @@ -914,7 +949,7 @@ Ext.define('Ext.button.Button', { return me; }, - /** + /** * Show this button's menu (if it has one) */ showMenu: function() { @@ -932,7 +967,7 @@ Ext.define('Ext.button.Button', { return me; }, - /** + /** * Hide this button's menu (if it has one) */ hideMenu: function() { @@ -942,7 +977,7 @@ Ext.define('Ext.button.Button', { return this; }, - /** + /** * Returns true if the button has a menu and it is visible * @return {Boolean} */ @@ -980,7 +1015,7 @@ Ext.define('Ext.button.Button', { } }, - /** + /** * @private mouseover handler called when a mouseover event occurs anywhere within the encapsulating element. * The targets are interrogated to see what is being entered from where. * @param e @@ -992,7 +1027,7 @@ Ext.define('Ext.button.Button', { } }, - /** + /** * @private mouseout handler called when a mouseout event occurs anywhere within the encapsulating element - * or the mouse leaves the encapsulating element. * The targets are interrogated to see what is being exited to where. @@ -1008,7 +1043,7 @@ Ext.define('Ext.button.Button', { } }, - /** + /** * @private mousemove handler called when the mouse moves anywhere within the encapsulating element. * The position is checked to determine if the mouse is entering or leaving the trigger area. Using * mousemove to check this is more resource intensive than we'd like, but it is necessary because @@ -1043,7 +1078,7 @@ Ext.define('Ext.button.Button', { } }, - /** + /** * @private Measures the size of the trigger area for menu and split buttons. Will be a width for * a right-aligned trigger and a height for a bottom-aligned trigger. Cached after first measurement. */ @@ -1060,7 +1095,7 @@ Ext.define('Ext.button.Button', { return size; }, - /** + /** * @private virtual mouseenter handler called when it is detected that the mouseout event * signified the mouse entering the encapsulating element. * @param e @@ -1071,7 +1106,7 @@ Ext.define('Ext.button.Button', { me.fireEvent('mouseover', me, e); }, - /** + /** * @private virtual mouseleave handler called when it is detected that the mouseover event * signified the mouse entering the encapsulating element. * @param e @@ -1082,7 +1117,7 @@ Ext.define('Ext.button.Button', { me.fireEvent('mouseout', me, e); }, - /** + /** * @private virtual mouseenter handler called when it is detected that the mouseover event * signified the mouse entering the arrow area of the button - the <em>. * @param e @@ -1093,7 +1128,7 @@ Ext.define('Ext.button.Button', { me.fireEvent('menutriggerover', me, me.menu, e); }, - /** + /** * @private virtual mouseleave handler called when it is detected that the mouseout event * signified the mouse leaving the arrow area of the button - the <em>. * @param e @@ -1126,7 +1161,7 @@ Ext.define('Ext.button.Button', { return me; }, - /** + /** * Method to change the scale of the button. See {@link #scale} for allowed configurations. * @param {String} scale The scale to change to. */ @@ -1222,7 +1257,7 @@ Ext.define('Ext.button.Button', { } }, - /** + /** * @private Some browsers (notably Safari and older Chromes on Windows) add extra "padding" inside the button * element that cannot be removed. This method returns the size of that padding with a one-time detection. * @return Array [top, right, bottom, left] @@ -1298,7 +1333,7 @@ Ext.define('Ext.button.Button', { } }, - /** + /** * Gets the pressed button in the passed group or null * @param {String} group * @return Button @@ -1318,4 +1353,6 @@ Ext.define('Ext.button.Button', { } }; }); -