Commits

Anonymous committed eb95fe9

updated docs pulled over trunk r1561

  • Participants
  • Parent commits 1de3893

Comments (0)

Files changed (6)

doc/rst/MochiKit/Async.rst

     a value available, any new callbacks added will be called
     immediately.
 
+    If the initial callback value provided to the :mochiref:`Deferred`
+    is omitted, an ``undefined`` value will be passed instead. This
+    also happens if a callback or errback function does not return a
+    value.
+
     There are two other "advanced" details about this implementation
     that are useful:
 
         Available in MochiKit 1.3.1+
 
 
-:mochidef:`Deferred.prototype.addBoth(func)`:
+:mochidef:`Deferred.prototype.addBoth(func[, ...])`:
 
     Add the same function as both a callback and an errback as the
     next element on the callback sequence. This is useful for code
-    that you want to guarantee to run, e.g. a finalizer.
+    that you want to guarantee to run.
 
     If additional arguments are given, then ``func`` will be replaced
     with :mochiref:`MochiKit.Base.partial.apply(null,
         Available in MochiKit 1.3.1+
 
 
-:mochidef:`Deferred.prototype.addErrback(func)`:
+:mochidef:`Deferred.prototype.addErrback(func[, ...])`:
 
     Add a single errback to the end of the callback sequence.
 
         Available in MochiKit 1.3.1+
 
 
+:mochidef:`Deferred.prototype.setFinalizer(func[, ...])`:
+
+    Sets the finalizer function of the callback sequence. The finalizer
+    will always be called last in the sequence, regardless of the number
+    of callbacks added afterwards. Note that the value returned by the
+    finalizer will always be ignored, and no new callbacks can be added
+    to the ``Deferred`` once finalized.
+
+    If additional arguments are given, then ``func`` will be replaced
+    with :mochiref:`MochiKit.Base.partial.apply(null,
+    arguments)`. 
+
+    *Availability*:
+        Available in MochiKit 1.5+
+
+
 :mochidef:`Deferred.prototype.callback([result])`:
 
     Begin the callback sequence with a non-``Error`` result. Result

doc/rst/MochiKit/Base.rst

         Available in MochiKit 1.3.1+
 
 
-:mochidef:`evalJSON(aJSONString)`:
+:mochidef:`evalJSON(jsonText)`:
 
-    Unserialize a JSON [1]_ represenation of an object.
+    Unserialize a JSON [1]_ representation of an object.
 
     Note that this uses the ``eval`` function of the interpreter, and
-    therefore trusts the contents of ``aJSONString`` to be safe.  This
+    therefore trusts the contents of ``jsonText`` to be safe.  This
     is acceptable when the JSON and JavaScript application originate
     from the same server, but in other scenarios it may not be the
     appropriate security model. Currently, a validating JSON parser is
-    beyond the scope of MochiKit, but there is one available from
-    json.org [1]_.
+    beyond the scope of MochiKit, but in most modern browsers the
+    ``JSON.parse`` function is built-in for this purpose. There is
+    also one available from json.org [1]_.
 
     *Availability*:
         Available in MochiKit 1.3.1+

doc/rst/MochiKit/Selector.rst

 
     MochiKit.Base.map(MochiKit.Visual.fade, $$('p.fademe'));
 
-    // Highlight all right hand cells of a row when the second column is clicked
-    forEach($$('tr td:nth-child(2)'), function(midcell){
-         connect(midcell, 'onclick', function(e){
-	     addElementClass('highlight', findRelatedElements(midcell, '~ td'));
-	 });
-    });
-
 
 Description
 ===========
 
 The original version of this module was ported from Prototype.
 
+**Note:** This module is currently experimental and API stability cannot be
+fully guaranteed. The implementation is scheduled to be replaced with a new
+faster version (now in development) during the MochiKit 1.5 development
+cycle.
+
 **Note:** Due to how Internet Explorer handles node attributes, some attribute
 selectors may not work as expected. In particular ``a[title]`` will not work
 as all ``A`` elements in the Internet Explorer DOM model have a title attribute
 :mochidef:`findDocElements(expression[, ...])`:
     
     Performs a selection on the active document. Equivalent
-    to ``findRelatedElements(MochiKit.DOM.currentDocument(), expression[, ...])``
+    to ``findChildElements(MochiKit.DOM.currentDocument(), [expression, ...])``
 
     *Availability*:
         Available in MochiKit 1.4+
 
 
-:mochidef:`findRelatedElements(element, expression[, ...])`:
+:mochidef:`findChildElements(element, expressions)`:
 
-    Performs a selection within the context of ``element`` and returns an array of
-    elements that match the CSS selector ``expression``. 
-    Each additional ``expression`` will concatenate matching items to the returned array.
+    Traverses the child nodes of ``element`` and returns the subset
+    of those that match any of the selector expressions in ``expressions``.
 
-    An expression can be a combination of simple expressions, by concatenating
+    Each expression can be a combination of simple expressions, by concatenating
     them with spaces or combinators. In that case, normal CSS rules apply, each
-    simple expression is evaluated in turn and the results of each expression is used
+    simple expression is evaluated in turn and the results of that one is used
     as the scope for the succeeding expression (see :mochiref:`Selector.findElements`).
     Finally, the results of the last simple expression is returned as the search result.
 
     *Availability*:
         Available in MochiKit 1.4+
 
-
-:mochidef:`findChildElements(element)`:
-
-    An alias to ``findRelatedElements``.
-
-    *Availability*:
-        Available in MochiKit 1.4, deprecated in favor of
-        :mochiref:`MochiKit.Selector.findRelatedElements` in 1.5+
-
-
 :mochidef:`$$(expression[, ...])`:
 
     An alias to ``findDocElements``.
         var searchResults = selector.findElements(rootElement);
 
     *Deprecated*:
-        Use :mochiref:`findRelatedElements` instead. The Selector class will be
+        Use :mochiref:`findChildElements` instead. The Selector class will be
         removed in version 1.5.
 
     *Availability*:
         ``~`` all succeeding siblings of ``scope`` are tested.
 
     *Deprecated*:
-        Use :mochiref:`findRelatedElements` instead. The Selector class will be
+        Use :mochiref:`findChildElements` instead. The Selector class will be
         removed in version 1.5.
 
     *Availability*:

doc/rst/MochiKit/Text.rst

 |         | ``toString()`` will be used. This is the default format type. |
 +---------+---------------------------------------------------------------+
 | ``r``   | The programmers representation format ``type``. The output    |
-|         | from :mochiref:`MochiKit.Base.repr()`` will be used.          |
+|         | from :mochiref:`MochiKit.Base.repr()` will be used.           |
 +---------+---------------------------------------------------------------+
 | ``b``   | The binary number format ``type``. Rounds the number to the   |
 |         | nearest integer and converts it to a base 2 representation.   |
 API Reference
 =============
 
