view release on metacpan or  search on metacpan

doc/html/KeyMap.html  view on Meta::CPAN

  </div>
  <div class="TN_node" id="SYNOPSIS">
    <h2 class="TN_label">SYNOPSIS</h2>
    <div class="TN_content">
      <pre>  var rules = {
  
    // attach handlers to specific keys
    RETURN: function(event){doSomethingWith(event)},  
    C_DOWN: ctrlArrowDownHandler,       
    C_S_F7: ctrlShiftF7Handler,
  
    // special rules using regular expressions
    REGEX: [ ["",   /^[0-9]$/,      digitHandler  ],
             ["C_", /^[aeiou]$/i, ctrlVowelHandler] ], 
  
    // use Ctrl-X as a prefix for another set of rules
    C_X: KeyMap.Prefix({R: ctrlX_R_handler,
                        4: ctrlX_4_handler})
  };
  
  // create a keymap object
  var aKeyMap = new KeyMap(rules);

  // attach the corresponding handler to the keydown event (on document)
  aKeyMap.observe("keydown");
  
  // other way to attach : manually insert handler
  document.onkeydown = aKeyMap.eventHandler({preventDefault: true,
                                             ignoreShift   : true});

  // dynamically change the map
  aKeyMap.rules.push(new_rules);
  
  // idem, temporarily ignore all keys
  aKeyMap.rules.push(KeyMap.MapAllKeys(function(){}));
  
  // back to previous handling state
  aKeyMap.rules.pop();</pre>


    </div>
  </div>
  <div class="TN_node" id="DESCRIPTION">
    <h2 class="TN_label">DESCRIPTION</h2>
    <div class="TN_content">
      <p>Provides an abstraction layer for associating handlers
with HTML key events, in a browser-independent way.</p>
<p>A <i>keymap</i> is a stack of collections of rules. Each rule has a 
<i>key specification</i>
or a <i>regexp specification</i>, and a <i>handler</i> to be called whenever the
specification is met. The keymap object as a whole can then be
registered as a usual HTML event handler associated to some DOM
element (most often the <i>document</i> element), and will dispatch key
events to appropriate handlers.</p>
<p>Key specifications look like <b>A</b> (key 'A'),
 <b>C_S_A</b> (control-shift-A), <b>A_DELETE</b> (alt-Delete).
They are formed from :</p>
<ul>
<li><a name="item_keynames"></a><b>keynames</b>
<p>For printable characters, the keyname is just that character; for special
editing keys such as backspace, arrow up, etc., names are taken 
from the following list of builtins :</p>
<pre>  BACKSPACE ESCAPE     TAB    RETURN LINEFEED SPACE 
  PAGE_UP   PAGE_DOWN  END    HOME 
  LEFT      UP         RIGHT  DOWN
  INSERT    DELETE     PAUSE  WINDOWS  PRINT_SCREEN
  CAPS_LOCK NUM_LOCK   SCROLL_LOCK
  F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
  CTRL      SHIFT      ALT</pre>

</li>
<li><a name="item_modifiers"></a><b>modifiers</b>
<p>Modifiers are specified through prefixes <b>C_</b>, <b>S_</b> and <b>A_</b>, corresponding
to key modifiers <i>control</i>, <i>shift</i> and <i>alt</i>. 
Several prefixes may be combined, but must appear in the order just given
(so for example <b>S_C_A</b> would be illegal).</p>
</li>
</ul>
<p>Alternatively, key specifications may also formed from key codes
instead of key names, so for example <code>C_13</code> is equivalent to <code>C_RETURN</code>.
For key codes  0-9, and additional '0' is required to avoid confusion
with digits: so <code>C_09</code> is equivalent to <code>C_TAB</code>, while <code>C_9</code> means
"control-numeric 9".</p>
<p>In addition, keymap objects can also manage <i>regex rules</i> that
cover several possible key events; details are given below.</p>

    </div>
  </div>
  <div class="TN_node" id="WRITING_HANDLERS">
    <h2 class="TN_label">WRITING HANDLERS</h2>
    <div class="TN_content">
      <p>Following the W3C event model, handlers called from the keymap object 
receive an <i>event object</i> as argument. This is the usual HTML event
object, augmented with two properties <code>keyName</code> and <code>keyModifiers</code>, 
computed according to the specifications given above. So for 
example a simple handler can be</p>
<pre>  var myHandler = function (event) {
    alert(event.keyName + " was pressed with modifiers " + 
          event.keyModifiers);
  }</pre>

<p>Further propagation of the event to other handlers is cancelled by
default : W3C methods <code>event.stopPropagation()</code> and
<code>event.preventDefault()</code> are called automatically by the keymap
object (or, if running under Microsoft Internet Explorer, property
<code>cancelBubble</code> is set to true and and property <code>returnValue</code> is set
to false). This default behaviour can be disabled if necessary, 
as explained below.</p>

    </div>
  </div>
  <div class="TN_node" id="ATTACHING_TO_HTML_ELEMENTS">
    <h2 class="TN_label">ATTACHING TO HTML ELEMENTS</h2>
    <div class="TN_content">
      <p>Keymaps may be attached to HTML elements on the 
