.. title:: MochiKit.Style - painless Style manipulation API

Name
====

MochiKit.Style - painless Style manipulation API


Synopsis
========

::

    var messagePos = getElementPosition('message');
    var messageSize = getElementDimensions('message');

    var notifyPos = new MochiKit.Style.Coordinates(
         messagePos.x + messageSize.w + 10,
         messagePos.y);

    setElementPosition('notify', notifyPos);


Description
===========

Refactored from :mochiref:`MochiKit.DOM`.


Dependencies
============

- :mochiref:`MochiKit.Base`
- :mochiref:`MochiKit.DOM`


Overview
========

Refactored from :mochiref:`MochiKit.DOM`.


Element Visibility
------------------

The :mochiref:`hideElement` and :mochiref:`showElement` functions are
provided as a convenience, but only work for elements that are
``display: block``. For a general solution to showing, hiding, and
checking the explicit visibility of elements, we recommend using a
solution that involves a little CSS. Here's an example::

    <style type="text/css">
        .invisible { display: none; }
    </style>

    <script type="text/javascript">
        function toggleVisible(elem) {
            toggleElementClass("invisible", elem);
        }

        function makeVisible(elem) {
            removeElementClass(elem, "invisible");
        }

        function makeInvisible(elem) {
            addElementClass(elem, "invisible");
        }

        function isVisible(elem) {
            // you may also want to check for
            // getElement(elem).style.display == "none"
            return !hasElementClass(elem, "invisible");
        };
    </script>

MochiKit doesn't ship with such a solution, because there is no
reliable and portable method for adding CSS rules on the fly with
JavaScript.


API Reference
=============

Functions
---------

:mochidef:`getStyle(element, cssSelector)`:

    Looks up a CSS property for the given element. The element can be
    specified as either a string with the element's ID or the element
    object itself.

    ``cssSelector``:
        The CSS selector, e.g. ``background-color``.

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`setStyle(element, styles)`:

    Set CSS properties on a the given element. The element can be
    specified as either a string with the element's ID or the element
    object itself.

    ``styles``:
        Dictionnary holding CSS properties to set, e.g.
        ``{'background-color': 'red', 'opacity': 0.5}``.

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`setOpacity(element, opacity)`:

    Sets ``opacity`` for ``element``. Valid ``opacity`` values range
    from 0 (invisible) to 1 (opaque). ``element`` is looked up with
    :mochiref:`getElement`, so string identifiers are also acceptable.

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`getElementDimensions(element[, contentSize=false])`:

    Return the absolute pixel width and height of ``element`` as an object with
    ``w`` and ``h`` properties, or ``undefined`` if ``element`` is not in the
    document. The size will include padding and border, but not margins, unless
    ``contentSize`` is set to true, in which case the size will be only the
    content size, without padding and border. ``element`` may be specified as
    a string to be looked up with :mochiref:`getElement`, a DOM element, or
    trivially as an object with ``w`` and/or ``h`` properties.

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`setElementDimensions(element, dimensions[, units='px'])`:

    Sets the dimensions of ``element`` in the document from an object
    with ``w`` and ``h`` properties.

    Warning: IE in quirks-mode seems to behave strange when you set
    the height off an element containing text to 0. You can workaround this
    by setting the value of visibly/display.

    ``element``:
        A reference to the DOM element to update (if a string is
        given, :mochiref:`getElement(node)` will be used to locate the
        node)

    ``dimensions``:
        An object with ``w`` and ``h`` properties. You can also specify only
        one property.

    ``units``:
        Optionally set the units to use, default is ``px``

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`getElementPosition(element[, relativeTo={x: 0, y: 0}])`:

    Return the absolute pixel position of ``element`` in the document
    as an object with ``x`` and ``y`` properties, or ``undefined`` if
    ``element`` is not in the document. ``element`` may be specified
    as a string to be looked up with :mochiref:`getElement`, a DOM
    element, or trivially as an object with ``x`` and/or ``y``
    properties.

    If ``relativeTo`` is given, then its coordinates are subtracted
    from the absolute position of ``element``, e.g.::

        var elemPos = getElementPosition(elem);
        var anotherElemPos = getElementPosition(anotherElem);
        var relPos = getElementPosition(elem, anotherElem);
        assert( relPos.x == (elemPos.x - anotherElemPos.x) );
        assert( relPos.y == (elemPos.y - anotherElemPos.y) );

    ``relativeTo`` may be specified as a string to be looked up with
    :mochiref:`getElement`, a DOM element, or trivially as an object
    with ``x`` and/or ``y`` properties.

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`setElementPosition(element, position[, units='px'])`:

    Sets the absolute position of ``element`` in the document from an
    object with ``x`` and ``y`` properties.

    ``element``:
        A reference to the DOM element to update (if a string is
        given, :mochiref:`getElement(node)` will be used to locate the
        node)

    ``position``:
        An object with ``x`` and ``y`` properties. You can also specify only
        one property.

    ``units``:
        Optionally set the units to use, default is ``px``

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`makePositioned(element)`:

    Ensure that ``element.style.position`` is set to ``"relative"`` if it
    is not set or is ``"static"``. If ``element`` is a
    string, then it will be looked up with :mochiref:`getElement`.

    *Availability*:
        Available in MochiKit 1.4.1+


