X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..f562e4c6e5fac7bcb445985b99acbea4d706e6f0:/src/window/Window.js diff --git a/src/window/Window.js b/src/window/Window.js index 750600c0..2ddb55d0 100644 --- a/src/window/Window.js +++ b/src/window/Window.js @@ -13,33 +13,33 @@ If you are unsure which license is appropriate for your use, please contact the */ /** - * @class Ext.window.Window - * @extends Ext.panel.Panel - *

A specialized panel intended for use as an application window. Windows are floated, {@link #resizable}, and - * {@link #draggable} by default. Windows can be {@link #maximizable maximized} to fill the viewport, - * restored to their prior size, and can be {@link #minimize}d.

- *

Windows can also be linked to a {@link Ext.ZIndexManager} or managed by the {@link Ext.WindowManager} to provide - * grouping, activation, to front, to back and other application-specific behavior.

- *

By default, Windows will be rendered to document.body. To {@link #constrain} a Window to another element - * specify {@link Ext.Component#renderTo renderTo}.

- *

As with all {@link Ext.container.Container Container}s, it is important to consider how you want the Window - * to size and arrange any child Components. Choose an appropriate {@link #layout} configuration which lays out - * child Components in the required manner.

- * {@img Ext.window.Window/Ext.window.Window.png Window component} - * Example:
-Ext.create('Ext.window.Window', {
-    title: 'Hello',
-    height: 200,
-    width: 400,
-    layout: 'fit',
-    items: {  // Let's put an empty grid in just to illustrate fit layout
-        xtype: 'grid',
-        border: false,
-        columns: [{header: 'World'}],                 // One header just for show. There's no data,
-        store: Ext.create('Ext.data.ArrayStore', {}) // A dummy empty data store
-    }
-}).show();
-
 + * A specialized panel intended for use as an application window. Windows are floated, {@link #resizable}, and + * {@link #draggable} by default. Windows can be {@link #maximizable maximized} to fill the viewport, restored to + * their prior size, and can be {@link #minimize}d. + * + * Windows can also be linked to a {@link Ext.ZIndexManager} or managed by the {@link Ext.WindowManager} to provide + * grouping, activation, to front, to back and other application-specific behavior. + * + * By default, Windows will be rendered to document.body. To {@link #constrain} a Window to another element specify + * {@link Ext.Component#renderTo renderTo}. + * + * **As with all {@link Ext.container.Container Container}s, it is important to consider how you want the Window to size + * and arrange any child Components. Choose an appropriate {@link #layout} configuration which lays out child Components + * in the required manner.** + * + * @example + * Ext.create('Ext.window.Window', { + * title: 'Hello', + * height: 200, + * width: 400, + * layout: 'fit', + * items: { // Let's put an empty grid in just to illustrate fit layout + * xtype: 'grid', + * border: false, + * columns: [{header: 'World'}], // One header just for show. There's no data, + * store: Ext.create('Ext.data.ArrayStore', {}) // A dummy empty data store + * } + * }).show(); */ Ext.define('Ext.window.Window', { extend: 'Ext.panel.Panel', @@ -52,112 +52,119 @@ Ext.define('Ext.window.Window', { /** * @cfg {Number} x - * The X position of the left edge of the window on initial showing. Defaults to centering the Window within - * the width of the Window's container {@link Ext.core.Element Element) (The Element that the Window is rendered to). + * The X position of the left edge of the window on initial showing. Defaults to centering the Window within the + * width of the Window's container {@link Ext.Element Element} (The Element that the Window is rendered to). */ + /** * @cfg {Number} y - * The Y position of the top edge of the window on initial showing. Defaults to centering the Window within - * the height of the Window's container {@link Ext.core.Element Element) (The Element that the Window is rendered to). + * The Y position of the top edge of the window on initial showing. Defaults to centering the Window within the + * height of the Window's container {@link Ext.Element Element} (The Element that the Window is rendered to). */ + /** - * @cfg {Boolean} modal + * @cfg {Boolean} [modal=false] * True to make the window modal and mask everything behind it when displayed, false to display it without - * restricting access to other UI elements (defaults to false). + * restricting access to other UI elements. */ + /** - * @cfg {String/Element} animateTarget - * Id or element from which the window should animate while opening (defaults to null with no animation). + * @cfg {String/Ext.Element} [animateTarget=null] + * Id or element from which the window should animate while opening. */ + /** - * @cfg {String/Number/Component} defaultFocus - *

Specifies a Component to receive focus when this Window is focused.

- *

This may be one of:

+ * @cfg {String/Number/Ext.Component} defaultFocus + * Specifies a Component to receive focus when this Window is focused. + * + * This may be one of: + * + * - The index of a footer Button. + * - The id or {@link Ext.AbstractComponent#itemId} of a descendant Component. + * - A Component. */ + /** * @cfg {Function} onEsc - * Allows override of the built-in processing for the escape key. Default action - * is to close the Window (performing whatever action is specified in {@link #closeAction}. - * To prevent the Window closing when the escape key is pressed, specify this as - * Ext.emptyFn (See {@link Ext#emptyFn Ext.emptyFn}). + * Allows override of the built-in processing for the escape key. Default action is to close the Window (performing + * whatever action is specified in {@link #closeAction}. To prevent the Window closing when the escape key is + * pressed, specify this as {@link Ext#emptyFn Ext.emptyFn}. */ + /** - * @cfg {Boolean} collapsed - * True to render the window collapsed, false to render it expanded (defaults to false). Note that if - * {@link #expandOnShow} is true (the default) it will override the collapsed config and the window - * will always be expanded when shown. + * @cfg {Boolean} [collapsed=false] + * True to render the window collapsed, false to render it expanded. Note that if {@link #expandOnShow} + * is true (the default) it will override the `collapsed` config and the window will always be + * expanded when shown. */ + /** - * @cfg {Boolean} maximized - * True to initially display the window in a maximized state. (Defaults to false). + * @cfg {Boolean} [maximized=false] + * True to initially display the window in a maximized state. */ /** - * @cfg {String} baseCls - * The base CSS class to apply to this panel's element (defaults to 'x-window'). + * @cfg {String} [baseCls='x-window'] + * The base CSS class to apply to this panel's element. */ baseCls: Ext.baseCSSPrefix + 'window', /** - * @cfg {Mixed} resizable - *

Specify as true to allow user resizing at each edge and corner of the window, false to disable - * resizing (defaults to true).

- *

This may also be specified as a config object to

+ * @cfg {Boolean/Object} resizable + * Specify as `true` to allow user resizing at each edge and corner of the window, false to disable resizing. + * + * This may also be specified as a config object to Ext.resizer.Resizer */ resizable: true, /** * @cfg {Boolean} draggable - *

True to allow the window to be dragged by the header bar, false to disable dragging (defaults to true). Note - * that by default the window will be centered in the viewport, so if dragging is disabled the window may need - * to be positioned programmatically after render (e.g., myWindow.setPosition(100, 100);).

+ * True to allow the window to be dragged by the header bar, false to disable dragging. Note that + * by default the window will be centered in the viewport, so if dragging is disabled the window may need to be + * positioned programmatically after render (e.g., myWindow.setPosition(100, 100);). */ draggable: true, /** * @cfg {Boolean} constrain - * True to constrain the window within its containing element, false to allow it to fall outside of its - * containing element. By default the window will be rendered to document.body. To render and constrain the - * window within another element specify {@link #renderTo}. - * (defaults to false). Optionally the header only can be constrained using {@link #constrainHeader}. + * True to constrain the window within its containing element, false to allow it to fall outside of its containing + * element. By default the window will be rendered to document.body. To render and constrain the window within + * another element specify {@link #renderTo}. Optionally the header only can be constrained + * using {@link #constrainHeader}. */ constrain: false, /** * @cfg {Boolean} constrainHeader - * True to constrain the window header within its containing element (allowing the window body to fall outside - * of its containing element) or false to allow the header to fall outside its containing element (defaults to - * false). Optionally the entire window can be constrained using {@link #constrain}. + * True to constrain the window header within its containing element (allowing the window body to fall outside of + * its containing element) or false to allow the header to fall outside its containing element. + * Optionally the entire window can be constrained using {@link #constrain}. */ constrainHeader: false, /** * @cfg {Boolean} plain - * True to render the window body with a transparent background so that it will blend into the framing - * elements, false to add a lighter background color to visually highlight the body element and separate it - * more distinctly from the surrounding frame (defaults to false). + * True to render the window body with a transparent background so that it will blend into the framing elements, + * false to add a lighter background color to visually highlight the body element and separate it more distinctly + * from the surrounding frame. */ plain: false, /** * @cfg {Boolean} minimizable * True to display the 'minimize' tool button and allow the user to minimize the window, false to hide the button - * and disallow minimizing the window (defaults to false). Note that this button provides no implementation -- - * the behavior of minimizing a window is implementation-specific, so the minimize event must be handled and a - * custom minimize behavior implemented for this option to be useful. + * and disallow minimizing the window. Note that this button provides no implementation -- the + * behavior of minimizing a window is implementation-specific, so the minimize event must be handled and a custom + * minimize behavior implemented for this option to be useful. */ minimizable: false, /** * @cfg {Boolean} maximizable * True to display the 'maximize' tool button and allow the user to maximize the window, false to hide the button - * and disallow maximizing the window (defaults to false). Note that when a window is maximized, the tool button - * will automatically change to a 'restore' button with the appropriate behavior already built-in that will - * restore the window to its previous size. + * and disallow maximizing the window. Note that when a window is maximized, the tool button + * will automatically change to a 'restore' button with the appropriate behavior already built-in that will restore + * the window to its previous size. */ maximizable: false, @@ -170,7 +177,7 @@ Ext.define('Ext.window.Window', { /** * @cfg {Boolean} expandOnShow * True to always expand the window when it is displayed, false to keep it in its current state (which may be - * {@link #collapsed}) when displayed (defaults to true). + * {@link #collapsed}) when displayed. */ expandOnShow: true, @@ -179,21 +186,20 @@ Ext.define('Ext.window.Window', { /** * @cfg {Boolean} closable - *

True to display the 'close' tool button and allow the user to close the window, false to - * hide the button and disallow closing the window (defaults to true).

- *

By default, when close is requested by either clicking the close button in the header - * or pressing ESC when the Window has focus, the {@link #close} method will be called. This - * will {@link Ext.Component#destroy destroy} the Window and its content meaning that - * it may not be reused.

- *

To make closing a Window hide the Window so that it may be reused, set - * {@link #closeAction} to 'hide'.

+ * True to display the 'close' tool button and allow the user to close the window, false to hide the button and + * disallow closing the window. + * + * By default, when close is requested by either clicking the close button in the header or pressing ESC when the + * Window has focus, the {@link #close} method will be called. This will _{@link Ext.Component#destroy destroy}_ the + * Window and its content meaning that it may not be reused. + * + * To make closing a Window _hide_ the Window so that it may be reused, set {@link #closeAction} to 'hide'. */ closable: true, /** * @cfg {Boolean} hidden - * Render this Window hidden (default is true). If true, the - * {@link #hide} method will be called internally. + * Render this Window hidden. If `true`, the {@link #hide} method will be called internally. */ hidden: true, @@ -207,11 +213,11 @@ Ext.define('Ext.window.Window', { floating: true, ariaRole: 'alertdialog', - + itemCls: 'x-window-item', overlapHeader: true, - + ignoreHeaderBorderManagement: true, // private @@ -224,11 +230,13 @@ Ext.define('Ext.window.Window', { * Fires after the window has been visually activated via {@link #setActive}. * @param {Ext.window.Window} this */ + /** * @event deactivate * Fires after the window has been visually deactivated via {@link #setActive}. * @param {Ext.window.Window} this */ + /** * @event resize * Fires after the window has been resized. @@ -237,18 +245,21 @@ Ext.define('Ext.window.Window', { * @param {Number} height The window's new height */ 'resize', + /** * @event maximize * Fires after the window has been maximized. * @param {Ext.window.Window} this */ 'maximize', + /** * @event minimize * Fires after the window has been minimized. * @param {Ext.window.Window} this */ 'minimize', + /** * @event restore * Fires after the window has been restored to its original size after being maximized. @@ -314,9 +325,14 @@ Ext.define('Ext.window.Window', { }, // private - onMouseDown: function () { + onMouseDown: function (e) { + var preventFocus; + if (this.floating) { - this.toFront(); + if (Ext.fly(e.getTarget()).focusable()) { + preventFocus = true; + } + this.toFront(preventFocus); } }, @@ -354,6 +370,11 @@ Ext.define('Ext.window.Window', { // clickToRaise me.mon(me.el, 'mousedown', me.onMouseDown, me); + + // allow the element to be focusable + me.el.set({ + tabIndex: -1 + }); // Initialize if (me.maximized) { @@ -389,7 +410,7 @@ Ext.define('Ext.window.Window', { if (!me.header) { me.updateHeader(true); } - + /* * Check the header here again. If for whatever reason it wasn't created in * updateHeader (preventHeader) then we'll just ignore the rest since the @@ -409,16 +430,14 @@ Ext.define('Ext.window.Window', { } /** - *

If this Window is configured {@link #draggable}, this property will contain - * an instance of {@link Ext.util.ComponentDragger} (A subclass of {@link Ext.dd.DragTracker DragTracker}) - * which handles dragging the Window's DOM Element, and constraining according to the {@link #constrain} - * and {@link #constrainHeader} .

- *

This has implementations of onBeforeStart, onDrag and onEnd - * which perform the dragging action. If extra logic is needed at these points, use - * {@link Ext.Function#createInterceptor createInterceptor} or {@link Ext.Function#createSequence createSequence} to - * augment the existing implementations.

- * @type Ext.util.ComponentDragger - * @property dd + * @property {Ext.util.ComponentDragger} dd + * If this Window is configured {@link #draggable}, this property will contain an instance of + * {@link Ext.util.ComponentDragger} (A subclass of {@link Ext.dd.DragTracker DragTracker}) which handles dragging + * the Window's DOM Element, and constraining according to the {@link #constrain} and {@link #constrainHeader} . + * + * This has implementations of `onBeforeStart`, `onDrag` and `onEnd` which perform the dragging action. If + * extra logic is needed at these points, use {@link Ext.Function#createInterceptor createInterceptor} or + * {@link Ext.Function#createSequence createSequence} to augment the existing implementations. */ me.dd = Ext.create('Ext.util.ComponentDragger', this, ddConfig); me.relayEvents(me.dd, ['dragstart', 'drag', 'dragend']); @@ -476,7 +495,7 @@ Ext.define('Ext.window.Window', { }, /** - * Gets the configured default focus item. If a {@link #defaultFocus} is set, it will receive focus, otherwise the + * Gets the configured default focus item. If a {@link #defaultFocus} is set, it will receive focus, otherwise the * Container itself will receive focus. */ getFocusEl: function() { @@ -513,17 +532,12 @@ Ext.define('Ext.window.Window', { var me = this, animating = animateTarget || me.animateTarget; - - if (animating) { - /* - * If we're animating, constrain the positioning before calling the - * superclass, otherwise we'll be animating to the unconstrained - * window position. - */ - me.doConstrain(); - } + + // No constraining code needs to go here. + // Component.onShow constrains the Component. *If the constrain config is true* + // Perform superclass's afterShow tasks - // Which might include animating a proxy from an animTarget + // Which might include animating a proxy from an animateTarget me.callParent(arguments); if (me.maximized) { @@ -544,13 +558,15 @@ Ext.define('Ext.window.Window', { doClose: function() { var me = this; - // immediate close + // Being called as callback after going through the hide call below if (me.hidden) { me.fireEvent('close', me); - me[me.closeAction](); + if (me.closeAction == 'destroy') { + this.destroy(); + } } else { // close after hiding - me.hide(me.animTarget, me.doClose, me); + me.hide(me.animateTarget, me.doClose, me); } }, @@ -579,9 +595,9 @@ Ext.define('Ext.window.Window', { }, /** - * Placeholder method for minimizing the window. By default, this method simply fires the {@link #minimize} event - * since the behavior of minimizing a window is application-specific. To implement custom minimize behavior, - * either the minimize event can be handled or this method can be overridden. + * Placeholder method for minimizing the window. By default, this method simply fires the {@link #minimize} event + * since the behavior of minimizing a window is application-specific. To implement custom minimize behavior, either + * the minimize event can be handled or this method can be overridden. * @return {Ext.window.Window} this */ minimize: function() { @@ -617,9 +633,8 @@ Ext.define('Ext.window.Window', { }, /** - * Fits the window within its current container and automatically replaces - * the {@link #maximizable 'maximize' tool button} with the 'restore' tool button. - * Also see {@link #toggleMaximize}. + * Fits the window within its current container and automatically replaces the {@link #maximizable 'maximize' tool + * button} with the 'restore' tool button. Also see {@link #toggleMaximize}. * @return {Ext.window.Window} this */ maximize: function() { @@ -656,10 +671,8 @@ Ext.define('Ext.window.Window', { }, /** - * Restores a {@link #maximizable maximized} window back to its original - * size and position prior to being maximized and also replaces - * the 'restore' tool button with the 'maximize' tool button. - * Also see {@link #toggleMaximize}. + * Restores a {@link #maximizable maximized} window back to its original size and position prior to being maximized + * and also replaces the 'restore' tool button with the 'maximize' tool button. Also see {@link #toggleMaximize}. * @return {Ext.window.Window} this */ restore: function() { @@ -749,3 +762,4 @@ Ext.define('Ext.window.Window', { * A width is a required configuration. **/ }); +