NAME

    Tickit - Terminal Interface Construction KIT

SYNOPSIS

       use Tickit;
       use Tickit::Widget::Box;
       use Tickit::Widget::Static;
    
       my $box = Tickit::Widget::Box->new(
          h_border => 4,
          v_border => 2,
          bg       => "green",
          child    => Tickit::Widget::Static->new(
             text     => "Hello, world!",
             bg       => "black",
             align    => "centre",
             valign   => "middle",
          ),
       );
    
       Tickit->new( root => $box )->run;

DESCRIPTION

    Tickit is a high-level toolkit for creating full-screen terminal-based
    interactive programs. It allows programs to be written in an abstracted
    way, working with a tree of widget objects, to represent the layout of
    the interface and implement its behaviours.

    Its supported terminal features includes a rich set of rendering
    attributes (bold, underline, italic, 256-colours, etc), support for
    mouse including wheel and position events above the 224th column and
    arbitrary modified key input via libtermkey (all of these will require
    a supporting terminal as well). It also supports having multiple
    instances and non-blocking or asynchronous control.

CONSTRUCTOR

 new

       $tickit = Tickit->new( %args )

    Constructs a new Tickit framework container object.

    Takes the following named arguments at construction time:

    term_in => IO

      IO handle for terminal input. Will default to STDIN.

    term_out => IO

      IO handle for terminal output. Will default to STDOUT.

    UTF8 => BOOL

      If defined, overrides locale detection to enable or disable UTF-8
      mode. If not defined then this will be detected from the locale by
      using Perl's ${^UTF8LOCALE} variable.

    root => Tickit::Widget

      If defined, sets the root widget using set_root_widget to the one
      specified.

    use_altscreen => BOOL

      If defined but false, disables the use of altscreen, even if
      supported by the terminal. This will mean that the screen contents
      are stll available after the program has finished.

METHODS

 watch_io

       $id = $tickit->watch_io( $fh, $cond, $code )

    Since version 0.71.

    Runs the given CODE reference at some point in the future, when IO
    operations are possible on the given filehandle. $cond should be a
    bitmask of at least one of the IO_IN, IO_OUT or IO_HUP constants
    describing which kinds of IO operation the callback is interested in.

    Returns an opaque integer value that may be passed to "watch_cancel".
    This value is safe to ignore if not required.

    When invoked, the callback will receive an event parameter which will
    be an instances of a type with a field called cond. This will contain
    the kinds of IO operation that are currently possible.

       $code->( $info )
    
       $current_cond = $info->cond;

    For example, to watch for both input and hangup conditions and respond
    to each individually:

       $tickit->watch_io( $fh, Tickit::IO_IN|Tickit::IO_HUP,
          sub {
             my ( $info ) = @_;
             if( $info->cond & Tickit::IO_IN ) {
                ...
             }
             if( $info->cond & Tickit::IO_HUP ) {
                ...
             }
          }
       );

 watch_later

       $id = $tickit->watch_later( $code )

    Since version 0.70.

    Runs the given CODE reference at some time soon in the future. It will
    not be invoked yet, but will be invoked at some point before the next
    round of input events are processed.

    Returns an opaque integer value that may be passed to "watch_cancel".
    This value is safe to ignore if not required.

 later

       $tickit->later( $code )

    For back-compatibility this method is a synonym for "watch_later".

 watch_timer_at

       $id = $tickit->watch_timer_at( $epoch, $code )

    Since version 0.70.

    Runs the given CODE reference at the given absolute time expressed as
    an epoch number. Fractions are supported to a resolution of
    microseconds.

    Returns an opaque integer value that may be passed to "watch_cancel".
    This value is safe to ignore if not required.

 watch_timer_after

       $id = $tickit->watch_timer_after( $delay, $code )

    Since version 0.70.

    Runs the given CODE reference at the given relative time expressed as a
    number of seconds hence. Fractions are supported to a resolution of
    microseconds.

    Returns an opaque integer value that may be passed to "watch_cancel".
    This value is safe to ignore if not required.

 timer

       $id = $tickit->timer( at => $epoch, $code )
    
       $id = $tickit->timer( after => $delay, $code )

    For back-compatibility this method is a wrapper for either
    "watch_timer_at" or "watch_timer_after" depending on the first
    argument.

    Returns an opaque integer value that may be passed to "cancel_timer".
    This value is safe to ignore if not required.

 watch_signal

       $id = $tickit->watch_signal( $signum, $code )

    Since version 0.72.

    Runs the given CODE reference whenever the given POSIX signal is
    received. Signals are given by number, not name.

    Returns an opaque integer value that may be passed to "watch_cancel".
    This value is safe to ignore if not required.

 watch_process

       $id = $tickit->watch_process( $pid, $code )

    Since version 0.72.

    Runs the given CODE reference when the given child process terminates.

    Returns an opaque integer value that may be passed to "watch_cancel".
    This value is safe to ignore if not required.

    When invoked, the callback will receive an event parameter which will
    be an instance of a type with a field called wstatus. This will contain
    the exit status of the terminated child process.

       $code->( $info )
    
       $pid    = $info->pid;
       $status = $info->wstatus;

 watch_cancel

       $tickit->watch_cancel( $id )

    Since version 0.70.

    Removes an idle or timer watch previously installed by one of the other
    watch_* methods. After doing so the code will no longer be invoked.

 cancel_timer

       $tickit->cancel_timer( $id )

    For back-compatibility this method is a synonym for "watch_cancel".

 term

       $term = $tickit->term

    Returns the underlying Tickit::Term object.

 cols

 lines

       $cols = $tickit->cols
    
       $lines = $tickit->lines

    Query the current size of the terminal. Will be cached and updated on
    receipt of SIGWINCH signals.

 bind_key

       $tickit->bind_key( $key, $code )

    Installs a callback to invoke if the given key is pressed, overwriting
    any previous callback for the same key. The code block is invoked as

       $code->( $tickit, $key )

    If $code is missing or undef, any existing callback is removed.

    As a convenience for the common application use case, the Ctrl-C key is
    bound to the stop method.

    To remove this binding, simply bind another callback, or remove the
    binding entirely by setting undef.

 rootwin

       $tickit->rootwin

    Returns the root Tickit::Window.

 set_root_widget

       $tickit->set_root_widget( $widget )

    Sets the root widget for the application's display. This must be a
    subclass of Tickit::Widget.

 tick

       $tickit->tick( $flags )

    Run a single round of IO events. Does not call setup_term or
    teardown_term.

    $flags may optionally be a bitmask of the following exported constants:

    RUN_NOHANG

      Does not block waiting for IO; simply process whatever is available
      then return immediately.

    RUN_NOSETUP

      Do not perform initial terminal setup before waiting on IO events.

 run

       $tickit->run

    Calls the setup_term method, then processes IO events until stopped, by
    the stop method, SIGINT, SIGTERM or the Ctrl-C key. Then runs the
    teardown_term method, and returns.

 stop

       $tickit->stop

    Causes a currently-running run method to stop processing events and
    return.

MISCELLANEOUS FUNCTIONS

 version_major

 version_minor

 version_patch

       $major = Tickit::version_major()
       $minor = Tickit::version_minor()
       $patch = Tickit::version_patch()

    These non-exported functions query the version of the libtickit library
    that the module is linked to.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>