API: container YAHOO.widget.Overlay (YUI Library)

# Yahoo! UI Library

### Container 2.2.2

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

## 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 10/23/2006the configuration that should be set for this Overlay. See configuration documentation for more details.

### Properties

#### YAHOO.widget.Overlay._DEFAULT_CONFIG `- private final Object`

Constant representing the Overlay's configuration properties

#### YAHOO.widget.Overlay._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

#### 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

#### Properties inherited from YAHOO.widget.Module:

`body, browser, cfg, contructor, element, footer, header, id, imageRoot, isSecure, platform, YAHOO.widget.Module._DEFAULT_CONFIG, YAHOO.widget.Module._EVENT_TYPES`

### Methods

#### 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`

#### 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`

#### hideIframe

`void hideIframe ( )`
Hides the iframe shim, if it has been enabled

Returns: `void`

#### hideMacGeckoScrollbars

`void hideMacGeckoScrollbars ( )`
Adds a special CSS class to the Overlay when Mac/Gecko is in use, to work around a Gecko bug where scrollbars cannot be hidden. See 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 ( )`
Removes a special CSS class from the Overlay when Mac/Gecko is in use, to work around a Gecko bug where scrollbars cannot be hidden. See https://bugzilla.mozilla.org/show_bug.cgi?id=187435

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`

#### Methods inherited from YAHOO.widget.Module:

`appendToBody, appendToFooter, appendToHeader, configMonitorResize, configVisible, destroy, hide, init, initDefaultConfig, initEvents, initResizeMonitor, onDomResize, render, setBody, setFooter, setHeader, show, toString`

### 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

#### Events inherited from YAHOO.widget.Module:

`appendEvent, beforeHideEvent, beforeInitEvent, beforeRenderEvent, beforeShowEvent, changeBodyEvent, changeContentEvent, changeFooterEvent, changeHeaderEvent, destroyEvent, hideEvent, initEvent, renderEvent, showEvent, YAHOO.widget.Module.textResizeEvent`

### 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`

True if the Overlay should have an IFRAME shim (for correcting the select z-index bug in IE6 and below).
Default Value: true for IE6 and below, false for all others

#### 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:

`effect, monitorresize, visible`

Copyright © 2007 Yahoo! Inc. All rights reserved.