RCU::Context - Remote Control Unit Interface

NAME

RCU::Context - Remote Control Unit Interface

SYNOPSIS

   use RCU::Context;

DESCRIPTION

$ctx = new RCU::Context;

Create a new key context.

$ctx->bind(event, action)

Bind the given action to an event (see EVENT SYNTAX, below, for an explanation of this string).

action must be one of the following:

 A code-reference
   This code reference will be called with the event name, generating rcu,
   timestamp and any additional arguments (usually none) fiven to the
   inject method.

 "enter", $context
 "enter*", $context
   Enter the given context object. The forms with an appended star "re-exec"
   the event in the new context.

 "leave"
 "leave*"
   leave the current context (restoring the context active before it was
   "enter"'ed)

 "switch", $context
 "switch*", $context
   switch to the given context object

For every keypress, only the first (in order of their definition) matching event handler is being executed.

$ctx->inject(event, time, rcu, args...)

Simulate the given event (see ``EVENT SYNTAX'', below).

$ctx->enter($rcu)

$ctx->leave($rcu)

``Enter'' (``Leave'') the context (and create an <enter> (<leave>``) event). Not usually called by application code.

EVENT SYNTAX

The simplest way to specify events is using the (cooked) keyname, e.g. the event cd-shuffle occurs when the key named ``cd-shuffle'' was pressed down.

Since events are regular expressions, you have to quote any special characters (like . or *, where ^, $ and . stop at keys boundaries) if you want to use them. On the other hand, regexes give you great freedom, if you specify the event:

 rcu-key-(\d+)

... you can then use ``$1'' in your callback to find out which digit was pressed.

You can prefix a keyname with a ``~'' which means the key was released (deactivates, switched off) instead of being pressed. If you want to force interpretation as a key-down event you can prefix the keyname with an ``='' character.

Every key will always generate two events: one key-down (activate) event when it is pressed and one ``~'' (key-up) event when it is released again. It is not possible that two keys are active at the same time.

To make matters slightly more complicated, you can also prepend a ``history'' of key names (all seperated by ``:'') before the current event. This means that the event depends on previous key-presses (no prefix characters are there).

Examples (all key names are, of course, hypothetical):

  <enter>          enter the current context
  key-ff           the fast forward key was pressed down
  =key-ff          same as above
  ~key-rev         the "rev"-key was released
  key-tuner:key-4  first the tuner key was pressed (and released), then "4"
  key-tuner:~key-4 first the tuner key was pressed, then "4" was released
  k1:k2:k3         the keys "1", "2" were pressed and released, then
                   "3" was pressed.

EBNF-Grammar

For those of you who need it...

  event     := history prefix eventname
  history   := <empty> | keyname ":" history
  prefix    := <empty> | "=" | "~"
  eventname := keyname | "<enter>" | "<leave>"
  keyname   := any string consisting of printable, non-whitespace
               characters without ":"

AUTHOR