|
1 /* |
|
2 Copyright (c) 2009, Yahoo! Inc. All rights reserved. |
|
3 Code licensed under the BSD License: |
|
4 http://developer.yahoo.net/yui/license.txt |
|
5 version: 3.0.0b1 |
|
6 build: 1163 |
|
7 */ |
|
8 YUI.add('widget-position-ext', function(Y) { |
|
9 |
|
10 /** |
|
11 * Provides extended/advanced XY positioning support for Widgets, through an extension. |
|
12 * |
|
13 * It builds on top of the widget-position module, to provide alignmentment and centering support. |
|
14 * Future releases aim to add constrained and fixed positioning support. |
|
15 * |
|
16 * @module widget-position-ext |
|
17 */ |
|
18 var L = Y.Lang, |
|
19 ALIGN = "align", |
|
20 |
|
21 BINDUI = "bindUI", |
|
22 SYNCUI = "syncUI", |
|
23 |
|
24 OFFSET_WIDTH = "offsetWidth", |
|
25 OFFSET_HEIGHT = "offsetHeight", |
|
26 VIEWPORT_REGION = "viewportRegion", |
|
27 REGION = "region", |
|
28 |
|
29 AlignChange = "alignChange"; |
|
30 |
|
31 /** |
|
32 * Widget extension, which can be used to add extended XY positioning support to the base Widget class, |
|
33 * through the <a href="Base.html#method_build">Base.build</a> method. This extension requires that |
|
34 * the WidgetPosition extension be added to the Widget (before WidgetPositionExt, if part of the same |
|
35 * extension list passed to Base.build). |
|
36 * |
|
37 * @class WidgetPositionExt |
|
38 * @param {Object} User configuration object |
|
39 */ |
|
40 function PositionExt(config) { |
|
41 if (!this.hasImpl(Y.WidgetPosition) || !this._posNode) { |
|
42 Y.error("WidgetPosition needs to be added to the Widget, before WidgetPositionExt is added"); |
|
43 } |
|
44 Y.after(this._syncUIPosExtras, this, SYNCUI); |
|
45 Y.after(this._bindUIPosExtras, this, BINDUI); |
|
46 } |
|
47 |
|
48 /** |
|
49 * Static property used to define the default attribute |
|
50 * configuration introduced by WidgetPositionExt. |
|
51 * |
|
52 * @property WidgetPositionExt.ATTRS |
|
53 * @type Object |
|
54 * @static |
|
55 */ |
|
56 PositionExt.ATTRS = { |
|
57 |
|
58 /** |
|
59 * @attribute align |
|
60 * @type Object |
|
61 * @default null |
|
62 * @desciption The align attribute is used to align a reference point on the widget, with the refernce point on another node, or the viewport. |
|
63 * The object which align expects has the following properties: |
|
64 * <dl> |
|
65 * <dt>node</dt> |
|
66 * <dd> |
|
67 * The node to which the Widget is to be aligned. If set to null, or not provided, the Widget is aligned to the viewport |
|
68 * </dd> |
|
69 * <dt>points</dt> |
|
70 * <dd> |
|
71 * <p> |
|
72 * A two element array, defining the two points on the Widget and node/viewport which are to be aligned. The first element is the point on the Widget, and the second element is the point on the node/viewport. |
|
73 * Supported alignment points are defined as static properties on <code>WidgetPositionExt</code>. |
|
74 * </p> |
|
75 * <p> |
|
76 * e.g. <code>[WidgetPositionExt.TR, WidgetPositionExt.TL]</code> aligns the Top-Right corner of the Widget with the |
|
77 * Top-Left corner of the node/viewport, and <code>[WidgetPositionExt.CC, WidgetPositionExt.TC]</code> aligns the Center of the |
|
78 * Widget with the Top-Center edge of the node/viewport. |
|
79 * </p> |
|
80 * </dd> |
|
81 * </dl> |
|
82 */ |
|
83 align: { |
|
84 value:null |
|
85 }, |
|
86 |
|
87 /** |
|
88 * @attribute centered |
|
89 * @type {boolean | node} |
|
90 * @default false |
|
91 * @description A convenience attribute, which can be used as a shortcut for the align attribute. |
|
92 * If set to true, the Widget is centered in the viewport. If set to a node reference or valid selector string, |
|
93 * the Widget will be centered within the node. If set the false, no center positioning is applied. |
|
94 */ |
|
95 centered: { |
|
96 setter: function(val) { |
|
97 return this._setAlignCenter(val); |
|
98 }, |
|
99 value:false |
|
100 } |
|
101 }; |
|
102 |
|
103 /** |
|
104 * Constant used to specify the top-left corner for alignment |
|
105 * |
|
106 * @property WidgetPositionExt.TL |
|
107 * @type String |
|
108 * @static |
|
109 * @value "tl" |
|
110 */ |
|
111 PositionExt.TL = "tl"; |
|
112 /** |
|
113 * Constant used to specify the top-right corner for alignment |
|
114 * |
|
115 * @property WidgetPositionExt.TR |
|
116 * @type String |
|
117 * @static |
|
118 * @value "tr" |
|
119 */ |
|
120 PositionExt.TR = "tr"; |
|
121 /** |
|
122 * Constant used to specify the bottom-left corner for alignment |
|
123 * |
|
124 * @property WidgetPositionExt.BL |
|
125 * @type String |
|
126 * @static |
|
127 * @value "bl" |
|
128 */ |
|
129 PositionExt.BL = "bl"; |
|
130 /** |
|
131 * Constant used to specify the bottom-right corner for alignment |
|
132 * |
|
133 * @property WidgetPositionExt.BR |
|
134 * @type String |
|
135 * @static |
|
136 * @value "br" |
|
137 */ |
|
138 PositionExt.BR = "br"; |
|
139 /** |
|
140 * Constant used to specify the top edge-center point for alignment |
|
141 * |
|
142 * @property WidgetPositionExt.TC |
|
143 * @type String |
|
144 * @static |
|
145 * @value "tc" |
|
146 */ |
|
147 PositionExt.TC = "tc"; |
|
148 /** |
|
149 * Constant used to specify the right edge, center point for alignment |
|
150 * |
|
151 * @property WidgetPositionExt.RC |
|
152 * @type String |
|
153 * @static |
|
154 * @value "rc" |
|
155 */ |
|
156 PositionExt.RC = "rc"; |
|
157 /** |
|
158 * Constant used to specify the bottom edge, center point for alignment |
|
159 * |
|
160 * @property WidgetPositionExt.BC |
|
161 * @type String |
|
162 * @static |
|
163 * @value "bc" |
|
164 */ |
|
165 PositionExt.BC = "bc"; |
|
166 /** |
|
167 * Constant used to specify the left edge, center point for alignment |
|
168 * |
|
169 * @property WidgetPositionExt.LC |
|
170 * @type String |
|
171 * @static |
|
172 * @value "lc" |
|
173 */ |
|
174 PositionExt.LC = "lc"; |
|
175 /** |
|
176 * Constant used to specify the center of widget/node/viewport for alignment |
|
177 * |
|
178 * @property WidgetPositionExt.CC |
|
179 * @type String |
|
180 * @static |
|
181 * @value "cc" |
|
182 */ |
|
183 PositionExt.CC = "cc"; |
|
184 |
|
185 PositionExt.prototype = { |
|
186 |
|
187 /** |
|
188 * Synchronizes the UI to match the Widgets extended positioning state. |
|
189 * This method in invoked after syncUI is invoked for the Widget class |
|
190 * using YUI's aop infrastructure. |
|
191 * |
|
192 * @method _syncUIPosExtras |
|
193 * @protected |
|
194 */ |
|
195 _syncUIPosExtras : function() { |
|
196 var align = this.get(ALIGN); |
|
197 if (align) { |
|
198 this._uiSetAlign(align.node, align.points); |
|
199 } |
|
200 }, |
|
201 |
|
202 /** |
|
203 * Binds event listeners responsible for updating the UI state in response to |
|
204 * Widget extended positioning related state changes. |
|
205 * <p> |
|
206 * This method is invoked after bindUI is invoked for the Widget class |
|
207 * using YUI's aop infrastructure. |
|
208 * </p> |
|
209 * @method _bindUIStack |
|
210 * @protected |
|
211 */ |
|
212 _bindUIPosExtras : function() { |
|
213 this.after(AlignChange, this._afterAlignChange); |
|
214 }, |
|
215 |
|
216 /** |
|
217 * Default setter for center attribute changes. Sets up the appropriate value, and passes |
|
218 * it through the to the align attribute. |
|
219 * |
|
220 * @method _setAlignCenter |
|
221 * @protected |
|
222 * @param {boolean | node} The attribute value being set. |
|
223 * @return {Number} The attribute value being set. |
|
224 */ |
|
225 _setAlignCenter : function(val) { |
|
226 if (val) { |
|
227 this.set(ALIGN, { |
|
228 node: val === true ? null : val, |
|
229 points: [PositionExt.CC, PositionExt.CC] |
|
230 }); |
|
231 } |
|
232 return val; |
|
233 }, |
|
234 |
|
235 /** |
|
236 * Default attribute change listener for the align attribute, responsible |
|
237 * for updating the UI, in response to attribute changes. |
|
238 * |
|
239 * @method _afterAlignChange |
|
240 * @protected |
|
241 * @param {EventFacade} e The event facade for the attribute change |
|
242 */ |
|
243 _afterAlignChange : function(e) { |
|
244 if (e.newVal) { |
|
245 this._uiSetAlign(e.newVal.node, e.newVal.points); |
|
246 } |
|
247 }, |
|
248 |
|
249 /** |
|
250 * Updates the UI to reflect the align value passed in (see the align attribute documentation, for the object stucture expected) |
|
251 * @method _uiSetAlign |
|
252 * @protected |
|
253 * @param {Node | null} The node to align to, or null to indicate the viewport |
|
254 */ |
|
255 _uiSetAlign: function (node, points) { |
|
256 |
|
257 if (!L.isArray(points) || points.length != 2) { |
|
258 Y.error("align: Invalid Points Arguments"); |
|
259 return; |
|
260 } |
|
261 |
|
262 var nodeRegion, widgetPoint, nodePoint, xy; |
|
263 |
|
264 if (!node) { |
|
265 nodeRegion = this._posNode.get(VIEWPORT_REGION); |
|
266 } else { |
|
267 node = Y.Node.get(node); |
|
268 if (node) { |
|
269 nodeRegion = node.get(REGION); |
|
270 } |
|
271 } |
|
272 |
|
273 if (nodeRegion) { |
|
274 |
|
275 // TODO: ViewportRegion doesn't have width/height - Workaround until normalized in Node/Dom |
|
276 nodeRegion.width = nodeRegion.width || nodeRegion.right - nodeRegion.left; |
|
277 nodeRegion.height = nodeRegion.height || nodeRegion.bottom - nodeRegion.top; |
|
278 |
|
279 widgetPoint = points[0]; |
|
280 nodePoint = points[1]; |
|
281 |
|
282 // TODO: Optimize KWeight - Would lookup table help? |
|
283 switch (nodePoint) { |
|
284 case PositionExt.TL: |
|
285 xy = [nodeRegion.left, nodeRegion.top]; |
|
286 break; |
|
287 case PositionExt.TR: |
|
288 xy = [nodeRegion.right, nodeRegion.top]; |
|
289 break; |
|
290 case PositionExt.BL: |
|
291 xy = [nodeRegion.left, nodeRegion.bottom]; |
|
292 break; |
|
293 case PositionExt.BR: |
|
294 xy = [nodeRegion.right, nodeRegion.bottom]; |
|
295 break; |
|
296 case PositionExt.TC: |
|
297 xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.top]; |
|
298 break; |
|
299 case PositionExt.BC: |
|
300 xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.bottom]; |
|
301 break; |
|
302 case PositionExt.LC: |
|
303 xy = [nodeRegion.left, nodeRegion.top + Math.floor(nodeRegion.height/2)]; |
|
304 break; |
|
305 case PositionExt.RC: |
|
306 xy = [nodeRegion.right, nodeRegion.top + Math.floor(nodeRegion.height/2), widgetPoint]; |
|
307 break; |
|
308 case PositionExt.CC: |
|
309 xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.top + Math.floor(nodeRegion.height/2), widgetPoint]; |
|
310 break; |
|
311 default: |
|
312 Y.log("align: Invalid Points Arguments", "info", "widget-position-extras"); |
|
313 break; |
|
314 } |
|
315 |
|
316 if (xy) { |
|
317 this._doAlign(widgetPoint, xy[0], xy[1]); |
|
318 } |
|
319 } |
|
320 }, |
|
321 |
|
322 /** |
|
323 * Helper method, used to align the given point on the widget, with the XY page co-ordinates provided. |
|
324 * |
|
325 * @method _doAlign |
|
326 * @private |
|
327 * @param {String} widgetPoint Supported point constant (e.g. WidgetPositionExt.TL) |
|
328 * @param {Number} x X page co-ordinate to align to |
|
329 * @param {Number} y Y page co-ordinate to align to |
|
330 */ |
|
331 _doAlign : function(widgetPoint, x, y) { |
|
332 var widgetNode = this._posNode, |
|
333 xy; |
|
334 |
|
335 switch (widgetPoint) { |
|
336 case PositionExt.TL: |
|
337 xy = [x, y]; |
|
338 break; |
|
339 case PositionExt.TR: |
|
340 xy = [x - widgetNode.get(OFFSET_WIDTH), y]; |
|
341 break; |
|
342 case PositionExt.BL: |
|
343 xy = [x, y - widgetNode.get(OFFSET_HEIGHT)]; |
|
344 break; |
|
345 case PositionExt.BR: |
|
346 xy = [x - widgetNode.get(OFFSET_WIDTH), y - widgetNode.get(OFFSET_HEIGHT)]; |
|
347 break; |
|
348 case PositionExt.TC: |
|
349 xy = [x - (widgetNode.get(OFFSET_WIDTH)/2), y]; |
|
350 break; |
|
351 case PositionExt.BC: |
|
352 xy = [x - (widgetNode.get(OFFSET_WIDTH)/2), y - widgetNode.get(OFFSET_HEIGHT)]; |
|
353 break; |
|
354 case PositionExt.LC: |
|
355 xy = [x, y - (widgetNode.get(OFFSET_HEIGHT)/2)]; |
|
356 break; |
|
357 case PositionExt.RC: |
|
358 xy = [(x - widgetNode.get(OFFSET_WIDTH)), y - (widgetNode.get(OFFSET_HEIGHT)/2)]; |
|
359 break; |
|
360 case PositionExt.CC: |
|
361 xy = [x - (widgetNode.get(OFFSET_WIDTH)/2), y - (widgetNode.get(OFFSET_HEIGHT)/2)]; |
|
362 break; |
|
363 default: |
|
364 Y.log("align: Invalid Points Argument", "info", "widget-position-extras"); |
|
365 break; |
|
366 } |
|
367 |
|
368 if (xy) { |
|
369 this.move(xy); |
|
370 } |
|
371 }, |
|
372 |
|
373 /** |
|
374 * Aligns the Widget to the provided node (or viewport) using the provided |
|
375 * points. The method can be invoked directly, however it will result in |
|
376 * the align attribute being out of sync with current position of the of Widget. |
|
377 * |
|
378 * @method align |
|
379 * @param {Node | String | null} node A reference (or selector string) for the Node which with the Widget is to be aligned. |
|
380 * If null is passed in, the Widget will be aligned with the viewport. |
|
381 * @param {Array[2]} points A two element array, specifying the points on the Widget and node/viewport which need to be aligned. |
|
382 * The first entry is the point on the Widget, and the second entry is the point on the node/viewport which need to align. |
|
383 * Valid point references are defined as static constants on the WidgetPositionExt class. |
|
384 * |
|
385 * e.g. [WidgetPositionExt.TL, WidgetPositionExt.TR] will align the top-left corner of the Widget with the top-right corner of the node/viewport. |
|
386 */ |
|
387 align: function (node, points) { |
|
388 this.set(ALIGN, {node: node, points:points}); |
|
389 }, |
|
390 |
|
391 /** |
|
392 * Centers the container in the viewport, or if a node is passed in, |
|
393 * the node. |
|
394 * |
|
395 * @method centered |
|
396 * @param {Node | String} node Optional. A node reference or selector string defining the node |
|
397 * inside which the Widget is to be centered. If not passed in, the Widget will be centered in the |
|
398 * viewport. |
|
399 */ |
|
400 centered: function (node) { |
|
401 this.align(node, [PositionExt.CC, PositionExt.CC]); |
|
402 } |
|
403 }; |
|
404 |
|
405 Y.WidgetPositionExt = PositionExt; |
|
406 |
|
407 |
|
408 |
|
409 }, '3.0.0b1' ,{requires:['widget', 'widget-position']}); |