# Yahoo! UI Library

### widget-position-ext 3.0.0b1

Yahoo! UI Library > widget-position-ext > WidgetPositionExt
Search:
Filters Show Private Show Protected Show Deprecated

## Class WidgetPositionExt

Widget extension, which can be used to add extended XY positioning support to the base Widget class, through the Base.build method. This extension requires that the WidgetPosition extension be added to the Widget (before WidgetPositionExt, if part of the same extension list passed to Base.build).

### Properties

#### WidgetPositionExt.ATTRS - `static Object`

Static property used to define the default attribute configuration introduced by WidgetPositionExt.

#### WidgetPositionExt.BC - `static String`

Constant used to specify the bottom edge, center point for alignment

#### WidgetPositionExt.BL - `static String`

Constant used to specify the bottom-left corner for alignment

#### WidgetPositionExt.BR - `static String`

Constant used to specify the bottom-right corner for alignment

#### WidgetPositionExt.CC - `static String`

Constant used to specify the center of widget/node/viewport for alignment

#### WidgetPositionExt.LC - `static String`

Constant used to specify the left edge, center point for alignment

#### WidgetPositionExt.RC - `static String`

Constant used to specify the right edge, center point for alignment

#### WidgetPositionExt.TC - `static String`

Constant used to specify the top edge-center point for alignment

#### WidgetPositionExt.TL - `static String`

Constant used to specify the top-left corner for alignment

#### WidgetPositionExt.TR - `static String`

Constant used to specify the top-right corner for alignment

### Methods

#### _afterAlignChange

`protected void _afterAlignChange ( e )`
Default attribute change listener for the align attribute, responsible for updating the UI, in response to attribute changes.

Parameters:
  `e <EventFacade>` The event facade for the attribute change

Returns: `void`

#### _bindUIStack

`protected void _bindUIStack ( )`
Binds event listeners responsible for updating the UI state in response to Widget extended positioning related state changes.

This method is invoked after bindUI is invoked for the Widget class using YUI's aop infrastructure.

Returns: `void`

#### _doAlign

`private void _doAlign ( widgetPoint , x , y )`
Helper method, used to align the given point on the widget, with the XY page co-ordinates provided.

Parameters:
  `widgetPoint <String>` Supported point constant (e.g. WidgetPositionExt.TL)
  `x <Number>` X page co-ordinate to align to
  `y <Number>` Y page co-ordinate to align to

Returns: `void`

#### _setAlignCenter

`protected Number _setAlignCenter ( The )`
Default setter for center attribute changes. Sets up the appropriate value, and passes it through the to the align attribute.

Parameters:
  `The <boolean | node>` attribute value being set.

Returns: `Number`
  The attribute value being set.

#### _syncUIPosExtras

`protected void _syncUIPosExtras ( )`
Synchronizes the UI to match the Widgets extended positioning state. This method in invoked after syncUI is invoked for the Widget class using YUI's aop infrastructure.

Returns: `void`

#### _uiSetAlign

`protected void _uiSetAlign ( The )`
Updates the UI to reflect the align value passed in (see the align attribute documentation, for the object stucture expected)

Parameters:
  `The <Node | null>` node to align to, or null to indicate the viewport

Returns: `void`

#### align

`void align ( node , points )`
Aligns the Widget to the provided node (or viewport) using the provided points. The method can be invoked directly, however it will result in the align attribute being out of sync with current position of the of Widget.

Parameters:
  `node <Node | String | null>` A reference (or selector string) for the Node which with the Widget is to be aligned. If null is passed in, the Widget will be aligned with the viewport.
  `points <Array[2]>` A two element array, specifying the points on the Widget and node/viewport which need to be aligned. The first entry is the point on the Widget, and the second entry is the point on the node/viewport which need to align. Valid point references are defined as static constants on the WidgetPositionExt class. e.g. [WidgetPositionExt.TL, WidgetPositionExt.TR] will align the top-left corner of the Widget with the top-right corner of the node/viewport.

Returns: `void`

#### centered

`void centered ( node )`
Centers the container in the viewport, or if a node is passed in, the node.

Parameters:
  `node <Node | String>` Optional. A node reference or selector string defining the node inside which the Widget is to be centered. If not passed in, the Widget will be centered in the viewport.

Returns: `void`

### Events

#### alignChange

`alignChange ( event )`
Fires when the value for the configuration attribute 'align' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### centeredChange

`centeredChange ( event )`
Fires when the value for the configuration attribute 'centered' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

### Configuration Attributes

#### align `- Object`

Default Value: null

#### centered `- {boolean | node}`

A convenience attribute, which can be used as a shortcut for the align attribute. If set to true, the Widget is centered in the viewport. If set to a node reference or valid selector string, the Widget will be centered within the node. If set the false, no center positioning is applied.
Default Value: false

Copyright © 2009 Yahoo! Inc. All rights reserved.