NAME
    Animation.Resize - Animation for resizing an element

SYNOPSIS
      Animation.Resize.resizeElement( { elementId:    "some-element",
                                        targetWidth:  200,
                                        targetHeight: 150,
                                        anchors:      { top: true },
                                        onFinish:     someFunction,
                                      } );

DESCRIPTION
    This library provides an animation effect for resizing elements by
    gradually changing the dimensions (and possibly position) of the element
    over a period of time. The animation can be anchored in various ways so
    that the animation moves in different ways.

FUNCTIONS
    This library provides one function, "resizeElement()". It requires an
    object with the following properties as its arguments.

    * elementId - required
        The element should be resized.

    * targetWidth - required
        The width, in pixels, to which the element should be resized.

    * targetHeight - required
        The height, in pixels, to which the element should be resized.

    * anchorSides - optional
        This parameter is itself an object with four possible keys, "top",
        "bottom", "left", "right". The anchors determine in which direction
        the element will appear to move as it is resized. You cannot anchor
        both the top and bottom or left and right at the same time. You
        *can* anchor only one side, or no sides.

    * frameCount - optional
        The number of frames in the animation. Defaults to 20.

    * totalDuration - optional
        The total length of the animation, in milliseconds. Defaults to 500,
        which makes for 40FPS with the default frameCount.

    * onFinish - optional
        A callback to be executed when the animation is done.

LIMITATIONS
    For the animation to work, the library must be able to get the width of
    the element being resized *in pixels*, as specified in CSS. In Firefox,
    the value of the style from "getComputedStyle()" is always in pixels,
    regardless of what units are used in the CSS, so resizing always works.
    In IE6, the value that can be retrieved is returned as is, so if you
    specify the value in percentage, points, or em units, the element cannot
    be resized.

    The one special case where the value does not need to be retrieved is if
    the element has zero width and height, which can be calculated without
    looking at the CSS styles.

    The reason this is all necessary is that the other ways of getting
    element sizes produce values that are not settable, for example using
    the "offsetHeight" or "clientHeight" properties. The only way to change
    the height or width of an element is to explicitly set its style
    attributes, so to calculate the animation, we need to start with those
    CSS values.

    This is different from how I've seen other libraries do resizing, such
    as Scriptaculous, but the Scriptaculous method has the downside that you
    cannot start with an element of zero size, because it simply multiplies
    the current size of the element by a scaling factor for each frame of
    the animation. If the element size starts at zero, the size will never
    change. Scriptaculous also doesn't give fine control over the final size
    of the element, as it does not account for rounding errors in its math.

    This is not really a criticism of Scriptaculous, as its doing something
    different. It lets you say "make this element about twice as big as it
    is right now", whereas "Animation.Resize" lets you say "resize this
    element to 300px by 200px".

AUTHOR
    Dave Rolsky, <autarch@urth.org>.

COPYRIGHT
    Copyright (c) 2006 Dave Rolsky. All rights reserved.

    This module is free software; you can redistribute it and/or modify it
    under the same terms as the Perl programming language (your choice of
    GPL or the Perl Artistic license).

</html>