Commit | Line | Data |
---|---|---|
6a1aa64f DV |
1 | .. title:: MochiKit.Visual - visual effects |
2 | ||
3 | Name | |
4 | ==== | |
5 | ||
6 | MochiKit.Visual - visual effects | |
7 | ||
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | :: | |
13 | ||
14 | // round the corners of all h1 elements | |
15 | roundClass("h1", null); | |
16 | ||
17 | // round the top left corner of the element with the id "title" | |
18 | roundElement("title", {corners: "tl"}); | |
19 | ||
20 | // Add an fade effect to an element | |
21 | fade('myelement'); | |
22 | ||
23 | ||
24 | Description | |
25 | =========== | |
26 | ||
27 | MochiKit.Visual provides visual effects and support functions for | |
28 | visuals. | |
29 | ||
30 | ||
31 | Dependencies | |
32 | ============ | |
33 | ||
34 | - :mochiref:`MochiKit.Base` | |
35 | - :mochiref:`MochiKit.Iter` | |
36 | - :mochiref:`MochiKit.DOM` | |
37 | - :mochiref:`MochiKit.Color` | |
38 | - :mochiref:`MochiKit.Position` | |
39 | ||
40 | Overview | |
41 | ======== | |
42 | ||
43 | MochiKit.Visual provides different visual effect: rounded corners and | |
44 | animations for your HTML elements. Rounded corners are created | |
45 | completely through CSS manipulations and require no external images or | |
46 | style sheets. This implementation was adapted from Rico_. Dynamic | |
47 | effects are ported from Scriptaculous_. | |
48 | ||
49 | .. _Rico: http://www.openrico.org | |
50 | ||
51 | .. _Scriptaculous: http://script.aculo.us | |
52 | ||
53 | ||
54 | API Reference | |
55 | ============= | |
56 | ||
57 | Functions | |
58 | --------- | |
59 | ||
60 | :mochidef:`roundClass(tagName[, className[, options]])`: | |
61 | ||
62 | Rounds all of the elements that match the ``tagName`` and | |
63 | ``className`` specifiers, using the options provided. ``tagName`` | |
64 | or ``className`` can be ``null`` to match all tags or classes. | |
65 | For more information about the options, see the | |
66 | :mochiref:`roundElement` function. | |
67 | ||
68 | *Availability*: | |
69 | Available in MochiKit 1.3.1+ | |
70 | ||
71 | ||
72 | :mochidef:`roundElement(element[, options])`: | |
73 | ||
74 | Immediately round the corners of the specified element. The | |
75 | element can be given as either a string with the element ID, or as | |
76 | an element object. | |
77 | ||
78 | The options mapping has the following defaults: | |
79 | ||
80 | ========= ================= | |
81 | corners ``"all"`` | |
82 | color ``"fromElement"`` | |
83 | bgColor ``"fromParent"`` | |
84 | blend ``true`` | |
85 | border ``false`` | |
86 | compact ``false`` | |
87 | ========= ================= | |
88 | ||
89 | corners: | |
90 | ||
91 | specifies which corners of the element should be rounded. | |
92 | Choices are: | |
93 | ||
94 | - all | |
95 | - top | |
96 | - bottom | |
97 | - tl (top left) | |
98 | - bl (bottom left) | |
99 | - tr (top right) | |
100 | - br (bottom right) | |
101 | ||
102 | Example: | |
103 | ``"tl br"``: top-left and bottom-right corners are rounded | |
104 | ||
105 | blend: | |
106 | specifies whether the color and background color should be | |
107 | blended together to produce the border color. | |
108 | ||
109 | *Availability*: | |
110 | Available in MochiKit 1.3.1+ | |
111 | ||
112 | ||
113 | :mochidef:`toggle(element[, effect[, options]])`: | |
114 | ||
115 | Toggle an element between visible and invisible state using an effect. | |
116 | ||
117 | effect: | |
118 | One of the visual pairs to use, between 'slide', 'blind', | |
119 | 'appear', and 'size'. | |
120 | ||
121 | *Availability*: | |
122 | Available in MochiKit 1.4+ | |
123 | ||
124 | ||
125 | :mochidef:`tagifyText(element[, tagifyStyle])`: | |
126 | ||
127 | Transform a node text into nodes containing one letter by tag. | |
128 | ||
129 | tagifyStyle: | |
130 | style to apply to character nodes, default to 'position: | |
131 | relative'. | |
132 | ||
133 | *Availability*: | |
134 | Available in MochiKit 1.4+ | |
135 | ||
136 | ||
137 | :mochidef:`multiple(elements, effect[, options])`: | |
138 | ||
139 | Launch the same effect on a list of elements. | |
140 | ||
141 | *Availability*: | |
142 | Available in MochiKit 1.4+ | |
143 | ||
144 | ||
145 | Basic Effects classes | |
146 | --------------------- | |
147 | ||
148 | :mochidef:`DefaultOptions`: | |
149 | ||
150 | Default options for all Effect creation. | |
151 | ||
152 | =========== ======================================== | |
153 | transition ``MochiKit.Visual.Transitions.sinoidal`` | |
154 | duration ``1.0`` | |
155 | fps ``25.0`` | |
156 | sync ``false`` | |
157 | from ``0.0`` | |
158 | to ``1.0`` | |
159 | delay ``0.0`` | |
160 | queue ``'parallel'`` | |
161 | =========== ======================================== | |
162 | ||
163 | *Availability*: | |
164 | Available in MochiKit 1.4+ | |
165 | ||
166 | ||
167 | :mochidef:`Base()`: | |
168 | ||
169 | Base class to all effects. Define a basic looping service, use it | |
170 | for creating new effects. | |
171 | ||
172 | You can override the methods ``setup``, ``update`` and ``finish```. | |
173 | ||
174 | The class defines a number of events that will be called during effect | |
175 | life. The events are: | |
176 | ||
177 | - beforeStart | |
178 | - beforeSetup | |
179 | - beforeUpdate | |
180 | - afterUpdate | |
181 | - beforeFinish | |
182 | - afterFinish | |
183 | ||
184 | If you want to define your own callbacks, define it in the options | |
185 | parameter of the effect. Example:: | |
186 | ||
187 | // I slide it up and then down again | |
188 | slideUp('myelement', {afterFinish: function () { | |
189 | slideDown('myelement'); | |
190 | }); | |
191 | ||
192 | Specific ``internal`` events are also available: for each one abone the | |
193 | same exists with 'Internal' (example: 'beforeStartInternal'). Their purpose | |
194 | is mainly for creating your own effect and keep the user access to event | |
195 | callbacks (not overriding the library ones). | |
196 | ||
197 | *Availability*: | |
198 | Available in MochiKit 1.4+ | |
199 | ||
200 | ||
201 | :mochidef:`Parallel(effects [, options])`: | |
202 | ||
203 | Launch effects in parallel. | |
204 | ||
205 | *Availability*: | |
206 | Available in MochiKit 1.4+ | |
207 | ||
208 | ||
209 | :mochidef:`Opacity(element [, options])`: | |
210 | ||
211 | Change the opacity of an element progressively. | |
212 | ||
213 | options: | |
214 | ||
215 | ====== ======== | |
216 | from ``0.0`` | |
217 | to ``1.0`` | |
218 | ====== ======== | |
219 | ||
220 | *Availability*: | |
221 | Available in MochiKit 1.4+ | |
222 | ||
223 | ||
224 | :mochidef:`Move(element [, options])`: | |
225 | ||
226 | Change the position of an element in small steps, creating a | |
227 | moving effect. | |
228 | ||
229 | options: | |
230 | ||
231 | ========= ================ | |
232 | x ``0`` | |
233 | y ``0`` | |
234 | position ``'relative'`` | |
235 | ========= ================ | |
236 | ||
237 | *Availability*: | |
238 | Available in MochiKit 1.4+ | |
239 | ||
240 | ||
241 | :mochidef:`Scale(element, percent [, options])`: | |
242 | ||
243 | Change the size of an element. | |
244 | ||
245 | percent: | |
246 | Final wanted size in percent of current size. The size will be | |
247 | reduced if the value is between 0 and 100, and raised if the | |
248 | value is above 100. | |
249 | ||
250 | options: | |
251 | ||
252 | ================ ============ | |
253 | scaleX ``true`` | |
254 | scaleY ``true`` | |
255 | scaleContent ``true`` | |
256 | scaleFromCenter ``false`` | |
257 | scaleMode ``'box'`` | |
258 | scaleFrom ``100.0`` | |
259 | scaleTo ``percent`` | |
260 | ================ ============ | |
261 | ||
262 | *Availability*: | |
263 | Available in MochiKit 1.4+ | |
264 | ||
265 | ||
266 | :mochidef:`Highlight(element [, options])`: | |
267 | ||
268 | Highlight an element, flashing with one color. | |
269 | ||
270 | options: | |
271 | ||
272 | =========== ============== | |
273 | startcolor ``'#ffff99'`` | |
274 | =========== ============== | |
275 | ||
276 | *Availability*: | |
277 | Available in MochiKit 1.4+ | |
278 | ||
279 | ||
280 | :mochidef:`ScrollTo(element [, options])`: | |
281 | ||
282 | Scroll the window to the position of the given element. | |
283 | ||
284 | *Availability*: | |
285 | Available in MochiKit 1.4+ | |
286 | ||
287 | ||
288 | :mochidef:`Morph(element [, options])`: | |
289 | ||
290 | Make a transformation to the given element. It's called with the option | |
291 | ``style`` with an array holding the styles to change. It works with | |
292 | properties for size (``font-size``, ``border-width``, ...) and properties | |
293 | for color (``color``, ``background-color``, ...). | |
294 | ||
295 | For size, it's better to have defined the original style. You *must* | |
296 | use the same unit in the call to Morph (no translation exists between two | |
297 | different units). | |
298 | ||
299 | Parsed length are postfixed with: em, ex, px, in, cm, mm, pt, pc. | |
300 | ||
301 | Example:: | |
302 | ||
303 | <div id="foo" style="font-size: 1em">MyDiv</div> | |
304 | ... | |
305 | Morph("foo", {"style": {"font-size": "2em"}}); | |
306 | ||
307 | ||
308 | *Availability*: | |
309 | Available in MochiKit 1.4+ | |
310 | ||
311 | ||
312 | Combination Effects | |
313 | ------------------- | |
314 | ||
315 | :mochidef:`fade(element [, options])`: | |
316 | ||
317 | Change the opacity of an element until making it disappear. | |
318 | ||
319 | options: | |
320 | ||
321 | ====== ============================================= | |
322 | from ``element.opacity || 1.0`` | |
323 | to ``0.0`` | |
324 | ====== ============================================= | |
325 | ||
326 | *Availability*: | |
327 | Available in MochiKit 1.4+ | |
328 | ||
329 | ||
330 | :mochidef:`appear(element [, options])`: | |
331 | ||
332 | Slowly show an invisible element. | |
333 | ||
334 | options: | |
335 | ||
336 | ===== ========= | |
337 | from ``0.0`` | |
338 | to ``1.0`` | |
339 | ===== ========= | |
340 | ||
341 | *Availability*: | |
342 | Available in MochiKit 1.4+ | |
343 | ||
344 | ||
345 | :mochidef:`puff(element [, options])`: | |
346 | ||
347 | Make an element double size, and then make it disappear. | |
348 | ||
349 | *Availability*: | |
350 | Available in MochiKit 1.4+ | |
351 | ||
352 | ||
353 | :mochidef:`blindUp(element [, options])`: | |
354 | ||
355 | Blind an element up, changing its vertical size to 0. | |
356 | ||
357 | *Availability*: | |
358 | Available in MochiKit 1.4+ | |
359 | ||
360 | ||
361 | :mochidef:`blindDown(element [, options])`: | |
362 | ||
363 | Blind an element down, restoring its vertical size. | |
364 | ||
365 | *Availability*: | |
366 | Available in MochiKit 1.4+ | |
367 | ||
368 | ||
369 | :mochidef:`switchOff(element [, options])`: | |
370 | ||
371 | A switch-off like effect, making the element disappear. | |
372 | ||
373 | *Availability*: | |
374 | Available in MochiKit 1.4+ | |
375 | ||
376 | ||
377 | :mochidef:`dropOut(element [, options])`: | |
378 | ||
379 | Make the element fall and fade. | |
380 | ||
381 | options: | |
382 | ||
383 | ======== ======= | |
384 | distance ``100`` | |
385 | ======== ======= | |
386 | ||
387 | *Availability*: | |
388 | Available in MochiKit 1.4+ | |
389 | ||
390 | ||
391 | :mochidef:`shake(element [, options])`: | |
392 | ||
393 | Shake an element from left to right. | |
394 | ||
395 | *Availability*: | |
396 | Available in MochiKit 1.4+ | |
397 | ||
398 | ||
399 | :mochidef:`slideDown(element [, options])`: | |
400 | ||
401 | Slide an element down. | |
402 | ||
403 | *Availability*: | |
404 | Available in MochiKit 1.4+ | |
405 | ||
406 | ||
407 | :mochidef:`slideUp(element [, options])`: | |
408 | ||
409 | Slide an element up. | |
410 | ||
411 | *Availability*: | |
412 | Available in MochiKit 1.4+ | |
413 | ||
414 | ||
415 | :mochidef:`squish(element [, options])`: | |
416 | ||
417 | Reduce the horizontal and vertical sizes at the same time, using | |
418 | the top left corner. | |
419 | ||
420 | *Availability*: | |
421 | Available in MochiKit 1.4+ | |
422 | ||
423 | ||
424 | :mochidef:`grow(element [, options])`: | |
425 | ||
426 | Restore the size of an element. | |
427 | ||
428 | *Availability*: | |
429 | Available in MochiKit 1.4+ | |
430 | ||
431 | ||
432 | :mochidef:`shrink(element [, options])`: | |
433 | ||
434 | Shrink an element to its center. | |
435 | ||
436 | *Availability*: | |
437 | Available in MochiKit 1.4+ | |
438 | ||
439 | ||
440 | :mochidef:`pulsate(element [, options])`: | |
441 | ||
442 | Switch an element between appear and fade. | |
443 | ||
444 | options: | |
445 | ||
446 | ====== ======== | |
447 | pulses ``null`` | |
448 | ====== ======== | |
449 | ||
450 | pulses controls the number of pulses made during the effect. | |
451 | ||
452 | *Availability*: | |
453 | Available in MochiKit 1.4+ | |
454 | ||
455 | ||
456 | :mochidef:`fold(element [, options])`: | |
457 | ||
458 | Reduce first the vertical size, and then the horizontal size. | |
459 | ||
460 | *Availability*: | |
461 | Available in MochiKit 1.4+ | |
462 | ||
463 | ||
464 | The Effects Queue | |
465 | ----------------- | |
466 | ||
467 | When you create effects based on user input (mouse clicks for example), it can | |
468 | create conflicts between the effects if multiple effects are running at the | |
469 | same time. To manage this problem, the Queue mechanism has been introduced: | |
470 | it's responsible for running the effects as you desired. | |
471 | ||
472 | By default, you have one Queue called 'global', and the effects run in 'parallel' | |
473 | (see default options). Every effects have a queue option to customize this. | |
474 | It can be a string, the scope is then global: | |
475 | ||
476 | - `start`: the effect will be run before any other; | |
477 | - `end`: the effect will be run after any other; | |
478 | - `break`: every other effects break when the the effect start; | |
479 | - `parallel`: the effect run normally with others. | |
480 | ||
481 | ||
482 | But you have even more control if you use an array with the following keys: | |
483 | ||
484 | - `position` takes a value listed above; | |
485 | - `scope` manages how the information has to be taken. If it's `global` | |
486 | then it's the same information for every effects. Otherwise you can define | |
487 | your own scode. For example, if you add an effect on a specified element, | |
488 | you may use the element id as scode; | |
489 | - `limit` defines how many effects can run in the current scode. If an | |
490 | effect is added whereas the limit is reached, it will never be run (it's | |
491 | lost). | |
492 | ||
493 | ||
494 | See Also | |
495 | ======== | |
496 | ||
497 | .. [1] Application Kit Reference - NSColor: http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSColor.html | |
498 | .. [2] SVG 1.0 color keywords: http://www.w3.org/TR/SVG/types.html#ColorKeywords | |
499 | .. [3] W3C CSS3 Color Module: http://www.w3.org/TR/css3-color/#svg-color | |
500 | ||
501 | ||
502 | Authors | |
503 | ======= | |
504 | ||
505 | - Kevin Dangoor <dangoor@gmail.com> | |
506 | - Bob Ippolito <bob@redivi.com> | |
507 | - Thomas Herve <therve@gmail.com> | |
508 | - Round corners originally adapted from Rico <http://openrico.org/> | |
509 | (though little remains) | |
510 | - Effects originally adapted from Script.aculo.us | |
511 | <http://script.aculo.us/> | |
512 | ||
513 | ||
514 | Copyright | |
515 | ========= | |
516 | ||
517 | Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is | |
518 | dual-licensed free software; you can redistribute it and/or modify it | |
519 | under the terms of the `MIT License`_ or the `Academic Free License | |
520 | v2.1`_. | |
521 | ||
522 | .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php | |
523 | .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php | |
524 | ||
525 | Portions adapted from `Rico`_ are available under the terms of the | |
526 | `Apache License, Version 2.0`_. | |
527 | ||
528 | Portions adapted from `Scriptaculous`_ are available under the terms | |
529 | of the `MIT License`_. | |
530 | ||
531 | .. _`Apache License, Version 2.0`: http://www.apache.org/licenses/LICENSE-2.0.html |