2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.com/yui/license.html
8 YUI.add('widget-position', function(Y) {
11 * Provides basic XY positioning support for Widgets, though an extension
13 * @module widget-position
20 POSITION = "position",
21 POSITIONED = "positioned",
22 BOUNDING_BOX = "boundingBox",
23 RELATIVE = "relative",
25 RENDERUI = "renderUI",
31 XYChange = "xyChange";
34 * Widget extension, which can be used to add positioning support to the base Widget class,
35 * through the <a href="Base.html#method_build">Base.build</a> method.
37 * @class WidgetPosition
38 * @param {Object} config User configuration object
40 function Position(config) {
41 this._posNode = this.get(BOUNDING_BOX);
43 // WIDGET METHOD OVERLAP
44 Y.after(this._renderUIPosition, this, RENDERUI);
45 Y.after(this._syncUIPosition, this, SYNCUI);
46 Y.after(this._bindUIPosition, this, BINDUI);
50 * Static property used to define the default attribute
51 * configuration introduced by WidgetPosition.
53 * @property WidgetPosition.ATTRS
64 * @description Page X co-ordinate for the widget. This attribute acts as a facade for the
65 * xy attribute. Changes in position can be monitored by listening for xyChange events.
68 setter: function(val) {
82 * @description Page Y co-ordinate for the widget. This attribute acts as a facade for the
83 * xy attribute. Changes in position can be monitored by listening for xyChange events.
86 setter: function(val) {
100 * @description Page XY co-ordinate pair for the widget.
104 validator: function(val) {
105 return this._validateXY(val);
111 * Default class used to mark the boundingBox of a positioned widget.
113 * @property WidgetPosition.POSITIONED_CLASS_NAME
115 * @default "yui-widget-positioned"
118 Position.POSITIONED_CLASS_NAME = Widget.getClassName(POSITIONED);
120 Position.prototype = {
123 * Creates/Initializes the DOM to support xy page positioning.
125 * This method in invoked after renderUI is invoked for the Widget class
126 * using YUI's aop infrastructure.
128 * @method _renderUIPosition
131 _renderUIPosition : function() {
132 this._posNode.addClass(Position.POSITIONED_CLASS_NAME);
136 * Synchronizes the UI to match the Widgets xy page position state.
138 * This method in invoked after syncUI is invoked for the Widget class
139 * using YUI's aop infrastructure.
141 * @method _syncUIPosition
144 _syncUIPosition : function() {
145 var posNode = this._posNode;
146 if (posNode.getStyle(POSITION) === RELATIVE) {
149 this._uiSetXY(this.get(XY_COORD));
153 * Binds event listeners responsible for updating the UI state in response to
154 * Widget position related state changes.
156 * This method in invoked after bindUI is invoked for the Widget class
157 * using YUI's aop infrastructure.
159 * @method _bindUIPosition
162 _bindUIPosition :function() {
163 this.after(XYChange, this._afterXYChange);
167 * Moves the Widget to the specified page xy co-ordinate position.
171 * @param {Number} x The new x position
172 * @param {Number} y The new y position
174 * @param {Array} x, y values passed as an array ([x, y]), to support
175 * simple pass through of Node.getXY results
178 var args = arguments,
179 coord = (Lang.isArray(args[0])) ? args[0] : [args[0], args[1]];
180 this.set(XY_COORD, coord);
184 * Synchronizes the Panel's "xy", "x", and "y" properties with the
185 * Widget's position in the DOM.
189 syncXY : function () {
190 this.set(XY_COORD, this._posNode.getXY(), {src: UI});
194 * Default validator for the XY attribute
196 * @method _validateXY
197 * @param {Array} val The XY page co-ordinate value which is being set.
198 * @return {boolean} true if valid, false if not.
200 _validateXY : function(val) {
201 return (Lang.isArray(val) && Lang.isNumber(val[0]) && Lang.isNumber(val[1]));
205 * Default setter for the X attribute. The setter passes the X value through
206 * to the XY attribute, which is the sole store for the XY state.
209 * @param {Number} val The X page co-ordinate value
211 _setX : function(val) {
212 this.set(XY_COORD, [val, this.get(XY_COORD)[1]]);
216 * Default setter for the Y attribute. The setter passes the Y value through
217 * to the XY attribute, which is the sole store for the XY state.
220 * @param {Number} val The Y page co-ordinate value
222 _setY : function(val) {
223 this.set(XY_COORD, [this.get(XY_COORD)[0], val]);
227 * Default getter for the X attribute. The value is retrieved from
228 * the XY attribute, which is the sole store for the XY state.
231 * @return {Number} The X page co-ordinate value
234 return this.get(XY_COORD)[0];
238 * Default getter for the Y attribute. The value is retrieved from
239 * the XY attribute, which is the sole store for the XY state.
242 * @return {Number} The Y page co-ordinate value
245 return this.get(XY_COORD)[1];
249 * Default attribute change listener for the xy attribute, responsible
250 * for updating the UI, in response to attribute changes.
252 * @method _afterXYChange
254 * @param {EventFacade} e The event facade for the attribute change
256 _afterXYChange : function(e) {
258 this._uiSetXY(e.newVal);
263 * Updates the UI to reflect the XY page co-ordinates passed in.
267 * @param {String} val The XY page co-ordinates value to be reflected in the UI
269 _uiSetXY : function(val) {
270 this._posNode.setXY(val);
274 Y.WidgetPosition = Position;
277 }, '3.3.0' ,{requires:['base-build', 'node-screen', 'widget']});