class Element.Layout
Description
A set of key/value pairs representing measurements of various dimensions of an element.
Overview
The Element.Layout
class is a specialized way to measure elements.
It helps mitigate:
- The convoluted steps often needed to get common measurements for elements.
- The tendency of browsers to report measurements in non-pixel units.
- The quirks that lead some browsers to report inaccurate measurements.
- The difficulty of measuring elements that are hidden.
Usage
Instantiate an Element.Layout
class by passing an element into the
constructor:
var layout = new Element.Layout(someElement);
You can also use Element.getLayout
, if you prefer.
Once you have a layout object, retrieve properties using Hash
's
familiar get
and set
syntax.
layout.get('width'); //-> 400
layout.get('top'); //-> 180
The following are the CSS-related properties that can be retrieved.
Nearly all of them map directly to their property names in CSS. (The
only exception is for borders — e.g., border-width
instead of
border-left-width
.)
height
width
top
left
right
bottom
border-left
border-right
border-top
border-bottom
padding-left
padding-right
padding-top
padding-bottom
margin-top
margin-bottom
margin-left
margin-right
In addition, these "composite" properties can be retrieved:
padding-box-width
(width of the content area, from the beginning of the left padding to the end of the right padding)padding-box-height
(height of the content area, from the beginning of the top padding to the end of the bottom padding)border-box-width
(width of the content area, from the outer edge of the left border to the outer edge of the right border)border-box-height
(height of the content area, from the outer edge of the top border to the outer edge of the bottom border)margin-box-width
(width of the content area, from the beginning of the left margin to the end of the right margin)margin-box-height
(height of the content area, from the beginning of the top margin to the end of the bottom margin)
Caching
Because these properties can be costly to retrieve, Element.Layout
behaves differently from an ordinary Hash
.
First: by default, values are "lazy-loaded" — they aren't computed until they're retrieved. To measure all properties at once, pass a second argument into the constructor:
var layout = new Element.Layout(someElement, true);
Second: once a particular value is computed, it's cached. Asking for
the same property again will return the original value without
re-computation. This means that **an instance of Element.Layout
becomes stale when the element's dimensions change**. When this
happens, obtain a new instance.
Hidden elements
Because it's a common case to want the dimensions of a hidden element
(e.g., for animations), it's possible to measure elements that are
hidden with display: none
.
However, **it's only possible to measure a hidden element if its parent
is visible**. If its parent (or any other ancestor) is hidden, any
width and height measurements will return 0
, as will measurements for
top|bottom|left|right
.