Tickit::Term(3pm)

🌸 Tickit::Term — terminal formatting abstraction 🌸

okay so bestie, welcome to Tickit::Term(3pm) from the User Contributed Perl Documentation — yes that's the whole title, and yes it's a whole vibe. this is the part of Tickit that talks to your terminal in control strings. let's get into it 💅

---

✨ SYNOPSIS ✨

ngl, this section is literally empty in the original 😭 like not one line. zero. nothing. so go straight to the constructor and the rest of the page, that's where the good stuff lives 🫶

---

🌈 DESCRIPTION 🌈

So what is this thing? Tickit::Term hands you a whole bunch of terminal control primitives for Tickit — basically a pile of methods that boss your terminal around by writing out control strings. 🔥

Here's the important part, so listen up 👑: this object does no actual IO work itself. None. It takes the bytes and hands them off to a delegated object that you give it in the constructor — that's called the writer. The writer does the real work, Tickit::Term just writes bytes to it. it's giving manager energy, honestly.

Also super important: your containing application doesn't normally construct this object directly — nah, it gets used indirectly by the other parts of the Tickit distribution. iykyk 🧚

And here's a subtle little thing that will absolutely bite you if you don't know it: one single program can contain multiple objects of this class that all refer to the same underlying TickitTerm instance from the C library. This is especially true of that first argument you get handed in event binding callbacks, bestie — that's the one, the sneaky one. 🙈

The good news? This class overloads numify and stringify, so you can compare instances with the == or eq operators, or even use them as keys in hashes, and everything behaves exactly like you'd expect. slay. ✨

⚠️ But do not rely on a plain refaddr comparison, okay? lowkey you may get incorrect results. consider yourself warned 💀

---

🎀 CONSTRUCTOR 🎀

new

$term = Tickit::Term->new( %params )

Constructs a shiny new Tickit::Term object. 🦋

It takes these named arguments at construction time:

• UTF8 => BOOL — if it's defined, this overrides locale detection and forces UTF-8 mode on or off, whichever you asked for. If you leave it undefined, UTF-8 mode gets detected from the locale by peeking at Perl's ${^UTF8LOCALE} variable. cute. ⭐
• writer => OBJECT — the delegated object that actually sends your strings of terminal control bytes off to the terminal itself. It only has to support one single method, write, which takes a string of bytes:

$writer->write( $data )

and guess what, an IO::Handle object already supports exactly that interface. 💖

• output_handle => HANDLE — optional. If you supply it, it gets used as the terminal filehandle for querying the size. But listen — even if you do supply it, all the writing operations still go through the writer function, not through IO operations on this filehandle. so don't get it twisted 😭
• input_handle => HANDLE — optional. If you supply it, it's the terminal filehandle used for reading keypresses and other events. 🍓

---

open_stdio

$term = Tickit::Term->open_stdio

A super convenient shortcut for grabbing a Tickit::Term instance already bound to the STDIN and STDOUT streams of the process. one line, zero stress, we love to see it 🫶🌸

---

okay that's the constructor covered — keep reading for the rest, bestie 💜

💖 METHODS 💖

🌸 get_input_handle 🌸

$fh = $term->get_input_handle

Returns the input handle that was set by the "input_handle" constructor arg. Bestie, heads up: because Tickit::Term merely wraps an object provided by the lower-level libtickit C library, it is no longer guaranteed that this method will return the same perl-level object that was given to the constructor. The object may be newly-constructed to represent a new perl-level readable filehandle on the same file number. It’s giving “same energy, new wrapper” ✨

🦋 get_output_handle 🦋

$fh = $term->get_output_handle

Returns the output handle that was set by the "output_handle" constructor arg. Same little plot twist as above: because Tickit::Term merely wraps an object provided by the lower-level libtickit C library, it is no longer guaranteed that this method will return the same perl-level object that was given to the constructor. The object may be newly-constructed to represent a new perl-level writable filehandle on the same file number. Periodt 💅

🎀 set_output_buffer 🎀

$term->set_output_buffer( $len )

Sets the size of the output buffer. That’s it, that’s the whole vibe.

🌈 await_started 🌈

$term->await_started( $timeout )

Waits for the terminal startup process to complete, up to the timeout given in seconds. Think of it as the terminal’s “almost ready, bestie” moment.

💜 pause 💜

$term->pause

Suspends operation of the terminal by resetting it to its default state. It’s lowkey putting the terminal in airplane mode.

🫶 resume 🫶

$term->resume

Resumes operation of the terminal after a "pause".

Typically these two methods are used together, either side of a blocking wait around a "SIGSTOP". Iconic teamwork, no cap:

sub suspend
{
   $term->pause;
   kill STOP => $$;
   $term->resume;
   $rootwin->expose;
}

🧚 teardown 🧚

$term->teardown

Shuts down operation of the terminal entirely, in preparation for terminating the process. This is the goodbye-for-real part, not a casual “brb” 💀

🍓 flush 🍓

$term->flush

Flushes the output buffer to the terminal. Your words are leaving the group chat and actually showing up on screen ✨

👑 bind_event 👑

$id = $term->bind_event( $ev, $code, $data )

Installs a new event handler to watch for the event specified by $ev, invoking the $code reference when it occurs. $code will be invoked with the given terminal, the event name, an event information object, and the $data value it was installed with. "bind_event" returns an ID value that may be used to remove the handler by calling "unbind_event_id".

 $ret = $code->( $term, $ev, $info, $data )

The type of $info will depend on the kind of event that was received, as indicated by $ev. The information structure types are documented in Tickit::Event. Slay.

🎀 bind_event (with flags) 🎀

$id = $term->bind_event( $ev, $flags, $code, $data )

The $code argument may optionally be preceded by an integer of flag values. This should be zero to apply default semantics, or a bitmask of one or more of the following constants:

• TICKIT_BIND_FIRST — Inserts this event handler first in the chain, before any existing ones.
• TICKIT_BIND_ONESHOT — Remove the event handler after it has been invoked the first time.

Choose your fighter, or combine flags like the main character you are 💅

🌸 unbind_event_id 🌸

$term->unbind_event_id( $id )

Removes an event handler that returned the given $id value. We love a clean exit.

🦋 refresh_size 🦋

$term->refresh_size

If a filehandle was supplied to the constructor, fetch the size of the terminal and update the cached sizes in the object. May invoke "on_resize" if the new size is different. The terminal said “new size, who dis?”

🌈 set_size 🌈

$term->set_size( $lines, $cols )

Defines the size of the terminal. Invoke "on_resize" if the new size is different. You’re literally setting the stage, bestie.

💜 lines / cols 💜

$lines = $term->lines

$cols = $term->cols

Query the size of the terminal, as set by the most recent "refresh_size" or "set_size" operation. Tiny vibe check, big usefulness.

🫶 goto 🫶

$success = $term->goto( $line, $col )

Move the cursor to the given position on the screen. If only one parameter is defined, does not alter the other. Both $line and $col are 0-based.

Note that not all terminals can support these partial moves. This method returns a boolean indicating success; if the terminal could not perform the move it will need to be retried using a fully-specified call. No cap, partial moves are not universally understood 😭

🧚 move 🧚

$term->move( $downward, $rightward )

Move the cursor relative to where it currently is. It’s giving “scoot over a lil bit” energy.

🍓 scrollrect 🍓

$success = $term->scrollrect( $top, $left, $lines, $cols, $downward, $rightward )

Attempt to scroll the rectangle of the screen defined by the first four parameters by an amount given by the latter two. Since most terminals cannot perform arbitrary rectangle scrolling, this method returns a boolean to indicate if it was successful. The caller should test this return value and fall back to another drawing strategy if the attempt was unsuccessful.

The cursor may move as a result of calling this method; its location is undefined if this method returns successful. Undefined cursor location is not a vibe, but it is the spec 💀

👑 chpen 👑

$term->chpen( $pen )

$term->chpen( %attrs )

Changes the current pen attributes to those given. Any attribute whose value is given as "undef" is reset. Any attributes not named are unchanged.

For details of the supported pen attributes, see Tickit::Pen. Your pen is having a little glow-up ✨

🎀 setpen 🎀

$term->setpen( $pen )

$term->setpen( %attrs )

Similar to "chpen", but completely defines the state of the terminal pen. Any attribute not given will be reset to its default value. Full reset, no crumbs, periodt.

🌸 print 🌸

$term->print( $text, [ $pen ] )

Print the given text to the terminal at the current cursor position.

An optional Tickit::Pen may be provided; if present it will be set as if given to "setpen" first. Cute text, cute styling, iconic behavior.

🦋 clear 🦋

$term->clear( [ $pen ] )

Erase the entire screen.

An optional Tickit::Pen may be provided; if present it will be set as if given to "setpen" first. Clean slate energy 🌈

🌈 erasech 🌈

$term->erasech( $count, $moveend, [ $pen ] )

Erase $count characters forwards. If $moveend is true, the cursor is moved to the end of the erased region. If defined but false, the cursor will remain where it is. If undefined, the terminal will perform whichever of these behaviours is more efficient, and the cursor will end at some undefined location.