+Errors
+------
+
+:mochidef:`FormatPatternError`:
+
+    Thrown when a syntax error is encountered inside a format string
+    by the :mochiref:`formatter`, :mochiref:`format` or
+    :mochiref:`formatValue` functions. In addition to the normal
+    :mochiref:`MochiKit.Base.NamedError` functions, each object also
+    has the following properties set:
+
+    ``pattern``:
+        The invalid format pattern string.
+    ``pos``:
+        The position of the error in the format pattern (zero-indexed).
+    ``message``:
+        The detailed error message text.
+
+    *Availability*:
+        Available in MochiKit 1.5+
+
 Functions
 ---------
 
     by this function. For more information see
     `Formatting Text`_.
 
+    A :mochiref:`FormatPatternError` will be thrown if the formatting
+    pattern is recognized as invalid.
+
     *Availability*:
         Available in MochiKit 1.5+
 
     ``pattern`` requires. For more information see
     `Formatting Text`_.
 
+    A :mochiref:`FormatPatternError` will be thrown if the formatting
+    pattern is recognized as invalid.
+
     *Availability*:
         Available in MochiKit 1.5+
 
     only how a particular value is to be formatted. For more information
     see `Formatting Text`_.
 
+    A :mochiref:`FormatPatternError` will be thrown if the partial
+    formatting pattern is recognized as invalid.
+
     *Availability*:
         Available in MochiKit 1.5+
 
         Available in MochiKit 1.5+
 
 
