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

     6 build: 1549

     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             lazyAdd:false,

    70             getter: function() {

    71                 return this._getX();

    72             }

    73         },

    74 

    75         /**

    76          * @attribute y

    77          * @type number

    78          * @default 0

    79          *

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

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

    82          */

    83         y: {

    84             setter: function(val) {

    85                 this._setY(val);

    86             },

    87             lazyAdd: false,

    88             getter: function() {

    89                 return this._getY();

    90             }

    91         },

    92         

    93         /**

    94          * @attribute xy

    95          * @type Array

    96          * @default [0,0]

    97          *

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

    99          */

   100         xy: {

   101             value:[0,0],

   102 

   103             validator: function(val) {

   104                 return this._validateXY(val);

   105             }

   106         }

   107     };

   108 

   109     /**

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

   111      *

   112      * @property WidgetPosition.POSITIONED_CLASS_NAME

   113      * @type String

   114      * @default "yui-widget-positioned"

   115      * @static

   116      */

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

   118 

   119     Position.prototype = {

   120 

   121         /**

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

   123          * <p>

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

   125          * using YUI's aop infrastructure.

   126          * </p>

   127          * @method _renderUIPosition

   128          * @protected

   129          */

   130         _renderUIPosition : function() {

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

   132         },

   133 

   134         /**

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

   136          * <p>

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

   138          * using YUI's aop infrastructure.

   139          * </p>

   140          * @method _syncUIPosition

   141          * @protected

   142          */

   143         _syncUIPosition : function() {

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

   145         },

   146 

   147         /**

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

   149          * Widget position related state changes.

   150          * <p>

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

   152          * using YUI's aop infrastructure.

   153          * </p>

   154          * @method _bindUIPosition

   155          * @protected

   156          */

   157         _bindUIPosition :function() {

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

   159         },

   160 

   161         /**

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

   163          *

   164          * @method move

   165          *

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

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

   168          * <p>Or</p>

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

   170          * simple pass through of Node.getXY results

   171          */

   172         move: function () {

   173             var args = arguments,

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

   175                 this.set(XY_COORD, coord);

   176         },

   177 

   178         /**

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

   180          * Widget's position in the DOM.

   181          *

   182          * @method syncXY

   183          */

   184         syncXY : function () {

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

   186         },

   187 

   188         /**

   189          * Default validator for the XY attribute

   190          *

   191          * @method _validateXY

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

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

   194          */

   195         _validateXY : function(val) {

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

   197         },

   198 

   199         /**

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

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

   202          *

   203          * @method _setX

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

   205          */

   206         _setX : function(val) {

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

   208         },

   209 

   210         /**

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

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

   213          *

   214          * @method _setY

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

   216          */

   217         _setY : function(val) {

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

   219         },

   220 

   221         /**

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

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

   224          *

   225          * @method _getX

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

   227          */

   228         _getX : function() {

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

   230         },

   231 

   232         /**

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

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

   235          *

   236          * @method _getY

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

   238          */

   239         _getY : function() {

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

   241         },

   242 

   243         /**

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

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

   246          * 

   247          * @method _afterXYChange

   248          * @protected

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

   250          */

   251         _afterXYChange : function(e) {

   252             if (e.src != UI) {

   253                 this._uiSetXY(e.newVal);

   254             }

   255         },

   256 

   257         /**

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

   259          * 

   260          * @method _uiSetXY

   261          * @protected

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

   263          */

   264         _uiSetXY : function(val) {

   265             this._posNode.setXY(val);

   266         }

   267     };

   268 

   269     Y.WidgetPosition = Position;

   270 

   271 

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