constrain.js revision 45b033d25e00d03f1a53ea6038bee331face3b78
/**
* 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.
* @module dd
* @submodule dd-constrain
*/
/**
* This is a plugin for the dd-drag module to add the constraining methods to it. It supports constraining to a renodenode or viewport. It anode* supports tick based moves and XY axis constraints.
* @class DragConstrained
* @extends Base
* @constructor
* @namespace plugin
*/
var DRAG_NODE = 'dragNode',
OFFSET_HEIGHT = 'offsetHeight',
OFFSET_WIDTH = 'offsetWidth',
HOST = 'host',
CON_2_REGION = 'constrain2region',
CON_2_NODE = 'constrain2node',
TICK_X_ARRAY = 'tickXArray',
TICK_Y_ARRAY = 'tickYArray',
DDM = Y.DD.DDM,
TOP = 'top',
RIGHT = 'right',
BOTTOM = 'bottom',
LEFT = 'left',
proto = null;
var C = function(config) {
C.superclass.constructor.apply(this, arguments);
};
C.NAME = 'DragConstrained';
/**
* @property con
* @description The Constrained instance will be placed on the Drag instance under the con namespace.
* @type {String}
*/
C.NS = 'con';
C.ATTRS = {
host: {
},
/**
* @attribute stickX
* @description Stick the drag movement to the X-Axis. Default: false
* @type Boolean
*/
stickX: {
value: false
},
/**
* @attribute stickY
* @description Stick the drag movement to the Y-Axis
* @type Boolean
*/
stickY: {
value: false
},
/**
* @attribute tickX
* @description The X tick offset the drag node should snap to on each drag move. False for no ticks. Default: false
* @type Number/false
*/
tickX: {
value: false
},
/**
* @attribute tickY
* @description The Y tick offset the drag node should snap to on each drag move. False for no ticks. Default: false
* @type Number/false
*/
tickY: {
value: false
},
/**
* @attribute tickXArray
* @description An array of page coordinates to use as X ticks for drag movement.
* @type Array
*/
tickXArray: {
value: false
},
/**
* @attribute tickYArray
* @description An array of page coordinates to use as Y ticks for drag movement.
* @type Array
*/
tickYArray: {
value: false
},
/**
* @attribute constrain2region
* @description An Object Literal containing a valid region (top, right, bottom, left) of page positions to constrain the drag node to.
* @type Object
*/
constrain2region: {
value: false,
getter: function(r) {
if (Y.Lang.isObject(r)) {
var o = {};
Y.mix(o, r);
return o;
} else {
return false;
}
},
setter: function (r) {
if (Y.Lang.isObject(r)) {
if (Y.Lang.isNumber(r[TOP]) && Y.Lang.isNumber(r[RIGHT]) && Y.Lang.isNumber(r[LEFT]) && Y.Lang.isNumber(r[BOTTOM])) {
var o = {};
Y.mix(o, r);
return o;
} else {
return false;
}
} else if (r !== false) {
return false;
}
return r;
}
},
/**
* @attribute gutter
* @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)
* @type String
*/
gutter: {
value: '0',
setter: function(gutter) {
return Y.DD.DDM.cssSizestoObject(gutter);
}
},
/**
* @attribute constrain2node
* @description Will attempt to constrain the drag node to the bounderies of this node.
* @type Object
*/
constrain2node: {
value: false,
setter: function(n) {
if (!this.get(CON_2_REGION)) {
var node = Y.Node.get(n);
if (node) {
return node;
}
} else if (this.get(CON_2_REGION) !== false) {
}
return false;
}
},
/**
* @attribute constrain2view
* @description Will attempt to constrain the drag node to the bounderies of the viewport region.
* @type Object
*/
constrain2view: {
value: false
}
};
proto = {
initializer: function() {
this.get(HOST).on('drag:start', Y.bind(this._handleStart, this));
this.get(HOST).after('drag:align', Y.bind(this.align, this));
},
/**
* @private
* @method _handleStart
* @description Fires on drag:start and clears the _regionCache
*/
_handleStart: function() {
this._regionCache = null;
},
/**
* @private
* @property _regionCache
* @description Store a cache of the region that we are constraining to
* @type Object
*/
_regionCache: null,
/**
* @private
* @method _cacheRegion
* @description Get's the region and caches it, called from window.resize and when the cache is null
*/
_cacheRegion: function() {
this._regionCache = this.get(CON_2_NODE).get('region');
},
/**
* @method getRegion
* @description Get the active region: viewport, node, custom region
* @param {Boolean} inc Include the node's height and width
* @return {Object}
*/
getRegion: function(inc) {
var r = {}, oh = null, ow = null,
g = this.get('gutter'),
host = this.get(HOST);
if (this.get(CON_2_NODE)) {
if (!this._regionCache) {
Y.on('resize', Y.bind(this._cacheRegion, this), window);
this._cacheRegion();
}
r = Y.clone(this._regionCache);
} else if (this.get(CON_2_REGION)) {
r = this.get(CON_2_REGION);
} else if (this.get('constrain2view')) {
r = host.get(DRAG_NODE).get('viewportRegion');
} else {
return false;
}
Y.each(g, function(i, n) {
if ((n == RIGHT) || (n == BOTTOM)) {
r[n] -= i;
} else {
r[n] += i;
}
});
if (inc) {
oh = host.get(DRAG_NODE).get(OFFSET_HEIGHT);
ow = host.get(DRAG_NODE).get(OFFSET_WIDTH);
r[RIGHT] = r[RIGHT] - ow;
r[BOTTOM] = r[BOTTOM] - oh;
}
return r;
},
/**
* @private
* @method _checkRegion
* @description Check if xy is inside a given region, if not change to it be inside.
* @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.
* @return {Array} The new XY that is inside the region
*/
_checkRegion: function(_xy) {
var oxy = _xy,
r = this.getRegion(),
host = this.get(HOST),
oh = host.get(DRAG_NODE).get(OFFSET_HEIGHT),
ow = host.get(DRAG_NODE).get(OFFSET_WIDTH);
if (oxy[1] > (r[BOTTOM] - oh)) {
_xy[1] = (r[BOTTOM] - oh);
}
if (r[TOP] > oxy[1]) {
_xy[1] = r[TOP];
}
if (oxy[0] > (r[RIGHT] - ow)) {
_xy[0] = (r[RIGHT] - ow);
}
if (r[LEFT] > oxy[0]) {
_xy[0] = r[LEFT];
}
return _xy;
},
/**
* @method inRegion
* @description Checks if the XY passed or the dragNode is inside the active region.
* @param {Array} xy Optional XY to check, if not supplied this.get('dragNode').getXY() is used.
* @return {Boolean} True if the XY is inside the region, false otherwise.
*/
inRegion: function(xy) {
xy = xy || this.get(HOST).get(DRAG_NODE).getXY();
var _xy = this._checkRegion([xy[0], xy[1]]),
inside = false;
if ((xy[0] === _xy[0]) && (xy[1] === _xy[1])) {
inside = true;
}
return inside;
},
/**
* @method align
* @description Modifies the Drag.actXY method from the after drag:align event. This is where the constraining happens.
*/
align: function() {
var host = this.get(HOST),
_xy = host.actXY,
r = this.getRegion(true);
if (this.get('stickX')) {
_xy[1] = (host.startXY[1] - host.deltaXY[1]);
}
if (this.get('stickY')) {
_xy[0] = (host.startXY[0] - host.deltaXY[0]);
}
if (r) {
_xy = this._checkRegion(_xy);
}
_xy = this._checkTicks(_xy, r);
host.actXY = _xy;
},
/**
* @private
* @method _checkTicks
* @description This method delegates the proper helper method for tick calculations
* @param {Array} xy The XY coords for the Drag
* @param {Object} r The optional region that we are bound to.
* @return {Array} The calced XY coords
*/
_checkTicks: function(xy, r) {
var host = this.get(HOST),
lx = (host.startXY[0] - host.deltaXY[0]),
ly = (host.startXY[1] - host.deltaXY[1]),
xt = this.get('tickX'),
yt = this.get('tickY');
if (xt && !this.get(TICK_X_ARRAY)) {
xy[0] = DDM._calcTicks(xy[0], lx, xt, r[LEFT], r[RIGHT]);
}
if (yt && !this.get(TICK_Y_ARRAY)) {
xy[1] = DDM._calcTicks(xy[1], ly, yt, r[TOP], r[BOTTOM]);
}
if (this.get(TICK_X_ARRAY)) {
xy[0] = DDM._calcTickArray(xy[0], this.get(TICK_X_ARRAY), r[LEFT], r[RIGHT]);
}
if (this.get(TICK_Y_ARRAY)) {
xy[1] = DDM._calcTickArray(xy[1], this.get(TICK_Y_ARRAY), r[TOP], r[BOTTOM]);
}
return xy;
}
};
Y.namespace('plugin');
Y.extend(C, Y.Base, proto);
Y.plugin.DDConstrained = C;
Y.mix(DDM, {
/**
* @for DDM
* @namespace DD
* @private
* @method _calcTicks
* @description Helper method to calculate the tick offsets for a given position
* @param {Number} pos The current X or Y position
* @param {Number} start The start X or Y position
* @param {Number} tick The X or Y tick increment
* @param {Number} off1 The min offset that we can't pass (region)
* @param {Number} off2 The max offset that we can't pass (region)
* @return {Number} The new position based on the tick calculation
*/
_calcTicks: function(pos, start, tick, off1, off2) {
var ix = ((pos - start) / tick),
min = Math.floor(ix),
max = Math.ceil(ix);
if ((min !== 0) || (max !== 0)) {
if ((ix >= min) && (ix <= max)) {
pos = (start + (tick * min));
if (off1 && off2) {
if (pos < off1) {
pos = (start + (tick * (min + 1)));
}
if (pos > off2) {
pos = (start + (tick * (min - 1)));
}
}
}
}
return pos;
},
/**
* @for DDM
* @namespace DD
* @private
* @method _calcTickArray
* @description This method is used with the tickXArray and tickYArray config options
* @param {Number} pos The current X or Y position
* @param {Number} ticks The array containing our custom tick positions.
* @param {Number} off1 The min offset that we can't pass (region)
* @param {Number} off2 The max offset that we can't pass (region)
* @return The tick position
*/
_calcTickArray: function(pos, ticks, off1, off2) {
var i = 0, len = ticks.length, next = 0,
diff1, diff2, ret;
if (!ticks || (ticks.length === 0)) {
return pos;
} else if (ticks[0] >= pos) {
return ticks[0];
} else {
for (i = 0; i < len; i++) {
next = (i + 1);
if (ticks[next] && ticks[next] >= pos) {
diff1 = pos - ticks[i];
diff2 = ticks[next] - pos;
ret = (diff2 > diff1) ? ticks[i] : ticks[next];
if (off1 && off2) {
if (ret > off2) {
if (ticks[i]) {
ret = ticks[i];
} else {
ret = ticks[len - 1];
}
}
}
return ret;
}
}
return ticks[ticks.length - 1];
}
}
});