| 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 |