Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / DD.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js">/*
19  * This is a derivative of the similarly named class in the YUI Library.
20  * The original license:
21  * Copyright (c) 2006, Yahoo! Inc. All rights reserved.
22  * Code licensed under the BSD License:
23  * http://developer.yahoo.net/yui/license.txt
24  */
25
26
27 <span id='Ext-dd-DD'>/**
28 </span> * @class Ext.dd.DD
29  * A DragDrop implementation where the linked element follows the
30  * mouse cursor during a drag.
31  * @extends Ext.dd.DragDrop
32  */
33 Ext.define('Ext.dd.DD', {
34     extend: 'Ext.dd.DragDrop',
35     requires: ['Ext.dd.DragDropManager'],
36
37 <span id='Ext-dd-DD-method-constructor'>    /**
38 </span>     * Creates new DD instance.
39      * @param {String} id the id of the linked element
40      * @param {String} sGroup the group of related DragDrop items
41      * @param {object} config an object containing configurable attributes.
42      * Valid properties for DD: scroll
43      */
44     constructor: function(id, sGroup, config) {
45         if (id) {
46             this.init(id, sGroup, config);
47         }
48     },
49
50 <span id='Ext-dd-DD-property-scroll'>    /**
51 </span>     * When set to true, the utility automatically tries to scroll the browser
52      * window when a drag and drop element is dragged near the viewport boundary.
53      * Defaults to true.
54      * @property scroll
55      * @type boolean
56      */
57     scroll: true,
58
59 <span id='Ext-dd-DD-method-autoOffset'>    /**
60 </span>     * Sets the pointer offset to the distance between the linked element's top
61      * left corner and the location the element was clicked
62      * @method autoOffset
63      * @param {int} iPageX the X coordinate of the click
64      * @param {int} iPageY the Y coordinate of the click
65      */
66     autoOffset: function(iPageX, iPageY) {
67         var x = iPageX - this.startPageX;
68         var y = iPageY - this.startPageY;
69         this.setDelta(x, y);
70     },
71
72 <span id='Ext-dd-DD-method-setDelta'>    /**
73 </span>     * Sets the pointer offset.  You can call this directly to force the
74      * offset to be in a particular location (e.g., pass in 0,0 to set it
75      * to the center of the object)
76      * @method setDelta
77      * @param {int} iDeltaX the distance from the left
78      * @param {int} iDeltaY the distance from the top
79      */
80     setDelta: function(iDeltaX, iDeltaY) {
81         this.deltaX = iDeltaX;
82         this.deltaY = iDeltaY;
83     },
84
85 <span id='Ext-dd-DD-method-setDragElPos'>    /**
86 </span>     * Sets the drag element to the location of the mousedown or click event,
87      * maintaining the cursor location relative to the location on the element
88      * that was clicked.  Override this if you want to place the element in a
89      * location other than where the cursor is.
90      * @method setDragElPos
91      * @param {int} iPageX the X coordinate of the mousedown or drag event
92      * @param {int} iPageY the Y coordinate of the mousedown or drag event
93      */
94     setDragElPos: function(iPageX, iPageY) {
95         // the first time we do this, we are going to check to make sure
96         // the element has css positioning
97
98         var el = this.getDragEl();
99         this.alignElWithMouse(el, iPageX, iPageY);
100     },
101
102 <span id='Ext-dd-DD-method-alignElWithMouse'>    /**
103 </span>     * Sets the element to the location of the mousedown or click event,
104      * maintaining the cursor location relative to the location on the element
105      * that was clicked.  Override this if you want to place the element in a
106      * location other than where the cursor is.
107      * @method alignElWithMouse
108      * @param {HTMLElement} el the element to move
109      * @param {int} iPageX the X coordinate of the mousedown or drag event
110      * @param {int} iPageY the Y coordinate of the mousedown or drag event
111      */
112     alignElWithMouse: function(el, iPageX, iPageY) {
113         var oCoord = this.getTargetCoord(iPageX, iPageY),
114             fly = el.dom ? el : Ext.fly(el, '_dd'),
115             elSize = fly.getSize(),
116             EL = Ext.core.Element,
117             vpSize;
118
119         if (!this.deltaSetXY) {
120             vpSize = this.cachedViewportSize = { width: EL.getDocumentWidth(), height: EL.getDocumentHeight() };
121             var aCoord = [
122                 Math.max(0, Math.min(oCoord.x, vpSize.width - elSize.width)),
123                 Math.max(0, Math.min(oCoord.y, vpSize.height - elSize.height))
124             ];
125             fly.setXY(aCoord);
126             var newLeft = fly.getLeft(true);
127             var newTop  = fly.getTop(true);
128             this.deltaSetXY = [newLeft - oCoord.x, newTop - oCoord.y];
129         } else {
130             vpSize = this.cachedViewportSize;
131             fly.setLeftTop(
132                 Math.max(0, Math.min(oCoord.x + this.deltaSetXY[0], vpSize.width - elSize.width)),
133                 Math.max(0, Math.min(oCoord.y + this.deltaSetXY[1], vpSize.height - elSize.height))
134             );
135         }
136
137         this.cachePosition(oCoord.x, oCoord.y);
138         this.autoScroll(oCoord.x, oCoord.y, el.offsetHeight, el.offsetWidth);
139         return oCoord;
140     },
141
142 <span id='Ext-dd-DD-method-cachePosition'>    /**
143 </span>     * Saves the most recent position so that we can reset the constraints and
144      * tick marks on-demand.  We need to know this so that we can calculate the
145      * number of pixels the element is offset from its original position.
146      * @method cachePosition
147      * @param iPageX the current x position (optional, this just makes it so we
148      * don't have to look it up again)
149      * @param iPageY the current y position (optional, this just makes it so we
150      * don't have to look it up again)
151      */
152     cachePosition: function(iPageX, iPageY) {
153         if (iPageX) {
154             this.lastPageX = iPageX;
155             this.lastPageY = iPageY;
156         } else {
157             var aCoord = Ext.core.Element.getXY(this.getEl());
158             this.lastPageX = aCoord[0];
159             this.lastPageY = aCoord[1];
160         }
161     },
162
163 <span id='Ext-dd-DD-method-autoScroll'>    /**
164 </span>     * Auto-scroll the window if the dragged object has been moved beyond the
165      * visible window boundary.
166      * @method autoScroll
167      * @param {int} x the drag element's x position
168      * @param {int} y the drag element's y position
169      * @param {int} h the height of the drag element
170      * @param {int} w the width of the drag element
171      * @private
172      */
173     autoScroll: function(x, y, h, w) {
174
175         if (this.scroll) {
176             // The client height
177             var clientH = Ext.core.Element.getViewHeight();
178
179             // The client width
180             var clientW = Ext.core.Element.getViewWidth();
181
182             // The amt scrolled down
183             var st = this.DDMInstance.getScrollTop();
184
185             // The amt scrolled right
186             var sl = this.DDMInstance.getScrollLeft();
187
188             // Location of the bottom of the element
189             var bot = h + y;
190
191             // Location of the right of the element
192             var right = w + x;
193
194             // The distance from the cursor to the bottom of the visible area,
195             // adjusted so that we don't scroll if the cursor is beyond the
196             // element drag constraints
197             var toBot = (clientH + st - y - this.deltaY);
198
199             // The distance from the cursor to the right of the visible area
200             var toRight = (clientW + sl - x - this.deltaX);
201
202
203             // How close to the edge the cursor must be before we scroll
204             // var thresh = (document.all) ? 100 : 40;
205             var thresh = 40;
206
207             // How many pixels to scroll per autoscroll op.  This helps to reduce
208             // clunky scrolling. IE is more sensitive about this ... it needs this
209             // value to be higher.
210             var scrAmt = (document.all) ? 80 : 30;
211
212             // Scroll down if we are near the bottom of the visible page and the
213             // obj extends below the crease
214             if ( bot &gt; clientH &amp;&amp; toBot &lt; thresh ) {
215                 window.scrollTo(sl, st + scrAmt);
216             }
217
218             // Scroll up if the window is scrolled down and the top of the object
219             // goes above the top border
220             if ( y &lt; st &amp;&amp; st &gt; 0 &amp;&amp; y - st &lt; thresh ) {
221                 window.scrollTo(sl, st - scrAmt);
222             }
223
224             // Scroll right if the obj is beyond the right border and the cursor is
225             // near the border.
226             if ( right &gt; clientW &amp;&amp; toRight &lt; thresh ) {
227                 window.scrollTo(sl + scrAmt, st);
228             }
229
230             // Scroll left if the window has been scrolled to the right and the obj
231             // extends past the left border
232             if ( x &lt; sl &amp;&amp; sl &gt; 0 &amp;&amp; x - sl &lt; thresh ) {
233                 window.scrollTo(sl - scrAmt, st);
234             }
235         }
236     },
237
238 <span id='Ext-dd-DD-method-getTargetCoord'>    /**
239 </span>     * Finds the location the element should be placed if we want to move
240      * it to where the mouse location less the click offset would place us.
241      * @method getTargetCoord
242      * @param {int} iPageX the X coordinate of the click
243      * @param {int} iPageY the Y coordinate of the click
244      * @return an object that contains the coordinates (Object.x and Object.y)
245      * @private
246      */
247     getTargetCoord: function(iPageX, iPageY) {
248         var x = iPageX - this.deltaX;
249         var y = iPageY - this.deltaY;
250
251         if (this.constrainX) {
252             if (x &lt; this.minX) {
253                 x = this.minX;
254             }
255             if (x &gt; this.maxX) {
256                 x = this.maxX;
257             }
258         }
259
260         if (this.constrainY) {
261             if (y &lt; this.minY) {
262                 y = this.minY;
263             }
264             if (y &gt; this.maxY) {
265                 y = this.maxY;
266             }
267         }
268
269         x = this.getTick(x, this.xTicks);
270         y = this.getTick(y, this.yTicks);
271
272
273         return {x: x, y: y};
274     },
275
276 <span id='Ext-dd-DD-method-applyConfig'>    /**
277 </span>     * Sets up config options specific to this class. Overrides
278      * Ext.dd.DragDrop, but all versions of this method through the
279      * inheritance chain are called
280      */
281     applyConfig: function() {
282         this.callParent();
283         this.scroll = (this.config.scroll !== false);
284     },
285
286 <span id='Ext-dd-DD-method-b4MouseDown'>    /**
287 </span>     * Event that fires prior to the onMouseDown event.  Overrides
288      * Ext.dd.DragDrop.
289      */
290     b4MouseDown: function(e) {
291         // this.resetConstraints();
292         this.autoOffset(e.getPageX(), e.getPageY());
293     },
294
295 <span id='Ext-dd-DD-method-b4Drag'>    /**
296 </span>     * Event that fires prior to the onDrag event.  Overrides
297      * Ext.dd.DragDrop.
298      */
299     b4Drag: function(e) {
300         this.setDragElPos(e.getPageX(), e.getPageY());
301     },
302
303     toString: function() {
304         return (&quot;DD &quot; + this.id);
305     }
306
307     //////////////////////////////////////////////////////////////////////////
308     // Debugging ygDragDrop events that can be overridden
309     //////////////////////////////////////////////////////////////////////////
310     /*
311     startDrag: function(x, y) {
312     },
313
314     onDrag: function(e) {
315     },
316
317     onDragEnter: function(e, id) {
318     },
319
320     onDragOver: function(e, id) {
321     },
322
323     onDragOut: function(e, id) {
324     },
325
326     onDragDrop: function(e, id) {
327     },
328
329     endDrag: function(e) {
330     }
331
332     */
333
334 });
335 </pre>
336 </body>
337 </html>