/**
+ * @class Ext.Element
*/
Ext.Element.addMethods({
- /**
- * Gets the x,y coordinates specified by the anchor position on the element.
- * @param {String} anchor (optional) The specified anchor position (defaults to "c"). See {@link #alignTo}
+ /**
+ * Gets the x,y coordinates specified by the anchor position on the element.
+ * @param {String} [anchor='c'] The specified anchor position. See {@link #alignTo}
* for details on supported anchor positions.
- * @param {Boolean} local (optional) True to get the local (element top/left-relative) anchor position instead
+ * @param {Boolean} [local] True to get the local (element top/left-relative) anchor position instead
* of page coordinates
- * @param {Object} size (optional) An object containing the size to use for calculating anchor position
+ * @param {Object} [size] An object containing the size to use for calculating anchor position
* {width: (target width), height: (target height)} (defaults to the element's current size)
- * @return {Array} [x, y] An array containing the element's x and y coordinates
+ * @return {Number[]} [x, y] An array containing the element's x and y coordinates
*/
getAnchorXY : function(anchor, local, s){
//Passing a different size is useful for pre-calculating anchors,
//especially for anchored animations that change the el size.
- anchor = (anchor || "tl").toLowerCase();
+ anchor = (anchor || "tl").toLowerCase();
s = s || {};
-
- var me = this,
- vp = me.dom == document.body || me.dom == document,
- w = s.width || vp ? Ext.lib.Dom.getViewWidth() : me.getWidth(),
- h = s.height || vp ? Ext.lib.Dom.getViewHeight() : me.getHeight(),
- xy,
- r = Math.round,
- o = me.getXY(),
- scroll = me.getScroll(),
- extraX = vp ? scroll.left : !local ? o[0] : 0,
- extraY = vp ? scroll.top : !local ? o[1] : 0,
- hash = {
- c : [r(w * 0.5), r(h * 0.5)],
- t : [r(w * 0.5), 0],
- l : [0, r(h * 0.5)],
- r : [w, r(h * 0.5)],
- b : [r(w * 0.5), h],
- tl : [0, 0],
- bl : [0, h],
- br : [w, h],
- tr : [w, 0]
- };
-
- xy = hash[anchor];
- return [xy[0] + extraX, xy[1] + extraY];
+
+ var me = this,
+ vp = me.dom == document.body || me.dom == document,
+ w = s.width || vp ? Ext.Element.getViewWidth() : me.getWidth(),
+ h = s.height || vp ? Ext.Element.getViewHeight() : me.getHeight(),
+ xy,
+ r = Math.round,
+ o = me.getXY(),
+ scroll = me.getScroll(),
+ extraX = vp ? scroll.left : !local ? o[0] : 0,
+ extraY = vp ? scroll.top : !local ? o[1] : 0,
+ hash = {
+ c : [r(w * 0.5), r(h * 0.5)],
+ t : [r(w * 0.5), 0],
+ l : [0, r(h * 0.5)],
+ r : [w, r(h * 0.5)],
+ b : [r(w * 0.5), h],
+ tl : [0, 0],
+ bl : [0, h],
+ br : [w, h],
+ tr : [w, 0]
+ };
+
+ xy = hash[anchor];
+ return [xy[0] + extraX, xy[1] + extraY];
},
- /**
- * Anchors an element to another element and realigns it when the window is resized.
- * @param {Mixed} element The element to align to.
+ /**
+ * Anchors an element to another element and realigns it when the window is resized.
+ * @param {String/HTMLElement/Ext.Element} element The element to align to.
* @param {String} position The position to align to.
- * @param {Array} offsets (optional) Offset the positioning by [x, y]
- * @param {Boolean/Object} animate (optional) True for the default animation or a standard Element animation config object
- * @param {Boolean/Number} monitorScroll (optional) True to monitor body scroll and reposition. If this parameter
+ * @param {Number[]} [offsets] Offset the positioning by [x, y]
+ * @param {Boolean/Object} [animate] True for the default animation or a standard Element animation config object
+ * @param {Boolean/Number} [monitorScroll] True to monitor body scroll and reposition. If this parameter
* is a number, it is used as the buffer delay (defaults to 50ms).
- * @param {Function} callback The function to call after the animation finishes
+ * @param {Function} [callback] The function to call after the animation finishes
* @return {Ext.Element} this
*/
- anchorTo : function(el, alignment, offsets, animate, monitorScroll, callback){
- var me = this,
+ anchorTo : function(el, alignment, offsets, animate, monitorScroll, callback){
+ var me = this,
dom = me.dom,
scroll = !Ext.isEmpty(monitorScroll),
action = function(){
@@ -78,7 +81,7 @@ Ext.Element.addMethods({
Ext.callback(callback, Ext.fly(dom));
},
anchor = this.getAnchor();
-
+
// previous listener anchor, remove it
this.removeAnchor();
Ext.apply(anchor, {
@@ -87,7 +90,7 @@ Ext.Element.addMethods({
});
Ext.EventManager.onWindowResize(action, null);
-
+
if(scroll){
Ext.EventManager.on(window, 'scroll', action, null,
{buffer: !isNaN(monitorScroll) ? monitorScroll : 50});
@@ -95,16 +98,16 @@ Ext.Element.addMethods({
action.call(me); // align immediately
return me;
},
-
- /**
- * Remove any anchor to this element. See {@link #anchorTo}.
+
+ /**
+ * Remove any anchor to this element. See {@link #anchorTo}.
* @return {Ext.Element} this
*/
removeAnchor : function(){
var me = this,
anchor = this.getAnchor();
-
- if(anchor && anchor.fn){
+
+ if(anchor && anchor.fn){
Ext.EventManager.removeResizeListener(anchor.fn);
if(anchor.scroll){
Ext.EventManager.un(window, 'scroll', anchor.fn);
@@ -113,7 +116,7 @@ Ext.Element.addMethods({
}
return me;
},
-
+
// private
getAnchor : function(){
var data = Ext.Element.data,
@@ -122,65 +125,100 @@ Ext.Element.addMethods({
return;
}
var anchor = data(dom, '_anchor');
-
+
if(!anchor){
anchor = data(dom, '_anchor', {});
}
return anchor;
},
- /**
- * Gets the x,y coordinates to align this element with another element. See {@link #alignTo} for more info on the
+ getAlignVector: function(el, spec, offset) {
+ var me = this,
+ side = {t:"top", l:"left", r:"right", b: "bottom"},
+ thisRegion = me.getRegion(),
+ elRegion;
+
+ el = Ext.get(el);
+ if(!el || !el.dom){
+ //<debug>
+ Ext.Error.raise({
+ sourceClass: 'Ext.Element',
+ sourceMethod: 'getAlignVector',
+ msg: 'Attempted to align an element that doesn\'t exist'
+ });
+ //</debug>
+ }
+
+ elRegion = el.getRegion();
+ },
+
+ /**
+ * Gets the x,y coordinates to align this element with another element. See {@link #alignTo} for more info on the
* supported position values.
- * @param {Mixed} element The element to align to.
- * @param {String} position (optional, defaults to "tl-bl?") The position to align to.
- * @param {Array} offsets (optional) Offset the positioning by [x, y]
- * @return {Array} [x, y]
+ * @param {String/HTMLElement/Ext.Element} element The element to align to.
+ * @param {String} [position="tl-bl?"] The position to align to (defaults to )
+ * @param {Number[]} [offsets] Offset the positioning by [x, y]
+ * @return {Number[]} [x, y]
*/
- getAlignToXY : function(el, p, o){
+ getAlignToXY : function(el, p, o){
el = Ext.get(el);
-
+
if(!el || !el.dom){
- throw "Element.alignToXY with an element that doesn't exist";
+ //<debug>
+ Ext.Error.raise({
+ sourceClass: 'Ext.Element',
+ sourceMethod: 'getAlignToXY',
+ msg: 'Attempted to align an element that doesn\'t exist'
+ });
+ //</debug>
}
-
+
o = o || [0,0];
- p = (!p || p == "?" ? "tl-bl?" : (!/-/.test(p) && p !== "" ? "tl-" + p : p || "tl-bl")).toLowerCase();
-
+ p = (!p || p == "?" ? "tl-bl?" : (!(/-/).test(p) && p !== "" ? "tl-" + p : p || "tl-bl")).toLowerCase();
+
var me = this,
- d = me.dom,
- a1,
- a2,
- x,
- y,
- //constrain the aligned el to viewport if necessary
- w,
- h,
- r,
- dw = Ext.lib.Dom.getViewWidth() -10, // 10px of margin for ie
- dh = Ext.lib.Dom.getViewHeight()-10, // 10px of margin for ie
- p1y,
- p1x,
- p2y,
- p2x,
- swapY,
- swapX,
- doc = document,
- docElement = doc.documentElement,
- docBody = doc.body,
- scrollX = (docElement.scrollLeft || docBody.scrollLeft || 0)+5,
- scrollY = (docElement.scrollTop || docBody.scrollTop || 0)+5,
- c = false, //constrain to viewport
- p1 = "",
- p2 = "",
- m = p.match(/^([a-z]+)-([a-z]+)(\?)?$/);
-
+ d = me.dom,
+ a1,
+ a2,
+ x,
+ y,
+ //constrain the aligned el to viewport if necessary
+ w,
+ h,
+ r,
+ dw = Ext.Element.getViewWidth() -10, // 10px of margin for ie
+ dh = Ext.Element.getViewHeight()-10, // 10px of margin for ie
+ p1y,
+ p1x,
+ p2y,
+ p2x,
+ swapY,
+ swapX,
+ doc = document,
+ docElement = doc.documentElement,
+ docBody = doc.body,
+ scrollX = (docElement.scrollLeft || docBody.scrollLeft || 0)+5,
+ scrollY = (docElement.scrollTop || docBody.scrollTop || 0)+5,
+ c = false, //constrain to viewport
+ p1 = "",
+ p2 = "",
+ m = p.match(/^([a-z]+)-([a-z]+)(\?)?$/);
+
if(!m){
- throw "Element.alignTo with an invalid alignment " + p;
+ //<debug>
+ Ext.Error.raise({
+ sourceClass: 'Ext.Element',
+ sourceMethod: 'getAlignToXY',
+ el: el,
+ position: p,
+ offset: o,
+ msg: 'Attemmpted to align an element with an invalid position: "' + p + '"'
+ });
+ //</debug>
}
-
- p1 = m[1];
- p2 = m[2];
+
+ p1 = m[1];
+ p2 = m[2];
c = !!m[3];
//Subtract the aligned el's internal xy from the target's offset xy
@@ -191,10 +229,10 @@ Ext.Element.addMethods({
x = a2[0] - a1[0] + o[0];
y = a2[1] - a1[1] + o[1];
- if(c){
- w = me.getWidth();
+ if(c){
+ w = me.getWidth();
h = me.getHeight();
- r = el.getRegion();
+ r = el.getRegion();
//If we are at a viewport boundary and the aligned el is anchored on a target border that is
//perpendicular to the vp border, allow the aligned el to slide on that border,
//otherwise swap the aligned el to the opposite border of the target.
@@ -202,44 +240,44 @@ Ext.Element.addMethods({
p1x = p1.charAt(p1.length-1);
p2y = p2.charAt(0);
p2x = p2.charAt(p2.length-1);
- swapY = ((p1y=="t" && p2y=="b") || (p1y=="b" && p2y=="t"));
- swapX = ((p1x=="r" && p2x=="l") || (p1x=="l" && p2x=="r"));
-
+ swapY = ((p1y=="t" && p2y=="b") || (p1y=="b" && p2y=="t"));
+ swapX = ((p1x=="r" && p2x=="l") || (p1x=="l" && p2x=="r"));
+
- if (x + w > dw + scrollX) {
+ if (x + w > dw + scrollX) {
x = swapX ? r.left-w : dw+scrollX-w;
}
- if (x < scrollX) {
+ if (x < scrollX) {
x = swapX ? r.right : scrollX;
}
- if (y + h > dh + scrollY) {
+ if (y + h > dh + scrollY) {
y = swapY ? r.top-h : dh+scrollY-h;
}
- if (y < scrollY){
+ if (y < scrollY){
y = swapY ? r.bottom : scrollY;
}
}
return [x,y];
},
- /**
- * Aligns this element with another element relative to the specified anchor points. If the other element is the
+ /**
+ * Aligns this element with another element relative to the specified anchor points. If the other element is the
* document it aligns it to the viewport.
* The position parameter is optional, and can be specified in any one of the following formats:
- *
- *
Blank: Defaults to aligning the element's top-left corner to the target's bottom-left corner ("tl-bl").
- *
One anchor (deprecated): The passed anchor position is used as the target element's anchor point.
- * The element being aligned will position its top-left corner (tl) to that point. This method has been
- * deprecated in favor of the newer two anchor syntax below.
- *
Two anchors: If two values from the table below are passed separated by a dash, the first value is used as the
- * element's anchor point, and the second value is used as the target's anchor point.
- *
- * In addition to the anchor points, the position parameter also supports the "?" character. If "?" is passed at the end of
+ * <ul>
+ * <li><b>Blank</b>: Defaults to aligning the element's top-left corner to the target's bottom-left corner ("tl-bl").</li>
+ * <li><b>One anchor (deprecated)</b>: The passed anchor position is used as the target element's anchor point.
+ * The element being aligned will position its top-left corner (tl) to that point. <i>This method has been
+ * deprecated in favor of the newer two anchor syntax below</i>.</li>
+ * <li><b>Two anchors</b>: If two values from the table below are passed separated by a dash, the first value is used as the
+ * element's anchor point, and the second value is used as the target's anchor point.</li>
+ * </ul>
+ * In addition to the anchor points, the position parameter also supports the "?" character. If "?" is passed at the end of
* the position string, the element will attempt to align as specified, but the position will be adjusted to constrain to
* the viewport if necessary. Note that the element being aligned might be swapped to align to a different position than
* that specified in order to enforce the viewport constraints.
* Following are all of the supported anchor positions:
-
+<pre>
Value Description
----- -----------------------------
tl The top left corner (default)
@@ -251,172 +289,114 @@ r The center of the right edge
bl The bottom left corner
b The center of the bottom edge
br The bottom right corner
-
+</pre>
Example Usage:
-
-// align el to other-el using the default positioning ("tl-bl", non-constrained)
-el.alignTo("other-el");
+<pre><code>
+// align el to other-el using the default positioning ("tl-bl", non-constrained)
+el.alignTo("other-el");
// align the top left corner of el with the top right corner of other-el (constrained to viewport)
-el.alignTo("other-el", "tr?");
+el.alignTo("other-el", "tr?");
// align the bottom right corner of el with the center left edge of other-el
-el.alignTo("other-el", "br-l?");
+el.alignTo("other-el", "br-l?");
// align the center of el with the bottom left corner of other-el and
// adjust the x position by -6 pixels (and the y position by 0)
-el.alignTo("other-el", "c-bl", [-6, 0]);
-
- * @param {Mixed} element The element to align to.
- * @param {String} position (optional, defaults to "tl-bl?") The position to align to.
- * @param {Array} offsets (optional) Offset the positioning by [x, y]
- * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
+el.alignTo("other-el", "c-bl", [-6, 0]);
+</code></pre>
+ * @param {String/HTMLElement/Ext.Element} element The element to align to.
+ * @param {String} [position="tl-bl?"] The position to align to
+ * @param {Number[]} [offsets] Offset the positioning by [x, y]
+ * @param {Boolean/Object} [animate] true for the default animation or a standard Element animation config object
* @return {Ext.Element} this
*/
alignTo : function(element, position, offsets, animate){
- var me = this;
+ var me = this;
return me.setXY(me.getAlignToXY(element, position, offsets),
- me.preanim && !!animate ? me.preanim(arguments, 3) : false);
+ me.anim && !!animate ? me.anim(animate) : false);
},
-
- // private ==> used outside of core
- adjustForConstraints : function(xy, parent, offsets){
- return this.getConstrainToXY(parent || document, false, offsets, xy) || xy;
- },
-
- // private ==> used outside of core
- getConstrainToXY : function(el, local, offsets, proposedXY){
- var os = {top:0, left:0, bottom:0, right: 0};
-
- return function(el, local, offsets, proposedXY){
- el = Ext.get(el);
- offsets = offsets ? Ext.applyIf(offsets, os) : os;
-
- var vw, vh, vx = 0, vy = 0;
- if(el.dom == document.body || el.dom == document){
- vw =Ext.lib.Dom.getViewWidth();
- vh = Ext.lib.Dom.getViewHeight();
- }else{
- vw = el.dom.clientWidth;
- vh = el.dom.clientHeight;
- if(!local){
- var vxy = el.getXY();
- vx = vxy[0];
- vy = vxy[1];
- }
- }
- var s = el.getScroll();
+ // private ==> used outside of core
+ adjustForConstraints : function(xy, parent) {
+ var vector = this.getConstrainVector(parent, xy);
+ if (vector) {
+ xy[0] += vector[0];
+ xy[1] += vector[1];
+ }
+ return xy;
+ },
- vx += offsets.left + s.left;
- vy += offsets.top + s.top;
+ /**
+ * <p>Returns the <code>[X, Y]</code> vector by which this element must be translated to make a best attempt
+ * to constrain within the passed constraint. Returns <code>false</code> is this element does not need to be moved.</p>
+ * <p>Priority is given to constraining the top and left within the constraint.</p>
+ * <p>The constraint may either be an existing element into which this element is to be constrained, or
+ * an {@link Ext.util.Region Region} into which this element is to be constrained.</p>
+ * @param constrainTo {Mixed} The Element or {@link Ext.util.Region Region} into which this element is to be constrained.
+ * @param proposedPosition {Array} A proposed <code>[X, Y]</code> position to test for validity and to produce a vector for instead
+ * of using this Element's current position;
+ * @returns {Number[]/Boolean} <b>If</b> this element <i>needs</i> to be translated, an <code>[X, Y]</code>
+ * vector by which this element must be translated. Otherwise, <code>false</code>.
+ */
+ getConstrainVector: function(constrainTo, proposedPosition) {
+ if (!(constrainTo instanceof Ext.util.Region)) {
+ constrainTo = Ext.get(constrainTo).getViewRegion();
+ }
+ var thisRegion = this.getRegion(),
+ vector = [0, 0],
+ shadowSize = this.shadow && this.shadow.offset,
+ overflowed = false;
- vw -= offsets.right;
- vh -= offsets.bottom;
+ // Shift this region to occupy the proposed position
+ if (proposedPosition) {
+ thisRegion.translateBy(proposedPosition[0] - thisRegion.x, proposedPosition[1] - thisRegion.y);
+ }
- var vr = vx+vw;
- var vb = vy+vh;
+ // Reduce the constrain region to allow for shadow
+ // TODO: Rewrite the Shadow class. When that's done, get the extra for each side from the Shadow.
+ if (shadowSize) {
+ constrainTo.adjust(0, -shadowSize, -shadowSize, shadowSize);
+ }
- var xy = proposedXY || (!local ? this.getXY() : [this.getLeft(true), this.getTop(true)]);
- var x = xy[0], y = xy[1];
- var w = this.dom.offsetWidth, h = this.dom.offsetHeight;
+ // Constrain the X coordinate by however much this Element overflows
+ if (thisRegion.right > constrainTo.right) {
+ overflowed = true;
+ vector[0] = (constrainTo.right - thisRegion.right); // overflowed the right
+ }
+ if (thisRegion.left + vector[0] < constrainTo.left) {
+ overflowed = true;
+ vector[0] = (constrainTo.left - thisRegion.left); // overflowed the left
+ }
- // only move it if it needs it
- var moved = false;
+ // Constrain the Y coordinate by however much this Element overflows
+ if (thisRegion.bottom > constrainTo.bottom) {
+ overflowed = true;
+ vector[1] = (constrainTo.bottom - thisRegion.bottom); // overflowed the bottom
+ }
+ if (thisRegion.top + vector[1] < constrainTo.top) {
+ overflowed = true;
+ vector[1] = (constrainTo.top - thisRegion.top); // overflowed the top
+ }
+ return overflowed ? vector : false;
+ },
- // first validate right/bottom
- if((x + w) > vr){
- x = vr - w;
- moved = true;
- }
- if((y + h) > vb){
- y = vb - h;
- moved = true;
- }
- // then make sure top/left isn't negative
- if(x < vx){
- x = vx;
- moved = true;
- }
- if(y < vy){
- y = vy;
- moved = true;
- }
- return moved ? [x, y] : false;
- };
- }(),
-
-
-
-// el = Ext.get(el);
-// offsets = Ext.applyIf(offsets || {}, {top : 0, left : 0, bottom : 0, right : 0});
-
-// var me = this,
-// doc = document,
-// s = el.getScroll(),
-// vxy = el.getXY(),
-// vx = offsets.left + s.left,
-// vy = offsets.top + s.top,
-// vw = -offsets.right,
-// vh = -offsets.bottom,
-// vr,
-// vb,
-// xy = proposedXY || (!local ? me.getXY() : [me.getLeft(true), me.getTop(true)]),
-// x = xy[0],
-// y = xy[1],
-// w = me.dom.offsetWidth, h = me.dom.offsetHeight,
-// moved = false; // only move it if it needs it
-//
-//
-// if(el.dom == doc.body || el.dom == doc){
-// vw += Ext.lib.Dom.getViewWidth();
-// vh += Ext.lib.Dom.getViewHeight();
-// }else{
-// vw += el.dom.clientWidth;
-// vh += el.dom.clientHeight;
-// if(!local){
-// vx += vxy[0];
-// vy += vxy[1];
-// }
-// }
-
-// // first validate right/bottom
-// if(x + w > vx + vw){
-// x = vx + vw - w;
-// moved = true;
-// }
-// if(y + h > vy + vh){
-// y = vy + vh - h;
-// moved = true;
-// }
-// // then make sure top/left isn't negative
-// if(x < vx){
-// x = vx;
-// moved = true;
-// }
-// if(y < vy){
-// y = vy;
-// moved = true;
-// }
-// return moved ? [x, y] : false;
-// },
-
- /**
- * Calculates the x, y to center this element on the screen
- * @return {Array} The x, y values [x, y]
+ /**
+ * Calculates the x, y to center this element on the screen
+ * @return {Number[]} The x, y values [x, y]
*/
getCenterXY : function(){
return this.getAlignToXY(document, 'c-c');
},
- /**
- * Centers the Element in either the viewport, or another Element.
- * @param {Mixed} centerIn (optional) The element in which to center the element.
+ /**
+ * Centers the Element in either the viewport, or another Element.
+ * @param {String/HTMLElement/Ext.Element} centerIn (optional) The element in which to center the element.
*/
center : function(centerIn){
- return this.alignTo(centerIn || document, 'c-c');
- }
+ return this.alignTo(centerIn || document, 'c-c');
+ }
});
-
+
-
\ No newline at end of file
+