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>