X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/25ef3491bd9ae007ff1fc2b0d7943e6eaaccf775..6e39d509471fe9b4e2660e0d1631b350d0c66f40:/docs/source/Button.html?ds=sidebyside diff --git a/docs/source/Button.html b/docs/source/Button.html index c51d4364..91c997d6 100644 --- a/docs/source/Button.html +++ b/docs/source/Button.html @@ -1,777 +1,804 @@ - -
-/*! - * Ext JS Library 3.0.3 - * Copyright(c) 2006-2009 Ext JS, LLC - * licensing@extjs.com - * http://www.extjs.com/license - */ -/** - * @class Ext.Button - * @extends Ext.BoxComponent - * Simple Button class - * @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:- * @cfg {Number} minWidth The minimum width for this button (used to give a set of buttons a common width). - * See also {@link Ext.Panel}.{@link Ext.Panel#minButtonWidth minButtonWidth}. - * @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). - * @constructor - * Create a new button - * @param {Object} config The config object - * @xtype button - */ -Ext.Button = Ext.extend(Ext.BoxComponent, { - /** - * 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 {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:- *
- - *
b
: ButtonThis Button.- - *
e
: EventObjectThe click event.
{@link Ext.Toolbar.Item#overflowText overflowText}
.
- */
- /**
- * @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',
-
- // private
- menuClassTarget : 'tr:nth(2)',
-
- /**
- * @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 'click'.
- */
- clickEvent : 'click',
-
- /**
- * @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} buttonSelector
- * (Optional) A {@link Ext.DomQuery DomQuery} selector which is used to extract the active, clickable element from the - * DOM structure created.
- *When a custom {@link #template} is used, you must ensure that this selector results in the selection of - * a focussable element.
- *Defaults to 'button:first-child'.
- */ - buttonSelector : 'button:first-child', - - /** - * @cfg {String} scale - *(Optional) The size of the Button. Three values are allowed:
- *Defaults to 'small'.
- */ - scale : 'small', - - /** - * @cfg {Object} scope The scope (this reference) in which the - *{@link #handler}
and {@link #toggleHandler}
is
- * executed. Defaults to this Button.
- */
-
- /**
- * @cfg {String} iconAlign
- * (Optional) The side of the Button box to render the icon. Four values are allowed:
- *Defaults to 'left'.
- */ - iconAlign : 'left', - - /** - * @cfg {String} arrowAlign - *(Optional) The side of the Button box to render the arrow if the button has an associated {@link #menu}. - * Two values are allowed:
- *Defaults to 'right'.
- */ - arrowAlign : 'right', - - /** - * @cfg {Ext.Template} template (Optional) - *A {@link Ext.Template 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 {@link #getTemplateArgs}. - * @type Ext.Template - * @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. - */ - - initComponent : function(){ - Ext.Button.superclass.initComponent.call(this); - - this.addEvents( - /** - * @event click - * Fires when this button is clicked - * @param {Button} this - * @param {EventObject} e The click event - */ - 'click', - /** - * @event toggle - * Fires when the 'pressed' state of this button changes (only if enableToggle = true) - * @param {Button} this - * @param {Boolean} pressed - */ - 'toggle', - /** - * @event mouseover - * Fires when the mouse hovers over the button - * @param {Button} this - * @param {Event} e The event object - */ - 'mouseover', - /** - * @event mouseout - * Fires when the mouse exits the button - * @param {Button} this - * @param {Event} e The event object - */ - 'mouseout', - /** - * @event menushow - * If this button has a menu, this event fires when it is shown - * @param {Button} this - * @param {Menu} menu - */ - 'menushow', - /** - * @event menuhide - * If this button has a menu, this event fires when it is hidden - * @param {Button} this - * @param {Menu} menu - */ - 'menuhide', - /** - * @event menutriggerover - * If this button has a menu, this event fires when the mouse enters the menu triggering element - * @param {Button} this - * @param {Menu} menu - * @param {EventObject} e - */ - 'menutriggerover', - /** - * @event menutriggerout - * If this button has a menu, this event fires when the mouse leaves the menu triggering element - * @param {Button} this - * @param {Menu} menu - * @param {EventObject} e - */ - 'menutriggerout' - ); - if(this.menu){ - this.menu = Ext.menu.MenuMgr.get(this.menu); - } - if(Ext.isString(this.toggleGroup)){ - this.enableToggle = true; - } - }, - -/** - *This method returns an object which provides substitution parameters for the {@link #template Template} 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.
- *The default implementation which provides data for the default {@link #template} returns an Array containing the - * following items:
/** + * @class Ext.Button + * @extends Ext.BoxComponent + * Simple Button class + * @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:+ * @cfg {Number} minWidth The minimum width for this button (used to give a set of buttons a common width). + * See also {@link Ext.Panel}.{@link Ext.Panel#minButtonWidth minButtonWidth}. + * @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). + * @constructor + * Create a new button + * @param {Object} config The config object + * @xtype button + */ +Ext.Button = Ext.extend(Ext.BoxComponent, { + /** + * 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 {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:+ *
- + *
b
: ButtonThis Button.- + *
e
: EventObjectThe click event.
{@link Ext.Toolbar.Item#overflowText overflowText}
.
+ */
+ /**
+ * @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',
+
+ // private
+ menuClassTarget : 'tr:nth(2)',
+
+ /**
+ * @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 'click'.
+ */
+ clickEvent : 'click',
+
+ /**
+ * @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} buttonSelector
+ * (Optional) A {@link Ext.DomQuery DomQuery} selector which is used to extract the active, clickable element from the + * DOM structure created.
+ *When a custom {@link #template} is used, you must ensure that this selector results in the selection of + * a focussable element.
+ *Defaults to 'button:first-child'.
+ */ + buttonSelector : 'button:first-child', + + /** + * @cfg {String} scale + *(Optional) The size of the Button. Three values are allowed:
+ *Defaults to 'small'.
+ */ + scale : 'small', + + /** + * @cfg {Object} scope The scope (this reference) in which the + *{@link #handler}
and {@link #toggleHandler}
is
+ * executed. Defaults to this Button.
+ */
+
+ /**
+ * @cfg {String} iconAlign
+ * (Optional) The side of the Button box to render the icon. Four values are allowed:
+ *Defaults to 'left'.
+ */ + iconAlign : 'left', + + /** + * @cfg {String} arrowAlign + *(Optional) The side of the Button box to render the arrow if the button has an associated {@link #menu}. + * Two values are allowed:
+ *Defaults to 'right'.
+ */ + arrowAlign : 'right', + + /** + * @cfg {Ext.Template} template (Optional) + *A {@link Ext.Template 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 {@link #getTemplateArgs}. + * @type Ext.Template + * @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. + */ + + initComponent : function(){ + Ext.Button.superclass.initComponent.call(this); + + this.addEvents( + /** + * @event click + * Fires when this button is clicked + * @param {Button} this + * @param {EventObject} e The click event + */ + 'click', + /** + * @event toggle + * Fires when the 'pressed' state of this button changes (only if enableToggle = true) + * @param {Button} this + * @param {Boolean} pressed + */ + 'toggle', + /** + * @event mouseover + * Fires when the mouse hovers over the button + * @param {Button} this + * @param {Event} e The event object + */ + 'mouseover', + /** + * @event mouseout + * Fires when the mouse exits the button + * @param {Button} this + * @param {Event} e The event object + */ + 'mouseout', + /** + * @event menushow + * If this button has a menu, this event fires when it is shown + * @param {Button} this + * @param {Menu} menu + */ + 'menushow', + /** + * @event menuhide + * If this button has a menu, this event fires when it is hidden + * @param {Button} this + * @param {Menu} menu + */ + 'menuhide', + /** + * @event menutriggerover + * If this button has a menu, this event fires when the mouse enters the menu triggering element + * @param {Button} this + * @param {Menu} menu + * @param {EventObject} e + */ + 'menutriggerover', + /** + * @event menutriggerout + * If this button has a menu, this event fires when the mouse leaves the menu triggering element + * @param {Button} this + * @param {Menu} menu + * @param {EventObject} e + */ + 'menutriggerout' + ); + if(this.menu){ + this.menu = Ext.menu.MenuMgr.get(this.menu); + } + if(Ext.isString(this.toggleGroup)){ + this.enableToggle = true; + } + }, + +/** + *This method returns an Array which provides substitution parameters for the {@link #template Template} 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.
+ *The default implementation which provides data for the default {@link #template} returns an Array containing the + * following items:
'x-btn-arrow'
or 'x-btn-arrow-bottom'
or ''
)this
reference) in which the handler function is executed.
+ * Defaults to this Button.
+ * @return {Ext.Button} this
+ */
+ setHandler : function(handler, scope){
+ this.handler = handler;
+ this.scope = scope;
+ return this;
+ },
+
+ /**
+ * Sets this Button's text
+ * @param {String} text The button text
+ * @return {Ext.Button} this
+ */
+ setText : function(text){
+ this.text = text;
+ if(this.el){
+ this.btnEl.update(text || ' ');
+ this.setButtonClass();
+ }
+ this.doAutoWidth();
+ return this;
+ },
+
+ /**
+ * 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
+ * @return {Ext.Button} this
+ */
+ setIcon : function(icon){
+ this.icon = icon;
+ if(this.el){
+ this.btnEl.setStyle('background-image', icon ? 'url(' + icon + ')' : '');
+ this.setButtonClass();
+ }
+ return this;
+ },
+
+ /**
+ * Gets the text for this Button
+ * @return {String} The button text
+ */
+ getText : function(){
+ 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.
+ * @return {Ext.Button} this
+ */
+ toggle : function(state, suppressEvent){
+ state = state === undefined ? !this.pressed : !!state;
+ if(state != this.pressed){
+ if(this.rendered){
+ this.el[state ? 'addClass' : 'removeClass']('x-btn-pressed');
+ }
+ this.pressed = state;
+ if(!suppressEvent){
+ this.fireEvent('toggle', this, state);
+ if(this.toggleHandler){
+ this.toggleHandler.call(this.scope || this, this, state);
+ }
+ }
+ }
+ return this;
+ },
+
+ /**
+ * Focus the button
+ */
+ focus : function(){
+ this.btnEl.focus();
+ },
+
+ // private
+ onDisable : function(){
+ this.onDisableChange(true);
+ },
+
+ // private
+ onEnable : function(){
+ this.onDisableChange(false);
+ },
+
+ onDisableChange : function(disabled){
+ if(this.el){
+ if(!Ext.isIE6 || !this.text){
+ this.el[disabled ? 'addClass' : 'removeClass'](this.disabledClass);
+ }
+ this.el.dom.disabled = disabled;
+ }
+ this.disabled = disabled;
+ },
+
+ /**
+ * Show this button's menu (if it has one)
+ */
+ showMenu : function(){
+ if(this.rendered && this.menu){
+ if(this.tooltip){
+ Ext.QuickTips.getQuickTip().cancelShow(this.btnEl);
+ }
+ this.menu.show(this.el, this.menuAlign);
+ }
+ return this;
+ },
+
+ /**
+ * Hide this button's menu (if it has one)
+ */
+ hideMenu : function(){
+ if(this.menu){
+ this.menu.hide();
+ }
+ return this;
+ },
+
+ /**
+ * Returns true if the button has a menu and it is visible
+ * @return {Boolean}
+ */
+ hasVisibleMenu : function(){
+ return this.menu && this.menu.isVisible();
+ },
+
+ // private
+ onClick : function(e){
+ if(e){
+ e.preventDefault();
+ }
+ if(e.button !== 0){
+ return;
+ }
+ if(!this.disabled){
+ if(this.enableToggle && (this.allowDepress !== false || !this.pressed)){
+ this.toggle();
+ }
+ if(this.menu && !this.menu.isVisible() && !this.ignoreNextClick){
+ this.showMenu();
+ }
+ this.fireEvent('click', this, e);
+ if(this.handler){
+ //this.el.removeClass('x-btn-over');
+ this.handler.call(this.scope || this, this, e);
+ }
+ }
+ },
+
+ // private
+ isMenuTriggerOver : function(e, internal){
+ return this.menu && !internal;
+ },
+
+ // private
+ isMenuTriggerOut : function(e, internal){
+ return this.menu && !internal;
+ },
+
+ // private
+ onMouseOver : function(e){
+ if(!this.disabled){
+ var internal = e.within(this.el, true);
+ if(!internal){
+ this.el.addClass('x-btn-over');
+ if(!this.monitoringMouseOver){
+ this.doc.on('mouseover', this.monitorMouseOver, this);
+ this.monitoringMouseOver = true;
+ }
+ this.fireEvent('mouseover', this, e);
+ }
+ if(this.isMenuTriggerOver(e, internal)){
+ this.fireEvent('menutriggerover', this, this.menu, e);
+ }
+ }
+ },
+
+ // private
+ monitorMouseOver : function(e){
+ if(e.target != this.el.dom && !e.within(this.el)){
+ if(this.monitoringMouseOver){
+ this.doc.un('mouseover', this.monitorMouseOver, this);
+ this.monitoringMouseOver = false;
+ }
+ this.onMouseOut(e);
+ }
+ },
+
+ // private
+ onMouseOut : function(e){
+ var internal = e.within(this.el) && e.target != this.el.dom;
+ this.el.removeClass('x-btn-over');
+ this.fireEvent('mouseout', this, e);
+ if(this.isMenuTriggerOut(e, internal)){
+ this.fireEvent('menutriggerout', this, this.menu, e);
+ }
+ },
+
+ focus : function() {
+ this.btnEl.focus();
+ },
+
+ blur : function() {
+ this.btnEl.blur();
+ },
+
+ // private
+ onFocus : function(e){
+ if(!this.disabled){
+ this.el.addClass('x-btn-focus');
+ }
+ },
+ // private
+ onBlur : function(e){
+ this.el.removeClass('x-btn-focus');
+ },
+
+ // private
+ getClickEl : function(e, isUp){
+ return this.el;
+ },
+
+ // private
+ onMouseDown : function(e){
+ if(!this.disabled && e.button === 0){
+ this.getClickEl(e).addClass('x-btn-click');
+ this.doc.on('mouseup', this.onMouseUp, this);
+ }
+ },
+ // private
+ onMouseUp : function(e){
+ if(e.button === 0){
+ this.getClickEl(e, true).removeClass('x-btn-click');
+ this.doc.un('mouseup', this.onMouseUp, this);
+ }
+ },
+ // private
+ onMenuShow : function(e){
+ this.menu.ownerCt = this;
+ this.ignoreNextClick = 0;
+ this.el.addClass('x-btn-menu-active');
+ this.fireEvent('menushow', this, this.menu);
+ },
+ // private
+ onMenuHide : function(e){
+ this.el.removeClass('x-btn-menu-active');
+ this.ignoreNextClick = this.restoreClick.defer(250, this);
+ this.fireEvent('menuhide', this, this.menu);
+ delete this.menu.ownerCt;
+ },
+
+ // private
+ restoreClick : function(){
+ this.ignoreNextClick = 0;
+ }
+
+ /**
+ * @cfg {String} autoEl @hide
+ */
+});
+Ext.reg('button', Ext.Button);
+
+// Private utility class used by Button
+Ext.ButtonToggleMgr = function(){
+ var groups = {};
+
+ function toggleGroup(btn, state){
+ if(state){
+ var g = groups[btn.toggleGroup];
+ for(var i = 0, l = g.length; i < l; i++){
+ if(g[i] != btn){
+ g[i].toggle(false);
+ }
+ }
+ }
+ }
+
+ return {
+ register : function(btn){
+ if(!btn.toggleGroup){
+ return;
+ }
+ var g = groups[btn.toggleGroup];
+ if(!g){
+ g = groups[btn.toggleGroup] = [];
+ }
+ g.push(btn);
+ btn.on('toggle', toggleGroup);
+ },
+
+ unregister : function(btn){
+ if(!btn.toggleGroup){
+ return;
+ }
+ var g = groups[btn.toggleGroup];
+ if(g){
+ g.remove(btn);
+ btn.un('toggle', toggleGroup);
+ }
+ },
+
+ /**
+ * Gets the pressed button in the passed group or null
+ * @param {String} group
+ * @return Button
+ */
+ getPressed : function(group){
+ var g = groups[group];
+ if(g){
+ for(var i = 0, len = g.length; i < len; i++){
+ if(g[i].pressed === true){
+ return g[i];
+ }
+ }
+ }
+ return null;
+ }
+ };
+}();
+
+
\ No newline at end of file