Changeset 750

Timestamp:

04/24/06 23:50:04 (2 years ago)

Author:

beau@hartshornesoftware.com

Message:

Signal doc updates

Files:

• mochikit/trunk/doc/html/MochiKit/Signal.html (modified) (8 diffs)
• mochikit/trunk/doc/rst/MochiKit/Signal.rst (modified) (9 diffs)

mochikit/trunk/doc/html/MochiKit/Signal.html

@@ -73 +73 @@
-<p>This module takes care of all the hard work—figuring out which event
-model to use, trying to retrieve the event object, and handling your own
-handle
+clean up
-nasty memory leakage.</p>
-You should read
-
-at: 
+Read more on
+
+
-</div>
-<div class="section">
@@ -90 +90 @@
-<div class="section">
-<h2><a id="using-signal-for-dom-events" name="using-signal-for-dom-events">Using Signal for DOM Events</a></h2>
-you should not directly use the browser's native
-
-
-This also means that 
+do not use the browser's native event API.
+
+
+
-<a class="mochiref reference" href="DOM.html#fn-addloadevent">MochiKit.DOM.addLoadEvent</a> should not be used in combination with
-this module.</p>
-'on' prefix, e.g.:
-'onclick', 'onkeyup'
-exactly one parameter,
-the custom 
+<tt class="docutils literal"><span class="pre">on</span></tt> prefix, e.g.: <tt class="docutils literal"><span class="pre">onclick</span></tt>,
+<tt class="docutils literal"><span class="pre">onkeyup</span></tt>
+one parameter, the custom
+
-</div>
-<div class="section">
@@ -107 +107 @@
-across all supported platforms and browsers, and provides many conveniences
-not available even in a correct W3C implementation.</p>
-<p>Here is a complete list of this object's methods:</p>
-<blockquote>
-<p>These are always generated:</p>
-<dl class="docutils">
-<dt>event():</dt>
-<dd>The native event produced by the browser. You should not need to
-access this.</dd>
-<dt>type():</dt>
-<dd>The event type: click, mouseover, keypress, etc. (Does not include
-the 'on' prefix.)</dd>
-<dt>target():</dt>
-<dd>The element that triggered the event.</dd>
-<dt>modifier().alt, modifier().ctrl, modifier().meta, modifier().shift:</dt>
-<dd><tt class="docutils literal"><span class="pre">true</span></tt> if pressed, <tt class="docutils literal"><span class="pre">false</span></tt> if not. <tt class="docutils literal"><span class="pre">modifier().meta</span></tt> will be
-<tt class="docutils literal"><span class="pre">false</span></tt> instead of <tt class="docutils literal"><span class="pre">undefined</span></tt> in IE.</dd>
-<dt>modifier().any:</dt>
-<dd><tt class="docutils literal"><span class="pre">true</span></tt> if any modifier is pressed, <tt class="docutils literal"><span class="pre">false</span></tt> if not.</dd>
-<dt>stopPropagation():</dt>
-<dd>Works like W3C's <tt class="docutils literal"><span class="pre">stopPropagation()</span></tt>.</dd>
-<dt>preventDefault():</dt>
-<dd>Works like W3C's <tt class="docutils literal"><span class="pre">preventDefault()</span></tt>.</dd>
-<dt>stop():</dt>
-<dd>Shortcut that calls <tt class="docutils literal"><span class="pre">stopPropagation()</span></tt> and <tt class="docutils literal"><span class="pre">preventDefault()</span></tt>.</dd>
-</dl>
-<p>You should use keydown and keyup to detect control characters,
-and keypressed to detect &quot;printable&quot; characters. key().code will be set to
-0 and key().string will be set to an empty string in a keypress handler if
-a user presses a control character like F1 or Escape. IE will not fire
-your keypressed handler when you press a control character like KEY_F1 or
-KEY_ESCAPE. In your keyup and keydown handlers, Signal will pass the
-keyboard code and a human-readable string like KEY_A or KEY_ARROW_DOWN or
-KEY_NUM_PAD_ASTERISK. See <tt class="docutils literal"><span class="pre">_specialKeys</span></tt> for a comprehensive list. These
-are generated for keydown and keyup events:</p>
-<dl class="docutils">
-<dt>key().code:</dt>
-<dd>contains the raw key code, such as 8 for backspace.</dd>
-<dt>key().string:</dt>
-<dd>contains a human readable string, such as 'KEY_BACKSPACE' or '!'.
-The complete list is defined in MochiKit.Signal._specialKeys.</dd>
-</dl>
-<p>These are only generated for mouse*, click, dblclick, and contextmenu
-(contextmenu doesn't work in Opera):</p>
-<dl class="docutils">
-<dt>mouse().page.x, mouse().page.y:</dt>
-<dd>represents the cursor position relative to the HTML document.
-(Equivalent to pageX/Y in Safari, Mozilla, and Opera.)</dd>
-<dt>mouse().client.x, mouse().client.y:</dt>
-<dd>represents the cursor position relative to the visible portion of the
-HTML document. (Equivalent to clientX/Y on all browsers.)</dd>
-</dl>
-<p>These are only generated for mouseup, mousedown, click, and dblclick:</p>
-<dl class="docutils">
-<dt>mouse().button.left, mouse().button.right, mouse().button.middle:</dt>
-<dd><p class="first"><tt class="docutils literal"><span class="pre">true</span></tt> or <tt class="docutils literal"><span class="pre">false</span></tt>. Mac browsers don't report right click
-consistently. Firefox fires the click and sets modifier().ctrl to
-true, Opera fires the click and sets modifier().meta to true, and
-Safari doesn't fire the click (<a class="reference" href="http://bugzilla.opendarwin.org/show_bug.cgi?id=6595">Safari Bug 6595</a>).</p>
-<p>If you want a right click, I suggest that instead of looking for
-a right click, look for a contextmenu event.</p>
-<p class="last">Current versions of Safari won't fire a dblclick event when attached
-via <tt class="docutils literal"><span class="pre">connect()</span></tt> (<a class="reference" href="http://bugzilla.opendarwin.org/show_bug.cgi?id=7790">Safari Bug 7790</a>).</p>
-</dd>
-</dl>
-<p>This is generated on mouseover and mouseout:</p>
-<dl class="docutils">
-<dt>relatedTarget():</dt>
-<dd>the document element that the mouse has moved to.</dd>
-</dl>
-</blockquote>
-<p>If you find that you're accessing the native event for any reason, create a
-<a class="reference" href="http://trac.mochikit.com/newticket">new ticket</a> and we'll look into normalizing the behavior you're looking for.</p>
@@ -184 +115 @@
-by the Signal mechanism until it is disconnected via <a class="mochiref reference" href="#fn-disconnect">disconnect()</a>
-or <a class="mochiref reference" href="#fn-disconnectall">disconnectAll()</a>.</p>
-'onunload'
+<tt class="docutils literal"><span class="pre">onunload</span></tt>
-objects on the page when the browser leaves the page. However, memory usage
-will grow during the page view for every connection made until it is
-disconnected. Even if the DOM object is removed from the document, it
-will still be referenced by Signal until it is explicitly disconnected.</p>
-
-
-
+
+
-</div>
-<div class="section">
@@ -215 +145 @@
-<h1><a id="api-reference" name="api-reference">API Reference</a></h1>
-<div class="section">
-functions" name="functions">Functions
+signal-api-reference" name="signal-api-reference">Signal API Reference
-<p>
-<a name="fn-connect"></a>
@@ -223 +153 @@
-used to disconnect that signal.</p>
-<p><tt class="docutils literal"><span class="pre">src</span></tt> is the object that has the signal. You may pass in a string, in
-E
+e
-<p><tt class="docutils literal"><span class="pre">signal</span></tt> is a string that represents a signal name. If 'src' is an HTML
-Window, or the Document, then it can be one of the 'on-XYZ'
-
+<tt class="docutils literal"><span class="pre">window</span></tt>, or the <tt class="docutils literal"><span class="pre">document</span></tt>, then it can be one of the
+'on-XYZ' 
-lower-case.</p>
-<p><tt class="docutils literal"><span class="pre">dest</span></tt> and <tt class="docutils literal"><span class="pre">func</span></tt> describe the slot, or the action to take when the
@@ -243 +173 @@
-</ul>
-</blockquote>
-should raise and
+will raise an
-<p>The return value can be passed to <a class="mochiref reference" href="#fn-disconnect">disconnect</a> to disconnect
-the signal.</p>
@@ -262 +192 @@
-<a class="mochiref reference" href="#fn-connect">connect()</a>.</blockquote>
-</div>
+<div class="section">
+<h2><a id="dom-event-api-reference" name="dom-event-api-reference">DOM Event API Reference</a></h2>
+<dl class="docutils">
+<dt>
+<a name="fn-event"></a>
+<a class="mochidef reference" href="#fn-event">event()</a>:</dt>
+<dd>The native event produced by the browser. You should not need to
+access this.</dd>
+<dt>
+<a name="fn-type"></a>
+<a class="mochidef reference" href="#fn-type">type()</a>:</dt>
+<dd>Returns the event type (<tt class="docutils literal"><span class="pre">click</span></tt>, <tt class="docutils literal"><span class="pre">mouseover</span></tt>, <tt class="docutils literal"><span class="pre">keypress</span></tt>, etc.) as a
+string. Does not include the <tt class="docutils literal"><span class="pre">on</span></tt> prefix.</dd>
+<dt>
+<a name="fn-target"></a>
+<a class="mochidef reference" href="#fn-target">target()</a>:</dt>
+<dd>Returns the element that triggered the event.</dd>
+<dt>
+<a name="fn-modifier"></a>
+<a class="mochidef reference" href="#fn-modifier">modifier()</a>:</dt>
+<dd>Returns <tt class="docutils literal"><span class="pre">{shift,</span> <span class="pre">ctrl,</span> <span class="pre">meta,</span> <span class="pre">alt,</span> <span class="pre">any}</span></tt>, where each property is <tt class="docutils literal"><span class="pre">true</span></tt>
+if its respective modifier key was pressed, <tt class="docutils literal"><span class="pre">false</span></tt> otherwise. <tt class="docutils literal"><span class="pre">any</span></tt>
+is <tt class="docutils literal"><span class="pre">true</span></tt> if any modifier is pressed, <tt class="docutils literal"><span class="pre">false</span></tt> otherwise.</dd>
+<dt>
+<a name="fn-stoppropagation"></a>
+<a class="mochidef reference" href="#fn-stoppropagation">stopPropagation()</a>:</dt>
+<dd>Works like W3C's <tt class="docutils literal"><span class="pre">stopPropagation()</span></tt>.</dd>
+<dt>
+<a name="fn-preventdefault"></a>
+<a class="mochidef reference" href="#fn-preventdefault">preventDefault()</a>:</dt>
+<dd>Works like W3C's <tt class="docutils literal"><span class="pre">preventDefault()</span></tt>.</dd>
+<dt>
+<a name="fn-stop"></a>
+<a class="mochidef reference" href="#fn-stop">stop()</a>:</dt>
+<dd>Shortcut that calls <tt class="docutils literal"><span class="pre">stopPropagation()</span></tt> and <tt class="docutils literal"><span class="pre">preventDefault()</span></tt>.</dd>
+<dt>
+<a name="fn-key"></a>
+<a class="mochidef reference" href="#fn-key">key()</a>:</dt>
+<dd><p class="first">Returns {code, string}.</p>
+<p>Use <tt class="docutils literal"><span class="pre">onkeydown</span></tt> and <tt class="docutils literal"><span class="pre">onkeyup</span></tt> handlers to detect control characters
+such as <tt class="docutils literal"><span class="pre">KEY_F1</span></tt>. Use the <tt class="docutils literal"><span class="pre">onkeypressed</span></tt> handler to detect &quot;printable&quot;
+characters, such as <tt class="docutils literal"><span class="pre">é</span></tt>.</p>
+<p>When a user presses F1, in <tt class="docutils literal"><span class="pre">onkeydown</span></tt> and <tt class="docutils literal"><span class="pre">onkeyup</span></tt> this method
+returns <tt class="docutils literal"><span class="pre">{code:</span> <span class="pre">122,</span> <span class="pre">string:</span> <span class="pre">'KEY_F1'}</span></tt>. In <tt class="docutils literal"><span class="pre">onkeypress</span></tt>, it returns
+<tt class="docutils literal"><span class="pre">{code:</span> <span class="pre">0,</span> <span class="pre">string:</span> <span class="pre">''}</span></tt>.</p>
+<p>If a user presses Shift+2 on a US keyboard, this method returns <tt class="docutils literal"><span class="pre">{code:</span>
+<span class="pre">50,</span> <span class="pre">string:</span> <span class="pre">'KEY_2'}</span></tt> in <tt class="docutils literal"><span class="pre">onkeydown</span></tt> and <tt class="docutils literal"><span class="pre">onkeyup</span></tt>. In
+<tt class="docutils literal"><span class="pre">onkeypress</span></tt>, it returns <tt class="docutils literal"><span class="pre">{code:</span> <span class="pre">64,</span> <span class="pre">string:</span> <span class="pre">'&#64;'}</span></tt>.</p>
+<p class="last">See <tt class="docutils literal"><span class="pre">_specialKeys</span></tt> for a comprehensive list of control characters.</p>
+</dd>
+<dt>
+<a name="fn-mouse"></a>
+<a class="mochidef reference" href="#fn-mouse">mouse()</a>:</dt>
+<dd><p class="first">Properties for <tt class="docutils literal"><span class="pre">onmouse*</span></tt>, <tt class="docutils literal"><span class="pre">onclick</span></tt>, <tt class="docutils literal"><span class="pre">ondblclick</span></tt>, and
+<tt class="docutils literal"><span class="pre">oncontextmenu</span></tt> events. (<tt class="docutils literal"><span class="pre">contextmenu</span></tt> doesn't work in Opera).</p>
+<blockquote>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">page</span></tt> is a <a class="mochiref reference" href="DOM.html#fn-coordinates">MochiKit.DOM.Coordinates</a> object that
+represents the cursor position relative to the HTML document.
+Equivalent to <tt class="docutils literal"><span class="pre">pageX</span></tt> and <tt class="docutils literal"><span class="pre">pageY</span></tt> in Safari, Mozilla, and Opera.</li>
+<li><tt class="docutils literal"><span class="pre">client</span></tt> is a <a class="mochiref reference" href="DOM.html#fn-coordinates">MochiKit.DOM.Coordinates</a> object that
+represents the cursor position relative to the visible portion of
+the HTML document. Equivalent to <tt class="docutils literal"><span class="pre">clientX</span></tt> and <tt class="docutils literal"><span class="pre">clientY</span></tt> on
+all browsers.</li>
+</ul>
+</blockquote>
+<p>Properties for <tt class="docutils literal"><span class="pre">onmouseup</span></tt>, <tt class="docutils literal"><span class="pre">onmousedown</span></tt>, <tt class="docutils literal"><span class="pre">onclick</span></tt>, and
+<tt class="docutils literal"><span class="pre">ondblclick</span></tt>:</p>
+<blockquote>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">mouse().button</span></tt> returns {left, right, middle} where each
+property is <tt class="docutils literal"><span class="pre">true</span></tt> if the mouse button was pressed, <tt class="docutils literal"><span class="pre">false</span></tt>
+otherwise.</li>
+</ul>
+</blockquote>
+<p>Mac browsers don't report right click consistently. Firefox fires the
+click and sets <tt class="docutils literal"><span class="pre">modifier().ctrl</span></tt> to true, Opera fires the click and sets
+<tt class="docutils literal"><span class="pre">modifier().meta</span></tt> to <tt class="docutils literal"><span class="pre">true</span></tt>, and Safari doesn't fire the click
+(<a class="reference" href="http://bugzilla.opendarwin.org/show_bug.cgi?id=6595">Safari Bug 6595</a>).</p>
+<p>If you want a right click, we suggest that instead of looking for a right
+click, look for a <tt class="docutils literal"><span class="pre">contextmenu</span></tt> event.</p>
+<p class="last">Current versions of Safari won't fire a <tt class="docutils literal"><span class="pre">dblclick</span></tt> event when attached
+via <tt class="docutils literal"><span class="pre">connect()</span></tt> (<a class="reference" href="http://bugzilla.opendarwin.org/show_bug.cgi?id=7790">Safari Bug 7790</a>).</p>
+</dd>
+<dt>
+<a name="fn-relatedtarget"></a>
+<a class="mochidef reference" href="#fn-relatedtarget">relatedTarget()</a>:</dt>
+<dd>This is generated on <tt class="docutils literal"><span class="pre">mouseover</span></tt> and <tt class="docutils literal"><span class="pre">mouseout</span></tt>. Returns the document
+element that the mouse has moved to.</dd>
+</dl>
+</div>
-</div>
-<div class="section">

mochikit/trunk/doc/rst/MochiKit/Signal.rst

@@ -68 +68 @@
-This module takes care of all the hard work |---| figuring out which event
-model to use, trying to retrieve the event object, and handling your own
-handle
+clean up
-nasty memory leakage.
-
-You should read
-
-at: 
+Read more on
+
+
-
-
@@ -89 +89 @@
----------------------------
-
-you should not directly use the browser's native
-
-
-This also means that 
+do not use the browser's native event API.
+
+
+
-:mochiref:`MochiKit.DOM.addLoadEvent` should not be used in combination with
-this module.
-
-'on' prefix, e.g.:
-'onclick', 'onkeyup'
-
-exactly one parameter,
-the custom 
+``on`` prefix, e.g.: ``onclick``,
+``onkeyup``
+
+one parameter, the custom
+
-
-
@@ -111 +111 @@
-not available even in a correct W3C implementation.
-
-Here is a complete list of this object's methods:
-
-    These are always generated:
-
-    event():
-        The native event produced by the browser. You should not need to
-        access this.
-
-    type():
-        The event type: click, mouseover, keypress, etc. (Does not include
-        the 'on' prefix.)
-
-    target():
-        The element that triggered the event.
-
-    modifier().alt, modifier().ctrl, modifier().meta, modifier().shift:
-        ``true`` if pressed, ``false`` if not. ``modifier().meta`` will be 
-        ``false`` instead of ``undefined`` in IE.
-        
-    modifier().any:
-        ``true`` if any modifier is pressed, ``false`` if not.
-
-    stopPropagation():
-        Works like W3C's ``stopPropagation()``.
-        
-    preventDefault():
-        Works like W3C's ``preventDefault()``.
-        
-    stop():
-        Shortcut that calls ``stopPropagation()`` and ``preventDefault()``.
-
-    You should use keydown and keyup to detect control characters,
-    and keypressed to detect "printable" characters. key().code will be set to
-    0 and key().string will be set to an empty string in a keypress handler if
-    a user presses a control character like F1 or Escape. IE will not fire
-    your keypressed handler when you press a control character like KEY_F1 or
-    KEY_ESCAPE. In your keyup and keydown handlers, Signal will pass the
-    keyboard code and a human-readable string like KEY_A or KEY_ARROW_DOWN or
-    KEY_NUM_PAD_ASTERISK. See ``_specialKeys`` for a comprehensive list. These
-    are generated for keydown and keyup events:
-
-    key().code:
-        contains the raw key code, such as 8 for backspace.
-
-    key().string:
-        contains a human readable string, such as 'KEY_BACKSPACE' or '!'.
-        The complete list is defined in MochiKit.Signal._specialKeys.
-
-    These are only generated for mouse*, click, dblclick, and contextmenu
-    (contextmenu doesn't work in Opera):
-
-    mouse().page.x, mouse().page.y:
-        represents the cursor position relative to the HTML document. 
-        (Equivalent to pageX/Y in Safari, Mozilla, and Opera.)
-        
-    mouse().client.x, mouse().client.y:
-        represents the cursor position relative to the visible portion of the
-        HTML document. (Equivalent to clientX/Y on all browsers.)
-    
-    These are only generated for mouseup, mousedown, click, and dblclick:
-
-    mouse().button.left, mouse().button.right, mouse().button.middle:
-        ``true`` or ``false``. Mac browsers don't report right click
-        consistently. Firefox fires the click and sets modifier().ctrl to
-        true, Opera fires the click and sets modifier().meta to true, and
-        Safari doesn't fire the click (`Safari Bug 6595`_).
-
-        If you want a right click, I suggest that instead of looking for
-        a right click, look for a contextmenu event.
-        
-        Current versions of Safari won't fire a dblclick event when attached
-        via ``connect()`` (`Safari Bug 7790`_).
-
-    This is generated on mouseover and mouseout:
-
-    relatedTarget():
-        the document element that the mouse has moved to.
-
-If you find that you're accessing the native event for any reason, create a
-`new ticket`_ and we'll look into normalizing the behavior you're looking for.
@@ -204 +126 @@
-or :mochiref:`disconnectAll()`.
-
-'onunload'
+``onunload``
-objects on the page when the browser leaves the page. However, memory usage
-will grow during the page view for every connection made until it is
@@ -210 +132 @@
-will still be referenced by Signal until it is explicitly disconnected.
-
-
-
-
+
+
-
-
@@ -240 +161 @@
-=============
-
-
-
+
+
+
-
-:mochidef:`connect(src, signal, dest[, func])`:
@@ -249 +171 @@
-
-    ``src`` is the object that has the signal. You may pass in a string, in
-E
+e
-
-    ``signal`` is a string that represents a signal name. If 'src' is an HTML
-Window, or the Document, then it can be one of the 'on-XYZ'
-
+``window``, or the ``document``, then it can be one of the
+'on-XYZ' 
-    lower-case.
-
@@ -271 +193 @@
-            signalled.
-
-should raise and
+will raise an
-
-    The return value can be passed to :mochiref:`disconnect` to disconnect
@@ -289 +211 @@
-    the connected slots. ``src`` and ``signal`` are the same as for
-    :mochiref:`connect()`.
+
+
+DOM Event API Reference
+-----------------------
+
+:mochidef:`event()`:
+    The native event produced by the browser. You should not need to
+    access this.
+
+:mochidef:`type()`:
+    Returns the event type (``click``, ``mouseover``, ``keypress``, etc.) as a
+    string. Does not include the ``on`` prefix.
+
+:mochidef:`target()`:
+    Returns the element that triggered the event.
+
+:mochidef:`modifier()`:
+    Returns ``{shift, ctrl, meta, alt, any}``, where each property is ``true``
+    if its respective modifier key was pressed, ``false`` otherwise. ``any``
+    is ``true`` if any modifier is pressed, ``false`` otherwise.
+    
+:mochidef:`stopPropagation()`:
+    Works like W3C's ``stopPropagation()``.
+    
+:mochidef:`preventDefault()`:
+    Works like W3C's ``preventDefault()``.
+    
+:mochidef:`stop()`:
+    Shortcut that calls ``stopPropagation()`` and ``preventDefault()``.
+
+:mochidef:`key()`:
+    Returns {code, string}.
+    
+    Use ``onkeydown`` and ``onkeyup`` handlers to detect control characters
+    such as ``KEY_F1``. Use the ``onkeypressed`` handler to detect "printable"
+    characters, such as ``é``.
+    
+    When a user presses F1, in ``onkeydown`` and ``onkeyup`` this method
+    returns ``{code: 122, string: 'KEY_F1'}``. In ``onkeypress``, it returns
+    ``{code: 0, string: ''}``.
+    
+    If a user presses Shift+2 on a US keyboard, this method returns ``{code:
+    50, string: 'KEY_2'}`` in ``onkeydown`` and ``onkeyup``. In
+    ``onkeypress``, it returns ``{code: 64, string: '@'}``.
+        
+    See ``_specialKeys`` for a comprehensive list of control characters.
+
+:mochidef:`mouse()`:
+    Properties for ``onmouse*``, ``onclick``, ``ondblclick``, and
+    ``oncontextmenu`` events. (``contextmenu`` doesn't work in Opera).
+
+        -   ``page`` is a :mochiref:`MochiKit.DOM.Coordinates` object that
+            represents the cursor position relative to the HTML document. 
+            Equivalent to ``pageX`` and ``pageY`` in Safari, Mozilla, and Opera.
+
+        -   ``client`` is a :mochiref:`MochiKit.DOM.Coordinates` object that
+            represents the cursor position relative to the visible portion of 
+            the HTML document. Equivalent to ``clientX`` and ``clientY`` on 
+            all browsers.
+
+    Properties for ``onmouseup``, ``onmousedown``, ``onclick``, and
+    ``ondblclick``:
+
+        -   ``mouse().button`` returns {left, right, middle} where each 
+            property is ``true`` if the mouse button was pressed, ``false`` 
+            otherwise.
+
+    Mac browsers don't report right click consistently. Firefox fires the
+    click and sets ``modifier().ctrl`` to true, Opera fires the click and sets
+    ``modifier().meta`` to ``true``, and Safari doesn't fire the click
+    (`Safari Bug 6595`_).
+
+    If you want a right click, we suggest that instead of looking for a right
+    click, look for a ``contextmenu`` event.
+
+    Current versions of Safari won't fire a ``dblclick`` event when attached
+    via ``connect()`` (`Safari Bug 7790`_).
+
+
+:mochidef:`relatedTarget()`:
+    This is generated on ``mouseover`` and ``mouseout``. Returns the document
+    element that the mouse has moved to.
-
-