jssource/src_files/include/javascript/yui3/build/dd/dd-constrain.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('dd-constrain', function(Y) {
   9
  10
  11         /**
  12          * The Drag & Drop Utility allows you to create a draggable interface efficiently, buffering you from browser-level abnormalities and enabling you to focus on the interesting logic surrounding your particular implementation. This component enables you to create a variety of standard draggable objects with just a few lines of code and then, using its extensive API, add your own specific implementation logic.
  13          * @module dd
  14          * @submodule dd-constrain
  15          */
  16         /**
  17          * Plugin for the dd-drag module to add the constraining methods to it. It supports constraining to a node or viewport. It supports tick based moves and XY axis constraints.
  18          * @class DDConstrained
  19          * @extends Base
  20          * @constructor
  21          * @namespace Plugin
  22          */
  23
  24         var DRAG_NODE = 'dragNode',
  25             OFFSET_HEIGHT = 'offsetHeight',
  26             OFFSET_WIDTH = 'offsetWidth',
  27             HOST = 'host',
  28             TICK_X_ARRAY = 'tickXArray',
  29             TICK_Y_ARRAY = 'tickYArray',
  30             DDM = Y.DD.DDM,
  31             TOP = 'top',
  32             RIGHT = 'right',
  33             BOTTOM = 'bottom',
  34             LEFT = 'left',
  35             VIEW = 'view',
  36             proto = null,
  37
  38                 /**
  39             * @event drag:tickAlignX
  40             * @description Fires when this node is aligned with the tickX value.
  41             * @param {Event.Facade} event An Event Facade object
  42             * @type {Event.Custom}
  43             */
  44             EV_TICK_ALIGN_X = 'drag:tickAlignX',
  45
  46                 /**
  47             * @event drag:tickAlignY
  48             * @description Fires when this node is aligned with the tickY value.
  49             * @param {Event.Facade} event An Event Facade object
  50             * @type {Event.Custom}
  51             */
  52             EV_TICK_ALIGN_Y = 'drag:tickAlignY',
  53
  54             C = function(config) {
  55                 this._lazyAddAttrs = false;
  56                 C.superclass.constructor.apply(this, arguments);
  57             };
  58
  59         C.NAME = 'ddConstrained';
  60         /**
  61         * @property NS
  62         * @default con
  63         * @readonly
  64         * @protected
  65         * @static
  66         * @description The Constrained instance will be placed on the Drag instance under the con namespace.
  67         * @type {String}
  68 */
  69         C.NS = 'con';
  70
  71         C.ATTRS = {
  72             host: {
  73             },
  74             /**
  75             * @attribute stickX
  76             * @description Stick the drag movement to the X-Axis. Default: false
  77             * @type Boolean
  78             */
  79             stickX: {
  80                 value: false
  81             },
  82             /**
  83             * @attribute stickY
  84             * @description Stick the drag movement to the Y-Axis
  85             * @type Boolean
  86             */
  87             stickY: {
  88                 value: false
  89             },
  90             /**
  91             * @attribute tickX
  92             * @description The X tick offset the drag node should snap to on each drag move. False for no ticks. Default: false
  93             * @type Number/false
  94             */
  95             tickX: {
  96                 value: false
  97             },
  98             /**
  99             * @attribute tickY
 100             * @description The Y tick offset the drag node should snap to on each drag move. False for no ticks. Default: false
 101             * @type Number/false
 102             */
 103             tickY: {
 104                 value: false
 105             },
 106             /**
 107             * @attribute tickXArray
 108             * @description An array of page coordinates to use as X ticks for drag movement.
 109             * @type Array
 110             */
 111             tickXArray: {
 112                 value: false
 113             },
 114             /**
 115             * @attribute tickYArray
 116             * @description An array of page coordinates to use as Y ticks for drag movement.
 117             * @type Array
 118             */
 119             tickYArray: {
 120                 value: false
 121             },
 122             /**
 123             * @attribute gutter
 124             * @description CSS style string for the gutter of a region (supports negative values): '5 0' (sets top and bottom to 5px, left and right to 0px), '1 2 3 4' (top 1px, right 2px, bottom 3px, left 4px)
 125             * @type String
 126             */
 127             gutter: {
 128                 value: '0',
 129                 setter: function(gutter) {
 130                     return Y.DD.DDM.cssSizestoObject(gutter);
 131                 }
 132             },
 133             /**
 134             * @attribute constrain
 135             * @description Will attempt to constrain the drag node to the boundaries. Arguments:<br>
 136             * 'view': Contrain to Viewport<br>
 137             * '#selector_string': Constrain to this node<br>
 138             * '{Region Object}': An Object Literal containing a valid region (top, right, bottom, left) of page positions
 139             * @type {String/Object/Node}
 140             */
 141             constrain: {
 142                 value: VIEW,
 143                 setter: function(con) {
 144                     var node = Y.one(con);
 145                     if (node) {
 146                         con = node;
 147                     }
 148                     return con;
 149                 }
 150             },
 151             /**
 152             * @deprecated
 153             * @attribute constrain2region
 154             * @description An Object Literal containing a valid region (top, right, bottom, left) of page positions to constrain the drag node to.
 155             * @type Object
 156             */
 157             constrain2region: {
 158                 setter: function(r) {
 159                     return this.set('constrain', r);
 160                 }
 161             },
 162             /**
 163             * @deprecated
 164             * @attribute constrain2node
 165             * @description Will attempt to constrain the drag node to the boundaries of this node.
 166             * @type Object
 167             */
 168             constrain2node: {
 169                 setter: function(n) {
 170                     return this.set('constrain', Y.one(n));
 171                 }
 172             },
 173             /**
 174             * @deprecated
 175             * @attribute constrain2view
 176             * @description Will attempt to constrain the drag node to the boundaries of the viewport region.
 177             * @type Object
 178             */
 179             constrain2view: {
 180                 setter: function(n) {
 181                     return this.set('constrain', VIEW);
 182                 }
 183             },
 184             /**
 185             * @attribute cacheRegion
 186             * @description Should the region be cached for performace. Default: true
 187             * @type Boolean
 188             */
 189             cacheRegion: {
 190                 value: true
 191             }
 192         };
 193
 194         proto = {
 195                 _lastTickXFired: null,
 196                 _lastTickYFired: null,
 197
 198             initializer: function() {
 199                         this._createEvents();
 200
 201                 this.get(HOST).on('drag:end', Y.bind(this._handleEnd, this));
 202                 this.get(HOST).on('drag:start', Y.bind(this._handleStart, this));
 203                 this.get(HOST).after('drag:align', Y.bind(this.align, this));
 204                 this.get(HOST).after('drag:drag', Y.bind(this.drag, this));
 205             },
 206             /**
 207             * @private
 208             * @method _createEvents
 209             * @description This method creates all the events for this Event Target and publishes them so we get Event Bubbling.
 210             */
 211                 _createEvents: function() {
 212                         var instance = this;
 213
 214                         var ev = [
 215                                 EV_TICK_ALIGN_X,
 216                                 EV_TICK_ALIGN_Y
 217                         ];
 218
 219                         Y.each(ev, function(v, k) {
 220                     this.publish(v, {
 221                         type: v,
 222                         emitFacade: true,
 223                         bubbles: true,
 224                         queuable: false,
 225                         prefix: 'drag'
 226                     });
 227                 }, this);
 228                 },
 229                 /**
 230             * @private
 231             * @method _handleEnd
 232             * @description Fires on drag:end
 233             */
 234             _handleEnd: function() {
 235                         this._lastTickYFired = null;
 236                         this._lastTickXFired = null;
 237             },
 238             /**
 239             * @private
 240             * @method _handleStart
 241             * @description Fires on drag:start and clears the _regionCache
 242             */
 243             _handleStart: function() {
 244                 this.resetCache();
 245             },
 246             /**
 247             * @private
 248             * @property _regionCache
 249             * @description Store a cache of the region that we are constraining to
 250             * @type Object
 251             */
 252             _regionCache: null,
 253             /**
 254             * @private
 255             * @method _cacheRegion
 256             * @description Get's the region and caches it, called from window.resize and when the cache is null
 257             */
 258             _cacheRegion: function() {
 259                 this._regionCache = this.get('constrain').get('region');
 260             },
 261             /**
 262             * @method resetCache
 263             * @description Reset the internal region cache.
 264             */
 265             resetCache: function() {
 266                 this._regionCache = null;
 267             },
 268             /**
 269             * @private
 270             * @method _getConstraint
 271             * @description Standardizes the 'constraint' attribute
 272             */
 273             _getConstraint: function() {
 274                 var con = this.get('constrain'),
 275                     g = this.get('gutter'),
 276                     region;
 277
 278                 if (con) {
 279                     if (con instanceof Y.Node) {
 280                         if (!this._regionCache) {
 281                             Y.on('resize', Y.bind(this._cacheRegion, this), Y.config.win);
 282                             this._cacheRegion();
 283                         }
 284                         region = Y.clone(this._regionCache);
 285                         if (!this.get('cacheRegion')) {
 286                             this.resetCache();
 287                         }
 288                     } else if (Y.Lang.isObject(con)) {
 289                         region = Y.clone(con);
 290                     }
 291                 }
 292                 if (!con || !region) {
 293                     con = VIEW;
 294                 }
 295                 if (con === VIEW) {
 296                     region = this.get(HOST).get(DRAG_NODE).get('viewportRegion');
 297                 }
 298
 299                 Y.each(g, function(i, n) {
 300                     if ((n == RIGHT) || (n == BOTTOM)) {
 301                         region[n] -= i;
 302                     } else {
 303                         region[n] += i;
 304                     }
 305                 });
 306                 return region;
 307             },
 308
 309             /**
 310             * @method getRegion
 311             * @description Get the active region: viewport, node, custom region
 312             * @param {Boolean} inc Include the node's height and width
 313             * @return {Object}
 314             */
 315             getRegion: function(inc) {
 316                 var r = {}, oh = null, ow = null,
 317                     host = this.get(HOST);
 318
 319                 r = this._getConstraint();
 320
 321                 if (inc) {
 322                     oh = host.get(DRAG_NODE).get(OFFSET_HEIGHT);
 323                     ow = host.get(DRAG_NODE).get(OFFSET_WIDTH);
 324                     r[RIGHT] = r[RIGHT] - ow;
 325                     r[BOTTOM] = r[BOTTOM] - oh;
 326                 }
 327                 return r;
 328             },
 329             /**
 330             * @private
 331             * @method _checkRegion
 332             * @description Check if xy is inside a given region, if not change to it be inside.
 333             * @param {Array} _xy The XY to check if it's in the current region, if it isn't inside the region, it will reset the xy array to be inside the region.
 334             * @return {Array} The new XY that is inside the region
 335             */
 336             _checkRegion: function(_xy) {
 337                 var oxy = _xy,
 338                     r = this.getRegion(),
 339                     host = this.get(HOST),
 340                     oh = host.get(DRAG_NODE).get(OFFSET_HEIGHT),
 341                     ow = host.get(DRAG_NODE).get(OFFSET_WIDTH);
 342
 343                     if (oxy[1] > (r[BOTTOM] - oh)) {
 344                         _xy[1] = (r[BOTTOM] - oh);
 345                     }
 346                     if (r[TOP] > oxy[1]) {
 347                         _xy[1] = r[TOP];
 348
 349                     }
 350                     if (oxy[0] > (r[RIGHT] - ow)) {
 351                         _xy[0] = (r[RIGHT] - ow);
 352                     }
 353                     if (r[LEFT] > oxy[0]) {
 354                         _xy[0] = r[LEFT];
 355                     }
 356
 357                 return _xy;
 358             },
 359             /**
 360             * @method inRegion
 361             * @description Checks if the XY passed or the dragNode is inside the active region.
 362             * @param {Array} xy Optional XY to check, if not supplied this.get('dragNode').getXY() is used.
 363             * @return {Boolean} True if the XY is inside the region, false otherwise.
 364             */
 365             inRegion: function(xy) {
 366                 xy = xy || this.get(HOST).get(DRAG_NODE).getXY();
 367
 368                 var _xy = this._checkRegion([xy[0], xy[1]]),
 369                     inside = false;
 370                     if ((xy[0] === _xy[0]) && (xy[1] === _xy[1])) {
 371                         inside = true;
 372                     }
 373                 return inside;
 374             },
 375             /**
 376             * @method align
 377             * @description Modifies the Drag.actXY method from the after drag:align event. This is where the constraining happens.
 378             */
 379             align: function() {
 380                 var host = this.get(HOST),
 381                     _xy = [host.actXY[0], host.actXY[1]],
 382                     r = this.getRegion(true);
 383
 384                 if (this.get('stickX')) {
 385                     _xy[1] = (host.startXY[1] - host.deltaXY[1]);
 386                 }
 387                 if (this.get('stickY')) {
 388                     _xy[0] = (host.startXY[0] - host.deltaXY[0]);
 389                 }
 390
 391                 if (r) {
 392                     _xy = this._checkRegion(_xy);
 393                 }
 394
 395                 _xy = this._checkTicks(_xy, r);
 396
 397                 host.actXY = _xy;
 398             },
 399             /**
 400             * @method drag
 401             * @description Fires after drag:drag. Handle the tickX and tickX align events.
 402             */
 403                 drag: function(event) {
 404                         var host = this.get(HOST),
 405                                 xt = this.get('tickX'),
 406                                 yt = this.get('tickY'),
 407                                 _xy = [host.actXY[0], host.actXY[1]];
 408
 409                         if ((Y.Lang.isNumber(xt) || this.get(TICK_X_ARRAY)) && (this._lastTickXFired !== _xy[0])) {
 410                                 this._tickAlignX();
 411                                 this._lastTickXFired = _xy[0];
 412                         }
 413
 414                         if ((Y.Lang.isNumber(yt) || this.get(TICK_Y_ARRAY)) && (this._lastTickYFired !== _xy[1])) {
 415                                 this._tickAlignY();
 416                                 this._lastTickYFired = _xy[1];
 417                         }
 418                 },
 419             /**
 420             * @private
 421             * @method _checkTicks
 422             * @description This method delegates the proper helper method for tick calculations
 423             * @param {Array} xy The XY coords for the Drag
 424             * @param {Object} r The optional region that we are bound to.
 425             * @return {Array} The calced XY coords
 426             */
 427             _checkTicks: function(xy, r) {
 428                 var host = this.get(HOST),
 429                     lx = (host.startXY[0] - host.deltaXY[0]),
 430                     ly = (host.startXY[1] - host.deltaXY[1]),
 431                     xt = this.get('tickX'),
 432                     yt = this.get('tickY');
 433                     if (xt && !this.get(TICK_X_ARRAY)) {
 434                         xy[0] = DDM._calcTicks(xy[0], lx, xt, r[LEFT], r[RIGHT]);
 435                     }
 436                     if (yt && !this.get(TICK_Y_ARRAY)) {
 437                         xy[1] = DDM._calcTicks(xy[1], ly, yt, r[TOP], r[BOTTOM]);
 438                     }
 439                     if (this.get(TICK_X_ARRAY)) {
 440                         xy[0] = DDM._calcTickArray(xy[0], this.get(TICK_X_ARRAY), r[LEFT], r[RIGHT]);
 441                     }
 442                     if (this.get(TICK_Y_ARRAY)) {
 443                         xy[1] = DDM._calcTickArray(xy[1], this.get(TICK_Y_ARRAY), r[TOP], r[BOTTOM]);
 444                     }
 445
 446                 return xy;
 447             },
 448             /**
 449             * @private
 450             * @method _tickAlignX
 451             * @description Fires when the actXY[0] reach a new value respecting the tickX gap.
 452             */
 453             _tickAlignX: function() {
 454                 this.fire(EV_TICK_ALIGN_X);
 455             },
 456             /**
 457             * @private
 458             * @method _tickAlignY
 459             * @description Fires when the actXY[1] reach a new value respecting the tickY gap.
 460             */
 461             _tickAlignY: function() {
 462                 this.fire(EV_TICK_ALIGN_Y);
 463             }
 464         };
 465
 466         Y.namespace('Plugin');
 467         Y.extend(C, Y.Base, proto);
 468         Y.Plugin.DDConstrained = C;
 469
 470         Y.mix(DDM, {
 471             /**
 472             * @for DDM
 473             * @namespace DD
 474             * @private
 475             * @method _calcTicks
 476             * @description Helper method to calculate the tick offsets for a given position
 477             * @param {Number} pos The current X or Y position
 478             * @param {Number} start The start X or Y position
 479             * @param {Number} tick The X or Y tick increment
 480             * @param {Number} off1 The min offset that we can't pass (region)
 481             * @param {Number} off2 The max offset that we can't pass (region)
 482             * @return {Number} The new position based on the tick calculation
 483             */
 484             _calcTicks: function(pos, start, tick, off1, off2) {
 485                 var ix = ((pos - start) / tick),
 486                     min = Math.floor(ix),
 487                     max = Math.ceil(ix);
 488                     if ((min !== 0) || (max !== 0)) {
 489                         if ((ix >= min) && (ix <= max)) {
 490                             pos = (start + (tick * min));
 491                             if (off1 && off2) {
 492                                 if (pos < off1) {
 493                                     pos = (start + (tick * (min + 1)));
 494                                 }
 495                                 if (pos > off2) {
 496                                     pos = (start + (tick * (min - 1)));
 497                                 }
 498                             }
 499                         }
 500                     }
 501                     return pos;
 502             },
 503             /**
 504             * @for DDM
 505             * @namespace DD
 506             * @private
 507             * @method _calcTickArray
 508             * @description This method is used with the tickXArray and tickYArray config options
 509             * @param {Number} pos The current X or Y position
 510             * @param {Number} ticks The array containing our custom tick positions.
 511             * @param {Number} off1 The min offset that we can't pass (region)
 512             * @param {Number} off2 The max offset that we can't pass (region)
 513             * @return The tick position
 514             */
 515             _calcTickArray: function(pos, ticks, off1, off2) {
 516                 var i = 0, len = ticks.length, next = 0,
 517                     diff1, diff2, ret;
 518
 519                 if (!ticks || (ticks.length === 0)) {
 520                     return pos;
 521                 } else if (ticks[0] >= pos) {
 522                     return ticks[0];
 523                 } else {
 524                     for (i = 0; i < len; i++) {
 525                         next = (i + 1);
 526                         if (ticks[next] && ticks[next] >= pos) {
 527                             diff1 = pos - ticks[i];
 528                             diff2 = ticks[next] - pos;
 529                             ret = (diff2 > diff1) ? ticks[i] : ticks[next];
 530                             if (off1 && off2) {
 531                                 if (ret > off2) {
 532                                     if (ticks[i]) {
 533                                         ret = ticks[i];
 534                                     } else {
 535                                         ret = ticks[len - 1];
 536                                     }
 537                                 }
 538                             }
 539                             return ret;
 540                         }
 541
 542                     }
 543                     return ticks[ticks.length - 1];
 544                 }
 545             }
 546         });
 547
 548
 549
 550 }, '3.3.0' ,{requires:['dd-drag'], skinnable:false});