jssource/src_files/include/javascript/yui3/build/widget/widget-position.js

   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']});