Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / source / ScrollManager.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-dd.ScrollManager'>/**
2 </span> * @class Ext.dd.ScrollManager
3  * &lt;p&gt;Provides automatic scrolling of overflow regions in the page during drag operations.&lt;/p&gt;
4  * &lt;p&gt;The ScrollManager configs will be used as the defaults for any scroll container registered with it,
5  * but you can also override most of the configs per scroll container by adding a
6  * &lt;tt&gt;ddScrollConfig&lt;/tt&gt; object to the target element that contains these properties: {@link #hthresh},
7  * {@link #vthresh}, {@link #increment} and {@link #frequency}.  Example usage:
8  * &lt;pre&gt;&lt;code&gt;
9 var el = Ext.get('scroll-ct');
10 el.ddScrollConfig = {
11     vthresh: 50,
12     hthresh: -1,
13     frequency: 100,
14     increment: 200
15 };
16 Ext.dd.ScrollManager.register(el);
17 &lt;/code&gt;&lt;/pre&gt;
18  * &lt;b&gt;Note: This class uses &quot;Point Mode&quot; and is untested in &quot;Intersect Mode&quot;.&lt;/b&gt;
19  * @singleton
20  */
21 Ext.define('Ext.dd.ScrollManager', {
22     singleton: true,
23     requires: [
24         'Ext.dd.DragDropManager'
25     ],
26
27     constructor: function() {
28         var ddm = Ext.dd.DragDropManager;
29         ddm.fireEvents = Ext.Function.createSequence(ddm.fireEvents, this.onFire, this);
30         ddm.stopDrag = Ext.Function.createSequence(ddm.stopDrag, this.onStop, this);
31         this.doScroll = Ext.Function.bind(this.doScroll, this);
32         this.ddmInstance = ddm;
33         this.els = {};
34         this.dragEl = null;
35         this.proc = {};
36     },
37
38     onStop: function(e){
39         var sm = Ext.dd.ScrollManager;
40         sm.dragEl = null;
41         sm.clearProc();
42     },
43
44     triggerRefresh: function() {
45         if (this.ddmInstance.dragCurrent) {
46             this.ddmInstance.refreshCache(this.ddmInstance.dragCurrent.groups);
47         }
48     },
49
50     doScroll: function() {
51         if (this.ddmInstance.dragCurrent) {
52             var proc   = this.proc,
53                 procEl = proc.el,
54                 ddScrollConfig = proc.el.ddScrollConfig,
55                 inc = ddScrollConfig ? ddScrollConfig.increment : this.increment;
56
57             if (!this.animate) {
58                 if (procEl.scroll(proc.dir, inc)) {
59                     this.triggerRefresh();
60                 }
61             } else {
62                 procEl.scroll(proc.dir, inc, true, this.animDuration, this.triggerRefresh);
63             }
64         }
65     },
66
67     clearProc: function() {
68         var proc = this.proc;
69         if (proc.id) {
70             clearInterval(proc.id);
71         }
72         proc.id = 0;
73         proc.el = null;
74         proc.dir = &quot;&quot;;
75     },
76
77     startProc: function(el, dir) {
78         this.clearProc();
79         this.proc.el = el;
80         this.proc.dir = dir;
81         var group = el.ddScrollConfig ? el.ddScrollConfig.ddGroup : undefined,
82             freq  = (el.ddScrollConfig &amp;&amp; el.ddScrollConfig.frequency)
83                   ? el.ddScrollConfig.frequency
84                   : this.frequency;
85
86         if (group === undefined || this.ddmInstance.dragCurrent.ddGroup == group) {
87             this.proc.id = setInterval(this.doScroll, freq);
88         }
89     },
90
91     onFire: function(e, isDrop) {
92         if (isDrop || !this.ddmInstance.dragCurrent) {
93             return;
94         }
95         if (!this.dragEl || this.dragEl != this.ddmInstance.dragCurrent) {
96             this.dragEl = this.ddmInstance.dragCurrent;
97             // refresh regions on drag start
98             this.refreshCache();
99         }
100
101         var xy = e.getXY(),
102             pt = e.getPoint(),
103             proc = this.proc,
104             els = this.els;
105
106         for (var id in els) {
107             var el = els[id], r = el._region;
108             var c = el.ddScrollConfig ? el.ddScrollConfig : this;
109             if (r &amp;&amp; r.contains(pt) &amp;&amp; el.isScrollable()) {
110                 if (r.bottom - pt.y &lt;= c.vthresh) {
111                     if(proc.el != el){
112                         this.startProc(el, &quot;down&quot;);
113                     }
114                     return;
115                 }else if (r.right - pt.x &lt;= c.hthresh) {
116                     if (proc.el != el) {
117                         this.startProc(el, &quot;left&quot;);
118                     }
119                     return;
120                 } else if(pt.y - r.top &lt;= c.vthresh) {
121                     if (proc.el != el) {
122                         this.startProc(el, &quot;up&quot;);
123                     }
124                     return;
125                 } else if(pt.x - r.left &lt;= c.hthresh) {
126                     if (proc.el != el) {
127                         this.startProc(el, &quot;right&quot;);
128                     }
129                     return;
130                 }
131             }
132         }
133         this.clearProc();
134     },
135
136 <span id='Ext-dd.ScrollManager-method-register'>    /**
137 </span>     * Registers new overflow element(s) to auto scroll
138      * @param {Mixed/Array} el The id of or the element to be scrolled or an array of either
139      */
140     register : function(el){
141         if (Ext.isArray(el)) {
142             for(var i = 0, len = el.length; i &lt; len; i++) {
143                     this.register(el[i]);
144             }
145         } else {
146             el = Ext.get(el);
147             this.els[el.id] = el;
148         }
149     },
150
151 <span id='Ext-dd.ScrollManager-method-unregister'>    /**
152 </span>     * Unregisters overflow element(s) so they are no longer scrolled
153      * @param {Mixed/Array} el The id of or the element to be removed or an array of either
154      */
155     unregister : function(el){
156         if(Ext.isArray(el)){
157             for (var i = 0, len = el.length; i &lt; len; i++) {
158                 this.unregister(el[i]);
159             }
160         }else{
161             el = Ext.get(el);
162             delete this.els[el.id];
163         }
164     },
165
166 <span id='Ext-dd.ScrollManager-property-vthresh'>    /**
167 </span>     * The number of pixels from the top or bottom edge of a container the pointer needs to be to
168      * trigger scrolling (defaults to 25)
169      * @type Number
170      */
171     vthresh : 25,
172 <span id='Ext-dd.ScrollManager-property-hthresh'>    /**
173 </span>     * The number of pixels from the right or left edge of a container the pointer needs to be to
174      * trigger scrolling (defaults to 25)
175      * @type Number
176      */
177     hthresh : 25,
178
179 <span id='Ext-dd.ScrollManager-property-increment'>    /**
180 </span>     * The number of pixels to scroll in each scroll increment (defaults to 100)
181      * @type Number
182      */
183     increment : 100,
184
185 <span id='Ext-dd.ScrollManager-property-frequency'>    /**
186 </span>     * The frequency of scrolls in milliseconds (defaults to 500)
187      * @type Number
188      */
189     frequency : 500,
190
191 <span id='Ext-dd.ScrollManager-property-animate'>    /**
192 </span>     * True to animate the scroll (defaults to true)
193      * @type Boolean
194      */
195     animate: true,
196
197 <span id='Ext-dd.ScrollManager-property-animDuration'>    /**
198 </span>     * The animation duration in seconds -
199      * MUST BE less than Ext.dd.ScrollManager.frequency! (defaults to .4)
200      * @type Number
201      */
202     animDuration: 0.4,
203
204 <span id='Ext-dd.ScrollManager-property-ddGroup'>    /**
205 </span>     * The named drag drop {@link Ext.dd.DragSource#ddGroup group} to which this container belongs (defaults to undefined).
206      * If a ddGroup is specified, then container scrolling will only occur when a dragged object is in the same ddGroup.
207      * @type String
208      */
209     ddGroup: undefined,
210
211 <span id='Ext-dd.ScrollManager-method-refreshCache'>    /**
212 </span>     * Manually trigger a cache refresh.
213      */
214     refreshCache : function(){
215         var els = this.els,
216             id;
217         for (id in els) {
218             if(typeof els[id] == 'object'){ // for people extending the object prototype
219                 els[id]._region = els[id].getRegion();
220             }
221         }
222     }
223 });
224 </pre></pre></body></html>