widget-position-ext.js revision 4d1598c3e0a0b50935d0b39e5d69b68f3fdc41f0
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Provides extended/advanced XY positioning support for Widgets, through an extension.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * It builds on top of the widget-position module, to provide alignmentment and centering support.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Future releases aim to add constrained and fixed positioning support.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @module widget-position-ext
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Widget extension, which can be used to add extended XY positioning support to the base Widget class,
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * through the <a href="Base.html#method_build">Base.build</a> method.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @class WidgetPositionExt
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @param {Object} User configuration object
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Static property used to define the default attribute
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * configuration introduced by WidgetPositionExt.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.ATTRS
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type Object
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @attribute align
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type Object
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @default null
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @desciption The align attribute is used to align a reference point on the widget, with the refernce point on another node, or the viewport.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * The object which align expects has the following properties:
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * <dt>node</dt>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * The node to which the Widget is to be aligned. If set to null, or not provided, the Widget is aligned to the viewport
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * <dt>points</dt>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * A two element array, defining the two points on the Widget and node/viewport which are to be aligned. The first element is the point on the Widget, and the second element is the point on the node/viewport.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Supported alignment points are defined as static properties on <code>WidgetPositionExt</code>.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * e.g. <code>[WidgetPositionExt.TR, WidgetPositionExt.TL]</code> aligns the Top-Right corner of the Widget with the
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Top-Left corner of the node/viewport, and <code>[WidgetPositionExt.CC, WidgetPositionExt.TC]</code> aligns the Center of the
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Widget with the Top-Center edge of the node/viewport.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @attribute centered
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type {boolean | node}
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @default false
2fe13ddab136a6eb6239d89e5e064e09d9e1bb92Luke Smith * @description A convenience attribute, which can be used as a shortcut for the align attribute.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * If set to true, the Widget is centered in the viewport. If set to a node reference or valid selector string,
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * the Widget will be centered within the node. If set the false, no center positioning is applied.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the top-left corner for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.TL
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "tl"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the top-right corner for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.TR
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "tr"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the bottom-left corner for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.BL
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "bl"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the bottom-right corner for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.BR
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "br"
2fe13ddab136a6eb6239d89e5e064e09d9e1bb92Luke Smith * Constant used to specify the top edge-center point for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.TC
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "tc"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the right edge, center point for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.RC
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "rc"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the bottom edge, center point for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.BC
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "bc"
_syncUIPosExtras : function() {
if (align) {
_bindUIPosExtras : function() {
if (val) {
return val;
_afterAlignChange : function(e) {
if (e.newVal) {
* Updates the UI to reflect the align value passed in (see the align attribute documentation, for the object stucture expected)
if (!node) {
if (node) {
if (nodeRegion) {
switch (nodePoint) {
xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.top + Math.floor(nodeRegion.height/2), widgetPoint];
if (xy) {
* Helper method, used to align the given point on the widget, with the XY page co-ordinates provided.
xy;
switch (widgetPoint) {
xy = [x, y];
if (xy) {
* @param {Node | String | null} node A reference (or selector string) for the Node which with the Widget is to be aligned.
* @param {Array[2]} points 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.