/ 
Tickit-0.70
River stage two • 35 direct dependents • 41 total dependents
/ Tickit

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.

At the current version, this is a Perl distribution which contains and XS and C implementation of the lower levels (Tickit::Term and Tickit::Pen), and implements the higher levels (Tickit::Window and Tickit::Widget) in pure perl. The XS parts are supported by libtickit, either from the installed library, or using a bundled copy compiled at build time. It is intended that eventually the Window layer will be rewritten in XS and C instead.

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_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_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>