Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / source / Window.html
1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-window.Window-method-constructor'><span id='Ext-window.Window'>/**
2 </span></span> * @class Ext.window.Window
3  * @extends Ext.panel.Panel
4  * &lt;p&gt;A specialized panel intended for use as an application window.  Windows are floated, {@link #resizable}, and
5  * {@link #draggable} by default.  Windows can be {@link #maximizable maximized} to fill the viewport,
6  * restored to their prior size, and can be {@link #minimize}d.&lt;/p&gt;
7  * &lt;p&gt;Windows can also be linked to a {@link Ext.ZIndexManager} or managed by the {@link Ext.WindowManager} to provide
8  * grouping, activation, to front, to back and other application-specific behavior.&lt;/p&gt;
9  * &lt;p&gt;By default, Windows will be rendered to document.body. To {@link #constrain} a Window to another element
10  * specify {@link Ext.Component#renderTo renderTo}.&lt;/p&gt;
11  * &lt;p&gt;&lt;b&gt;As with all {@link Ext.container.Container Container}s, it is important to consider how you want the Window
12  * to size and arrange any child Components. Choose an appropriate {@link #layout} configuration which lays out
13  * child Components in the required manner.&lt;/b&gt;&lt;/p&gt;
14  * {@img Ext.window.Window/Ext.window.Window.png Window component}
15  * Example:&lt;code&gt;&lt;pre&gt;
16 Ext.create('Ext.window.Window', {
17     title: 'Hello',
18     height: 200,
19     width: 400,
20     layout: 'fit',
21     items: {  // Let's put an empty grid in just to illustrate fit layout
22         xtype: 'grid',
23         border: false,
24         columns: [{header: 'World'}],                 // One header just for show. There's no data,
25         store: Ext.create('Ext.data.ArrayStore', {}) // A dummy empty data store
26     }
27 }).show();
28 &lt;/pre&gt;&lt;/code&gt;
29  * @constructor
30  * @param {Object} config The config object
31  * @xtype window
32  */
33 Ext.define('Ext.window.Window', {
34     extend: 'Ext.panel.Panel',
35
36     alternateClassName: 'Ext.Window',
37
38     requires: ['Ext.util.ComponentDragger', 'Ext.util.Region', 'Ext.EventManager'],
39
40     alias: 'widget.window',
41
42 <span id='Ext-window.Window-cfg-x'>    /**
43 </span>     * @cfg {Number} x
44      * The X position of the left edge of the window on initial showing. Defaults to centering the Window within
45      * the width of the Window's container {@link Ext.core.Element Element) (The Element that the Window is rendered to).
46      */
47 <span id='Ext-window.Window-cfg-y'>    /**
48 </span>     * @cfg {Number} y
49      * The Y position of the top edge of the window on initial showing. Defaults to centering the Window within
50      * the height of the Window's container {@link Ext.core.Element Element) (The Element that the Window is rendered to).
51      */
52 <span id='Ext-window.Window-cfg-modal'>    /**
53 </span>     * @cfg {Boolean} modal
54      * True to make the window modal and mask everything behind it when displayed, false to display it without
55      * restricting access to other UI elements (defaults to false).
56      */
57 <span id='Ext-window.Window-cfg-animateTarget'>    /**
58 </span>     * @cfg {String/Element} animateTarget
59      * Id or element from which the window should animate while opening (defaults to null with no animation).
60      */
61 <span id='Ext-window.Window-cfg-defaultFocus'>    /**
62 </span>     * @cfg {String/Number/Component} defaultFocus
63      * &lt;p&gt;Specifies a Component to receive focus when this Window is focused.&lt;/p&gt;
64      * &lt;p&gt;This may be one of:&lt;/p&gt;&lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
65      * &lt;li&gt;The index of a footer Button.&lt;/li&gt;
66      * &lt;li&gt;The id or {@link Ext.AbstractComponent#itemId} of a descendant Component.&lt;/li&gt;
67      * &lt;li&gt;A Component.&lt;/li&gt;
68      * &lt;/ul&gt;&lt;/div&gt;
69      */
70 <span id='Ext-window.Window-cfg-onEsc'>    /**
71 </span>     * @cfg {Function} onEsc
72      * Allows override of the built-in processing for the escape key. Default action
73      * is to close the Window (performing whatever action is specified in {@link #closeAction}.
74      * To prevent the Window closing when the escape key is pressed, specify this as
75      * Ext.emptyFn (See {@link Ext#emptyFn Ext.emptyFn}).
76      */
77 <span id='Ext-window.Window-cfg-collapsed'>    /**
78 </span>     * @cfg {Boolean} collapsed
79      * True to render the window collapsed, false to render it expanded (defaults to false). Note that if
80      * {@link #expandOnShow} is true (the default) it will override the &lt;code&gt;collapsed&lt;/code&gt; config and the window
81      * will always be expanded when shown.
82      */
83 <span id='Ext-window.Window-cfg-maximized'>    /**
84 </span>     * @cfg {Boolean} maximized
85      * True to initially display the window in a maximized state. (Defaults to false).
86      */
87
88 <span id='Ext-window.Window-cfg-baseCls'>    /**
89 </span>    * @cfg {String} baseCls
90     * The base CSS class to apply to this panel's element (defaults to 'x-window').
91     */
92     baseCls: Ext.baseCSSPrefix + 'window',
93
94 <span id='Ext-window.Window-cfg-resizable'>    /**
95 </span>     * @cfg {Mixed} resizable
96      * &lt;p&gt;Specify as &lt;code&gt;true&lt;/code&gt; to allow user resizing at each edge and corner of the window, false to disable
97      * resizing (defaults to true).&lt;/p&gt;
98      * &lt;p&gt;This may also be specified as a config object to &lt;/p&gt;
99      */
100     resizable: true,
101
102 <span id='Ext-window.Window-cfg-draggable'>    /**
103 </span>     * @cfg {Boolean} draggable
104      * &lt;p&gt;True to allow the window to be dragged by the header bar, false to disable dragging (defaults to true).  Note
105      * that by default the window will be centered in the viewport, so if dragging is disabled the window may need
106      * to be positioned programmatically after render (e.g., myWindow.setPosition(100, 100);).&lt;p&gt;
107      */
108     draggable: true,
109
110 <span id='Ext-window.Window-cfg-constrain'>    /**
111 </span>     * @cfg {Boolean} constrain
112      * True to constrain the window within its containing element, false to allow it to fall outside of its
113      * containing element. By default the window will be rendered to document.body.  To render and constrain the
114      * window within another element specify {@link #renderTo}.
115      * (defaults to false).  Optionally the header only can be constrained using {@link #constrainHeader}.
116      */
117     constrain: false,
118
119 <span id='Ext-window.Window-cfg-constrainHeader'>    /**
120 </span>     * @cfg {Boolean} constrainHeader
121      * True to constrain the window header within its containing element (allowing the window body to fall outside
122      * of its containing element) or false to allow the header to fall outside its containing element (defaults to
123      * false). Optionally the entire window can be constrained using {@link #constrain}.
124      */
125     constrainHeader: false,
126
127 <span id='Ext-window.Window-cfg-plain'>    /**
128 </span>     * @cfg {Boolean} plain
129      * True to render the window body with a transparent background so that it will blend into the framing
130      * elements, false to add a lighter background color to visually highlight the body element and separate it
131      * more distinctly from the surrounding frame (defaults to false).
132      */
133     plain: false,
134
135 <span id='Ext-window.Window-cfg-minimizable'>    /**
136 </span>     * @cfg {Boolean} minimizable
137      * True to display the 'minimize' tool button and allow the user to minimize the window, false to hide the button
138      * and disallow minimizing the window (defaults to false).  Note that this button provides no implementation --
139      * the behavior of minimizing a window is implementation-specific, so the minimize event must be handled and a
140      * custom minimize behavior implemented for this option to be useful.
141      */
142     minimizable: false,
143
144 <span id='Ext-window.Window-cfg-maximizable'>    /**
145 </span>     * @cfg {Boolean} maximizable
146      * True to display the 'maximize' tool button and allow the user to maximize the window, false to hide the button
147      * and disallow maximizing the window (defaults to false).  Note that when a window is maximized, the tool button
148      * will automatically change to a 'restore' button with the appropriate behavior already built-in that will
149      * restore the window to its previous size.
150      */
151     maximizable: false,
152
153     // inherit docs
154     minHeight: 100,
155
156     // inherit docs
157     minWidth: 200,
158
159 <span id='Ext-window.Window-cfg-expandOnShow'>    /**
160 </span>     * @cfg {Boolean} expandOnShow
161      * True to always expand the window when it is displayed, false to keep it in its current state (which may be
162      * {@link #collapsed}) when displayed (defaults to true).
163      */
164     expandOnShow: true,
165
166     // inherited docs, same default
167     collapsible: false,
168
169 <span id='Ext-window.Window-cfg-closable'>    /**
170 </span>     * @cfg {Boolean} closable
171      * &lt;p&gt;True to display the 'close' tool button and allow the user to close the window, false to
172      * hide the button and disallow closing the window (defaults to &lt;code&gt;true&lt;/code&gt;).&lt;/p&gt;
173      * &lt;p&gt;By default, when close is requested by either clicking the close button in the header
174      * or pressing ESC when the Window has focus, the {@link #close} method will be called. This
175      * will &lt;i&gt;{@link Ext.Component#destroy destroy}&lt;/i&gt; the Window and its content meaning that
176      * it may not be reused.&lt;/p&gt;
177      * &lt;p&gt;To make closing a Window &lt;i&gt;hide&lt;/i&gt; the Window so that it may be reused, set
178      * {@link #closeAction} to 'hide'.&lt;/p&gt;
179      */
180     closable: true,
181
182 <span id='Ext-window.Window-cfg-hidden'>    /**
183 </span>     * @cfg {Boolean} hidden
184      * Render this Window hidden (default is &lt;code&gt;true&lt;/code&gt;). If &lt;code&gt;true&lt;/code&gt;, the
185      * {@link #hide} method will be called internally.
186      */
187     hidden: true,
188
189     // Inherit docs from Component. Windows render to the body on first show.
190     autoRender: true,
191
192     // Inherit docs from Component. Windows hide using visibility.
193     hideMode: 'visibility',
194
195 <span id='Ext-window.Window-cfg-floating'>    /** @cfg {Boolean} floating @hide Windows are always floating*/
196 </span>    floating: true,
197
198     ariaRole: 'alertdialog',
199     
200     itemCls: 'x-window-item',
201
202     overlapHeader: true,
203     
204     ignoreHeaderBorderManagement: true,
205
206     // private
207     initComponent: function() {
208         var me = this;
209         me.callParent();
210         me.addEvents(
211 <span id='Ext-window.Window-event-activate'>            /**
212 </span>             * @event activate
213              * Fires after the window has been visually activated via {@link #setActive}.
214              * @param {Ext.window.Window} this
215              */
216 <span id='Ext-window.Window-event-deactivate'>            /**
217 </span>             * @event deactivate
218              * Fires after the window has been visually deactivated via {@link #setActive}.
219              * @param {Ext.window.Window} this
220              */
221 <span id='Ext-window.Window-event-resize'>            /**
222 </span>             * @event resize
223              * Fires after the window has been resized.
224              * @param {Ext.window.Window} this
225              * @param {Number} width The window's new width
226              * @param {Number} height The window's new height
227              */
228             'resize',
229 <span id='Ext-window.Window-event-maximize'>            /**
230 </span>             * @event maximize
231              * Fires after the window has been maximized.
232              * @param {Ext.window.Window} this
233              */
234             'maximize',
235 <span id='Ext-window.Window-event-minimize'>            /**
236 </span>             * @event minimize
237              * Fires after the window has been minimized.
238              * @param {Ext.window.Window} this
239              */
240             'minimize',
241 <span id='Ext-window.Window-event-restore'>            /**
242 </span>             * @event restore
243              * Fires after the window has been restored to its original size after being maximized.
244              * @param {Ext.window.Window} this
245              */
246             'restore'
247         );
248
249         if (me.plain) {
250             me.addClsWithUI('plain');
251         }
252
253         if (me.modal) {
254             me.ariaRole = 'dialog';
255         }
256     },
257
258     // State Management
259     // private
260
261     initStateEvents: function(){
262         var events = this.stateEvents;
263         // push on stateEvents if they don't exist
264         Ext.each(['maximize', 'restore', 'resize', 'dragend'], function(event){
265             if (Ext.Array.indexOf(events, event)) {
266                 events.push(event);
267             }
268         });
269         this.callParent();
270     },
271
272     getState: function() {
273         var me = this,
274             state = me.callParent() || {},
275             maximized = !!me.maximized;
276
277         state.maximized = maximized;
278         Ext.apply(state, {
279             size: maximized ? me.restoreSize : me.getSize(),
280             pos: maximized ? me.restorePos : me.getPosition()
281         });
282         return state;
283     },
284
285     applyState: function(state){
286         var me = this;
287
288         if (state) {
289             me.maximized = state.maximized;
290             if (me.maximized) {
291                 me.hasSavedRestore = true;
292                 me.restoreSize = state.size;
293                 me.restorePos = state.pos;
294             } else {
295                 Ext.apply(me, {
296                     width: state.size.width,
297                     height: state.size.height,
298                     x: state.pos[0],
299                     y: state.pos[1]
300                 });
301             }
302         }
303     },
304
305     // private
306     onMouseDown: function () {
307         if (this.floating) {
308             this.toFront();
309         }
310     },
311
312     // private
313     onRender: function(ct, position) {
314         var me = this;
315         me.callParent(arguments);
316         me.focusEl = me.el;
317
318         // Double clicking a header will toggleMaximize
319         if (me.maximizable) {
320             me.header.on({
321                 dblclick: {
322                     fn: me.toggleMaximize,
323                     element: 'el',
324                     scope: me
325                 }
326             });
327         }
328     },
329
330     // private
331     afterRender: function() {
332         var me = this,
333             hidden = me.hidden,
334             keyMap;
335
336         me.hidden = false;
337         // Component's afterRender sizes and positions the Component
338         me.callParent();
339         me.hidden = hidden;
340
341         // Create the proxy after the size has been applied in Component.afterRender
342         me.proxy = me.getProxy();
343
344         // clickToRaise
345         me.mon(me.el, 'mousedown', me.onMouseDown, me);
346
347         // Initialize
348         if (me.maximized) {
349             me.maximized = false;
350             me.maximize();
351         }
352
353         if (me.closable) {
354             keyMap = me.getKeyMap();
355             keyMap.on(27, me.onEsc, me);
356             keyMap.disable();
357         }
358     },
359
360 <span id='Ext-window.Window-method-initDraggable'>    /**
361 </span>     * @private
362      * @override
363      * Override Component.initDraggable.
364      * Window uses the header element as the delegate.
365      */
366     initDraggable: function() {
367         var me = this,
368             ddConfig;
369
370         if (!me.header) {
371             me.updateHeader(true);
372         }
373
374         ddConfig = Ext.applyIf({
375             el: me.el,
376             delegate: '#' + me.header.id
377         }, me.draggable);
378
379         // Add extra configs if Window is specified to be constrained
380         if (me.constrain || me.constrainHeader) {
381             ddConfig.constrain = me.constrain;
382             ddConfig.constrainDelegate = me.constrainHeader;
383             ddConfig.constrainTo = me.constrainTo || me.container;
384         }
385
386 <span id='Ext-window.Window-property-dd'>        /**
387 </span>         * &lt;p&gt;If this Window is configured {@link #draggable}, this property will contain
388          * an instance of {@link Ext.util.ComponentDragger} (A subclass of {@link Ext.dd.DragTracker DragTracker})
389          * which handles dragging the Window's DOM Element, and constraining according to the {@link #constrain}
390          * and {@link #constrainHeader} .&lt;/p&gt;
391          * &lt;p&gt;This has implementations of &lt;code&gt;onBeforeStart&lt;/code&gt;, &lt;code&gt;onDrag&lt;/code&gt; and &lt;code&gt;onEnd&lt;/code&gt;
392          * which perform the dragging action. If extra logic is needed at these points, use
393          * {@link Ext.Function#createInterceptor createInterceptor} or {@link Ext.Function#createSequence createSequence} to
394          * augment the existing implementations.&lt;/p&gt;
395          * @type Ext.util.ComponentDragger
396          * @property dd
397          */
398         me.dd = Ext.create('Ext.util.ComponentDragger', this, ddConfig);
399         me.relayEvents(me.dd, ['dragstart', 'drag', 'dragend']);
400     },
401
402     // private
403     onEsc: function(k, e) {
404         e.stopEvent();
405         this[this.closeAction]();
406     },
407
408     // private
409     beforeDestroy: function() {
410         var me = this;
411         if (me.rendered) {
412             delete this.animateTarget;
413             me.hide();
414             Ext.destroy(
415                 me.keyMap
416             );
417         }
418         me.callParent();
419     },
420
421 <span id='Ext-window.Window-method-addTools'>    /**
422 </span>     * @private
423      * @override
424      * Contribute class-specific tools to the header.
425      * Called by Panel's initTools.
426      */
427     addTools: function() {
428         var me = this;
429
430         // Call Panel's initTools
431         me.callParent();
432
433         if (me.minimizable) {
434             me.addTool({
435                 type: 'minimize',
436                 handler: Ext.Function.bind(me.minimize, me, [])
437             });
438         }
439         if (me.maximizable) {
440             me.addTool({
441                 type: 'maximize',
442                 handler: Ext.Function.bind(me.maximize, me, [])
443             });
444             me.addTool({
445                 type: 'restore',
446                 handler: Ext.Function.bind(me.restore, me, []),
447                 hidden: true
448             });
449         }
450     },
451
452 <span id='Ext-window.Window-method-getFocusEl'>    /**
453 </span>     * Gets the configured default focus item.  If a {@link #defaultFocus} is set, it will receive focus, otherwise the
454      * Container itself will receive focus.
455      */
456     getFocusEl: function() {
457         var me = this,
458             f = me.focusEl,
459             defaultComp = me.defaultButton || me.defaultFocus,
460             t = typeof db,
461             el,
462             ct;
463
464         if (Ext.isDefined(defaultComp)) {
465             if (Ext.isNumber(defaultComp)) {
466                 f = me.query('button')[defaultComp];
467             } else if (Ext.isString(defaultComp)) {
468                 f = me.down('#' + defaultComp);
469             } else {
470                 f = defaultComp;
471             }
472         }
473         return f || me.focusEl;
474     },
475
476     // private
477     beforeShow: function() {
478         this.callParent();
479
480         if (this.expandOnShow) {
481             this.expand(false);
482         }
483     },
484
485     // private
486     afterShow: function(animateTarget) {
487         var me = this,
488             size;
489
490         // Perform superclass's afterShow tasks
491         // Which might include animating a proxy from an animTarget
492         me.callParent(arguments);
493
494         if (me.maximized) {
495             me.fitContainer();
496         }
497
498         if (me.monitorResize || me.constrain || me.constrainHeader) {
499             Ext.EventManager.onWindowResize(me.onWindowResize, me);
500         }
501         me.doConstrain();
502         if (me.keyMap) {
503             me.keyMap.enable();
504         }
505     },
506
507     // private
508     doClose: function() {
509         var me = this;
510
511         // immediate close
512         if (me.hidden) {
513             me.fireEvent('close', me);
514             me[me.closeAction]();
515         } else {
516             // close after hiding
517             me.hide(me.animTarget, me.doClose, me);
518         }
519     },
520
521     // private
522     afterHide: function() {
523         var me = this;
524
525         // No longer subscribe to resizing now that we're hidden
526         if (me.monitorResize || me.constrain || me.constrainHeader) {
527             Ext.EventManager.removeResizeListener(me.onWindowResize, me);
528         }
529
530         // Turn off keyboard handling once window is hidden
531         if (me.keyMap) {
532             me.keyMap.disable();
533         }
534
535         // Perform superclass's afterHide tasks.
536         me.callParent(arguments);
537     },
538
539     // private
540     onWindowResize: function() {
541         if (this.maximized) {
542             this.fitContainer();
543         }
544         this.doConstrain();
545     },
546
547 <span id='Ext-window.Window-method-minimize'>    /**
548 </span>     * Placeholder method for minimizing the window.  By default, this method simply fires the {@link #minimize} event
549      * since the behavior of minimizing a window is application-specific.  To implement custom minimize behavior,
550      * either the minimize event can be handled or this method can be overridden.
551      * @return {Ext.window.Window} this
552      */
553     minimize: function() {
554         this.fireEvent('minimize', this);
555         return this;
556     },
557
558     afterCollapse: function() {
559         var me = this;
560
561         if (me.maximizable) {
562             me.tools.maximize.hide();
563             me.tools.restore.hide();
564         }
565         if (me.resizer) {
566             me.resizer.disable();
567         }
568         me.callParent(arguments);
569     },
570
571     afterExpand: function() {
572         var me = this;
573
574         if (me.maximized) {
575             me.tools.restore.show();
576         } else if (me.maximizable) {
577             me.tools.maximize.show();
578         }
579         if (me.resizer) {
580             me.resizer.enable();
581         }
582         me.callParent(arguments);
583     },
584
585 <span id='Ext-window.Window-method-maximize'>    /**
586 </span>     * Fits the window within its current container and automatically replaces
587      * the {@link #maximizable 'maximize' tool button} with the 'restore' tool button.
588      * Also see {@link #toggleMaximize}.
589      * @return {Ext.window.Window} this
590      */
591     maximize: function() {
592         var me = this;
593
594         if (!me.maximized) {
595             me.expand(false);
596             if (!me.hasSavedRestore) {
597                 me.restoreSize = me.getSize();
598                 me.restorePos = me.getPosition(true);
599             }
600             if (me.maximizable) {
601                 me.tools.maximize.hide();
602                 me.tools.restore.show();
603             }
604             me.maximized = true;
605             me.el.disableShadow();
606
607             if (me.dd) {
608                 me.dd.disable();
609             }
610             if (me.collapseTool) {
611                 me.collapseTool.hide();
612             }
613             me.el.addCls(Ext.baseCSSPrefix + 'window-maximized');
614             me.container.addCls(Ext.baseCSSPrefix + 'window-maximized-ct');
615
616             me.setPosition(0, 0);
617             me.fitContainer();
618             me.fireEvent('maximize', me);
619         }
620         return me;
621     },
622
623 <span id='Ext-window.Window-method-restore'>    /**
624 </span>     * Restores a {@link #maximizable maximized}  window back to its original
625      * size and position prior to being maximized and also replaces
626      * the 'restore' tool button with the 'maximize' tool button.
627      * Also see {@link #toggleMaximize}.
628      * @return {Ext.window.Window} this
629      */
630     restore: function() {
631         var me = this,
632             tools = me.tools;
633
634         if (me.maximized) {
635             delete me.hasSavedRestore;
636             me.removeCls(Ext.baseCSSPrefix + 'window-maximized');
637
638             // Toggle tool visibility
639             if (tools.restore) {
640                 tools.restore.hide();
641             }
642             if (tools.maximize) {
643                 tools.maximize.show();
644             }
645             if (me.collapseTool) {
646                 me.collapseTool.show();
647             }
648
649             // Restore the position/sizing
650             me.setPosition(me.restorePos);
651             me.setSize(me.restoreSize);
652
653             // Unset old position/sizing
654             delete me.restorePos;
655             delete me.restoreSize;
656
657             me.maximized = false;
658
659             me.el.enableShadow(true);
660
661             // Allow users to drag and drop again
662             if (me.dd) {
663                 me.dd.enable();
664             }
665
666             me.container.removeCls(Ext.baseCSSPrefix + 'window-maximized-ct');
667
668             me.doConstrain();
669             me.fireEvent('restore', me);
670         }
671         return me;
672     },
673
674 <span id='Ext-window.Window-method-toggleMaximize'>    /**
675 </span>     * A shortcut method for toggling between {@link #maximize} and {@link #restore} based on the current maximized
676      * state of the window.
677      * @return {Ext.window.Window} this
678      */
679     toggleMaximize: function() {
680         return this[this.maximized ? 'restore': 'maximize']();
681     }
682
683 <span id='Ext-window.Window-cfg-autoWidth'>    /**
684 </span>     * @cfg {Boolean} autoWidth @hide
685      * Absolute positioned element and therefore cannot support autoWidth.
686      * A width is a required configuration.
687      **/
688 });</pre></pre></body></html>