Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Element.scroll.html
index adb7a04..3ae6341 100644 (file)
-<html>\r
-<head>\r
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js">/**\r
- * @class Ext.Element\r
- */\r
-Ext.Element.addMethods({\r
-    <div id="method-Ext.Element-isScrollable"></div>/**\r
-     * Returns true if this element is scrollable.\r
-     * @return {Boolean}\r
-     */\r
-    isScrollable : function(){\r
-        var dom = this.dom;\r
-        return dom.scrollHeight > dom.clientHeight || dom.scrollWidth > dom.clientWidth;\r
-    },\r
-\r
-    <div id="method-Ext.Element-scrollTo"></div>/**\r
-     * Scrolls this element the specified scroll point. It does NOT do bounds checking so if you scroll to a weird value it will try to do it. For auto bounds checking, use scroll().\r
-     * @param {String} side Either "left" for scrollLeft values or "top" for scrollTop values.\r
-     * @param {Number} value The new scroll value.\r
-     * @return {Element} this\r
-     */\r
-    scrollTo : function(side, value){\r
-        this.dom["scroll" + (/top/i.test(side) ? "Top" : "Left")] = value;\r
-        return this;\r
-    },\r
-\r
-    <div id="method-Ext.Element-getScroll"></div>/**\r
-     * Returns the current scroll position of the element.\r
-     * @return {Object} An object containing the scroll position in the format {left: (scrollLeft), top: (scrollTop)}\r
-     */\r
-    getScroll : function(){\r
-        var d = this.dom, \r
-            doc = document,\r
-            body = doc.body,\r
-            docElement = doc.documentElement,\r
-            l,\r
-            t,\r
-            ret;\r
-\r
-        if(d == doc || d == body){\r
-            if(Ext.isIE && Ext.isStrict){\r
-                l = docElement.scrollLeft; \r
-                t = docElement.scrollTop;\r
-            }else{\r
-                l = window.pageXOffset;\r
-                t = window.pageYOffset;\r
-            }\r
-            ret = {left: l || (body ? body.scrollLeft : 0), top: t || (body ? body.scrollTop : 0)};\r
-        }else{\r
-            ret = {left: d.scrollLeft, top: d.scrollTop};\r
-        }\r
-        return ret;\r
-    }\r
-});</pre>    \r
-</body>\r
-</html>
\ No newline at end of file
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-Element'>/**
+</span> * @class Ext.Element
+ */
+Ext.override(Ext.Element, {
+<span id='Ext-Element-method-isScrollable'>    /**
+</span>     * Returns true if this element is scrollable.
+     * @return {Boolean}
+     */
+    isScrollable : function(){
+        var dom = this.dom;
+        return dom.scrollHeight &gt; dom.clientHeight || dom.scrollWidth &gt; dom.clientWidth;
+    },
+
+<span id='Ext-Element-method-getScroll'>    /**
+</span>     * Returns the current scroll position of the element.
+     * @return {Object} An object containing the scroll position in the format {left: (scrollLeft), top: (scrollTop)}
+     */
+    getScroll : function() {
+        var d = this.dom, 
+            doc = document,
+            body = doc.body,
+            docElement = doc.documentElement,
+            l,
+            t,
+            ret;
+
+        if (d == doc || d == body) {
+            if (Ext.isIE &amp;&amp; Ext.isStrict) {
+                l = docElement.scrollLeft; 
+                t = docElement.scrollTop;
+            } else {
+                l = window.pageXOffset;
+                t = window.pageYOffset;
+            }
+            ret = {
+                left: l || (body ? body.scrollLeft : 0), 
+                top : t || (body ? body.scrollTop : 0)
+            };
+        } else {
+            ret = {
+                left: d.scrollLeft, 
+                top : d.scrollTop
+            };
+        }
+        
+        return ret;
+    },
+    
+<span id='Ext-Element-method-scrollTo'>    /**
+</span>     * Scrolls this element the specified scroll point. It does NOT do bounds checking so if you scroll to a weird value it will try to do it. For auto bounds checking, use scroll().
+     * @param {String} side Either &quot;left&quot; for scrollLeft values or &quot;top&quot; for scrollTop values.
+     * @param {Number} value The new scroll value
+     * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
+     * @return {Ext.Element} this
+     */
+    scrollTo : function(side, value, animate) {
+        //check if we're scrolling top or left
+        var top = /top/i.test(side),
+            me = this,
+            dom = me.dom,
+            obj = {},
+            prop;
+        if (!animate || !me.anim) {
+            // just setting the value, so grab the direction
+            prop = 'scroll' + (top ? 'Top' : 'Left');
+            dom[prop] = value;
+        }
+        else {
+            if (!Ext.isObject(animate)) {
+                animate = {};
+            }
+            obj['scroll' + (top ? 'Top' : 'Left')] = value;
+            me.animate(Ext.applyIf({
+                to: obj
+            }, animate));
+        }
+        return me;
+    },
+
+<span id='Ext-Element-method-scrollIntoView'>    /**
+</span>     * Scrolls this element into view within the passed container.
+     * @param {String/HTMLElement/Ext.Element} container (optional) The container element to scroll (defaults to document.body).  Should be a
+     * string (id), dom node, or Ext.Element.
+     * @param {Boolean} hscroll (optional) False to disable horizontal scroll (defaults to true)
+     * @return {Ext.Element} this
+     */
+    scrollIntoView : function(container, hscroll) {
+        container = Ext.getDom(container) || Ext.getBody().dom;
+        var el = this.dom,
+            offsets = this.getOffsetsTo(container),
+            // el's box
+            left = offsets[0] + container.scrollLeft,
+            top = offsets[1] + container.scrollTop,
+            bottom = top + el.offsetHeight,
+            right = left + el.offsetWidth,
+            // ct's box
+            ctClientHeight = container.clientHeight,
+            ctScrollTop = parseInt(container.scrollTop, 10),
+            ctScrollLeft = parseInt(container.scrollLeft, 10),
+            ctBottom = ctScrollTop + ctClientHeight,
+            ctRight = ctScrollLeft + container.clientWidth;
+
+        if (el.offsetHeight &gt; ctClientHeight || top &lt; ctScrollTop) {
+            container.scrollTop = top;
+        } else if (bottom &gt; ctBottom) {
+            container.scrollTop = bottom - ctClientHeight;
+        }
+        // corrects IE, other browsers will ignore
+        container.scrollTop = container.scrollTop;
+
+        if (hscroll !== false) {
+            if (el.offsetWidth &gt; container.clientWidth || left &lt; ctScrollLeft) {
+                container.scrollLeft = left;
+            }
+            else if (right &gt; ctRight) {
+                container.scrollLeft = right - container.clientWidth;
+            }
+            container.scrollLeft = container.scrollLeft;
+        }
+        return this;
+    },
+
+    // private
+    scrollChildIntoView : function(child, hscroll) {
+        Ext.fly(child, '_scrollChildIntoView').scrollIntoView(this, hscroll);
+    },
+
+<span id='Ext-Element-method-scroll'>    /**
+</span>     * Scrolls this element the specified direction. Does bounds checking to make sure the scroll is
+     * within this element's scrollable range.
+     * @param {String} direction Possible values are: &quot;l&quot; (or &quot;left&quot;), &quot;r&quot; (or &quot;right&quot;), &quot;t&quot; (or &quot;top&quot;, or &quot;up&quot;), &quot;b&quot; (or &quot;bottom&quot;, or &quot;down&quot;).
+     * @param {Number} distance How far to scroll the element in pixels
+     * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
+     * @return {Boolean} Returns true if a scroll was triggered or false if the element
+     * was scrolled as far as it could go.
+     */
+     scroll : function(direction, distance, animate) {
+        if (!this.isScrollable()) {
+            return false;
+        }
+        var el = this.dom,
+            l = el.scrollLeft, t = el.scrollTop,
+            w = el.scrollWidth, h = el.scrollHeight,
+            cw = el.clientWidth, ch = el.clientHeight,
+            scrolled = false, v,
+            hash = {
+                l: Math.min(l + distance, w-cw),
+                r: v = Math.max(l - distance, 0),
+                t: Math.max(t - distance, 0),
+                b: Math.min(t + distance, h-ch)
+            };
+            hash.d = hash.b;
+            hash.u = hash.t;
+
+        direction = direction.substr(0, 1);
+        if ((v = hash[direction]) &gt; -1) {
+            scrolled = true;
+            this.scrollTo(direction == 'l' || direction == 'r' ? 'left' : 'top', v, this.anim(animate));
+        }
+        return scrolled;
+    }
+});</pre>
+</body>
+</html>