+ * 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.
+ * Supported alignment points are defined as static properties on WidgetPositionExt.
+ *
+ * e.g. [WidgetPositionExt.TR, WidgetPositionExt.TL] aligns the Top-Right corner of the Widget with the
+ * Top-Left corner of the node/viewport, and [WidgetPositionExt.CC, WidgetPositionExt.TC] aligns the Center of the
+ * Widget with the Top-Center edge of the node/viewport.
+ *
+ * This method is invoked after bindUI is invoked for the Widget class + * using YUI's aop infrastructure. + *
+ * @method _bindUIStack + * @protected + */ + _bindUIPosExtras : function() { + this.after(AlignChange, this._afterAlignChange); + }, + + /** + * Default setter for center attribute changes. Sets up the appropriate value, and passes + * it through the to the align attribute. + * + * @method _setAlignCenter + * @protected + * @param {boolean | node} The attribute value being set. + * @return {Number} The attribute value being set. + */ + _setAlignCenter : function(val) { + if (val) { + this.set(ALIGN, { + node: val === true ? null : val, + points: [PositionExt.CC, PositionExt.CC] + }); + } + return val; + }, + + /** + * Default attribute change listener for the align attribute, responsible + * for updating the UI, in response to attribute changes. + * + * @method _afterAlignChange + * @protected + * @param {EventFacade} e The event facade for the attribute change + */ + _afterAlignChange : function(e) { + if (e.newVal) { + this._uiSetAlign(e.newVal.node, e.newVal.points); + } + }, + + /** + * Updates the UI to reflect the align value passed in (see the align attribute documentation, for the object stucture expected) + * @method _uiSetAlign + * @protected + * @param {Node | null} The node to align to, or null to indicate the viewport + */ + _uiSetAlign: function (node, points) { + + if (!L.isArray(points) || points.length != 2) { + Y.error("align: Invalid Points Arguments"); + return; + } + + var nodeRegion, widgetPoint, nodePoint, xy; + + if (!node) { + nodeRegion = this._posNode.get(VIEWPORT_REGION); + } else { + node = Y.Node.get(node); + if (node) { + nodeRegion = node.get(REGION); + } + } + + if (nodeRegion) { + + // TODO: ViewportRegion doesn't have width/height - Workaround until normalized in Node/Dom + nodeRegion.width = nodeRegion.width || nodeRegion.right - nodeRegion.left; + nodeRegion.height = nodeRegion.height || nodeRegion.bottom - nodeRegion.top; + + widgetPoint = points[0]; + nodePoint = points[1]; + + // TODO: Optimize KWeight - Would lookup table help? + switch (nodePoint) { + case PositionExt.TL: + xy = [nodeRegion.left, nodeRegion.top]; + break; + case PositionExt.TR: + xy = [nodeRegion.right, nodeRegion.top]; + break; + case PositionExt.BL: + xy = [nodeRegion.left, nodeRegion.bottom]; + break; + case PositionExt.BR: + xy = [nodeRegion.right, nodeRegion.bottom]; + break; + case PositionExt.TC: + xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.top]; + break; + case PositionExt.BC: + xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.bottom]; + break; + case PositionExt.LC: + xy = [nodeRegion.left, nodeRegion.top + Math.floor(nodeRegion.height/2)]; + break; + case PositionExt.RC: + xy = [nodeRegion.right, nodeRegion.top + Math.floor(nodeRegion.height/2), widgetPoint]; + break; + case PositionExt.CC: + xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.top + Math.floor(nodeRegion.height/2), widgetPoint]; + break; + default: + Y.log("align: Invalid Points Arguments", "info", "widget-position-extras"); + break; + } + + if (xy) { + this._doAlign(widgetPoint, xy[0], xy[1]); + } + } + }, + + /** + * Helper method, used to align the given point on the widget, with the XY page co-ordinates provided. + * + * @method _doAlign + * @private + * @param {String} widgetPoint Supported point constant (e.g. WidgetPositionExt.TL) + * @param {Number} x X page co-ordinate to align to + * @param {Number} y Y page co-ordinate to align to + */ + _doAlign : function(widgetPoint, x, y) { + var widgetNode = this._posNode, + xy; + + switch (widgetPoint) { + case PositionExt.TL: + xy = [x, y]; + break; + case PositionExt.TR: + xy = [x - widgetNode.get(OFFSET_WIDTH), y]; + break; + case PositionExt.BL: + xy = [x, y - widgetNode.get(OFFSET_HEIGHT)]; + break; + case PositionExt.BR: + xy = [x - widgetNode.get(OFFSET_WIDTH), y - widgetNode.get(OFFSET_HEIGHT)]; + break; + case PositionExt.TC: + xy = [x - (widgetNode.get(OFFSET_WIDTH)/2), y]; + break; + case PositionExt.BC: + xy = [x - (widgetNode.get(OFFSET_WIDTH)/2), y - widgetNode.get(OFFSET_HEIGHT)]; + break; + case PositionExt.LC: + xy = [x, y - (widgetNode.get(OFFSET_HEIGHT)/2)]; + break; + case PositionExt.RC: + xy = [(x - widgetNode.get(OFFSET_WIDTH)), y - (widgetNode.get(OFFSET_HEIGHT)/2)]; + break; + case PositionExt.CC: + xy = [x - (widgetNode.get(OFFSET_WIDTH)/2), y - (widgetNode.get(OFFSET_HEIGHT)/2)]; + break; + default: + Y.log("align: Invalid Points Argument", "info", "widget-position-extras"); + break; + } + + if (xy) { + this.move(xy); + } + }, + + /** + * 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. + * + * @method align + * @param {Node | String | null} node 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. + * @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. + * 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. + */ + align: function (node, points) { + this.set(ALIGN, {node: node, points:points}); + }, + + /** + * Centers the container in the viewport, or if a node is passed in, + * the node. + * + * @method centered + * @param {Node | String} node 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. + */ + centered: function (node) { + this.align(node, [PositionExt.CC, PositionExt.CC]); + } + }; + + Y.WidgetPositionExt = PositionExt; + + + +}, '3.0.0b1' ,{requires:['widget', 'widget-position']});