:mochidef:`undoPositioned(element)`:

    Restore the setting of ``element.style.position`` set by
    :mochiref:`makePositioned(element)`. If ``element`` is a string, then
    it will be looked up with :mochiref:`getElement`.

    *Availability*:
        Available in MochiKit 1.4.1+


:mochidef:`makeClipping(element)`:

    Ensure that ``element.style.overflow = 'hidden'``. If ``element`` is a
    string, then it will be looked up with :mochiref:`getElement`.

    Returns the original values of ``overflow``, ``overflow-y`` and
    ``overflow-y`` so that they may be restored with
    :mochiref:`undoClipping(element, overflow)`.

    *Availability*:
        Available in MochiKit 1.4.1+


:mochidef:`undoClipping(element, overflow)`:

    Restore the setting of ``element.style.overflow`` set by
    :mochiref:`makeClipping(element)`. If ``element`` is a string, then
    it will be looked up with :mochiref:`getElement`.

    *Availability*:
        Available in MochiKit 1.4.1+


:mochidef:`setDisplayForElement(display, element[, ...])`:

    Change the ``style.display`` for the given element(s). Usually
    used as the partial forms:

    - :mochiref:`showElement(element, ...)`
    - :mochiref:`hideElement(element, ...)`

    Elements are looked up with :mochiref:`getElement`, so string
    identifiers are acceptable.

    For information about the caveats of using a ``style.display``
    based show/hide mechanism, and a CSS based alternative, see
    `Element Visibility`_.

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`showElement(element, ...)`:

    Partial form of :mochiref:`setDisplayForElement`, specifically::

        partial(setDisplayForElement, "block")

    For information about the caveats of using a ``style.display``
    based show/hide mechanism, and a CSS based alternative, see
    `Element Visibility`_.

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`hideElement(element, ...)`:

    Partial form of :mochiref:`setDisplayForElement`, specifically::

        partial(setDisplayForElement, "none")

    For information about the caveats of using a ``style.display``
    based show/hide mechanism, and a CSS based alternative, see
    `Element Visibility`_.

    *Availability*:
        Available in MochiKit 1.4+


:mochidef:`getViewportDimensions()`:

    Return the pixel width and height of the viewport as an object
    with ``w`` and ``h`` properties.

    *Availability*:
        Available in MochiKit 1.4+

:mochidef:`getViewportPosition()`:

    Return the pixel position of the viewport inside the window, as a
    :mochiref:`Coordinates` object.

    *Availability*:
        Available in MochiKit 1.4+


Objects
-------

:mochidef:`Coordinates(x, y)`:

    Constructs an object with ``x`` and ``y`` properties. ``obj.toString()``
    returns something like ``{x: 0, y: 42}`` for debugging.

    *Availability*:
        Available in MochiKit 1.4+

:mochidef:`Dimensions(w, h)`:

    Constructs an object with ``w`` and ``h`` properties. ``obj.toString()``
    returns something like ``{w: 0, h: 42}`` for debugging.

    *Availability*:
        Available in MochiKit 1.4+


Authors
=======

- Bob Ippolito <bob@redivi.com>
- Beau Hartshorne <beau@hartshornesoftware.com>


Copyright
=========

Copyright 2005-2006 Bob Ippolito <bob@redivi.com>, and Beau Hartshorne
<beau@hartshornesoftware.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`_.

.. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
.. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php