1 /*

     2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.

     3 Code licensed under the BSD License:

     4 http://developer.yahoo.net/yui/license.txt

     5 version: 3.0.0b1

     6 build: 1163

     7 */

     8 YUI.add('widget-position', function(Y) {

     9 

    10 /**

    11  * Provides basic XY positioning support for Widgets, though an extension

    12  *

    13  * @module widget-position

    14  */

    15     var Lang = Y.Lang,

    16         Widget = Y.Widget,

    17 

    18         XY_COORD = "xy",

    19 

    20         POSITIONED = "positioned",

    21         BOUNDING_BOX = "boundingBox",

    22 

    23         RENDERUI = "renderUI",

    24         BINDUI = "bindUI",

    25         SYNCUI = "syncUI",

    26 

    27         UI = Widget.UI_SRC,

    28 

    29         XYChange = "xyChange";

    30 

    31     /**

    32      * Widget extension, which can be used to add positioning support to the base Widget class, 

    33      * through the <a href="Base.html#method_build">Base.build</a> method.

    34      *

    35      * @class WidgetPosition

    36      * @param {Object} config User configuration object

    37      */

    38     function Position(config) {

    39         this._posNode = this.get(BOUNDING_BOX);

    40 

    41         // WIDGET METHOD OVERLAP

    42         Y.after(this._renderUIPosition, this, RENDERUI);

    43         Y.after(this._syncUIPosition, this, SYNCUI);

    44         Y.after(this._bindUIPosition, this, BINDUI);

    45     }

    46 

    47     /**

    48      * Static property used to define the default attribute 

    49      * configuration introduced by WidgetPosition.

    50      *

    51      * @property WidgetPosition.ATTRS

    52      * @static

    53      * @type Object

    54      */

    55     Position.ATTRS = {

    56 

    57         /**

    58          * @attribute x

    59          * @type number

    60          * @default 0

    61          *

    62          * @description Page X co-ordinate for the widget. This attribute acts as a facade for the 

    63          * xy attribute. Changes in position can be monitored by listening for xyChange events.

    64          */

    65         x: {

    66             setter: function(val) {

    67                 this._setX(val);

    68             },

    69             getter: function() {

    70                 return this._getX();

    71             }

    72         },

    73 

    74         /**

    75          * @attribute y

    76          * @type number

    77          * @default 0

    78          *

    79          * @description Page Y co-ordinate for the widget. This attribute acts as a facade for the 

    80          * xy attribute. Changes in position can be monitored by listening for xyChange events.

    81          */

    82         y: {

    83             setter: function(val) {

    84                 this._setY(val);

    85             },

    86             getter: function() {

    87                 return this._getY();

    88             }

    89         },

    90 

    91         /**

    92          * @attribute xy

    93          * @type Array

    94          * @default [0,0]

    95          *

    96          * @description Page XY co-ordinate pair for the widget.

    97          */

    98         xy: {

    99             value:[0,0],

   100             validator: function(val) {

   101                 return this._validateXY(val);

   102             }

   103         }

   104     };

   105 

   106     /**

   107      * Default class used to mark the boundingBox of a positioned widget.

   108      *

   109      * @property WidgetPosition.POSITIONED_CLASS_NAME

   110      * @type String

   111      * @default "yui-widget-positioned"

   112      * @static

   113      */

   114     Position.POSITIONED_CLASS_NAME = Widget.getClassName(POSITIONED);

   115 

   116     Position.prototype = {

   117 

   118         /**

   119          * Creates/Initializes the DOM to support xy page positioning.

   120          * <p>

   121          * This method in invoked after renderUI is invoked for the Widget class

   122          * using YUI's aop infrastructure.

   123          * </p>

   124          * @method _renderUIPosition

   125          * @protected

   126          */

   127         _renderUIPosition : function() {

   128             this._posNode.addClass(Position.POSITIONED_CLASS_NAME);

   129         },

   130 

   131         /**

   132          * Synchronizes the UI to match the Widgets xy page position state.

   133          * <p>

   134          * This method in invoked after syncUI is invoked for the Widget class

   135          * using YUI's aop infrastructure.

   136          * </p>

   137          * @method _syncUIPosition

   138          * @protected

   139          */

   140         _syncUIPosition : function() {

   141             this._uiSetXY(this.get(XY_COORD));

   142         },

   143 

   144         /**

   145          * Binds event listeners responsible for updating the UI state in response to 

   146          * Widget position related state changes.

   147          * <p>

   148          * This method in invoked after bindUI is invoked for the Widget class

   149          * using YUI's aop infrastructure.

   150          * </p>

   151          * @method _bindUIPosition

   152          * @protected

   153          */

   154         _bindUIPosition :function() {

   155             this.after(XYChange, this._afterXYChange);

   156         },

   157 

   158         /**

   159          * Moves the Widget to the specified page xy co-ordinate position.

   160          *

   161          * @method move

   162          *

   163          * @param {Number} x The new x position

   164          * @param {Number} y The new y position

   165          * <p>Or</p>

   166          * @param {Array} x, y values passed as an array ([x, y]), to support

   167          * simple pass through of Node.getXY results

   168          */

   169         move: function () {

   170             var args = arguments,

   171                 coord = (Lang.isArray(args[0])) ? args[0] : [args[0], args[1]];

   172                 this.set(XY_COORD, coord);

   173         },

   174 

   175         /**

   176          * Synchronizes the Panel's "xy", "x", and "y" properties with the 

   177          * Widget's position in the DOM.

   178          *

   179          * @method syncXY

   180          */

   181         syncXY : function () {

   182             this.set(XY_COORD, this._posNode.getXY(), {src: UI});

   183         },

   184 

   185         /**

   186          * Default validator for the XY attribute

   187          *

   188          * @method _validateXY

   189          * @param {Array} val The XY page co-ordinate value which is being set.

   190          * @return {boolean} true if valid, false if not.

   191          */

   192         _validateXY : function(val) {

   193             return (Lang.isArray(val) && Lang.isNumber(val[0]) && Lang.isNumber(val[1]));

   194         },

   195 

   196         /**

   197          * Default setter for the X attribute. The setter passes the X value through

   198          * to the XY attribute, which is the sole store for the XY state.

   199          *

   200          * @method _setX

   201          * @param {Number} val The X page co-ordinate value

   202          */

   203         _setX : function(val) {

   204             this.set(XY_COORD, [val, this.get(XY_COORD)[0]]);

   205         },

   206 

   207         /**

   208          * Default setter for the Y attribute. The setter passes the Y value through

   209          * to the XY attribute, which is the sole store for the XY state.

   210          *

   211          * @method _setY

   212          * @param {Number} val The Y page co-ordinate value

   213          */

   214         _setY : function(val) {

   215             this.set(XY_COORD, [this.get(XY_COORD)[1], val]);

   216         },

   217 

   218         /**

   219          * Default getter for the X attribute. The value is retrieved from 

   220          * the XY attribute, which is the sole store for the XY state.

   221          *

   222          * @method _getX

   223          * @return {Number} The X page co-ordinate value

   224          */

   225         _getX : function() {

   226             return this.get(XY_COORD)[0];

   227         },

   228 

   229         /**

   230          * Default getter for the Y attribute. The value is retrieved from 

   231          * the XY attribute, which is the sole store for the XY state.

   232          *

   233          * @method _getY

   234          * @return {Number} The Y page co-ordinate value

   235          */

   236         _getY : function() {

   237             return this.get(XY_COORD)[1];

   238         },

   239 

   240         /**

   241          * Default attribute change listener for the xy attribute, responsible

   242          * for updating the UI, in response to attribute changes.

   243          * 

   244          * @method _afterXYChange

   245          * @protected

   246          * @param {EventFacade} e The event facade for the attribute change

   247          */

   248         _afterXYChange : function(e) {

   249             if (e.src != UI) {

   250                 this._uiSetXY(e.newVal);

   251             }

   252         },

   253 

   254         /**

   255          * Updates the UI to reflect the XY page co-ordinates passed in.

   256          * 

   257          * @method _uiSetXY

   258          * @protected

   259          * @param {String} val The XY page co-ordinates value to be reflected in the UI

   260          */

   261         _uiSetXY : function(val) {

   262             this._posNode.setXY(val);

   263         }

   264     };

   265 

   266     Y.WidgetPosition = Position;

   267 

   268 

   269 

   270 }, '3.0.0b1' ,{requires:['widget']});