| 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 |