<code>keydown</code>, <code>keypress</code> or <code>keyup</code> event types.
Choosing the proper event type is important, as it
affects not only the time at which events are fired, 
but also the returned keycodes :</p>
<ul>
<li><a name="item__code_keydown__code__and__code_keyup__code_"></a><b><code>keydown</code> and <code>keyup</code></b>

doc/html/KeyMap.html  view on Meta::CPAN

<p>Generates an event handler that can be attached to an HTML element.
This method is called internally by the <a href="#observe">/"observe"</a> method.
Use <code>eventHandler</code> directly if you need fine control
on how the handler is attached to the dynamic HTML model.</p>
<p>The <code>options</code> argument is optional. If present, it should be an
inline object containing truth values for the following
keys :</p>
<ul>
<li><a name="item__code_ignoreCtrl__code_"></a><b><code>ignoreCtrl</code></b>
<p>ignore the <code>Ctrl</code> keyboard modifier</p>
</li>
<li><a name="item__code_ignoreShift__code_"></a><b><code>ignoreShift</code></b>
<p>ignore the <code>Shift</code> keyboard modifier</p>
</li>
<li><a name="item__code_ignoreAlt__code_"></a><b><code>ignoreAlt</code></b>
<p>ignore the <code>Alt</code> keyboard modifier</p>
</li>
<li><a name="item__code_stopPropagation__code_"></a><b><code>stopPropagation</code></b>
<p>stop propagation of the event</p>
</li>
<li><a name="item__code_preventDefault__code_"></a><b><code>preventDefault</code></b>
<p>prevent default navigator behaviour on that event</p>
</li>
</ul>
<p>For example if <code>ignoreCtrl</code> is true, then the key 
specification <code>"C_S_TAB"</code> would
never fire, because Ctrl-Shift-TAB key events would be encoded merely
as <code>"S_TAB"</code>.</p>

    </div>
  </div>
  <div class="TN_node" id="observe">
    <h3 class="TN_label"><code>observe</code></h3>
    <div class="TN_content">
      <pre>  aKeyMap.observe(eventType, htmlElement, options);</pre>

<p>This is the preferred way for attaching the keymap object to an HTML
element, on a given event type (<code>keydown</code>, <code>keypress</code> or <code>keyup</code>).
Arguments are optional. The default event type is <code>"keydown"</code>,
and the default element is <code>document</code>.</p>
<p>Options are passed to the <a href="#eventHandler">/"eventHandler"</a> method.
If not explicitly given, the options default
to <code>undefined</code> except for event type <code>keypress</code>, where
<code>ignoreShift</code> defaults to <code>true</code>. The reason is that the Shift
modifier heavily depends on which keyboard the user is using, and
often the user really has no choice on pressing or not the Shift key
(this would generate a different keycode). So it makes sense to just
stop paying attention to the Shift key for <code>keypress</code> events.</p>

    </div>
  </div>
  <div class="TN_node" id="rules">
    <h3 class="TN_label"><code>rules</code></h3>
    <div class="TN_content">
      <pre>  aKeyMap.rules.push(new_rules);
  
  aKeyMap.rules.pop();</pre>

<p>A DHTML application may need to temporarily change the key handlers (for 
example when switching from navigation mode to editing mode).
Therefore, a keymap object actually holds a <i>stack</i> of rules
and publishes this stack in its <code>rules</code> property.
Rules pushed on top of that stack will take precedence over 
pre-existing rules; conversely, popping from the stack
restores the keymap to its previous state.</p>

    </div>
  </div>
  <div class="TN_node" id="MapAllKeys">
    <h3 class="TN_label"><code>MapAllKeys</code></h3>
    <div class="TN_content">
      <pre>  // grab all keys
  aKeyMap.rules.push(KeyMap.MapAllKeys(my_handler)); 
  
  // ignore all keys
  aKeyMap.rules.push(KeyMap.MapAllKeys(function (){}));</pre>

<p>Convenience function to build a regex rule that matches all keys.</p>

    </div>
  </div>
  <div class="TN_node" id="Prefix">
    <h3 class="TN_label"><code>Prefix</code></h3>
    <div class="TN_content">
      <pre>  main_rules = {C_X: KeyMap.Prefix({R: ctrlX_R_handler,
                                    4: ctrlX_4_handler})};</pre>

<p>Specifies that a key (here <code>Ctrl-X</code>) is a prefix to another
set of rules : the next key event will be passed to these rules,
and after that the main rules resumes normal behaviour.
Hence you can attach handlers to sequences of keys, like for
example in Emacs.</p>

    </div>
  </div>
  <div class="TN_node" id="destroy">
    <h3 class="TN_label"><code>destroy</code></h3>
    <div class="TN_content">
      <pre>  aKeyMap.destroy();</pre>

<p>This method will remove the keymap handler attached the element/document.
Call this method when the concerned element is removed from the DOM
or to deactivate the keymap handler.</p>

    </div>
  </div>

    </div>
  </div>

</div>
</body>
</html>