Element/Element.Dimensions.js

   1 /*
   2 Script: Element.Dimensions.js
   3         Contains Element prototypes to deal with Element size and position in space.
   4
   5 Note:
   6         The functions in this script require n XHTML doctype.
   7
   8 License:
   9         MIT-style license.
  10 */
  11
  12 /*
  13 Class: Element
  14         Custom class to allow all of its methods to be used with any DOM element via the dollar function <$>.
  15 */
  16
  17 Element.extend({
  18
  19         /*
  20         Property: scrollTo
  21                 Scrolls the element to the specified coordinated (if the element has an overflow)
  22
  23         Arguments:
  24                 x - the x coordinate
  25                 y - the y coordinate
  26
  27         Example:
  28                 >$('myElement').scrollTo(0, 100)
  29         */
  30
  31         scrollTo: function(x, y){
  32                 this.scrollLeft = x;
  33                 this.scrollTop = y;
  34         },
  35
  36         /*
  37         Property: getSize
  38                 Return an Object representing the size/scroll values of the element.
  39
  40         Example:
  41                 (start code)
  42                 $('myElement').getSize();
  43                 (end)
  44
  45         Returns:
  46                 (start code)
  47                 {
  48                         'scroll': {'x': 100, 'y': 100},
  49                         'size': {'x': 200, 'y': 400},
  50                         'scrollSize': {'x': 300, 'y': 500}
  51                 }
  52                 (end)
  53         */
  54
  55         getSize: function(){
  56                 return {
  57                         'scroll': {'x': this.scrollLeft, 'y': this.scrollTop},
  58                         'size': {'x': this.offsetWidth, 'y': this.offsetHeight},
  59                         'scrollSize': {'x': this.scrollWidth, 'y': this.scrollHeight}
  60                 };
  61         },
  62
  63         /*
  64         Property: getPosition
  65                 Returns the real offsets of the element.
  66
  67         Arguments:
  68                 overflown - optional, an array of nested scrolling containers for scroll offset calculation, use this if your element is inside any element containing scrollbars
  69
  70         Example:
  71                 >$('element').getPosition();
  72
  73         Returns:
  74                 >{x: 100, y:500};
  75         */
  76
  77         getPosition: function(overflown){
  78                 overflown = overflown || [];
  79                 var el = this, left = 0, top = 0;
  80                 do {
  81                         left += el.offsetLeft || 0;
  82                         top += el.offsetTop || 0;
  83                         el = el.offsetParent;
  84                 } while (el);
  85                 overflown.each(function(element){
  86                         left -= element.scrollLeft || 0;
  87                         top -= element.scrollTop || 0;
  88                 });
  89                 return {'x': left, 'y': top};
  90         },
  91
  92         /*
  93         Property: getTop
  94                 Returns the distance from the top of the window to the Element.
  95
  96         Arguments:
  97                 overflown - optional, an array of nested scrolling containers, see Element::getPosition
  98         */
  99
 100         getTop: function(overflown){
 101                 return this.getPosition(overflown).y;
 102         },
 103
 104         /*
 105         Property: getLeft
 106                 Returns the distance from the left of the window to the Element.
 107
 108         Arguments:
 109                 overflown - optional, an array of nested scrolling containers, see Element::getPosition
 110         */
 111
 112         getLeft: function(overflown){
 113                 return this.getPosition(overflown).x;
 114         },
 115
 116         /*
 117         Property: getCoordinates
 118                 Returns an object with width, height, left, right, top, and bottom, representing the values of the Element
 119
 120         Arguments:
 121                 overflown - optional, an array of nested scrolling containers, see Element::getPosition
 122
 123         Example:
 124                 (start code)
 125                 var myValues = $('myElement').getCoordinates();
 126                 (end)
 127
 128         Returns:
 129                 (start code)
 130                 {
 131                         width: 200,
 132                         height: 300,
 133                         left: 100,
 134                         top: 50,
 135                         right: 300,
 136                         bottom: 350
 137                 }
 138                 (end)
 139         */
 140
 141         getCoordinates: function(overflown){
 142                 var position = this.getPosition(overflown);
 143                 var obj = {
 144                         'width': this.offsetWidth,
 145                         'height': this.offsetHeight,
 146                         'left': position.x,
 147                         'top': position.y
 148                 };
 149                 obj.right = obj.left + obj.width;
 150                 obj.bottom = obj.top + obj.height;
 151                 return obj;
 152         }
 153
 154 });