view release on metacpan or  search on metacpan

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

performs the translation from keys to characters, according to your
specific keyboard. However, this event type only fires for 
printable characters, so you cannot observe <code>keypress</code> if
you intend to capture special keys such as arrow keys, function keys, etc.</p>
</li>
</ul>
<p>In theory, attributes such as <code>onkeydown</code> or <code>onkeypress</code> may be
used with most HTML elements; but in practice, most of them will actually
never fire the key events! So the most common and most sensible way
for capturing key events is to attach to the <code>document</code> element.</p>
<p>Events <code>keypress</code> and <code>keydown</code> will repeat if the
key is held down.</p>
<p>In order to attach the keymap to an element, you can either
use the supplied <a href="#observe">/"observe"</a> method, or call the 
<a href="#eventHandler">/"eventHandler"</a> method to get the keymap event handler, and
then use your favorite technique to attach that handler
to an element.</p>

    </div>
  </div>
  <div class="TN_node" id="METHODS">
    <h2 class="TN_label">METHODS</h2>
    <div class="TN_content">
        <div class="TN_node" id="KeyMap">
    <h3 class="TN_label"><code>KeyMap</code></h3>
    <div class="TN_content">
      <pre>  var myKeyMap = new KeyMap(rules);</pre>

<p>Constructor for a keymap object.</p>
  <div class="TN_node" id="Single_key_rules">
    <h4 class="TN_label">Single-key rules</h4>
    <div class="TN_content">
      <p>The rules argument is a map from key specifications to handlers, like
for example</p>
<pre>  { A:     function() {alert("pressed 'A'");},
    S_TAB: function() {alert("pressed 'Shift-Tab'");},
    CTRL:  function() {alert("pressed the 'Ctrl' key");},
    10:    function() {alert("pressed 'Linefeed' or maybe 'Ctrl-Return'");}
  }</pre>

<p>Each key specification in the map corresponds to exacly one key
combination, so for example <code>S_TAB</code> will not fire if the user pressed
<code>Ctrl-Shift-Tab</code>.</p>

    </div>
  </div>
  <div class="TN_node" id="Regex_rules">
    <h4 class="TN_label">Regex rules</h4>
    <div class="TN_content">
      <p>For situations where several key combination will
fire the same handler, you can insert a <code>REGEX</code> entry in the map.
This should be an array of triplets, where each triplet is of shape
<code>[modifiers, regex, handler]</code>, like for example</p>
<pre>  var regexRules = [["C_",   "[0-9]",             myCtrlDigitHandler],
                    ["C_S_", /^[AEIOU]$/,         myCtrlShiftVowelHandler],
                    [null,   "RETURN|TAB|ESCAPE", someOtherHandler]   ];</pre>

<p>Whenever a key event is received, it is converted into a keyname, and 
then that keynames is compared against the regex rules, in order : the 
first rule that matches calls the corresponding handler and terminates
the event handling process.</p>
<p>More specifically, the members of rule triplets are :</p>
<ul>
<li><a name="item_modifiers"></a><b>modifiers</b>
<p>A string specifiying the key modifiers for which the rule will fire;
the string a concatenation of <b>C_</b>, <b>S_</b> and <b>A_</b>, as explained above.
An empty string means that the rule only fires when no modifiers
are pressed. By contrast, a <code>null</code> value specifies that
modifiers are ignored (the rule fires in any case).</p>
</li>
<li><a name="item_regex"></a><b>regex</b>
<p>Either a string containing a regular expression, or an already built
Javascript RegExp object. Strings will be automatically converted
to regular expressions, with start anchor <code>^</code> and end anchor <code>$</code>
automatically added. If you supply an already built RegExp object,
make sure to deal properly with the anchors; otherwise the rule
might fire in unexpected cases (for example the plain regex <code>/[AEIOU]/</code>
would match any builtin keyname like <code>RETURN</code> or <code>ESCAPE</code>, which
is probably not the intended meaning of the rule).</p>
</li>
<li><a name="item_handler"></a><b>handler</b>
<p>The function to be called when the rule succeeds.</p>
</li>
</ul>

    </div>
  </div>
  <div class="TN_node" id="Antiregex_rules">
    <h4 class="TN_label">Antiregex rules</h4>
    <div class="TN_content">
      <p>An <code>ANTIREGEX</code> entry in the map
works exactly like a <code>REGEX</code>, except that
the handler is called when the regex does
<b>not</b> match. This is useful if you want to 
catch most key events, except 
a given set.</p>

    </div>
  </div>

    </div>
  </div>
  <div class="TN_node" id="eventHandler">
    <h3 class="TN_label"><code>eventHandler</code></h3>
    <div class="TN_content">
      <pre>  document.onkeydown = aKeyMap.eventHandler(options);</pre>

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