lib/yuilib/3.13.0/widget-position/widget-position.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('widget-position', function (Y, NAME) {
   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         POSITION = "position",
  21         POSITIONED = "positioned",
  22         BOUNDING_BOX = "boundingBox",
  23         RELATIVE = "relative",
  24
  25         RENDERUI = "renderUI",
  26         BINDUI = "bindUI",
  27         SYNCUI = "syncUI",
  28
  29         UI = Widget.UI_SRC,
  30
  31         XYChange = "xyChange";
  32
  33     /**
  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.
  36      *
  37      * @class WidgetPosition
  38      * @param {Object} config User configuration object
  39      */
  40     function Position(config) {
  41     }
  42
  43     /**
  44      * Static property used to define the default attribute
  45      * configuration introduced by WidgetPosition.
  46      *
  47      * @property ATTRS
  48      * @static
  49      * @type Object
  50      */
  51     Position.ATTRS = {
  52
  53         /**
  54          * @attribute x
  55          * @type number
  56          * @default 0
  57          *
  58          * @description Page X co-ordinate for the widget. This attribute acts as a facade for the
  59          * xy attribute. Changes in position can be monitored by listening for xyChange events.
  60          */
  61         x: {
  62             setter: function(val) {
  63                 this._setX(val);
  64             },
  65             getter: function() {
  66                 return this._getX();
  67             },
  68             lazyAdd:false
  69         },
  70
  71         /**
  72          * @attribute y
  73          * @type number
  74          * @default 0
  75          *
  76          * @description Page Y co-ordinate for the widget. This attribute acts as a facade for the
  77          * xy attribute. Changes in position can be monitored by listening for xyChange events.
  78          */
  79         y: {
  80             setter: function(val) {
  81                 this._setY(val);
  82             },
  83             getter: function() {
  84                 return this._getY();
  85             },
  86             lazyAdd: false
  87         },
  88
  89         /**
  90          * @attribute xy
  91          * @type Array
  92          * @default [0,0]
  93          *
  94          * @description Page XY co-ordinate pair for the widget.
  95          */
  96         xy: {
  97             value:[0,0],
  98             validator: function(val) {
  99                 return this._validateXY(val);
 100             }
 101         }
 102     };
 103
 104     /**
 105      * Default class used to mark the boundingBox of a positioned widget.
 106      *
 107      * @property POSITIONED_CLASS_NAME
 108      * @type String
 109      * @default "yui-widget-positioned"
 110      * @static
 111      */
 112     Position.POSITIONED_CLASS_NAME = Widget.getClassName(POSITIONED);
 113
 114     Position.prototype = {
 115
 116         initializer : function() {
 117             this._posNode = this.get(BOUNDING_BOX);
 118
 119             // WIDGET METHOD OVERLAP
 120             Y.after(this._renderUIPosition, this, RENDERUI);
 121             Y.after(this._syncUIPosition, this, SYNCUI);
 122             Y.after(this._bindUIPosition, this, BINDUI);
 123         },
 124
 125         /**
 126          * Creates/Initializes the DOM to support xy page positioning.
 127          * <p>
 128          * This method in invoked after renderUI is invoked for the Widget class
 129          * using YUI's aop infrastructure.
 130          * </p>
 131          * @method _renderUIPosition
 132          * @protected
 133          */
 134         _renderUIPosition : function() {
 135             this._posNode.addClass(Position.POSITIONED_CLASS_NAME);
 136         },
 137
 138         /**
 139          * Synchronizes the UI to match the Widgets xy page position state.
 140          * <p>
 141          * This method in invoked after syncUI is invoked for the Widget class
 142          * using YUI's aop infrastructure.
 143          * </p>
 144          * @method _syncUIPosition
 145          * @protected
 146          */
 147         _syncUIPosition : function() {
 148             var posNode = this._posNode;
 149             if (posNode.getStyle(POSITION) === RELATIVE) {
 150                 this.syncXY();
 151             }
 152             this._uiSetXY(this.get(XY_COORD));
 153         },
 154
 155         /**
 156          * Binds event listeners responsible for updating the UI state in response to
 157          * Widget position related state changes.
 158          * <p>
 159          * This method in invoked after bindUI is invoked for the Widget class
 160          * using YUI's aop infrastructure.
 161          * </p>
 162          * @method _bindUIPosition
 163          * @protected
 164          */
 165         _bindUIPosition :function() {
 166             this.after(XYChange, this._afterXYChange);
 167         },
 168
 169         /**
 170          * Moves the Widget to the specified page xy co-ordinate position.
 171          *
 172          * @method move
 173          *
 174          * @param {Number} x The new x position
 175          * @param {Number} y The new y position
 176          * <p>Or</p>
 177          * @param {Array} x, y values passed as an array ([x, y]), to support
 178          * simple pass through of Node.getXY results
 179          */
 180         move: function () {
 181             var args = arguments,
 182                 coord = (Lang.isArray(args[0])) ? args[0] : [args[0], args[1]];
 183                 this.set(XY_COORD, coord);
 184         },
 185
 186         /**
 187          * Synchronizes the Panel's "xy", "x", and "y" properties with the
 188          * Widget's position in the DOM.
 189          *
 190          * @method syncXY
 191          */
 192         syncXY : function () {
 193             this.set(XY_COORD, this._posNode.getXY(), {src: UI});
 194         },
 195
 196         /**
 197          * Default validator for the XY attribute
 198          *
 199          * @method _validateXY
 200          * @protected
 201          * @param {Array} val The XY page co-ordinate value which is being set.
 202          * @return {boolean} true if valid, false if not.
 203          */
 204         _validateXY : function(val) {
 205             return (Lang.isArray(val) && Lang.isNumber(val[0]) && Lang.isNumber(val[1]));
 206         },
 207
 208         /**
 209          * Default setter for the X attribute. The setter passes the X value through
 210          * to the XY attribute, which is the sole store for the XY state.
 211          *
 212          * @method _setX
 213          * @protected
 214          * @param {Number} val The X page co-ordinate value
 215          */
 216         _setX : function(val) {
 217             this.set(XY_COORD, [val, this.get(XY_COORD)[1]]);
 218         },
 219
 220         /**
 221          * Default setter for the Y attribute. The setter passes the Y value through
 222          * to the XY attribute, which is the sole store for the XY state.
 223          *
 224          * @method _setY
 225          * @protected
 226          * @param {Number} val The Y page co-ordinate value
 227          */
 228         _setY : function(val) {
 229             this.set(XY_COORD, [this.get(XY_COORD)[0], val]);
 230         },
 231
 232         /**
 233          * Default getter for the X attribute. The value is retrieved from
 234          * the XY attribute, which is the sole store for the XY state.
 235          *
 236          * @method _getX
 237          * @protected
 238          * @return {Number} The X page co-ordinate value
 239          */
 240         _getX : function() {
 241             return this.get(XY_COORD)[0];
 242         },
 243
 244         /**
 245          * Default getter for the Y attribute. The value is retrieved from
 246          * the XY attribute, which is the sole store for the XY state.
 247          *
 248          * @method _getY
 249          * @protected
 250          * @return {Number} The Y page co-ordinate value
 251          */
 252         _getY : function() {
 253             return this.get(XY_COORD)[1];
 254         },
 255
 256         /**
 257          * Default attribute change listener for the xy attribute, responsible
 258          * for updating the UI, in response to attribute changes.
 259          *
 260          * @method _afterXYChange
 261          * @protected
 262          * @param {EventFacade} e The event facade for the attribute change
 263          */
 264         _afterXYChange : function(e) {
 265             if (e.src != UI) {
 266                 this._uiSetXY(e.newVal);
 267             }
 268         },
 269
 270         /**
 271          * Updates the UI to reflect the XY page co-ordinates passed in.
 272          *
 273          * @method _uiSetXY
 274          * @protected
 275          * @param {String} val The XY page co-ordinates value to be reflected in the UI
 276          */
 277         _uiSetXY : function(val) {
 278             this._posNode.setXY(val);
 279         }
 280     };
 281
 282     Y.WidgetPosition = Position;
 283
 284
 285 }, '3.13.0', {"requires": ["base-build", "node-screen", "widget"]});