Upgrade to ExtJS 3.0.0 - Released 07/06/2009
[extjs.git] / docs / source / SplitBar.html
diff --git a/docs/source/SplitBar.html b/docs/source/SplitBar.html
new file mode 100644 (file)
index 0000000..b0afb60
--- /dev/null
@@ -0,0 +1,440 @@
+<html>\r
+<head>\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"><div id="cls-Ext.SplitBar"></div>/**\r
+ * @class Ext.SplitBar\r
+ * @extends Ext.util.Observable\r
+ * Creates draggable splitter bar functionality from two elements (element to be dragged and element to be resized).\r
+ * <br><br>\r
+ * Usage:\r
+ * <pre><code>\r
+var split = new Ext.SplitBar("elementToDrag", "elementToSize",\r
+                   Ext.SplitBar.HORIZONTAL, Ext.SplitBar.LEFT);\r
+split.setAdapter(new Ext.SplitBar.AbsoluteLayoutAdapter("container"));\r
+split.minSize = 100;\r
+split.maxSize = 600;\r
+split.animate = true;\r
+split.on('moved', splitterMoved);\r
+</code></pre>\r
+ * @constructor\r
+ * Create a new SplitBar\r
+ * @param {Mixed} dragElement The element to be dragged and act as the SplitBar.\r
+ * @param {Mixed} resizingElement The element to be resized based on where the SplitBar element is dragged\r
+ * @param {Number} orientation (optional) Either Ext.SplitBar.HORIZONTAL or Ext.SplitBar.VERTICAL. (Defaults to HORIZONTAL)\r
+ * @param {Number} placement (optional) Either Ext.SplitBar.LEFT or Ext.SplitBar.RIGHT for horizontal or  \r
+                        Ext.SplitBar.TOP or Ext.SplitBar.BOTTOM for vertical. (By default, this is determined automatically by the initial\r
+                        position of the SplitBar).\r
+ */\r
+Ext.SplitBar = function(dragElement, resizingElement, orientation, placement, existingProxy){\r
+    \r
+    /** @private */\r
+    this.el = Ext.get(dragElement, true);\r
+    this.el.dom.unselectable = "on";\r
+    /** @private */\r
+    this.resizingEl = Ext.get(resizingElement, true);\r
+\r
+    /**\r
+     * @private\r
+     * The orientation of the split. Either Ext.SplitBar.HORIZONTAL or Ext.SplitBar.VERTICAL. (Defaults to HORIZONTAL)\r
+     * Note: If this is changed after creating the SplitBar, the placement property must be manually updated\r
+     * @type Number\r
+     */\r
+    this.orientation = orientation || Ext.SplitBar.HORIZONTAL;\r
+    \r
+    <div id="prop-Ext.SplitBar-tickSize"></div>/**\r
+     * The increment, in pixels by which to move this SplitBar. When <i>undefined</i>, the SplitBar moves smoothly.\r
+     * @type Number\r
+     * @property tickSize\r
+     */\r
+    <div id="prop-Ext.SplitBar-minSize"></div>/**\r
+     * The minimum size of the resizing element. (Defaults to 0)\r
+     * @type Number\r
+     */\r
+    this.minSize = 0;\r
+    \r
+    <div id="prop-Ext.SplitBar-maxSize"></div>/**\r
+     * The maximum size of the resizing element. (Defaults to 2000)\r
+     * @type Number\r
+     */\r
+    this.maxSize = 2000;\r
+    \r
+    <div id="prop-Ext.SplitBar-animate"></div>/**\r
+     * Whether to animate the transition to the new size\r
+     * @type Boolean\r
+     */\r
+    this.animate = false;\r
+    \r
+    <div id="prop-Ext.SplitBar-useShim"></div>/**\r
+     * Whether to create a transparent shim that overlays the page when dragging, enables dragging across iframes.\r
+     * @type Boolean\r
+     */\r
+    this.useShim = false;\r
+    \r
+    /** @private */\r
+    this.shim = null;\r
+    \r
+    if(!existingProxy){\r
+        /** @private */\r
+        this.proxy = Ext.SplitBar.createProxy(this.orientation);\r
+    }else{\r
+        this.proxy = Ext.get(existingProxy).dom;\r
+    }\r
+    /** @private */\r
+    this.dd = new Ext.dd.DDProxy(this.el.dom.id, "XSplitBars", {dragElId : this.proxy.id});\r
+    \r
+    /** @private */\r
+    this.dd.b4StartDrag = this.onStartProxyDrag.createDelegate(this);\r
+    \r
+    /** @private */\r
+    this.dd.endDrag = this.onEndProxyDrag.createDelegate(this);\r
+    \r
+    /** @private */\r
+    this.dragSpecs = {};\r
+    \r
+    /**\r
+     * @private The adapter to use to positon and resize elements\r
+     */\r
+    this.adapter = new Ext.SplitBar.BasicLayoutAdapter();\r
+    this.adapter.init(this);\r
+    \r
+    if(this.orientation == Ext.SplitBar.HORIZONTAL){\r
+        /** @private */\r
+        this.placement = placement || (this.el.getX() > this.resizingEl.getX() ? Ext.SplitBar.LEFT : Ext.SplitBar.RIGHT);\r
+        this.el.addClass("x-splitbar-h");\r
+    }else{\r
+        /** @private */\r
+        this.placement = placement || (this.el.getY() > this.resizingEl.getY() ? Ext.SplitBar.TOP : Ext.SplitBar.BOTTOM);\r
+        this.el.addClass("x-splitbar-v");\r
+    }\r
+    \r
+    this.addEvents(\r
+        <div id="event-Ext.SplitBar-resize"></div>/**\r
+         * @event resize\r
+         * Fires when the splitter is moved (alias for {@link #moved})\r
+         * @param {Ext.SplitBar} this\r
+         * @param {Number} newSize the new width or height\r
+         */\r
+        "resize",\r
+        <div id="event-Ext.SplitBar-moved"></div>/**\r
+         * @event moved\r
+         * Fires when the splitter is moved\r
+         * @param {Ext.SplitBar} this\r
+         * @param {Number} newSize the new width or height\r
+         */\r
+        "moved",\r
+        <div id="event-Ext.SplitBar-beforeresize"></div>/**\r
+         * @event beforeresize\r
+         * Fires before the splitter is dragged\r
+         * @param {Ext.SplitBar} this\r
+         */\r
+        "beforeresize",\r
+\r
+        "beforeapply"\r
+    );\r
+\r
+    Ext.SplitBar.superclass.constructor.call(this);\r
+};\r
+\r
+Ext.extend(Ext.SplitBar, Ext.util.Observable, {\r
+    onStartProxyDrag : function(x, y){\r
+        this.fireEvent("beforeresize", this);\r
+        this.overlay =  Ext.DomHelper.append(document.body,  {cls: "x-drag-overlay", html: "&#160;"}, true);\r
+        this.overlay.unselectable();\r
+        this.overlay.setSize(Ext.lib.Dom.getViewWidth(true), Ext.lib.Dom.getViewHeight(true));\r
+        this.overlay.show();\r
+        Ext.get(this.proxy).setDisplayed("block");\r
+        var size = this.adapter.getElementSize(this);\r
+        this.activeMinSize = this.getMinimumSize();\r
+        this.activeMaxSize = this.getMaximumSize();\r
+        var c1 = size - this.activeMinSize;\r
+        var c2 = Math.max(this.activeMaxSize - size, 0);\r
+        if(this.orientation == Ext.SplitBar.HORIZONTAL){\r
+            this.dd.resetConstraints();\r
+            this.dd.setXConstraint(\r
+                this.placement == Ext.SplitBar.LEFT ? c1 : c2, \r
+                this.placement == Ext.SplitBar.LEFT ? c2 : c1,\r
+                this.tickSize\r
+            );\r
+            this.dd.setYConstraint(0, 0);\r
+        }else{\r
+            this.dd.resetConstraints();\r
+            this.dd.setXConstraint(0, 0);\r
+            this.dd.setYConstraint(\r
+                this.placement == Ext.SplitBar.TOP ? c1 : c2, \r
+                this.placement == Ext.SplitBar.TOP ? c2 : c1,\r
+                this.tickSize\r
+            );\r
+         }\r
+        this.dragSpecs.startSize = size;\r
+        this.dragSpecs.startPoint = [x, y];\r
+        Ext.dd.DDProxy.prototype.b4StartDrag.call(this.dd, x, y);\r
+    },\r
+    \r
+    /** \r
+     * @private Called after the drag operation by the DDProxy\r
+     */\r
+    onEndProxyDrag : function(e){\r
+        Ext.get(this.proxy).setDisplayed(false);\r
+        var endPoint = Ext.lib.Event.getXY(e);\r
+        if(this.overlay){\r
+            Ext.destroy(this.overlay);\r
+            delete this.overlay;\r
+        }\r
+        var newSize;\r
+        if(this.orientation == Ext.SplitBar.HORIZONTAL){\r
+            newSize = this.dragSpecs.startSize + \r
+                (this.placement == Ext.SplitBar.LEFT ?\r
+                    endPoint[0] - this.dragSpecs.startPoint[0] :\r
+                    this.dragSpecs.startPoint[0] - endPoint[0]\r
+                );\r
+        }else{\r
+            newSize = this.dragSpecs.startSize + \r
+                (this.placement == Ext.SplitBar.TOP ?\r
+                    endPoint[1] - this.dragSpecs.startPoint[1] :\r
+                    this.dragSpecs.startPoint[1] - endPoint[1]\r
+                );\r
+        }\r
+        newSize = Math.min(Math.max(newSize, this.activeMinSize), this.activeMaxSize);\r
+        if(newSize != this.dragSpecs.startSize){\r
+            if(this.fireEvent('beforeapply', this, newSize) !== false){\r
+                this.adapter.setElementSize(this, newSize);\r
+                this.fireEvent("moved", this, newSize);\r
+                this.fireEvent("resize", this, newSize);\r
+            }\r
+        }\r
+    },\r
+    \r
+    <div id="method-Ext.SplitBar-getAdapter"></div>/**\r
+     * Get the adapter this SplitBar uses\r
+     * @return The adapter object\r
+     */\r
+    getAdapter : function(){\r
+        return this.adapter;\r
+    },\r
+    \r
+    <div id="method-Ext.SplitBar-setAdapter"></div>/**\r
+     * Set the adapter this SplitBar uses\r
+     * @param {Object} adapter A SplitBar adapter object\r
+     */\r
+    setAdapter : function(adapter){\r
+        this.adapter = adapter;\r
+        this.adapter.init(this);\r
+    },\r
+    \r
+    <div id="method-Ext.SplitBar-getMinimumSize"></div>/**\r
+     * Gets the minimum size for the resizing element\r
+     * @return {Number} The minimum size\r
+     */\r
+    getMinimumSize : function(){\r
+        return this.minSize;\r
+    },\r
+    \r
+    <div id="method-Ext.SplitBar-setMinimumSize"></div>/**\r
+     * Sets the minimum size for the resizing element\r
+     * @param {Number} minSize The minimum size\r
+     */\r
+    setMinimumSize : function(minSize){\r
+        this.minSize = minSize;\r
+    },\r
+    \r
+    <div id="method-Ext.SplitBar-getMaximumSize"></div>/**\r
+     * Gets the maximum size for the resizing element\r
+     * @return {Number} The maximum size\r
+     */\r
+    getMaximumSize : function(){\r
+        return this.maxSize;\r
+    },\r
+    \r
+    <div id="method-Ext.SplitBar-setMaximumSize"></div>/**\r
+     * Sets the maximum size for the resizing element\r
+     * @param {Number} maxSize The maximum size\r
+     */\r
+    setMaximumSize : function(maxSize){\r
+        this.maxSize = maxSize;\r
+    },\r
+    \r
+    <div id="method-Ext.SplitBar-setCurrentSize"></div>/**\r
+     * Sets the initialize size for the resizing element\r
+     * @param {Number} size The initial size\r
+     */\r
+    setCurrentSize : function(size){\r
+        var oldAnimate = this.animate;\r
+        this.animate = false;\r
+        this.adapter.setElementSize(this, size);\r
+        this.animate = oldAnimate;\r
+    },\r
+    \r
+    <div id="method-Ext.SplitBar-destroy"></div>/**\r
+     * Destroy this splitbar. \r
+     * @param {Boolean} removeEl True to remove the element\r
+     */\r
+    destroy : function(removeEl){\r
+               Ext.destroy(this.shim, Ext.get(this.proxy));\r
+        this.dd.unreg();\r
+        if(removeEl){\r
+            this.el.remove();\r
+        }\r
+               this.purgeListeners();\r
+    }\r
+});\r
+\r
+/**\r
+ * @private static Create our own proxy element element. So it will be the same same size on all browsers, we won't use borders. Instead we use a background color.\r
+ */\r
+Ext.SplitBar.createProxy = function(dir){\r
+    var proxy = new Ext.Element(document.createElement("div"));\r
+    proxy.unselectable();\r
+    var cls = 'x-splitbar-proxy';\r
+    proxy.addClass(cls + ' ' + (dir == Ext.SplitBar.HORIZONTAL ? cls +'-h' : cls + '-v'));\r
+    document.body.appendChild(proxy.dom);\r
+    return proxy.dom;\r
+};\r
+\r
+<div id="cls-Ext.SplitBar.BasicLayoutAdapter"></div>/** \r
+ * @class Ext.SplitBar.BasicLayoutAdapter\r
+ * Default Adapter. It assumes the splitter and resizing element are not positioned\r
+ * elements and only gets/sets the width of the element. Generally used for table based layouts.\r
+ */\r
+Ext.SplitBar.BasicLayoutAdapter = function(){\r
+};\r
+\r
+Ext.SplitBar.BasicLayoutAdapter.prototype = {\r
+    // do nothing for now\r
+    init : function(s){\r
+    \r
+    },\r
+    <div id="method-Ext.SplitBar.BasicLayoutAdapter-getElementSize"></div>/**\r
+     * Called before drag operations to get the current size of the resizing element. \r
+     * @param {Ext.SplitBar} s The SplitBar using this adapter\r
+     */\r
+     getElementSize : function(s){\r
+        if(s.orientation == Ext.SplitBar.HORIZONTAL){\r
+            return s.resizingEl.getWidth();\r
+        }else{\r
+            return s.resizingEl.getHeight();\r
+        }\r
+    },\r
+    \r
+    <div id="method-Ext.SplitBar.BasicLayoutAdapter-setElementSize"></div>/**\r
+     * Called after drag operations to set the size of the resizing element.\r
+     * @param {Ext.SplitBar} s The SplitBar using this adapter\r
+     * @param {Number} newSize The new size to set\r
+     * @param {Function} onComplete A function to be invoked when resizing is complete\r
+     */\r
+    setElementSize : function(s, newSize, onComplete){\r
+        if(s.orientation == Ext.SplitBar.HORIZONTAL){\r
+            if(!s.animate){\r
+                s.resizingEl.setWidth(newSize);\r
+                if(onComplete){\r
+                    onComplete(s, newSize);\r
+                }\r
+            }else{\r
+                s.resizingEl.setWidth(newSize, true, .1, onComplete, 'easeOut');\r
+            }\r
+        }else{\r
+            \r
+            if(!s.animate){\r
+                s.resizingEl.setHeight(newSize);\r
+                if(onComplete){\r
+                    onComplete(s, newSize);\r
+                }\r
+            }else{\r
+                s.resizingEl.setHeight(newSize, true, .1, onComplete, 'easeOut');\r
+            }\r
+        }\r
+    }\r
+};\r
+\r
+<div id="cls-Ext.SplitBar.AbsoluteLayoutAdapter"></div>/** \r
+ *@class Ext.SplitBar.AbsoluteLayoutAdapter\r
+ * @extends Ext.SplitBar.BasicLayoutAdapter\r
+ * Adapter that  moves the splitter element to align with the resized sizing element. \r
+ * Used with an absolute positioned SplitBar.\r
+ * @param {Mixed} container The container that wraps around the absolute positioned content. If it's\r
+ * document.body, make sure you assign an id to the body element.\r
+ */\r
+Ext.SplitBar.AbsoluteLayoutAdapter = function(container){\r
+    this.basic = new Ext.SplitBar.BasicLayoutAdapter();\r
+    this.container = Ext.get(container);\r
+};\r
+\r
+Ext.SplitBar.AbsoluteLayoutAdapter.prototype = {\r
+    init : function(s){\r
+        this.basic.init(s);\r
+    },\r
+    \r
+    getElementSize : function(s){\r
+        return this.basic.getElementSize(s);\r
+    },\r
+    \r
+    setElementSize : function(s, newSize, onComplete){\r
+        this.basic.setElementSize(s, newSize, this.moveSplitter.createDelegate(this, [s]));\r
+    },\r
+    \r
+    moveSplitter : function(s){\r
+        var yes = Ext.SplitBar;\r
+        switch(s.placement){\r
+            case yes.LEFT:\r
+                s.el.setX(s.resizingEl.getRight());\r
+                break;\r
+            case yes.RIGHT:\r
+                s.el.setStyle("right", (this.container.getWidth() - s.resizingEl.getLeft()) + "px");\r
+                break;\r
+            case yes.TOP:\r
+                s.el.setY(s.resizingEl.getBottom());\r
+                break;\r
+            case yes.BOTTOM:\r
+                s.el.setY(s.resizingEl.getTop() - s.el.getHeight());\r
+                break;\r
+        }\r
+    }\r
+};\r
+\r
+<div id="prop-Ext.SplitBar.AbsoluteLayoutAdapter-VERTICAL"></div>/**\r
+ * Orientation constant - Create a vertical SplitBar\r
+ * @static\r
+ * @type Number\r
+ */\r
+Ext.SplitBar.VERTICAL = 1;\r
+\r
+<div id="prop-Ext.SplitBar.AbsoluteLayoutAdapter-HORIZONTAL"></div>/**\r
+ * Orientation constant - Create a horizontal SplitBar\r
+ * @static\r
+ * @type Number\r
+ */\r
+Ext.SplitBar.HORIZONTAL = 2;\r
+\r
+<div id="prop-Ext.SplitBar.AbsoluteLayoutAdapter-LEFT"></div>/**\r
+ * Placement constant - The resizing element is to the left of the splitter element\r
+ * @static\r
+ * @type Number\r
+ */\r
+Ext.SplitBar.LEFT = 1;\r
+\r
+<div id="prop-Ext.SplitBar.AbsoluteLayoutAdapter-RIGHT"></div>/**\r
+ * Placement constant - The resizing element is to the right of the splitter element\r
+ * @static\r
+ * @type Number\r
+ */\r
+Ext.SplitBar.RIGHT = 2;\r
+\r
+<div id="prop-Ext.SplitBar.AbsoluteLayoutAdapter-TOP"></div>/**\r
+ * Placement constant - The resizing element is positioned above the splitter element\r
+ * @static\r
+ * @type Number\r
+ */\r
+Ext.SplitBar.TOP = 3;\r
+\r
+<div id="prop-Ext.SplitBar.AbsoluteLayoutAdapter-BOTTOM"></div>/**\r
+ * Placement constant - The resizing element is positioned under splitter element\r
+ * @static\r
+ * @type Number\r
+ */\r
+Ext.SplitBar.BOTTOM = 4;\r
+</pre>    \r
+</body>\r
+</html>
\ No newline at end of file