Yahoo! UI Library

widget-position-constrain  3.3.0pr1

Yahoo! UI Library > widget-position-constrain > WidgetPositionConstrain
Search:
 
Filters

Class WidgetPositionConstrain

A widget extension, which can be used to add constrained 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 WidgetPositionConstrain, if part of the same extension list passed to Base.build).

Properties

WidgetPositionConstrain._PREVENT_OVERLAP - protected static Object

The set of positions for which to prevent overlap.

WidgetPositionConstrain.ATTRS - static Object

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

Methods

_afterConstrainChange

protected void _afterConstrainChange ( e )
After change listener for the "constrain" attribute, responsible for updating the UI, in response to attribute changes.
Parameters:
e <EventFacade> The event facade

_bindUIPosConstrained

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

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

_constrain

protected Number _constrain ( val , axis , nodeRegion , constrainingRegion )
The method which performs the actual constrain calculations for a given axis ("x" or "y") based on the regions provided.
Parameters:
val <Number> The value to constrain
axis <String> The axis to use for constrainment
nodeRegion <Region> The region of the node to constrain
constrainingRegion <Region> The region of the node (or viewport) to constrain to
Returns: Number
The constrained value

_constrainOnXYChange

protected void _constrainOnXYChange ( e )
The on change listener for the "xy" attribute. Modifies the event facade's newVal property with the constrained XY value.
Parameters:
e <EventFacade> The event facade for the attribute change

_getRegion

private void _getRegion ( node )
Utility method to normalize region retrieval from a node instance, or the viewport, if no node is provided.
Parameters:
node <Node> Optional.

_preventOverlap

protected Number _preventOverlap ( val , axis , nodeRegion , constrainingRegion )
The method which performs the preventOverlap calculations for a given axis ("x" or "y") based on the value and regions provided.
Parameters:
val <Number> The value being constrain
axis <String> The axis to being constrained
nodeRegion <Region> The region of the node being constrained
constrainingRegion <Region> The region of the node (or viewport) we need to constrain to
Returns: Number
The constrained value

_setConstrain

protected void _setConstrain ( val )
The setter implementation for the "constrain" attribute.
Parameters:
val <Node | boolean> The attribute value

constrain

void constrain ( xy , node )
Constrains the widget's bounding box to a node (or the viewport). If xy or node are not passed in, the current position and the value of "constrain" will be used respectively. The widget's position will be changed to the constrained position.
Parameters:
xy <Array> Optional. The xy values to constrain
node <Node | boolean> Optional. The node to constrain to, or true for the viewport

enable or disable constraints listeners

private void enable or disable constraints listeners ( enable )
Updates the UI if enabling constraints, and sets up the xyChange event listeners to constrain whenever the widget is moved. Disabling constraints removes the listeners.
Parameters:
enable <boolean> Enable or disable constraints

getConstrainedXY

Array getConstrainedXY ( xy , node )
Calculates the constrained positions for the XY positions provided, using the provided node argument is passed in. If no node value is passed in, the value of the "constrain" attribute is used.
Parameters:
xy <Array> The xy values to constrain
node <Node | boolean> Optional. The node to constrain to, or true for the viewport
Returns: Array
The constrained xy values

Events

constrainChange

constrainChange ( event )
Fires when the value for the configuration attribute 'constrain' 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

preventOverlapChange

preventOverlapChange ( event )
Fires when the value for the configuration attribute 'preventOverlap' 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

constrain - boolean | Node

The node to constrain the widget's bounding box to, when setting xy. Can also be set to true, to constrain to the viewport.
Default Value: null

preventOverlap - boolean

If set to true, and WidgetPositionAlign is also added to the Widget, constrained positioning will attempt to prevent the widget's bounding box from overlapping the element to which it has been aligned, by flipping the orientation of the alignment for corner based alignments

Configuration Attributes

Copyright © 2010 Yahoo! Inc. All rights reserved.