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

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