#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# WidgetPositionConstrain Class

Defined in: `widget-position-constrain/js/Widget-PositionConstrain.js:30`
Module: widget-position-constrain

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).

- Index
- Methods
- Properties
- Attributes

## Item Index

### Methods

- _afterConstrainChange
- _bindUIPosConstrained
- _constrain
- _constrainOnXYChange
- _getRegion
- _preventOverlap
- _setConstrain
- constrain
- enable or disable constraints listeners
- getConstrainedXY

### Properties

- _PREVENT_OVERLAP static
- ATTRS static

### Attributes

- constrain
- preventOverlap

## Methods

### `_afterConstrainChange`

(

- `e`

)
protected

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:275`

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

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:259`

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`

(

- `val`
- `axis`
- `nodeRegion`
- `constrainingRegion`

)
Number protected

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:164`

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`

(

- `e`

)
protected

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:305`

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`

(

- `node`

)
private

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:319`

Utility method to normalize region retrieval from a node instance, or the viewport, if no node is provided.

#### Parameters:

- `node` Node

  Optional.

### `_preventOverlap`

(

- `val`
- `axis`
- `nodeRegion`
- `constrainingRegion`

)
Number protected

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:208`

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`

(

- `val`

)
protected

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:153`

The setter implementation for the "constrain" attribute.

#### Parameters:

- `val` Node | boolean

  The attribute value

### `constrain`

(

- `xy`
- `node`

)

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:128`

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`

(

- `enable`

)
private

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:287`

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`

(

- `xy`
- `node`

)
Array

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:106`

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

## Properties

### `_PREVENT_OVERLAP`

Object protected static

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:81`

The set of positions for which to prevent overlap.

### `ATTRS`

Object static

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:46`

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

## Attributes

### `constrain`

Boolean | Node

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:56`

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

#### Fires event `constrainChange`

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:

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

### `preventOverlap`

Boolean

Defined in `widget-position-constrain/js/Widget-PositionConstrain.js:68`

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

#### Fires event `preventOverlapChange`

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:

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