API Docs for: 3.8.0
Show:

WidgetPositionConstrain Class

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

Methods

_afterConstrainChange

(
  • e
)
protected

After change listener for the "constrain" attribute, responsible for updating the UI, in response to attribute changes.

Parameters:

_bindUIPosConstrained

() protected

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

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

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

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

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

The setter implementation for the "constrain" attribute.

Parameters:

  • val Node | boolean

    The attribute value

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

(
  • enable
)
private

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

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

The set of positions for which to prevent overlap.

ATTRS

Object static

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

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

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.