mochikit_v14/doc/rst/MochiKit/Style.rst

   1 .. title:: MochiKit.Style - painless Style manipulation API
   2
   3 Name
   4 ====
   5
   6 MochiKit.Style - painless Style manipulation API
   7
   8
   9 Synopsis
  10 ========
  11
  12 ::
  13
  14     var messagePos = getElementPosition('message');
  15     var messageSize = getElementDimensions('message');
  16
  17     var notifyPos = new MochiKit.Style.Coordinates(
  18          messagePos.x + messageSize.w + 10,
  19          messagePos.y);
  20
  21     setElementPosition('notify', notifyPos);
  22
  23
  24 Description
  25 ===========
  26
  27 Refactored from :mochiref:`MochiKit.DOM`.
  28
  29
  30 Dependencies
  31 ============
  32
  33 - :mochiref:`MochiKit.Base`
  34 - :mochiref:`MochiKit.DOM`
  35
  36
  37 Overview
  38 ========
  39
  40 Refactored from :mochiref:`MochiKit.DOM`.
  41
  42
  43 Element Visibility
  44 ------------------
  45
  46 The :mochiref:`hideElement` and :mochiref:`showElement` functions are
  47 provided as a convenience, but only work for elements that are
  48 ``display: block``. For a general solution to showing, hiding, and
  49 checking the explicit visibility of elements, we recommend using a
  50 solution that involves a little CSS. Here's an example::
  51
  52     <style type="text/css">
  53         .invisible { display: none; }
  54     </style>
  55
  56     <script type="text/javascript">
  57         function toggleVisible(elem) {
  58             toggleElementClass("invisible", elem);
  59         }
  60
  61         function makeVisible(elem) {
  62             removeElementClass(elem, "invisible");
  63         }
  64
  65         function makeInvisible(elem) {
  66             addElementClass(elem, "invisible");
  67         }
  68
  69         function isVisible(elem) {
  70             // you may also want to check for
  71             // getElement(elem).style.display == "none"
  72             return !hasElementClass(elem, "invisible");
  73         };
  74     </script>
  75
  76 MochiKit doesn't ship with such a solution, because there is no
  77 reliable and portable method for adding CSS rules on the fly with
  78 JavaScript.
  79
  80
  81 API Reference
  82 =============
  83
  84 Functions
  85 ---------
  86
  87 :mochidef:`getStyle(element, cssSelector)`:
  88
  89     Looks up a CSS property for the given element. The element can be
  90     specified as either a string with the element's ID or the element
  91     object itself.
  92
  93     ``cssSelector``:
  94         The CSS selector, e.g. ``background-color``.
  95
  96     *Availability*:
  97         Available in MochiKit 1.4+
  98
  99
 100 :mochidef:`setStyle(element, styles)`:
 101
 102     Set CSS properties on a the given element. The element can be
 103     specified as either a string with the element's ID or the element
 104     object itself.
 105
 106     ``styles``:
 107         Dictionnary holding CSS properties to set, e.g.
 108         ``{'background-color': 'red', 'opacity': 0.5}``.
 109
 110     *Availability*:
 111         Available in MochiKit 1.4+
 112
 113
 114 :mochidef:`setOpacity(element, opacity)`:
 115
 116     Sets ``opacity`` for ``element``. Valid ``opacity`` values range
 117     from 0 (invisible) to 1 (opaque). ``element`` is looked up with
 118     :mochiref:`getElement`, so string identifiers are also acceptable.
 119
 120     *Availability*:
 121         Available in MochiKit 1.4+
 122
 123
 124 :mochidef:`getElementDimensions(element)`:
 125
 126     Return the absolute pixel width and height (including padding and border,
 127     but not margins) of ``element`` as an object with ``w`` and ``h``
 128     properties, or ``undefined`` if ``element`` is not in the document.
 129     ``element`` may be specified as a string to be looked up with
 130     :mochiref:`getElement`, a DOM element, or trivially as an object with
 131     ``w`` and/or ``h`` properties.
 132
 133     *Availability*:
 134         Available in MochiKit 1.4+
 135
 136
 137 :mochidef:`setElementDimensions(element, dimensions[, units='px'])`:
 138
 139     Sets the dimensions of ``element`` in the document from an object
 140     with ``w`` and ``h`` properties.
 141
 142     Warning: IE in quirks-mode seems to behave strange when you set
 143     the height off an element containing text to 0. You can workaround this
 144     by setting the value of visibly/display.
 145
 146     ``element``:
 147         A reference to the DOM element to update (if a string is
 148         given, :mochiref:`getElement(node)` will be used to locate the
 149         node)
 150
 151     ``dimensions``:
 152         An object with ``w`` and ``h`` properties. You can also specify only
 153         one property.
 154
 155     ``units``:
 156         Optionally set the units to use, default is ``px``
 157
 158     *Availability*:
 159         Available in MochiKit 1.4+
 160
 161
 162 :mochidef:`getElementPosition(element[, relativeTo={x: 0, y: 0}])`:
 163
 164     Return the absolute pixel position of ``element`` in the document
 165     as an object with ``x`` and ``y`` properties, or ``undefined`` if
 166     ``element`` is not in the document. ``element`` may be specified
 167     as a string to be looked up with :mochiref:`getElement`, a DOM
 168     element, or trivially as an object with ``x`` and/or ``y``
 169     properties.
 170
 171     If ``relativeTo`` is given, then its coordinates are subtracted
 172     from the absolute position of ``element``, e.g.::
 173
 174         var elemPos = getElementPosition(elem);
 175         var anotherElemPos = getElementPosition(anotherElem);
 176         var relPos = getElementPosition(elem, anotherElem);
 177         assert( relPos.x == (elemPos.x - anotherElemPos.x) );
 178         assert( relPos.y == (elemPos.y - anotherElemPos.y) );
 179
 180     ``relativeTo`` may be specified as a string to be looked up with
 181     :mochiref:`getElement`, a DOM element, or trivially as an object
 182     with ``x`` and/or ``y`` properties.
 183
 184     *Availability*:
 185         Available in MochiKit 1.4+
 186
 187
 188 :mochidef:`setElementPosition(element, position[, units='px'])`:
 189
 190     Sets the absolute position of ``element`` in the document from an
 191     object with ``x`` and ``y`` properties.
 192
 193     ``element``:
 194         A reference to the DOM element to update (if a string is
 195         given, :mochiref:`getElement(node)` will be used to locate the
 196         node)
 197
 198     ``position``:
 199         An object with ``x`` and ``y`` properties. You can also specify only
 200         one property.
 201
 202     ``units``:
 203         Optionally set the units to use, default is ``px``
 204
 205     *Availability*:
 206         Available in MochiKit 1.4+
 207
 208
 209 :mochidef:`setDisplayForElement(display, element[, ...])`:
 210
 211     Change the ``style.display`` for the given element(s). Usually
 212     used as the partial forms:
 213
 214     - :mochiref:`showElement(element, ...)`
 215     - :mochiref:`hideElement(element, ...)`
 216
 217     Elements are looked up with :mochiref:`getElement`, so string
 218     identifiers are acceptable.
 219
 220     For information about the caveats of using a ``style.display``
 221     based show/hide mechanism, and a CSS based alternative, see
 222     `Element Visibility`_.
 223
 224     *Availability*:
 225         Available in MochiKit 1.4+
 226
 227
 228 :mochidef:`showElement(element, ...)`:
 229
 230     Partial form of :mochiref:`setDisplayForElement`, specifically::
 231
 232         partial(setDisplayForElement, "block")
 233
 234     For information about the caveats of using a ``style.display``
 235     based show/hide mechanism, and a CSS based alternative, see
 236     `Element Visibility`_.
 237
 238     *Availability*:
 239         Available in MochiKit 1.4+
 240
 241
 242 :mochidef:`hideElement(element, ...)`:
 243
 244     Partial form of :mochiref:`setDisplayForElement`, specifically::
 245
 246         partial(setDisplayForElement, "none")
 247
 248     For information about the caveats of using a ``style.display``
 249     based show/hide mechanism, and a CSS based alternative, see
 250     `Element Visibility`_.
 251
 252     *Availability*:
 253         Available in MochiKit 1.4+
 254
 255
 256 :mochidef:`getViewportDimensions()`:
 257
 258     Return the pixel width and height of the viewport as an object
 259     with ``w`` and ``h`` properties.
 260
 261     *Availability*:
 262         Available in MochiKit 1.4+
 263
 264 :mochidef:`getViewportPosition()`:
 265
 266     Return the pixel position of the viewport inside the window, as a
 267     :mochiref:`Coordinates` object.
 268
 269     *Availability*:
 270         Available in MochiKit 1.4+
 271
 272
 273 Objects
 274 -------
 275
 276 :mochidef:`Coordinates(x, y)`:
 277
 278     Constructs an object with ``x`` and ``y`` properties. ``obj.toString()``
 279     returns something like ``{x: 0, y: 42}`` for debugging.
 280
 281     *Availability*:
 282         Available in MochiKit 1.4+
 283
 284 :mochidef:`Dimensions(w, h)`:
 285
 286     Constructs an object with ``w`` and ``h`` properties. ``obj.toString()``
 287     returns something like ``{w: 0, h: 42}`` for debugging.
 288
 289     *Availability*:
 290         Available in MochiKit 1.4+
 291
 292
 293 Authors
 294 =======
 295
 296 - Bob Ippolito <bob@redivi.com>
 297 - Beau Hartshorne <beau@hartshornesoftware.com>
 298
 299
 300 Copyright
 301 =========
 302
 303 Copyright 2005-2006 Bob Ippolito <bob@redivi.com>, and Beau Hartshorne
 304 <beau@hartshornesoftware.com>. This program is dual-licensed free
 305 software; you can redistribute it and/or modify it under the terms of
 306 the `MIT License`_ or the `Academic Free License v2.1`_.
 307
 308 .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
 309 .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php