view release on metacpan or  search on metacpan

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

=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

=item C<ignoreShift>

ignore the C<Shift> keyboard modifier

=item C<ignoreAlt>

ignore the C<Alt> keyboard modifier

=item C<stopPropagation>

stop propagation of the event

=item C<preventDefault>

prevent default navigator behaviour on that event

=back

For example if C<ignoreCtrl> is true, then the key 
specification C<"C_S_TAB"> would