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

SEE ALSO

RCU.

AUTHOR

This perl extension was written by Marc Lehmann <pcg@goof.com>.