mochikit_v14/doc/html/MochiKit/Style.html

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