Tickit(3pm)

✨ Tickit(3pm) — the Terminal Interface Construction KIT ✨

okay so bestie, welcome to Tickit, the Terminal Interface Construction KIT 💅 it's a Perl module and honestly it ate. this is the manual page, rewritten with love, and every single detail is still here — no cap.

---

🌸 SYNOPSIS 🌸

like, here's the whole vibe in one go:

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;

that's it. that's the whole flex. 🫶

---

🦋 DESCRIPTION 🦋

Tickit is a high-level toolkit for building full-screen, terminal-based interactive programs — literally the main character of your terminal 🔥 it lets you write programs in an abstracted way, working with a whole tree of widget objects to represent the layout of your interface and implement its behaviours. it's giving architecture. it's giving structure.

its supported terminal features include:

• a rich set of rendering attributes — bold, underline, italic, 256-colours, etc. 💖
• support for mouse, including wheel and position events above the 224th column 🐭
• arbitrary modified key input via libtermkey
• and honestly? it also supports having multiple instances, plus non-blocking or asynchronous control ✨

⚠️ heads up bestie: all of those features will require a supporting terminal as well — the module can only do so much, your terminal has to show up for the vibe check too.

---

🎀 CONSTRUCTOR 🎀

new

$tickit = Tickit->new( %args )

Constructs a new Tickit framework container object. your whole app lives in here basically 👑

it takes these named arguments at construction time:

• term_in => IO — the IO handle for terminal input. defaults to STDIN.
• term_out => IO — the IO handle for terminal output. defaults to STDOUT.
• UTF8 => BOOL — if you define it, it overrides locale detection to force UTF-8 mode on or off. if you leave it undefined, it gets detected from the locale using Perl's ${^UTF8LOCALE} variable.
• root => Tickit::Widget — if defined, sets the root widget (via set_root_widget) to the one you specified.
• use_altscreen => BOOL — if it's defined but false, it disables the use of altscreen even if the terminal supports it. which means the screen contents are still available after the program has finished. (yes, the original really does spell it "stll" — we're keeping their typo energy, it's iconic 🙈)

---

💜 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, whenever IO operations are actually 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 you may pass to watch_cancel. it's totally safe to ignore this value if you don't need it.

when it gets invoked, the callback receives an event parameter — an instance of a type with a field called cond. that contains the kinds of IO operation that are currently possible:

$code->( $info )

$current_cond = $info->cond;

for example, watching for both input and hangup conditions and responding to each one 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 some time soon in the future. not right this second though — it won't be invoked yet, but it will be invoked at some point before the next round of input events are processed. lowkey a queue moment.

returns an opaque integer value that may be passed to watch_cancel. safe to ignore if you don't need it.

later

$tickit->later( $code )

for back-compatibility, this method is a synonym for watch_later. old-school slay 💅

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, down to a resolution of microseconds. precise queen 🎀

returns an opaque integer value that may be passed to watch_cancel. 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 from now. fractions supported too, microseconds resolution. same energy, different math ✨

returns an opaque integer value that may be passed to watch_cancel. safe to ignore if not required.

timer

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

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

for back-compatibility, this one's a wrapper that calls either watch_timer_at or watch_timer_after, depending on whichever first argument you give it. choose your fighter 🫶

returns an opaque integer value that may be passed to cancel_timer. 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. and listen — signals are given by number, not name 🔢 don't come at it with "SIGINT", bestie, it wants the digits.

returns an opaque integer value that may be passed to watch_cancel. 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. bye-bye little subprocess 👋

returns an opaque integer value that may be passed to watch_cancel. safe to ignore if not required.

when invoked, the callback gets an event parameter — an instance of a type with a field called wstatus. that contains 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. once you do this, the code will no longer be invoked. sorry to that code 😭 it's cancelled (literally).

cancel_timer

$tickit->cancel_timer( $id )

for back-compatibility, this method is a synonym for watch_cancel. vintage behaviour, still valid 💖

term

$term = $tickit->term

returns the underlying Tickit::Term object. the whole terminal, right there in your hand 🖥️

cols

lines

$cols = $tickit->cols

$lines = $tickit->lines

query the current size of the terminal. it'll be cached and updated when SIGWINCH signals arrive — so if you resize your window it knows, it always knows 👀

bind_key

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

installs a callback to invoke when the given key is pressed, overwriting any previous callback for that same key. the code block gets invoked like:

$code->( $tickit, $key )

if $code is missing or undef, any existing callback is removed. clean slate, periodt.

as a convenience for the common application use case, the Ctrl-C key is bound to the stop method by default ⭐ iconic default behaviour honestly.

to remove that binding, just bind another callback, or remove the binding entirely by setting undef.

rootwin

$tickit->rootwin

returns the root Tickit::Window. the big boss window 🌈

set_root_widget

$tickit->set_root_widget( $widget )

sets the root widget for the application's display. it must be a subclass of Tickit::Widget — no random objects, bestie, we have standards 💅

tick

$tickit->tick( $flags )

runs a single round of IO events. note that it does not call setup_term or teardown_term — it's just one little tick, not the whole lifecycle 🕰️

$flags may optionally be a bitmask of these exported constants:

• RUN_NOHANG — does not block waiting for IO; it just processes whatever is available and returns immediately. impatient icon ✨
• RUN_NOSETUP — do not perform initial terminal setup before waiting on IO events. skip the pre-show.

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 it runs the teardown_term method, and returns. full lifecycle, start to finish, main character energy 👑

stop

$tickit->stop

causes a currently-running run method to stop processing events and return. the graceful exit we all deserve 🦋

---

⭐ 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. note that's the libtickit library version, not the Perl module's — important distinction, iykyk 👀

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — the legend responsible for all of this. thank you king 🫶

---

okay that's the whole page, every single flag, every default, every version note, every caveat, all accounted for 💖 and for the cute sign-off: this page is from perl v5.42.3, dated 2026-08-19, and it's the Tickit(3pm) page from the User Contributed Perl Documentation. slay. ✨🎀💅