NAME
    "POE::Wheel::TermKey" - terminal key input using "libtermkey" with "POE"

SYNOPSIS
     use Term::TermKey qw( FORMAT_VIM KEYMOD_CTRL );
     use POE qw(Wheel::TermKey);
 
     POE::Session->create(
        inline_states => {
           _start => sub {
              $_[HEAP]{termkey} = POE::Wheel::TermKey->new(
                 InputEvent => 'got_key',
              );
           },
           got_key => sub {
              my $key     = $_[ARG0];
              my $termkey = $_[HEAP]{termkey};
 
              print "Got key: ".$termkey->format_key( $key, FORMAT_VIM )."\n";
 
              # Gotta exit somehow.
              delete $_[HEAP]{termkey} if $key->type_is_unicode and
                                          $key->utf8 eq "C" and
                                          $key->modifiers & KEYMOD_CTRL;
           },
        }
     );

     POE::Kernel->run;

DESCRIPTION
    This class implements an asynchronous perl wrapper around the
    "libtermkey" library, which provides an abstract way to read keypress
    events in terminal-based programs. It yields structures that describe
    keys, rather than simply returning raw bytes as read from the TTY
    device.

    This class is a subclass of POE::Wheel, which internally uses an
    instance of Term::TermKey to access the underlying C library. For
    details of on general operation, including the representation of
    keypress events as objects, see the documentation on "Term::TermKey"
    instead.

    Proxy methods exist for normal acessors of "Term::TermKey", and the
    usual behaviour of "getkey" or other methods is instead replaced by the
    "InputEvent".

CONSTRUCTOR
  $wheel = POE::Wheel::TermKey->new( %args )
    Returns a new instance of a "POE::Wheel::TermKey" object. It takes the
    following named parameters:

    Term => IO or INT
            Optional. File handle or POSIX file descriptor number for the
            filehandle to use as the connection to the terminal. If not
            supplied "STDIN" will be used.

    Flags => INT
            "libtermkey" flags to pass to the "Term::TermKey" constructor.

    InputEvent => STRING
            Name of the session event to emit when a key is received. The
            event will be given a single argument, the "Term::TermKey::Key"
            event object, as $_[ARG0].

METHODS
  $tk = $wheel->termkey
    Returns the "Term::TermKey" object being used to access the "libtermkey"
    library. Normally should not be required; the proxy methods should be
    used instead. See below.

  $flags = $wheel->get_flags
  $wheel->set_flags( $flags )
  $canonflags = $wheel->get_canonflags
  $wheel->set_canonflags( $canonflags )
  $msec = $wheel->get_waittime
  $wheel->set_waittime( $msec )
  $str = $wheel->get_keyname( $sym )
  $sym = $wheel->keyname2sym( $keyname )
  ( $ev, $button, $line, $col ) = $wheel->interpret_mouse( $key )
  $str = $wheel->format_key( $key, $format )
  $key = $wheel->parse_key( $str, $format )
  $key = $wheel->parse_key_at_pos( $str, $format )
  $cmp = $wheel->keycmp( $key1, $key2 )
    These methods all proxy to the "Term::TermKey" object, and allow
    transparent use of the "POE::Wheel::TermKey" object as if it was a
    subclass. Their arguments, behaviour and return value are therefore
    those provided by that class. For more detail, see the Term::TermKey
    documentation.

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>