Docs/Element/Element.Dimensions.md

   1 Type: Element {#Element}
   2 =========================
   3
   4 Custom Type to allow all of its methods to be used with any DOM element via the dollar function [$][].
   5
   6 ### Notes:
   7
   8 * These methods don't take into consideration the body element margins and borders. If you need margin/borders on the body, consider adding a wrapper div, but always reset the margin and borders of body to 0.
   9 * If you need to measure the properties of elements that are not displayed (either their display style is none or one of their parents display style is none), you will need to use [Element.measure][] to expose it.
  10
  11 ### Credits:
  12
  13 - Element positioning based on the [qooxdoo](http://qooxdoo.org/) code and smart browser fixes, [LGPL License](http://www.gnu.org/licenses/lgpl.html).
  14 - Viewport dimensions based on [YUI](http://developer.yahoo.com/yui/) code, [BSD License](http://developer.yahoo.com/yui/license.html).
  15
  16
  17
  18 Element Method: scrollTo {#Element:scrollTo}
  19 --------------------------------------------
  20
  21 Scrolls the element to the specified coordinated (if the element has an overflow).
  22 The following method is also available on the Window object.
  23
  24 ### Syntax:
  25
  26         myElement.scrollTo(x, y);
  27
  28 ### Arguments:
  29
  30 1. x - (*number*) The x coordinate.
  31 2. y - (*number*) The y coordinate.
  32
  33 ### Example:
  34
  35         $('myElement').scrollTo(0, 100);
  36
  37 ### See Also:
  38
  39 - [MDC Element:scrollLeft][], [MDC Element:scrollTop][]
  40
  41
  42
  43 Element Method: getSize {#Element:getSize}
  44 ------------------------------------------
  45
  46 Returns the height and width of the Element, taking into account borders and padding.
  47 The following method is also available on the Window object.
  48
  49 ### Syntax:
  50
  51         myElement.getSize();
  52
  53 ### Returns:
  54
  55 * (*object*) An object containing the width (as x) and the height (as y) of the target Element.
  56
  57 ### Example:
  58
  59         var size = myElement.getSize();
  60         alert("The element is "+size.x+" pixels wide and "+size.y+"pixels high.");
  61
  62 ### Note:
  63
  64 If you need to measure the properties of elements that are not displayed (either their display style is none or one of their parents display style is none), you will need to use [Element.measure][] to expose it.
  65
  66
  67 Element Method: getScrollSize {#Element:getScrollSize}
  68 ------------------------------------------------------
  69
  70 Returns an Object representing the size of the target Element, including scrollable area.
  71 The following method is also available on the Window object.
  72
  73 ### Syntax:
  74
  75         myElement.getScrollSize();
  76
  77 ### Returns:
  78
  79 * (*object*) An object containing the x and y dimensions of the target Element.
  80
  81 ### Example:
  82
  83         var scroll = $('myElement').getScrollSize();
  84         alert('My element can scroll to ' + scroll.y + 'px'); //alerts 'My element can scroll down to 820px'
  85
  86 ### See Also:
  87
  88 - [MDC Element:scrollLeft][], [MDC Element:scrollTop][], [MDC Element:offsetWidth][], [MDC Element:offsetHeight][], [MDC Element:scrollWidth][], [MDC Element:scrollHeight][]
  89
  90 ### Note:
  91
  92 If you need to measure the properties of elements that are not displayed (either their display style is none or one of their parents display style is none), you will need to use [Element.measure][] to expose it.
  93
  94
  95 Element Method: getScroll {#Element:getScroll}
  96 ----------------------------------------------
  97
  98 Returns an Object representing how far the target Element is scrolled in either direction.
  99 The following method is also available on the Window object.
 100
 101 ### Syntax:
 102
 103         myElement.getScroll();
 104
 105 ### Returns:
 106
 107 * (*object*) An object containing the x and y dimensions of the target Element's scroll.
 108
 109 ### Example:
 110
 111         var scroll = $('myElement').getScroll();
 112         alert('My element is scrolled down ' + scroll.y + 'px'); //alerts 'My element is scrolled down to 620px'
 113
 114 ### Note:
 115
 116 If you need to measure the properties of elements that are not displayed (either their display style is none or one of their parents display style is none), you will need to use [Element.measure][] to expose it.
 117
 118
 119 Element Method: getPosition {#Element:getPosition}
 120 --------------------------------------------------
 121
 122 Returns the real offsets of the element.
 123
 124 ### Syntax:
 125
 126         myElement.getPosition(relative);
 127
 128 ### Arguments:
 129
 130 relative - (Element, defaults to the document) If set, the position will be relative to this Element.
 131
 132 ### Returns:
 133
 134 * (*object*) An object with the x and y coordinates of the Element's position.
 135
 136 ### Example:
 137
 138         $('element').getPosition(); //returns {x: 100, y: 500};
 139
 140 ### See Also:
 141
 142 - [QuirksMode: Find position](http://www.quirksmode.org/js/findpos.html)
 143
 144 ### Note:
 145
 146 If you need to measure the properties of elements that are not displayed (either their display style is none or one of their parents display style is none), you will need to use [Element.measure][] to expose it.
 147
 148
 149 Element Method: setPosition {#Element:setPosition}
 150 --------------------------------------------------
 151
 152 Sets the position of the element's *left* and *top* values to the x/y positions you specify.
 153
 154 ### Syntax
 155
 156         myElement.setPosition(positions);
 157
 158 ### Arguments
 159
 160 1. positions - (*object*) an object with x/y values (integers or strings, i.e. 10 or "10px")
 161
 162 ### Returns
 163
 164 * (*element*) the element that is positioned.
 165
 166 ### Example
 167
 168         myElement.setPosition({x: 10, y: 100});
 169
 170
 171
 172 Element Method: getCoordinates {#Element:getCoordinates}
 173 --------------------------------------------------------
 174
 175 Returns an object with width, height, left, right, top, and bottom coordinate values of the Element.
 176
 177 ### Syntax:
 178
 179         myElement.getCoordinates(relative);
 180
 181 ### Arguments:
 182
 183 relative - (*element*, optional) if set, the position will be relative to this element, otherwise relative to the document.
 184
 185 ### Returns:
 186
 187 * (*object*) An object containing the Element's current: top, left, width, height, right, and bottom.
 188
 189 ### Example:
 190
 191         var myValues = $('myElement').getCoordinates();
 192
 193 #### Returns:
 194
 195         {
 196                 top: 50,
 197                 left: 100,
 198                 width: 200,
 199                 height: 300,
 200                 right: 300,
 201                 bottom: 350
 202         }
 203
 204 ### See Also:
 205
 206 [Element:getPosition](#Element:getPosition)
 207
 208 ### Note:
 209
 210 If you need to measure the properties of elements that are not displayed (either their display style is none or one of their parents display style is none), you will need to use [Element.measure][] to expose it.
 211
 212
 213 Element Method: getOffsetParent {#Element:getOffsetParent}
 214 ----------------------------------------------------------
 215
 216 Returns the parent of the element that is positioned, if there is one.
 217
 218 ### Syntax
 219
 220         myElement.getOffsetParent();
 221
 222 ### Returns
 223
 224 * (*mixed*) If the element has a parent that is positioned, it returns that element, otherwise it returns *null*.
 225
 226
 227
 228 [$]: /core/Element/Element#Window:dollar
 229 [MDC Element:scrollLeft]: http://developer.mozilla.org/en/docs/DOM:element.scrollLeft
 230 [MDC Element:scrollTop]: http://developer.mozilla.org/en/docs/DOM:element.scrollTop
 231 [MDC Element:offsetWidth]: http://developer.mozilla.org/en/docs/DOM:element.offsetWidth
 232 [MDC Element:offsetHeight]: http://developer.mozilla.org/en/docs/DOM:element.offsetHeight
 233 [MDC Element:scrollWidth]: http://developer.mozilla.org/en/docs/DOM:element.scrollWidth
 234 [MDC Element:scrollHeight]: http://developer.mozilla.org/en/docs/DOM:element.scrollHeight
 235 [Element.measure]: /more/Element/Element.Measure