-:mochidef:`splitJoin(func, str, separator="\n")`:
+:mochidef:`split(str, separator="\\n" [, max])`:
 
-    Splits ``str``, applies the ``func`` function on each part, and
-    finally joins the results back together again using the same
-    ``separator`` string. This is a convenience function for calling
-    ``String.prototype.split()``, :mochiref:`MochiKit.Base.map()` and
-    ``Array.prototype.join()`` separately.
+    Splits ``str`` using a ``separator`` string. 
+    If ``max`` is given, at most ``max`` splits will be performed
+    (giving at most ``max`` + 1 parts returned).
 
-    It can be used to trim each line in a text string by calling
-    ``splitJoin(strip, str)``.
+    If ``max`` is omitted, this is equivalent to the built in
+    ``str.split(separator)``.
+    The difference to the built in method can be illustrated by:
+
+    >>> "lovely bunch of coconuts".split(" ", 2)
+    ["lovely", "bunch"]
+
+
+    >>> MochiKit.Text.split("lovely bunch of coconuts", " ", 2)
+    ["lovely", "bunch", "of coconuts"]
+
+    *Availability*:
+        Available in MochiKit 1.5+
+
+
+:mochidef:`rsplit(str, separator="\\n" [, max])`:
+
+    Splits ``str`` using a ``separator`` string. 
+    This is similar to ``split``, except that if ``max`` is given,
+    splits are performed from the right hand side first
+
+    >>> MochiKit.Text.rsplit("lovely bunch of coconuts", " ", 2)
+    ["lovely bunch", "of", "coconuts"]
 
     *Availability*:
         Available in MochiKit 1.5+
     *Availability*:
         Available in MochiKit 1.5+
 
-Errors
-------
-
-:mochidef:`FormatPatternError`:
-
-    Thrown by a :mochiref:`Deferred` if ``.callback`` or ``.errback``
-    are called more than once.
-
-    *Availability*:
-        Available in MochiKit 1.5+
-
 
 See Also
 ========
 Copyright
 =========
 
-Copyright 2005-2008 by Bob Ippolito <bob@redivi.com> and Per Cederberg
+Copyright 2005-2009 by Bob Ippolito <bob@redivi.com> and Per Cederberg
 <cederberg@gmail.com>. This program is dual-licensed free software; you can
 redistribute it and/or modify it under the terms of the `MIT License`_ or the
 `Academic Free License v2.1`_.

doc/rst/MochiKit/VersionHistory.rst

 2009-XX-YY      v1.5
 
-- Changed the signature of MochiKit.Selector.findRelatedElements to accept arguments of the form
-  findRelatedElements(el, exp1, exp2, exp3...) as well as the previous findChildElements(el, [exp1, exp2, exp3...])
-- Renamed MochiKit.Selector.findChildElements to MochiKit.Selector.findRelatedElements
-  to reflect its' ability to accept more axes than the child axis
 - Changed MochiKit.Signal.signal to support DOM source objects with custom
   arguments, instead of always wrapping into Event object.
 - Removed the Dojo and JSAN integrations, since they are not maintained.
 - Simplified module init and export code, saving up to 5kB in packed
   download size.
