← Back to branch summary

~bac/juju-gui/trunkcopy

« back to all changes in this revision

Viewing changes to lib/yui/build/widget-position-constrain/widget-position-constrain.js

  • Committer: kapil.foss at gmail
  • Date: 2012-07-13 18:45:59 UTC
  • Revision ID: kapil.foss@gmail.com-20120713184559-2xl7be17egsrz0c9
reshape

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/yui/build/widget-position-constrain/widget-position-constrain.js
1
 
/*
2
 
YUI 3.5.1 (build 22)
3
 
Copyright 2012 Yahoo! Inc. All rights reserved.
4
 
Licensed under the BSD License.
5
 
http://yuilibrary.com/license/
6
 
*/
7
 
YUI.add('widget-position-constrain', function(Y) {
8
 
 
9
 
/**
10
 
 * Provides constrained xy positioning support for Widgets, through an extension.
11
 
 *
12
 
 * It builds on top of the widget-position module, to provide constrained positioning support.
13
 
 *
14
 
 * @module widget-position-constrain
15
 
 */
16
 
var CONSTRAIN = "constrain",
17
 
    CONSTRAIN_XYCHANGE = "constrain|xyChange",
18
 
    CONSTRAIN_CHANGE = "constrainChange",
19
 
 
20
 
    PREVENT_OVERLAP = "preventOverlap",
21
 
    ALIGN = "align",
22
 
    
23
 
    EMPTY_STR = "",
24
 
 
25
 
    BINDUI = "bindUI",
26
 
 
27
 
    XY = "xy",
28
 
    X_COORD = "x",
29
 
    Y_COORD = "y",
30
 
 
31
 
    Node = Y.Node,
32
 
 
33
 
    VIEWPORT_REGION = "viewportRegion",
34
 
    REGION = "region",
35
 
 
36
 
    PREVENT_OVERLAP_MAP;
37
 
 
38
 
/**
39
 
 * A widget extension, which can be used to add constrained xy positioning support to the base Widget class,
40
 
 * through the <a href="Base.html#method_build">Base.build</a> method. This extension requires that 
41
 
 * the WidgetPosition extension be added to the Widget (before WidgetPositionConstrain, if part of the same 
42
 
 * extension list passed to Base.build).
43
 
 *
44
 
 * @class WidgetPositionConstrain
45
 
 * @param {Object} User configuration object
46
 
 */
47
 
function PositionConstrain(config) {
48
 
    if (!this._posNode) {
49
 
        Y.error("WidgetPosition needs to be added to the Widget, before WidgetPositionConstrain is added"); 
50
 
    }
51
 
    Y.after(this._bindUIPosConstrained, this, BINDUI);
52
 
}
53
 
 
54
 
/**
55
 
 * Static property used to define the default attribute 
56
 
 * configuration introduced by WidgetPositionConstrain.
57
 
 *
58
 
 * @property ATTRS
59
 
 * @type Object
60
 
 * @static
61
 
 */
62
 
PositionConstrain.ATTRS = {
63
 
 
64
 
    /**
65
 
     * @attribute constrain
66
 
     * @type boolean | Node
67
 
     * @default null
68
 
     * @description The node to constrain the widget's bounding box to, when setting xy. Can also be
69
 
     * set to true, to constrain to the viewport.
70
 
     */
71
 
    constrain : {
72
 
        value: null,
73
 
        setter: "_setConstrain"
74
 
    },
75
 
 
76
 
    /**
77
 
     * @attribute preventOverlap
78
 
     * @type boolean
79
 
     * @description If set to true, and WidgetPositionAlign is also added to the Widget, 
80
 
     * constrained positioning will attempt to prevent the widget's bounding box from overlapping 
81
 
     * the element to which it has been aligned, by flipping the orientation of the alignment
82
 
     * for corner based alignments  
83
 
     */
84
 
    preventOverlap : {
85
 
        value:false
86
 
    }
87
 
};
88
 
 
89
 
/**
90
 
 * @property _PREVENT_OVERLAP
91
 
 * @static
92
 
 * @protected
93
 
 * @type Object
94
 
 * @description The set of positions for which to prevent
95
 
 * overlap.
96
 
 */
97
 
PREVENT_OVERLAP_MAP = PositionConstrain._PREVENT_OVERLAP = {
98
 
    x: {
99
 
        "tltr": 1,
100
 
        "blbr": 1,
101
 
        "brbl": 1,
102
 
        "trtl": 1
103
 
    },
104
 
    y : {
105
 
        "trbr": 1,
106
 
        "tlbl": 1,
107
 
        "bltl": 1,
108
 
        "brtr": 1
109
 
    }
110
 
};
111
 
 
112
 
PositionConstrain.prototype = {
113
 
 
114
 
    /**
115
 
     * Calculates the constrained positions for the XY positions provided, using
116
 
     * the provided node argument is passed in. If no node value is passed in, the value of 
117
 
     * the "constrain" attribute is used.
118
 
     * 
119
 
     * @method getConstrainedXY
120
 
     * @param {Array} xy The xy values to constrain
121
 
     * @param {Node | boolean} node Optional. The node to constrain to, or true for the viewport
122
 
     * @return {Array} The constrained xy values
123
 
     */
124
 
    getConstrainedXY : function(xy, node) {
125
 
        node = node || this.get(CONSTRAIN);
126
 
 
127
 
        var constrainingRegion = this._getRegion((node === true) ? null : node),
128
 
            nodeRegion = this._posNode.get(REGION);
129
 
 
130
 
        return [
131
 
            this._constrain(xy[0], X_COORD, nodeRegion, constrainingRegion),
132
 
            this._constrain(xy[1], Y_COORD, nodeRegion, constrainingRegion)
133
 
        ];
134
 
    },
135
 
 
136
 
    /**
137
 
     * Constrains the widget's bounding box to a node (or the viewport). If xy or node are not 
138
 
     * passed in, the current position and the value of "constrain" will be used respectively.
139
 
     * 
140
 
     * The widget's position will be changed to the constrained position.
141
 
     *
142
 
     * @method constrain 
143
 
     * @param {Array} xy Optional. The xy values to constrain
144
 
     * @param {Node | boolean} node Optional. The node to constrain to, or true for the viewport
145
 
     */
146
 
    constrain : function(xy, node) {
147
 
        var currentXY, 
148
 
            constrainedXY,
149
 
            constraint = node || this.get(CONSTRAIN);
150
 
 
151
 
        if (constraint) {
152
 
            currentXY = xy || this.get(XY);
153
 
            constrainedXY = this.getConstrainedXY(currentXY, constraint);
154
 
 
155
 
            if (constrainedXY[0] !== currentXY[0] || constrainedXY[1] !== currentXY[1]) {
156
 
                this.set(XY, constrainedXY, { constrained:true });
157
 
            }
158
 
        }
159
 
    },
160
 
 
161
 
    /**
162
 
     * The setter implementation for the "constrain" attribute.
163
 
     *
164
 
     * @method _setConstrain
165
 
     * @protected
166
 
     * @param {Node | boolean} val The attribute value 
167
 
     */
168
 
    _setConstrain : function(val) {
169
 
        return (val === true) ? val : Node.one(val);
170
 
    },
171
 
 
172
 
    /**
173
 
     * The method which performs the actual constrain calculations for a given axis ("x" or "y") based
174
 
     * on the regions provided.
175
 
     * 
176
 
     * @method _constrain
177
 
     * @protected
178
 
     * 
179
 
     * @param {Number} val The value to constrain
180
 
     * @param {String} axis The axis to use for constrainment
181
 
     * @param {Region} nodeRegion The region of the node to constrain
182
 
     * @param {Region} constrainingRegion The region of the node (or viewport) to constrain to
183
 
     * 
184
 
     * @return {Number} The constrained value
185
 
     */
186
 
    _constrain: function(val, axis, nodeRegion, constrainingRegion) {
187
 
        if (constrainingRegion) {
188
 
 
189
 
            if (this.get(PREVENT_OVERLAP)) {
190
 
                val = this._preventOverlap(val, axis, nodeRegion, constrainingRegion);
191
 
            }
192
 
 
193
 
            var x = (axis == X_COORD),
194
 
 
195
 
                regionSize    = (x) ? constrainingRegion.width : constrainingRegion.height,
196
 
                nodeSize      = (x) ? nodeRegion.width : nodeRegion.height,
197
 
                minConstraint = (x) ? constrainingRegion.left : constrainingRegion.top,
198
 
                maxConstraint = (x) ? constrainingRegion.right - nodeSize : constrainingRegion.bottom - nodeSize;
199
 
 
200
 
            if (val < minConstraint || val > maxConstraint) {
201
 
                if (nodeSize < regionSize) {
202
 
                    if (val < minConstraint) {
203
 
                        val = minConstraint;
204
 
                    } else if (val > maxConstraint) {
205
 
                        val = maxConstraint;
206
 
                    }
207
 
                } else {
208
 
                    val = minConstraint;
209
 
                }
210
 
            }
211
 
        }
212
 
 
213
 
        return val;
214
 
    },
215
 
 
216
 
    /**
217
 
     * The method which performs the preventOverlap calculations for a given axis ("x" or "y") based
218
 
     * on the value and regions provided.
219
 
     * 
220
 
     * @method _preventOverlap
221
 
     * @protected
222
 
     *
223
 
     * @param {Number} val The value being constrain
224
 
     * @param {String} axis The axis to being constrained
225
 
     * @param {Region} nodeRegion The region of the node being constrained
226
 
     * @param {Region} constrainingRegion The region of the node (or viewport) we need to constrain to
227
 
     * 
228
 
     * @return {Number} The constrained value
229
 
     */
230
 
    _preventOverlap : function(val, axis, nodeRegion, constrainingRegion) {
231
 
 
232
 
        var align = this.get(ALIGN),
233
 
            x = (axis === X_COORD),
234
 
            nodeSize,
235
 
            alignRegion,
236
 
            nearEdge,
237
 
            farEdge,
238
 
            spaceOnNearSide, 
239
 
            spaceOnFarSide;
240
 
 
241
 
        if (align && align.points && PREVENT_OVERLAP_MAP[axis][align.points.join(EMPTY_STR)]) {
242
 
 
243
 
            alignRegion = this._getRegion(align.node);
244
 
 
245
 
            if (alignRegion) {
246
 
                nodeSize        = (x) ? nodeRegion.width : nodeRegion.height;
247
 
                nearEdge        = (x) ? alignRegion.left : alignRegion.top;
248
 
                farEdge         = (x) ? alignRegion.right : alignRegion.bottom;
249
 
                spaceOnNearSide = (x) ? alignRegion.left - constrainingRegion.left : alignRegion.top - constrainingRegion.top;
250
 
                spaceOnFarSide  = (x) ? constrainingRegion.right - alignRegion.right : constrainingRegion.bottom - alignRegion.bottom;
251
 
            }
252
 
 
253
 
            if (val > nearEdge) {
254
 
                if (spaceOnFarSide < nodeSize && spaceOnNearSide > nodeSize) {
255
 
                    val = nearEdge - nodeSize;
256
 
                }
257
 
            } else {
258
 
                if (spaceOnNearSide < nodeSize && spaceOnFarSide > nodeSize) {
259
 
                    val = farEdge;
260
 
                }
261
 
            }
262
 
        }
263
 
 
264
 
        return val;
265
 
    },
266
 
 
267
 
    /**
268
 
     * Binds event listeners responsible for updating the UI state in response to 
269
 
     * Widget constrained positioning related state changes.
270
 
     * <p>
271
 
     * This method is invoked after bindUI is invoked for the Widget class
272
 
     * using YUI's aop infrastructure.
273
 
     * </p>
274
 
     *
275
 
     * @method _bindUIPosConstrained
276
 
     * @protected
277
 
     */
278
 
    _bindUIPosConstrained : function() {
279
 
        this.after(CONSTRAIN_CHANGE, this._afterConstrainChange);
280
 
        this._enableConstraints(this.get(CONSTRAIN));
281
 
    },
282
 
 
283
 
    /**
284
 
     * After change listener for the "constrain" attribute, responsible
285
 
     * for updating the UI, in response to attribute changes.
286
 
     *
287
 
     * @method _afterConstrainChange
288
 
     * @protected
289
 
     * @param {EventFacade} e The event facade
290
 
     */
291
 
    _afterConstrainChange : function(e) {
292
 
        this._enableConstraints(e.newVal);
293
 
    },
294
 
 
295
 
    /**
296
 
     * Updates the UI if enabling constraints, and sets up the xyChange event listeners
297
 
     * to constrain whenever the widget is moved. Disabling constraints removes the listeners.
298
 
     * 
299
 
     * @method enable or disable constraints listeners
300
 
     * @private
301
 
     * @param {boolean} enable Enable or disable constraints 
302
 
     */
303
 
    _enableConstraints : function(enable) {
304
 
        if (enable) {
305
 
            this.constrain();
306
 
            this._cxyHandle = this._cxyHandle || this.on(CONSTRAIN_XYCHANGE, this._constrainOnXYChange);
307
 
        } else if (this._cxyHandle) {
308
 
            this._cxyHandle.detach();
309
 
            this._cxyHandle = null;    
310
 
        }
311
 
    },
312
 
 
313
 
    /**
314
 
     * The on change listener for the "xy" attribute. Modifies the event facade's
315
 
     * newVal property with the constrained XY value.
316
 
     *
317
 
     * @method _constrainOnXYChange
318
 
     * @protected
319
 
     * @param {EventFacade} e The event facade for the attribute change
320
 
     */
321
 
    _constrainOnXYChange : function(e) {
322
 
        if (!e.constrained) {
323
 
            e.newVal = this.getConstrainedXY(e.newVal);
324
 
        }
325
 
    },
326
 
 
327
 
    /**
328
 
     * Utility method to normalize region retrieval from a node instance, 
329
 
     * or the viewport, if no node is provided. 
330
 
     * 
331
 
     * @method _getRegion
332
 
     * @private
333
 
     * @param {Node} node Optional.
334
 
     */
335
 
    _getRegion : function(node) {
336
 
        var region;
337
 
        if (!node) {
338
 
            region = this._posNode.get(VIEWPORT_REGION);
339
 
        } else {
340
 
            node = Node.one(node);
341
 
            if (node) {
342
 
                region = node.get(REGION);
343
 
            }
344
 
        }
345
 
        return region;
346
 
    }
347
 
};
348
 
 
349
 
Y.WidgetPositionConstrain = PositionConstrain;
350
 
 
351
 
 
352
 
}, '3.5.1' ,{requires:['widget-position']});