Yahoo! UI Library

Container  2.5.0

Yahoo! UI Library > container > YAHOO.widget.Overlay

Show Private Show Protected

Class YAHOO.widget.Overlay - extends YAHOO.widget.Module

Known Subclasses:
YAHOO.widget.Panel YAHOO.widget.Menu YAHOO.widget.Tooltip
Overlay is a Module that is absolutely positioned above the page flow. It has convenience methods for positioning and sizing, as well as options for controlling zIndex and constraining the Overlay's position to the current visible viewport. Overlay also contains a dynamicly generated IFRAME which is placed beneath it for Internet Explorer 6 and 5.x so that it will be properly rendered above SELECT elements.

Constructor

YAHOO.widget.Overlay ( el , userConfig )
Parameters:
el <String> The element ID representing the Overlay OR
el <HTMLElement> The element representing the Overlay
userConfig <Object> The configuration object literal containing the configuration that should be set for this Overlay. See configuration documentation for more details.

Properties

DEFAULT_CONFIG - private final Object

Constant representing the Overlay's configuration properties

EVENT_TYPES - private final Object

Constant representing the name of the Overlay's events

YAHOO.widget.Overlay._initialized - private Boolean

A boolean that indicated whether the window resize and scroll events have already been subscribed to.

YAHOO.widget.Overlay.BOTTOM_LEFT - static final String

Constant representing the top bottom left corner of an element, used for configuring the context element alignment

YAHOO.widget.Overlay.BOTTOM_RIGHT - static final String

Constant representing the bottom right corner of an element, used for configuring the context element alignment

YAHOO.widget.Overlay.CSS_OVERLAY - static final String

Constant representing the default CSS class used for an Overlay

YAHOO.widget.Overlay.IFRAME_SRC - static final String

The URL that will be placed in the iframe
Default Value: 3

YAHOO.widget.Overlay.TOP_LEFT - static final String

Constant representing the top left corner of an element, used for configuring the context element alignment

YAHOO.widget.Overlay.TOP_RIGHT - static final String

Constant representing the top right corner of an element, used for configuring the context element alignment

YAHOO.widget.Overlay.VIEWPORT_OFFSET - static final Number

Number representing the minimum distance an Overlay instance should be positioned relative to the boundaries of the browser's viewport, in pixels.
Default Value: 10

Methods

_primeXYFromDOM

protected void _primeXYFromDOM ( )
Set's the container's XY value from DOM if not already set. Differs from syncPosition, in that the XY value is only sync'd with DOM if not already set. The method also refire's the XY config property event, so any beforeMove, Move event listeners are invoked.
Returns: void

align