-- Changed MochiKit.Selector.findRelatedElements to support element lookup
+- Changed MochiKit.Selector.findChildElements to support element lookup
   via MochiKit.DOM.getElement.
 - Fixed MochiKit.DOM.hasElementClass handling of text DOM nodes (#330).
 - Reimplemented MochiKit.Format.truncToFixed and roundToFixed to resolve
   position (#332).
 - Added new MochiKit.Text module to eventually replace MochiKit.Format.
 - Added the MochiKit.Base.bool() function.
+- Added MochiKit.Visual.Transitions.spring for creating "springy" effects
+- Changed MochiKit.Visual to support specifying transitions a strings.
+- Added new 'replace' queue position to MochiKit.Visual for cancelling
+  existing effects instead of completing them (as 'break' does).
+- Removed MochiKit.Visual.Color and getElementsComputedStyle compatibility
+  aliases (obsolete since version 1.1, see #337).
+- Added the MochiKit.Async.Deferred.prototype.setFinalizer() function.
+- Added "rowSpan" attribute mapping in MochiKit.DOM for IE (#357).
+
+2009-XX-YY      v1.4.3 (bug fix release)
+
+- Fixed MochiKit.Logging usage of map without a namespace (#338).
+- Fixed MochiKit.Color.Color.prototype.isLight() and isDark() to not
+  return constant false and true values (#341).
+- Fixed incorrect z-index restore after MochiKit.DragAndDrop usage (#339).
+- Fixed MochiKit.Async.wait() handling of missing optional value (#345).
+- Fixed MochiKit.Signal.signal() re-entrancy locking when observers
+  both disconnect other observers and signal new events (#346).
+- Fixed possible exception throwing in MochiKit.Base.repr() (#353).
+- Added MochiKit.Signal.Event.prototype.mouse() support for HTML5
+  drag events (#354).
 
 2008-11-27      v1.4.2 (bug fix release)
 

doc/rst/MochiKit/Visual.rst

 - `front`: the effect will be run before any other non-started effect;
 - `end`: the effect will be run when all other effects have finished;
 - `break`: every other effect is immediately finalized when the the effect start;
+- `replace`: every other effect is canceled when the the effect start (available in MochiKit 1.5+);
 - `parallel`: the effect runs in parallel with other effects.
 
 But you have even more control if you use an object with the following
     reverse     A reverse linear transition.
     flicker     A sine transition with random additions.
     wobble      A multi-period sine curve transition with 4.5 wobbles and ending with one (1).
+    spring      A multi-period sine curve transition decreasing wobble amplitudes (spring-like effect).
     pulse       A multi-period triangle curve transition with 5 pulses (by default) and ending with zero (0).
-    parabolic   A smooth parabolic transition.
+    parabolic   A smooth parabolic transition (square function).
     none        A fixed zero (0) value transition.
     full        A fixed one (1) value transition.
     =========== ========================================
 
     *Availability*:
-        Available in MochiKit 1.4+
+        Available in MochiKit 1.4+. The ``spring`` transition is available
+        since MochiKit 1.5+.
 
 
 :mochidef:`DefaultOptions`:
     effect options.
 
     =========== ========================================
-    transition  ``MochiKit.Visual.Transitions.sinoidal``
+    transition  ``MochiKit.Visual.Transitions.sinoidal`` (or ``"sinoidal"``)
     duration    ``1.0`` (seconds)
     fps         ``25.0``
     sync        ``false`` (only set for :mochiref:`Parallel` or :mochiref:`Sequence` effects)
     from        ``0.0``
     to          ``1.0``
     delay       ``0.0``
-    queue       ``'parallel'``
+    queue       ``'parallel'`` (see :mochiref:`The Effects Queue`)
     =========== ========================================
 
     *Availability*:
     parameter of the effect. Example::
 
         // I slide it up and then down again
-        slideUp('myelement', {afterFinish: function () {
-            slideDown('myelement');
+        slideUp('myelement', {
+            afterFinish: function () {
+                slideDown('myelement');
+            }
         });
 
     Specific ``internal`` events are also available: for each one listed above,