view release on metacpan or  search on metacpan

lib/Alien/GvaScript/KeyMap.pod  view on Meta::CPAN

specific keyboard. However, this event type only fires for 
printable characters, so you cannot observe C<keypress> if
you intend to capture special keys such as arrow keys, function keys, etc.

=back

In theory, attributes such as C<onkeydown> or C<onkeypress> 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 C<document> element.

Events C<keypress> and C<keydown> will repeat if the
key is held down.


In order to attach the keymap to an element, you can either
use the supplied L</"observe"> method, or call the 
L</"eventHandler"> method to get the keymap event handler, and
then use your favorite technique to attach that handler
to an element.



=head1 METHODS

=head2 C<KeyMap>

  var myKeyMap = new KeyMap(rules);

Constructor for a keymap object. 

=head3 Single-key rules

The rules argument is a map from key specifications to handlers, like
for example 

  { 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'");}
  }

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

=head3 Regex rules

For situations where several key combination will
fire the same handler, you can insert a C<REGEX> entry in the map.
This should be an array of triplets, where each triplet is of shape
C<[modifiers, regex, handler]>, like for example

  var regexRules = [["C_",   "[0-9]",             myCtrlDigitHandler],
                    ["C_S_", /^[AEIOU]$/,         myCtrlShiftVowelHandler],
                    [null,   "RETURN|TAB|ESCAPE", someOtherHandler]   ];

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.

More specifically, the members of rule triplets are :

=over

=item modifiers

A string specifiying the key modifiers for which the rule will fire;
the string a concatenation of B<C_>, B<S_> and B<A_>, as explained above.
An empty string means that the rule only fires when no modifiers
are pressed. By contrast, a C<null> value specifies that
modifiers are ignored (the rule fires in any case).

=item regex

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 C<^> and end anchor C<$>
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 C</[AEIOU]/>
would match any builtin keyname like C<RETURN> or C<ESCAPE>, which
is probably not the intended meaning of the rule).

=item handler

The function to be called when the rule succeeds.

=back


=head3 Antiregex rules

An C<ANTIREGEX> entry in the map
works exactly like a C<REGEX>, except that
the handler is called when the regex does
B<not> match. This is useful if you want to 
catch most key events, except 
a given set.



=head2 C<eventHandler>

  document.onkeydown = aKeyMap.eventHandler(options);

Generates an event handler that can be attached to an HTML element.
This method is called internally by the L</"observe"> method.
Use C<eventHandler> directly if you need fine control
on how the handler is attached to the dynamic HTML model.

The C<options> argument is optional. If present, it should be an
inline object containing truth values for the following
keys :

=over

=item C<ignoreCtrl>

ignore the C<Ctrl> keyboard modifier