Prototype JavaScript framework - Position

Position

2006-12-05T21:48:00Z

As of Prototype 1.6, the complete Position object has been deprecated in favor of methods on the Element object.

The Position object provides a series of methods that help with element positioning and layout-related issues. These are mainly used by third party UI libraries like script.aculo.us.

absolutize

2006-11-02T22:15:00Z

absolutize(element)

Turns element into an absolutely-positioned element without changing its position in the page layout.

Deprecated in favor of Element#absolutize

relativize

2006-11-02T22:15:00Z

relativize(element)

Turns element into an relatively-positioned element without changing its position in the page layout.

Deprecated in favor of Element#relativize

overlap

2006-11-02T22:14:00Z

overlap(mode, element) -> Number

Returns a Number between 0 and 1 corresponding to the proportion to which element overlaps the point previously defined by Position.within. mode can be set to either vertical or horizontal.

Deprecated.

Imagine a block-level element (i.e., with dimensions) and a point x, y measured in pixels from the top left corner of the page. Calling Position.within will indicate whether that point is within the area occupied by element.

Now imagine an element of equal dimensions to element with its top left corner at x, y. Position.overlap indicates the amount these two boxes overlap in either the horizontal or vertical direction.

Note that Position.within must be called right before calling this method.

Example


var element = $('some_positioned_element');
Position.cumulativeOffset(element);
// -> [100, 100] (element is 100px from the top and left edges of the page)
element.getDimensions();
// -> { width: 150, height: 150 }

Position.within(element, 175, 145);
// -> true

Position.overlap('horizontal', element);
// -> 0.5 (point is halfway across the element's length)

Position.overlap('vertical', element);
// -> 0.3 (point is 3/10ths of the way across the element's height)

page

2006-11-02T22:14:00Z

page(element) -> [Number, Number]

Returns the X/Y coordinates of element relative to the viewport.

Deprecated in favor of Element#viewportOffset

Note that all values are returned as numbers only although they are expressed in pixels.

clone

2006-11-02T22:14:00Z

clone(source, target[, options]) -> [Number, Number]

Clones the position and/or dimensions of source onto target as defined by the optional argument options.

Deprecated in favor of Element#clonePosition

Note that target will be positioned exactly like source whether or not it is part of the same CSS containing block.

Options

Name	Default	Description
`setLeft`	`true`	clones `source`’s `left` CSS property onto `target`.
`setTop`	`true`	clones `source`’s `top` CSS property onto `target`.
`setWidth`	`true`	clones `source`’s `width` onto `target`.
`setHeight`	`true`	clones `source`’s `width` onto `target`.
`offsetLeft`	`0`	Number by which to offset `target`’s `left` CSS property.
`offsetTop`	`0`	Number by which to offset `target`’s `top` CSS property.

withinIncludingScrolloffsets

2006-11-02T22:13:00Z

withinIncludingScrolloffsets(element, x, y) -> Boolean

Indicates whether the point x, y (measured from the top-left corner of the document) is within the boundaries of element. Used instead of Position.within whenever element is a child of a scrolling container. Must be called immediately before Position.overlap and immediately after Position.prepare.

Deprecated.

This method handles an edge case of Position.within: when element is the child of a scrolling container. (Scriptaculous, for instance, uses it whenever a Draggable’s container is scrollable.) For performance reasons, this method should not be used unless you need this specific edge case.

You must call Position.prepare first, since it calculates offsets that are used by this method.

offsetParent

2006-11-02T22:12:00Z

offsetParent(element) -> HTMLElement

Returns element’s closest positioned ancestor. If none is found, the body element is returned.

Deprecated in favor of Element#getoffsetparent

The returned element is element’s CSS containing block.

within

2006-11-02T22:12:00Z

within(element, x, y) -> Boolean

Indicates whether the point x, y (measured from the top-left corner of the document) is within the boundaries of element. Must be called immediately before Position.overlap.

Deprecated.

This function uses Position.cumulativeOffset to determine element’s offset from the top of the page, then combines those values with element’s height and width to identify the offsets of all four corners of the element. It then compares these coordinates to the x and y arguments, returning true if those coordinates fall within the bounding box of element.

Example


var element = $('some_positioned_element');
Position.cumulativeOffset(element);
// -> [100, 100]  (item is 100px from the left and top edges of the page)
Element.getDimensions(element);
// -> { width: 150, height: 150 }

Position.within(element, 200, 200);
// -> true

Position.within(element, 260, 260);
// -> false

positionedOffset

2006-11-02T22:11:00Z

positionedOffset(element) -> [Number, Number]

Calculates the element’s offset relative to its closest positioned ancestor (i.e., the element that would be returned by Position.offsetParent(element).

Deprecated in favor of Element#positionedOffset

Calculates the cumulative offsetLeft and offsetTop of an element and all its parents until it reaches an element with a position other than static.

Note that all values are returned as numbers only although they are expressed in pixels.

realOffset

2006-11-02T21:57:00Z

realOffset(element) -> [Number, Number]

Calculates the cumulative scroll offset of an element in nested scrolling containers.

Deprecated in favor of Element#cumulativeScrollOffset

Adds the cumulative scrollLeft and scrollTop of an element and all its parents.

Used for calculating the scroll offset of an element that is in more than one scroll container (e.g., a draggable in a scrolling container which is itself part of a scrolling document).

Note that all values are returned as numbers only although they are expressed in pixels.

cumulativeOffset

2006-11-02T21:57:00Z

cumulativeOffset(element) -> [Number, Number]

Returns the offsets of element from the top left corner of the document.

Deprecated in favor of Element#cumulativeOffset

Adds the cumulative offsetLeft and offsetTop of an element and all its parents.

Note that all values are returned as numbers only although they are expressed in pixels.

prepare

2006-11-02T21:54:00Z

prepare()

Calculates document scroll offsets for use with Position.withinIncludingScrolloffsets.

Deprecated.