1Tickit(3pm) User Contributed Perl Documentation Tickit(3pm)
2
6 "Tickit" - Terminal Interface Construction KIT
7
9 use Tickit;
10 use Tickit::Widget::Box;
11 use Tickit::Widget::Static;
12 my $box = Tickit::Widget::Box->new(
14 h_border => 4,
15 v_border => 2,
16 bg => "green",
17 child => Tickit::Widget::Static->new(
18 text => "Hello, world!",
19 bg => "black",
20 align => "centre",
21 valign => "middle",
22 ),
23 );
24 Tickit->new( root => $box )->run;
26
28 "Tickit" is a high-level toolkit for creating full-screen terminal-
29 based interactive programs. It allows programs to be written in an
30 abstracted way, working with a tree of widget objects, to represent the
31 layout of the interface and implement its behaviours.
32 Its supported terminal features includes a rich set of rendering
34 attributes (bold, underline, italic, 256-colours, etc), support for
35 mouse including wheel and position events above the 224th column and
36 arbitrary modified key input via libtermkey (all of these will require
37 a supporting terminal as well). It also supports having multiple
38 instances and non-blocking or asynchronous control.
39
41 new
42 $tickit = Tickit->new( %args )
43 Constructs a new "Tickit" framework container object.
45 Takes the following named arguments at construction time:
47 term_in => IO
49 IO handle for terminal input. Will default to "STDIN".
50 term_out => IO
52 IO handle for terminal output. Will default to "STDOUT".
53 UTF8 => BOOL
55 If defined, overrides locale detection to enable or disable
56 UTF-8 mode. If not defined then this will be detected from the
57 locale by using Perl's "${^UTF8LOCALE}" variable.
58 root => Tickit::Widget
60 If defined, sets the root widget using "set_root_widget" to the
61 one specified.
62 use_altscreen => BOOL
64 If defined but false, disables the use of altscreen, even if
65 supported by the terminal. This will mean that the screen
66 contents are stll available after the program has finished.
67
69 watch_io
70 $id = $tickit->watch_io( $fh, $cond, $code )
71 Since version 0.71.
73 Runs the given CODE reference at some point in the future, when IO
75 operations are possible on the given filehandle. $cond should be a
76 bitmask of at least one of the "IO_IN", "IO_OUT" or "IO_HUP" constants
77 describing which kinds of IO operation the callback is interested in.
78 Returns an opaque integer value that may be passed to "watch_cancel".
80 This value is safe to ignore if not required.
81 When invoked, the callback will receive an event parameter which will
83 be an instances of a type with a field called "cond". This will contain
84 the kinds of IO operation that are currently possible.
85 $code->( $info )
87 $current_cond = $info->cond;
89 For example, to watch for both input and hangup conditions and respond
91 to each individually:
92 $tickit->watch_io( $fh, Tickit::IO_IN|Tickit::IO_HUP,
94 sub {
95 my ( $info ) = @_;
96 if( $info->cond & Tickit::IO_IN ) {
97 ...
98 }
99 if( $info->cond & Tickit::IO_HUP ) {
100 ...
101 }
102 }
103 );
104 watch_later
106 $id = $tickit->watch_later( $code )
107 Since version 0.70.
109 Runs the given CODE reference at some time soon in the future. It will
111 not be invoked yet, but will be invoked at some point before the next
112 round of input events are processed.
113 Returns an opaque integer value that may be passed to "watch_cancel".
115 This value is safe to ignore if not required.
116 later
118 $tickit->later( $code )
119 For back-compatibility this method is a synonym for "watch_later".
121 watch_timer_at
123 $id = $tickit->watch_timer_at( $epoch, $code )
124 Since version 0.70.
126 Runs the given CODE reference at the given absolute time expressed as
128 an epoch number. Fractions are supported to a resolution of
129 microseconds.
130 Returns an opaque integer value that may be passed to "watch_cancel".
132 This value is safe to ignore if not required.
133 watch_timer_after
135 $id = $tickit->watch_timer_after( $delay, $code )
136 Since version 0.70.
138 Runs the given CODE reference at the given relative time expressed as a
140 number of seconds hence. Fractions are supported to a resolution of
141 microseconds.
142 Returns an opaque integer value that may be passed to "watch_cancel".
144 This value is safe to ignore if not required.
145 timer
147 $id = $tickit->timer( at => $epoch, $code )
148 $id = $tickit->timer( after => $delay, $code )
150 For back-compatibility this method is a wrapper for either
152 "watch_timer_at" or "watch_timer_after" depending on the first
153 argument.
154 Returns an opaque integer value that may be passed to "cancel_timer".
156 This value is safe to ignore if not required.
157 watch_signal
159 $id = $tickit->watch_signal( $signum, $code )
160 Since version 0.72.
162 Runs the given CODE reference whenever the given POSIX signal is
164 received. Signals are given by number, not name.
165 Returns an opaque integer value that may be passed to "watch_cancel".
167 This value is safe to ignore if not required.
168 watch_process
170 $id = $tickit->watch_process( $pid, $code )
171 Since version 0.72.
173 Runs the given CODE reference when the given child process terminates.
175 Returns an opaque integer value that may be passed to "watch_cancel".
177 This value is safe to ignore if not required.
178 When invoked, the callback will receive an event parameter which will
180 be an instance of a type with a field called "wstatus". This will
181 contain the exit status of the terminated child process.
182 $code->( $info )
184 $pid = $info->pid;
186 $status = $info->wstatus;
187 watch_cancel
189 $tickit->watch_cancel( $id )
190 Since version 0.70.
192 Removes an idle or timer watch previously installed by one of the other
194 "watch_*" methods. After doing so the code will no longer be invoked.
195 cancel_timer
197 $tickit->cancel_timer( $id )
198 For back-compatibility this method is a synonym for "watch_cancel".
200 term
202 $term = $tickit->term
203 Returns the underlying Tickit::Term object.
205 cols
207 lines
208 $cols = $tickit->cols
209 $lines = $tickit->lines
211 Query the current size of the terminal. Will be cached and updated on
213 receipt of "SIGWINCH" signals.
214 bind_key
216 $tickit->bind_key( $key, $code )
217 Installs a callback to invoke if the given key is pressed, overwriting
219 any previous callback for the same key. The code block is invoked as
220 $code->( $tickit, $key )
222 If $code is missing or "undef", any existing callback is removed.
224 As a convenience for the common application use case, the "Ctrl-C" key
226 is bound to the "stop" method.
227 To remove this binding, simply bind another callback, or remove the
229 binding entirely by setting "undef".
230 rootwin
232 $tickit->rootwin
233 Returns the root Tickit::Window.
235 set_root_widget
237 $tickit->set_root_widget( $widget )
238 Sets the root widget for the application's display. This must be a
240 subclass of Tickit::Widget.
241 tick
243 $tickit->tick( $flags )
244 Run a single round of IO events. Does not call "setup_term" or
246 "teardown_term".
247 $flags may optionally be a bitmask of the following exported constants:
249 RUN_NOHANG
251 Does not block waiting for IO; simply process whatever is available
252 then return immediately.
253 RUN_NOSETUP
255 Do not perform initial terminal setup before waiting on IO events.
256 run
258 $tickit->run
259 Calls the "setup_term" method, then processes IO events until stopped,
261 by the "stop" method, "SIGINT", "SIGTERM" or the "Ctrl-C" key. Then
262 runs the "teardown_term" method, and returns.
263 stop
265 $tickit->stop
266 Causes a currently-running "run" method to stop processing events and
268 return.
269
271 version_major
272 version_minor
273 version_patch
274 $major = Tickit::version_major()
275 $minor = Tickit::version_minor()
276 $patch = Tickit::version_patch()
277 These non-exported functions query the version of the libtickit library
279 that the module is linked to.
280
282 Paul Evans <leonerd@leonerd.org.uk>
283perl v5.38.0 2023-07-21 Tickit(3pm)