void align ( elementAlign , contextAlign )
Aligns the Overlay to its context element using the specified corner points (represented by the constants TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, and BOTTOM_RIGHT.
Parameters:
elementAlign <String> The String representing the corner of the Overlay that should be aligned to the context element
contextAlign <String> The corner of the context element that the elementAlign corner should stick to.
Returns: void

bringToTop

void bringToTop ( )
Places the Overlay on top of all other instances of YAHOO.widget.Overlay.
Returns: void

center

void center ( )
Centers the container in the viewport.
Returns: void

configConstrainToViewport

void configConstrainToViewport ( type , args , obj )
The default event handler fired when the "constraintoviewport" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configContext

void configContext ( type , args , obj )
The default event handler fired when the "context" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configFixedCenter

void configFixedCenter ( type , args , obj )
The default event handler fired when the "fixedcenter" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configHeight

void configHeight ( type , args , obj )
The default event handler fired when the "height" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configIframe

void configIframe ( type , args , obj )
The default event handler fired when the "iframe" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configVisible

void configVisible ( type , args , obj )
The default event handler fired when the "visible" property is changed. This method is responsible for firing showEvent and hideEvent.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configWidth

void configWidth ( type , args , obj )
The default event handler fired when the "width" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configX

void configX ( type , args , obj )
The default event handler fired when the "x" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configXY

void configXY ( type , args , obj )
The default event handler fired when the "xy" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configY

void configY ( type , args , obj )
The default event handler fired when the "y" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

configzIndex

void configzIndex ( type , args , obj )
The default event handler fired when the "zIndex" property is changed.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

destroy

void destroy ( )
Removes the Overlay element from the DOM and sets all child elements to null.
Returns: void

doCenterOnDOMEvent

void doCenterOnDOMEvent ( )
Center event handler used for centering on scroll/resize, but only if the Overlay is visible
Returns: void

enforceConstraints

void enforceConstraints ( type , args , obj )
The default event handler executed when the moveEvent is fired, if the "constraintoviewport" is set to true.
Parameters:
type <String> The CustomEvent type (usually the property name)
args <Object[]> The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
obj <Object> The scope object. For configuration handlers, this will usually equal the owner.
Returns: void

getConstrainedXY

Array getConstrainedXY ( x , y )
Given x, y coordinate values, returns the calculated coordinates required to position the Overlay if it is to be constrained to the viewport, based on the current element size, viewport dimensions and scroll values.
Parameters:
x <Number> The X coordinate value to be constrained
y <Number> The Y coordinate value to be constrained
Returns: Array
The constrained x and y coordinates at index 0 and 1 respectively;

hideIframe

void hideIframe ( )
Hides the iframe shim, if it has been enabled.
Returns: void

hideMacGeckoScrollbars

void hideMacGeckoScrollbars ( )
Adds a CSS class ("hide-scrollbars") and removes a CSS class ("show-scrollbars") to the Overlay to fix a bug in Gecko on Mac OS X (https://bugzilla.mozilla.org/show_bug.cgi?id=187435)
Returns: void

init

void init ( el , userConfig )
The Overlay initialization method, which is executed for Overlay and all of its subclasses. This method is automatically called by the constructor, and sets up all DOM references for pre-existing markup, and creates required markup if it is not already present.
Parameters:
el <String> The element ID representing the Overlay OR
el <HTMLElement> The element representing the Overlay
userConfig <Object> The configuration object literal containing the configuration that should be set for this Overlay. See configuration documentation for more details.
Returns: void

initDefaultConfig

void initDefaultConfig ( )
Initializes the class's configurable properties which can be changed using the Overlay's Config object (cfg).
Returns: void

initEvents

void initEvents ( )
Initializes the custom events for Overlay which are fired automatically at appropriate times by the Overlay class.
Returns: void

moveTo

void moveTo ( x , y )
Moves the Overlay to the specified position. This function is identical to calling this.cfg.setProperty("xy", [x,y]);
Parameters:
x <Number> The Overlay's new x position
y <Number> The Overlay's new y position
Returns: void

onDomResize

void onDomResize ( e , obj )
Event handler fired when the resize monitor element is resized.
Parameters:
e <DOMEvent> The resize DOM event
obj <Object> The scope object
Returns: void

showIframe

void showIframe ( )
Shows the iframe shim, if it has been enabled.
Returns: void

showMacGeckoScrollbars

void showMacGeckoScrollbars ( )
Adds a CSS class ("show-scrollbars") and removes a CSS class ("hide-scrollbars") to the Overlay to fix a bug in Gecko on Mac OS X (https://bugzilla.mozilla.org/show_bug.cgi?id=187435)
Returns: void

stackIframe

void stackIframe ( )
Sets the zindex of the iframe shim, if it exists, based on the zindex of the Overlay element. The zindex of the iframe is set to be one less than the Overlay element's zindex.

NOTE: This method will not bump up the zindex of the Overlay element to ensure that the iframe shim has a non-negative zindex. If you require the iframe zindex to be 0 or higher, the zindex of the Overlay element should be set to a value greater than 0, before this method is called.

Returns: void

syncIframe

void syncIframe ( )
Syncronizes the size and position of iframe shim to that of its corresponding Overlay instance.
Returns: void

syncPosition

void syncPosition ( )
Synchronizes the Panel's "xy", "x", and "y" properties with the Panel's position in the DOM. This is primarily used to update position information during drag & drop.
Returns: void

toString

String toString ( )
Returns a String representation of the object.
Returns: String
The string representation of the Overlay.

YAHOO.widget.Overlay.windowResizeHandler

static void YAHOO.widget.Overlay.windowResizeHandler ( e )
The DOM event handler used to fire the CustomEvent for window resize
Parameters:
e <DOMEvent> The DOM resize event
Returns: void

YAHOO.widget.Overlay.windowScrollHandler

static void YAHOO.widget.Overlay.windowScrollHandler ( e )
The DOM event handler used to fire the CustomEvent for window scroll
Parameters:
e <DOMEvent> The DOM scroll event
Returns: void

Events

beforeMoveEvent

beforeMoveEvent ( x , y )
CustomEvent fired before the Overlay is moved.
Parameters:
x <Number> x coordinate
y <Number> y coordinate

moveEvent

moveEvent ( x , y )
CustomEvent fired after the Overlay is moved.
Parameters:
x <Number> x coordinate
y <Number> y coordinate

YAHOO.widget.Overlay.windowResizeEvent

YAHOO.widget.Overlay.windowResizeEvent ( )
A singleton CustomEvent used for reacting to the DOM event for window resize

YAHOO.widget.Overlay.windowScrollEvent

YAHOO.widget.Overlay.windowScrollEvent ( )
A singleton CustomEvent used for reacting to the DOM event for window scroll

Configuration Attributes

constraintoviewport - Boolean

True if the Overlay should be prevented from being positioned out of the viewport.
Default Value: false

context - Array

The array of context arguments for context-sensitive positioning. The format is: [id or element, element corner, context corner]. For example, setting this property to ["img1", "tl", "bl"] would align the Overlay's top left corner to the context element's bottom left corner.
Default Value: null

fixedcenter - Boolean

True if the Overlay should be anchored to the center of the viewport.
Default Value: false

height - String

CSS height of the Overlay.
Default Value: null

iframe - Boolean

Boolean indicating whether or not the Overlay should have an IFRAME shim; used to prevent SELECT elements from poking through an Overlay instance in IE6. When set to "true", the iframe shim is created when the Overlay instance is intially made visible.
Default Value: true for IE6 and below, false for all other browsers.

width - String

CSS width of the Overlay.
Default Value: null

x - Number

The absolute x-coordinate position of the Overlay
Default Value: null

xy - Number[]

An array with the absolute x and y positions of the Overlay
Default Value: null

y - Number

The absolute y-coordinate position of the Overlay
Default Value: null

zIndex - Number

CSS z-index of the Overlay.
Default Value: null

Configuration attributes inherited from YAHOO.widget.Module:


Copyright © 2007 Yahoo! Inc. All rights reserved.