mochikit_v14/doc/rst/MochiKit/Visual.rst

   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