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