src/dimensions/dimensions.js

   1 /**
   2  * This plugin overrides jQuery's height() and width() functions and
   3  * adds more handy stuff for cross-browser compatibility.
   4  */
   5
   6 /**
   7  * Returns the css height value for the first matched element.
   8  * If used on document, returns the document's height (innerHeight)
   9  * If used on window, returns the viewport's (window) height
  10  *
  11  * @example $("#testdiv").height()
  12  * @result "200px"
  13  *
  14  * @example $(document).height();
  15  * @result 800
  16  *
  17  * @example $(window).height();
  18  * @result 400
  19  *
  20  * @name height
  21  * @type Object
  22  * @cat Dimensions
  23  */
  24 jQuery.fn.height = function() {
  25         if ( this.get(0) == window )
  26                 return self.innerHeight ||
  27                         jQuery.boxModel && document.documentElement.clientHeight ||
  28                         document.body.clientHeight;
  29
  30         if ( this.get(0) == document )
  31                 return Math.max( document.body.scrollHeight, document.body.offsetHeight );
  32
  33         return this.css("height");
  34 };
  35
  36 /**
  37  * Returns the css width value for the first matched element.
  38  * If used on document, returns the document's width (innerWidth)
  39  * If used on window, returns the viewport's (window) width
  40  *
  41  * @example $("#testdiv").width()
  42  * @result "200px"
  43  *
  44  * @example $(document).width();
  45  * @result 800
  46  *
  47  * @example $(window).width();
  48  * @result 400
  49  *
  50  * @name width
  51  * @type Object
  52  * @cat Dimensions
  53  */
  54 jQuery.fn.width = function() {
  55         if ( this.get(0) == window )
  56                 return self.innerWidth ||
  57                         jQuery.boxModel && document.documentElement.clientWidth ||
  58                         document.body.clientWidth;
  59
  60         if ( this.get(0) == document )
  61                 return Math.max( document.body.scrollWidth, document.body.offsetWidth );
  62
  63         return this.css("width");
  64 };
  65
  66 /**
  67  * Returns the inner height value (without border) for the first matched element.
  68  * If used on document, returns the document's height (innerHeight)
  69  * If used on window, returns the viewport's (window) height
  70  *
  71  * @example $("#testdiv").innerHeight()
  72  * @result 800
  73  *
  74  * @name innerHeight
  75  * @type Number
  76  * @cat Dimensions
  77  */
  78 jQuery.fn.innerHeight = function() {
  79         return this.get(0) == window || this.get(0) == document ?
  80                 this.height() :
  81                 this.get(0).offsetHeight - parseInt(this.css("borderTop") || 0) - parseInt(this.css("borderBottom") || 0);
  82 };
  83
  84 /**
  85  * Returns the inner width value (without border) for the first matched element.
  86  * If used on document, returns the document's Width (innerWidth)
  87  * If used on window, returns the viewport's (window) width
  88  *
  89  * @example $("#testdiv").innerWidth()
  90  * @result 1000
  91  *
  92  * @name innerWidth
  93  * @type Number
  94  * @cat Dimensions
  95  */
  96 jQuery.fn.innerWidth = function() {
  97         return this.get(0) == window || this.get(0) == document ?
  98                 this.width() :
  99                 this.get(0).offsetWidth - parseInt(this.css("borderLeft") || 0) - parseInt(this.css("borderRight") || 0);
 100 };
 101
 102 /**
 103  * Returns the outer height value (including border) for the first matched element.
 104  * Cannot be used on document or window.
 105  *
 106  * @example $("#testdiv").outerHeight()
 107  * @result 1000
 108  *
 109  * @name outerHeight
 110  * @type Number
 111  * @cat Dimensions
 112  */
 113 jQuery.fn.outerHeight = function() {
 114         return this.get(0) == window || this.get(0) == document ?
 115                 this.height() :
 116                 this.get(0).offsetHeight;
 117 };
 118
 119 /**
 120  * Returns the outer width value (including border) for the first matched element.
 121  * Cannot be used on document or window.
 122  *
 123  * @example $("#testdiv").outerWidth()
 124  * @result 1000
 125  *
 126  * @name outerWidth
 127  * @type Number
 128  * @cat Dimensions
 129  */
 130 jQuery.fn.outerWidth = function() {
 131         return this.get(0) == window || this.get(0) == document ?
 132                 this.width() :
 133                 this.get(0).offsetWidth;
 134 };
 135
 136 /**
 137  * Returns how many pixels the user has scrolled to the right (scrollLeft).
 138  * Works on containers with overflow: auto and window/document.
 139  *
 140  * @example $("#testdiv").scrollLeft()
 141  * @result 100
 142  *
 143  * @name scrollLeft
 144  * @type Number
 145  * @cat Dimensions
 146  */
 147 jQuery.fn.scrollLeft = function() {
 148         if ( this.get(0) == window || this.get(0) == document )
 149                 return self.pageXOffset ||
 150                         jQuery.boxModel && document.documentElement.scrollLeft ||
 151                         document.body.scrollLeft;
 152
 153         return this.get(0).scrollLeft;
 154 };
 155
 156 /**
 157  * Returns how many pixels the user has scrolled to the bottom (scrollTop).
 158  * Works on containers with overflow: auto and window/document.
 159  *
 160  * @example $("#testdiv").scrollTop()
 161  * @result 100
 162  *
 163  * @name scrollTop
 164  * @type Number
 165  * @cat Dimensions
 166  */
 167 jQuery.fn.scrollTop = function() {
 168         if ( this.get(0) == window || this.get(0) == document )
 169                 return self.pageYOffset ||
 170                         jQuery.boxModel && document.documentElement.scrollTop ||
 171                         document.body.scrollTop;
 172
 173         return this.get(0).scrollTop;
 174 };
 175
 176 /**
 177  * This returns an object with top, left, width, height, borderLeft,
 178  * borderTop, marginLeft, marginTop, scrollLeft, scrollTop,
 179  * pageXOffset, pageYOffset.
 180  *
 181  * The top and left values include the scroll offsets but the
 182  * scrollLeft and scrollTop properties of the returned object
 183  * are the combined scroll offets of the parent elements
 184  * (not including the window scroll offsets). This is not the
 185  * same as the element's scrollTop and scrollLeft.
 186  *
 187  * For accurate readings make sure to use pixel values.
 188  *
 189  * @name offset
 190  * @type Object
 191  * @cat Dimensions
 192  * @author Brandon Aaron (brandon.aaron@gmail.com || http://brandonaaron.net)
 193  */
 194 /**
 195  * This returns an object with top, left, width, height, borderLeft,
 196  * borderTop, marginLeft, marginTop, scrollLeft, scrollTop,
 197  * pageXOffset, pageYOffset.
 198  *
 199  * The top and left values include the scroll offsets but the
 200  * scrollLeft and scrollTop properties of the returned object
 201  * are the combined scroll offets of the parent elements
 202  * (not including the window scroll offsets). This is not the
 203  * same as the element's scrollTop and scrollLeft.
 204  *
 205  * For accurate readings make sure to use pixel values.
 206  *
 207  * @name offset
 208  * @type Object
 209  * @param String refElement This is an expression. The offset returned will be relative to the first matched element.
 210  * @cat Dimensions
 211  * @author Brandon Aaron (brandon.aaron@gmail.com || http://brandonaaron.net)
 212  */
 213 /**
 214  * This returns an object with top, left, width, height, borderLeft,
 215  * borderTop, marginLeft, marginTop, scrollLeft, scrollTop,
 216  * pageXOffset, pageYOffset.
 217  *
 218  * The top and left values include the scroll offsets but the
 219  * scrollLeft and scrollTop properties of the returned object
 220  * are the combined scroll offets of the parent elements
 221  * (not including the window scroll offsets). This is not the
 222  * same as the element's scrollTop and scrollLeft.
 223  *
 224  * For accurate readings make sure to use pixel values.
 225  *
 226  * @name offset
 227  * @type Object
 228  * @param jQuery refElement The offset returned will be relative to the first matched element.
 229  * @cat Dimensions
 230  * @author Brandon Aaron (brandon.aaron@gmail.com || http://brandonaaron.net)
 231  */
 232 /**
 233  * This returns an object with top, left, width, height, borderLeft,
 234  * borderTop, marginLeft, marginTop, scrollLeft, scrollTop,
 235  * pageXOffset, pageYOffset.
 236  *
 237  * The top and left values include the scroll offsets but the
 238  * scrollLeft and scrollTop properties of the returned object
 239  * are the combined scroll offets of the parent elements
 240  * (not including the window scroll offsets). This is not the
 241  * same as the element's scrollTop and scrollLeft.
 242  *
 243  * For accurate readings make sure to use pixel values.
 244  *
 245  * @name offset
 246  * @type Object
 247  * @param HTMLElement refElement The offset returned will be relative to this element.
 248  * @cat Dimensions
 249  * @author Brandon Aaron (brandon.aaron@gmail.com || http://brandonaaron.net)
 250  */
 251 jQuery.fn.offset = function(refElem) {
 252         if (!this[0]) throw 'jQuery.fn.offset requires an element.';
 253
 254         refElem = (refElem) ? jQuery(refElem)[0] : null;
 255         var x = 0, y = 0, elm = this[0], parent = this[0], pos = null, borders = [0,0], isElm = true, sl = 0, st = 0;
 256         do {
 257                 if (parent.tagName == 'BODY' || parent.tagName == 'HTML') {
 258                         // Safari and IE don't add margin for static and relative
 259                         if ((jQuery.browser.safari || jQuery.browser.msie) && pos != 'absolute') {
 260                                 x += parseInt(jQuery.css(parent, 'marginLeft')) || 0;
 261                                 y += parseInt(jQuery.css(parent, 'marginTop'))  || 0;
 262                         }
 263                         break;
 264                 }
 265
 266                 pos    = jQuery.css(parent, 'position');
 267                 border = [parseInt(jQuery.css(parent, 'borderLeftWidth')) || 0,
 268                                                         parseInt(jQuery.css(parent, 'borderTopWidth'))  || 0];
 269                 sl = parent.scrollLeft;
 270                 st = parent.scrollTop;
 271
 272                 x += (parent.offsetLeft || 0) + border[0] - sl;
 273                 y += (parent.offsetTop  || 0) + border[1] - st;
 274
 275                 // Safari and Opera include the border already for parents with position = absolute|relative
 276                 if ((jQuery.browser.safari || jQuery.browser.opera) && !isElm && (pos == 'absolute' || pos == 'relative')) {
 277                         x -= border[0];
 278                         y -= border[1];
 279                 }
 280
 281                 parent = parent.offsetParent;
 282                 isElm  = false;
 283         } while(parent);
 284
 285         if (refElem) {
 286                 var offset = jQuery(refElem).offset();
 287                 x  = x  - offset.left;
 288                 y  = y  - offset.top;
 289                 sl = sl - offset.scrollLeft;
 290                 st = st - offset.scrollTop;
 291         }
 292
 293         return {
 294                 top:  y,
 295                 left: x,
 296                 width:  elm.offsetWidth,
 297                 height: elm.offsetHeight,
 298                 borderTop:  parseInt(jQuery.css(elm, 'borderTopWidth'))  || 0,
 299                 borderLeft: parseInt(jQuery.css(elm, 'borderLeftWidth')) || 0,
 300                 marginTop:  parseInt(jQuery.css(elm, 'marginTopWidth'))  || 0,
 301                 marginLeft: parseInt(jQuery.css(elm, 'marginLeftWidth')) || 0,
 302                 scrollTop:  st,
 303                 scrollLeft: sl,
 304                 pageYOffset: window.pageYOffset || document.documentElement.scrollTop  || document.body.scrollTop  || 0,
 305                 pageXOffset: window.pageXOffset || document.documentElement.scrollLeft || document.body.scrollLeft || 0
 306         };
 307 };