1 .. title:: MochiKit.Visual - visual effects
6 MochiKit.Visual - visual effects
14 // round the corners of all h1 elements
15 roundClass("h1", null);
17 // round the top left corner of the element with the id "title"
18 roundElement("title", {corners: "tl"});
20 // Add an fade effect to an element
27 MochiKit.Visual provides visual effects and support functions for
34 - :mochiref:`MochiKit.Base`
35 - :mochiref:`MochiKit.Iter`
36 - :mochiref:`MochiKit.DOM`
37 - :mochiref:`MochiKit.Color`
38 - :mochiref:`MochiKit.Position`
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_.
49 .. _Rico: http://www.openrico.org
51 .. _Scriptaculous: http://script.aculo.us
60 :mochidef:`roundClass(tagName[, className[, options]])`:
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.
69 Available in MochiKit 1.3.1+
72 :mochidef:`roundElement(element[, options])`:
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
78 The options mapping has the following defaults:
80 ========= =================
82 color ``"fromElement"``
83 bgColor ``"fromParent"``
87 ========= =================
91 specifies which corners of the element should be rounded.
103 ``"tl br"``: top-left and bottom-right corners are rounded
106 specifies whether the color and background color should be
107 blended together to produce the border color.
110 Available in MochiKit 1.3.1+
113 :mochidef:`toggle(element[, effect[, options]])`:
115 Toggle an element between visible and invisible state using an effect.
118 One of the visual pairs to use, between 'slide', 'blind',
119 'appear', and 'size'.
122 Available in MochiKit 1.4+
125 :mochidef:`tagifyText(element[, tagifyStyle])`:
127 Transform a node text into nodes containing one letter by tag.
130 style to apply to character nodes, default to 'position:
134 Available in MochiKit 1.4+
137 :mochidef:`multiple(elements, effect[, options])`:
139 Launch the same effect on a list of elements.
142 Available in MochiKit 1.4+
145 Basic Effects classes
146 ---------------------
148 :mochidef:`DefaultOptions`:
150 Default options for all Effect creation.
152 =========== ========================================
153 transition ``MochiKit.Visual.Transitions.sinoidal``
161 =========== ========================================
164 Available in MochiKit 1.4+
169 Base class to all effects. Define a basic looping service, use it
170 for creating new effects.
172 You can override the methods ``setup``, ``update`` and ``finish```.
174 The class defines a number of events that will be called during effect
175 life. The events are:
184 If you want to define your own callbacks, define it in the options
185 parameter of the effect. Example::
187 // I slide it up and then down again
188 slideUp('myelement', {afterFinish: function () {
189 slideDown('myelement');
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).
198 Available in MochiKit 1.4+
201 :mochidef:`Parallel(effects [, options])`:
203 Launch effects in parallel.
206 Available in MochiKit 1.4+
209 :mochidef:`Opacity(element [, options])`:
211 Change the opacity of an element progressively.
221 Available in MochiKit 1.4+
224 :mochidef:`Move(element [, options])`:
226 Change the position of an element in small steps, creating a
231 ========= ================
234 position ``'relative'``
235 ========= ================
238 Available in MochiKit 1.4+
241 :mochidef:`Scale(element, percent [, options])`:
243 Change the size of an element.
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
252 ================ ============
255 scaleContent ``true``
256 scaleFromCenter ``false``
260 ================ ============
263 Available in MochiKit 1.4+
266 :mochidef:`Highlight(element [, options])`:
268 Highlight an element, flashing with one color.
272 =========== ==============
273 startcolor ``'#ffff99'``
274 =========== ==============
277 Available in MochiKit 1.4+
280 :mochidef:`ScrollTo(element [, options])`:
282 Scroll the window to the position of the given element.
285 Available in MochiKit 1.4+
288 :mochidef:`Morph(element [, options])`:
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``, ...).
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
299 Parsed length are postfixed with: em, ex, px, in, cm, mm, pt, pc.
303 <div id="foo" style="font-size: 1em">MyDiv</div>
305 Morph("foo", {"style": {"font-size": "2em"}});
309 Available in MochiKit 1.4+
315 :mochidef:`fade(element [, options])`:
317 Change the opacity of an element until making it disappear.
321 ====== =============================================
322 from ``element.opacity || 1.0``
324 ====== =============================================
327 Available in MochiKit 1.4+
330 :mochidef:`appear(element [, options])`:
332 Slowly show an invisible element.
342 Available in MochiKit 1.4+
345 :mochidef:`puff(element [, options])`:
347 Make an element double size, and then make it disappear.
350 Available in MochiKit 1.4+
353 :mochidef:`blindUp(element [, options])`:
355 Blind an element up, changing its vertical size to 0.
358 Available in MochiKit 1.4+
361 :mochidef:`blindDown(element [, options])`:
363 Blind an element down, restoring its vertical size.
366 Available in MochiKit 1.4+
369 :mochidef:`switchOff(element [, options])`:
371 A switch-off like effect, making the element disappear.
374 Available in MochiKit 1.4+
377 :mochidef:`dropOut(element [, options])`:
379 Make the element fall and fade.
388 Available in MochiKit 1.4+
391 :mochidef:`shake(element [, options])`:
393 Shake an element from left to right.
396 Available in MochiKit 1.4+
399 :mochidef:`slideDown(element [, options])`:
401 Slide an element down.
404 Available in MochiKit 1.4+
407 :mochidef:`slideUp(element [, options])`:
412 Available in MochiKit 1.4+
415 :mochidef:`squish(element [, options])`:
417 Reduce the horizontal and vertical sizes at the same time, using
421 Available in MochiKit 1.4+
424 :mochidef:`grow(element [, options])`:
426 Restore the size of an element.
429 Available in MochiKit 1.4+
432 :mochidef:`shrink(element [, options])`:
434 Shrink an element to its center.
437 Available in MochiKit 1.4+
440 :mochidef:`pulsate(element [, options])`:
442 Switch an element between appear and fade.
450 pulses controls the number of pulses made during the effect.
453 Available in MochiKit 1.4+
456 :mochidef:`fold(element [, options])`:
458 Reduce first the vertical size, and then the horizontal size.
461 Available in MochiKit 1.4+
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.
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:
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.
482 But you have even more control if you use an array with the following keys:
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
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
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/>
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
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
525 Portions adapted from `Rico`_ are available under the terms of the
526 `Apache License, Version 2.0`_.
528 Portions adapted from `Scriptaculous`_ are available under the terms
529 of the `MIT License`_.
531 .. _`Apache License, Version 2.0`: http://www.apache.org/licenses/LICENSE-2.0.html