Upgrade to ExtJS 3.2.0 - Released 03/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.2.0
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.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 freq = (el.ddScrollConfig && el.ddScrollConfig.frequency) ? 
81                 el.ddScrollConfig.frequency : Ext.dd.ScrollManager.frequency;
82         proc.id = setInterval(doScroll, freq);
83     };
84     
85     var onFire = function(e, isDrop){
86         if(isDrop || !ddm.dragCurrent){ return; }
87         var dds = Ext.dd.ScrollManager;
88         if(!dragEl || dragEl != ddm.dragCurrent){
89             dragEl = ddm.dragCurrent;
90             // refresh regions on drag start
91             dds.refreshCache();
92         }
93         
94         var xy = Ext.lib.Event.getXY(e);
95         var pt = new Ext.lib.Point(xy[0], xy[1]);
96         for(var id in els){
97             var el = els[id], r = el._region;
98             var c = el.ddScrollConfig ? el.ddScrollConfig : dds;
99             if(r && r.contains(pt) && el.isScrollable()){
100                 if(r.bottom - pt.y <= c.vthresh){
101                     if(proc.el != el){
102                         startProc(el, "down");
103                     }
104                     return;
105                 }else if(r.right - pt.x <= c.hthresh){
106                     if(proc.el != el){
107                         startProc(el, "left");
108                     }
109                     return;
110                 }else if(pt.y - r.top <= c.vthresh){
111                     if(proc.el != el){
112                         startProc(el, "up");
113                     }
114                     return;
115                 }else if(pt.x - r.left <= c.hthresh){
116                     if(proc.el != el){
117                         startProc(el, "right");
118                     }
119                     return;
120                 }
121             }
122         }
123         clearProc();
124     };
125     
126     ddm.fireEvents = ddm.fireEvents.createSequence(onFire, ddm);
127     ddm.stopDrag = ddm.stopDrag.createSequence(onStop, ddm);
128     
129     return {
130         <div id="method-Ext.dd.ScrollManager-register"></div>/**
131          * Registers new overflow element(s) to auto scroll
132          * @param {Mixed/Array} el The id of or the element to be scrolled or an array of either
133          */
134         register : function(el){
135             if(Ext.isArray(el)){
136                 for(var i = 0, len = el.length; i < len; i++) {
137                         this.register(el[i]);
138                 }
139             }else{
140                 el = Ext.get(el);
141                 els[el.id] = el;
142             }
143         },
144         
145         <div id="method-Ext.dd.ScrollManager-unregister"></div>/**
146          * Unregisters overflow element(s) so they are no longer scrolled
147          * @param {Mixed/Array} el The id of or the element to be removed or an array of either
148          */
149         unregister : function(el){
150             if(Ext.isArray(el)){
151                 for(var i = 0, len = el.length; i < len; i++) {
152                         this.unregister(el[i]);
153                 }
154             }else{
155                 el = Ext.get(el);
156                 delete els[el.id];
157             }
158         },
159         
160         <div id="prop-Ext.dd.ScrollManager-vthresh"></div>/**
161          * The number of pixels from the top or bottom edge of a container the pointer needs to be to
162          * trigger scrolling (defaults to 25)
163          * @type Number
164          */
165         vthresh : 25,
166         <div id="prop-Ext.dd.ScrollManager-hthresh"></div>/**
167          * The number of pixels from the right or left edge of a container the pointer needs to be to
168          * trigger scrolling (defaults to 25)
169          * @type Number
170          */
171         hthresh : 25,
172
173         <div id="prop-Ext.dd.ScrollManager-increment"></div>/**
174          * The number of pixels to scroll in each scroll increment (defaults to 50)
175          * @type Number
176          */
177         increment : 100,
178         
179         <div id="prop-Ext.dd.ScrollManager-frequency"></div>/**
180          * The frequency of scrolls in milliseconds (defaults to 500)
181          * @type Number
182          */
183         frequency : 500,
184         
185         <div id="prop-Ext.dd.ScrollManager-animate"></div>/**
186          * True to animate the scroll (defaults to true)
187          * @type Boolean
188          */
189         animate: true,
190         
191         <div id="prop-Ext.dd.ScrollManager-animDuration"></div>/**
192          * The animation duration in seconds - 
193          * MUST BE less than Ext.dd.ScrollManager.frequency! (defaults to .4)
194          * @type Number
195          */
196         animDuration: .4,
197         
198         <div id="method-Ext.dd.ScrollManager-refreshCache"></div>/**
199          * Manually trigger a cache refresh.
200          */
201         refreshCache : function(){
202             for(var id in els){
203                 if(typeof els[id] == 'object'){ // for people extending the object prototype
204                     els[id]._region = els[id].getRegion();
205                 }
206             }
207         }
208     };
209 }();</pre>    
210 </body>
211 </html>