Using $moveend may be more efficient than separate "erasech" and "goto" calls on terminals that do not have an erase function, as it will be implemented by printing spaces. This removes the need for two cursor jumps. Efficiency slay 🔥

An optional Tickit::Pen may be provided; if present it will be set as if given to "setpen" first.

💜 getctl_int / setctl_int 💜

$value = $term->getctl_int( $ctl )

$success = $term->setctl_int( $ctl, $value )

Gets or sets the value of an integer terminal control option. $ctl should be one of the following options. They can be specified either as integers, using the following named constants, or as strings giving the part following "TERMCTL_" in lower-case.

On failure, each method returns "undef".

• TERMCTL_ALTSCREEN — Enables DEC Alternate Screen mode.
• TERMCTL_CURSORVIS — Enables cursor visible mode.
• TERMCTL_CURSORBLINK — Enables cursor blinking mode.
• TERMCTL_CURSORSHAPE — Sets the shape of the cursor. $value should be one of "CURSORSHAPE_BLOCK", "CURSORSHAPE_UNDER" or "CURSORSHAPE_LEFT_BAR".
• TERMCTL_KEYPAD_APP — Enables keypad application mode.
• TERMCTL_MOUSE — Enables mouse tracking mode. $vaule should be one of "TERM_MOUSEMODE_CLICK", "TERM_MOUSEMODE_DRAG", "TERM_MOUSEMODE_MOVE" or "TERM_MOUSEMODE_OFF".

(Yes, $vaule — the typo is canon, and we respect the lore 🫶)

🫶 setctl_str 🫶

$success = $term->setctl_str( $ctl, $value )

Sets the value of a string terminal control option. $ctrl should be one of the following options. They can be specified either as integers or strings, as for "setctl_int".

• TERMCTL_ICON_TEXT, TERMCTL_TITLE_TEXT, TERMCTL_ICONTITLE_TEXT — Sets the terminal window icon text, title, or both.

Window title glow-up? We love to see it 💅

🧚 getctl / setctl 🧚

$value = $term->getctl( $ctl )

$success = $term->setctl( $ctl, $value )

A newer form of the various typed get and set methods above. This version will interpret the given value as appropriate, depending on the control type. It’s giving “one method to rule them all” energy.

🍓 input_push_bytes 🍓

$term->input_push_bytes( $bytes )

Feeds more bytes of input. May result in "key" or "mouse" events. Snack time for the input parser.

👑 input_readable 👑

$term->input_readable

Informs the term that the input handle may be readable. Attempts to read more bytes of input. May result in "key" or "mouse" events. A little “hey bestie, check your messages” moment.

🎀 input_wait 🎀

$term->input_wait( $timeout )

Block until some input is available, and process it. Returns after one round of input has been processed. May result in "key" or "mouse" events. If $timeout is defined, it will wait a period of time no longer than this time before returning, even if no input events were received. Patient but not too patient, iykyk.

🌸 check_timeout 🌸

$timeout = $term->check_timeout

Returns a number in seconds to represent when the next timeout should occur on the terminal, or "undef" if nothing is waiting. May invoke expired timeouts, and cause a "key" event to occur. Timeout check, but make it fashion ⏰

🦋 emit_key 🦋

$term->emit_key(
   type => $type, str => $str, [ mod => $mod ]
)

Invokes the key event handlers as if an event with the given info had just been received. The "mod" argument is optional, a default of 0 will apply if it is missing. Pretend keypress, real handler energy.

🌈 emit_mouse 🌈

$term->emit_mouse(
   type => $type, button => $button, line => $line, col => $col,
   [ mod => $mod ]
)

Invokes the mouse event handlers as if an event with the given info had just been received. The "mod" argument is optional, a default of 0 will apply if it is missing. Mouse drama, simulated and served 💅

🌈 EVENTS 🌈

The following event types are emitted and may be observed by "bind_event".

• resize — Emitted when the terminal itself has been resized.
• key — Emitted when a key on the keyboard is pressed.
• mouse — Emitted when a mouse button is pressed or released, the cursor moved while a button is held (a dragging event), or the wheel is scrolled.

Behaviour of events involving more than one mouse button is not well-specified by terminals. Multiple-button mouse chaos is lowkey a mystery 💀

🦋 TODO 🦋

• Track cursor position, and optimise (or eliminate entirely) "goto" calls.

Future glow-up noted, bestie ✨

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

This absolute icon of a page is Tickit::Term(3pm) from perl v5.42.3, dated 2026-08-19. Bye bestie, go slay some terminal controls 💖✨🎀