1Tickit(3)             User Contributed Perl Documentation            Tickit(3)
2
3
4

NAME

6       "Tickit" - Terminal Interface Construction KIT
7

SYNOPSIS

9          use Tickit;
10          use Tickit::Widget::Box;
11          use Tickit::Widget::Static;
12
13          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
25          Tickit->new( root => $box )->run;
26

DESCRIPTION

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

CONSTRUCTOR

41   new
42          $tickit = Tickit->new( %args )
43
44       Constructs a new "Tickit" framework container object.
45
46       Takes the following named arguments at construction time:
47
48       term_in => IO
49               IO handle for terminal input. Will default to "STDIN".
50
51       term_out => IO
52               IO handle for terminal output. Will default to "STDOUT".
53
54       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
59       root => Tickit::Widget
60               If defined, sets the root widget using "set_root_widget" to the
61               one specified.
62
63       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

METHODS

69   watch_io
70          $id = $tickit->watch_io( $fh, $cond, $code )
71
72       Since version 0.71.
73
74       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
79       Returns an opaque integer value that may be passed to "watch_cancel".
80       This value is safe to ignore if not required.
81
82       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
86          $code->( $info )
87
88          $current_cond = $info->cond;
89
90       For example, to watch for both input and hangup conditions and respond
91       to each individually:
92
93          $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
105   watch_later
106          $id = $tickit->watch_later( $code )
107
108       Since version 0.70.
109
110       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
114       Returns an opaque integer value that may be passed to "watch_cancel".
115       This value is safe to ignore if not required.
116
117   later
118          $tickit->later( $code )
119
120       For back-compatibility this method is a synonym for "watch_later".
121
122   watch_timer_at
123          $id = $tickit->watch_timer_at( $epoch, $code )
124
125       Since version 0.70.
126
127       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
131       Returns an opaque integer value that may be passed to "watch_cancel".
132       This value is safe to ignore if not required.
133
134   watch_timer_after
135          $id = $tickit->watch_timer_after( $delay, $code )
136
137       Since version 0.70.
138
139       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
143       Returns an opaque integer value that may be passed to "watch_cancel".
144       This value is safe to ignore if not required.
145
146   timer
147          $id = $tickit->timer( at => $epoch, $code )
148
149          $id = $tickit->timer( after => $delay, $code )
150
151       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
155       Returns an opaque integer value that may be passed to "cancel_timer".
156       This value is safe to ignore if not required.
157
158   watch_signal
159          $id = $tickit->watch_signal( $signum, $code )
160
161       Since version 0.72.
162
163       Runs the given CODE reference whenever the given POSIX signal is
164       received.  Signals are given by number, not name.
165
166       Returns an opaque integer value that may be passed to "watch_cancel".
167       This value is safe to ignore if not required.
168
169   watch_process
170          $id = $tickit->watch_process( $pid, $code )
171
172       Since version 0.72.
173
174       Runs the given CODE reference when the given child process terminates.
175
176       Returns an opaque integer value that may be passed to "watch_cancel".
177       This value is safe to ignore if not required.
178
179       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
183          $code->( $info )
184
185          $pid    = $info->pid;
186          $status = $info->wstatus;
187
188   watch_cancel
189          $tickit->watch_cancel( $id )
190
191       Since version 0.70.
192
193       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
196   cancel_timer
197          $tickit->cancel_timer( $id )
198
199       For back-compatibility this method is a synonym for "watch_cancel".
200
201   term
202          $term = $tickit->term
203
204       Returns the underlying Tickit::Term object.
205
206   cols
207   lines
208          $cols = $tickit->cols
209
210          $lines = $tickit->lines
211
212       Query the current size of the terminal. Will be cached and updated on
213       receipt of "SIGWINCH" signals.
214
215   bind_key
216          $tickit->bind_key( $key, $code )
217
218       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
221          $code->( $tickit, $key )
222
223       If $code is missing or "undef", any existing callback is removed.
224
225       As a convenience for the common application use case, the "Ctrl-C" key
226       is bound to the "stop" method.
227
228       To remove this binding, simply bind another callback, or remove the
229       binding entirely by setting "undef".
230
231   rootwin
232          $tickit->rootwin
233
234       Returns the root Tickit::Window.
235
236   set_root_widget
237          $tickit->set_root_widget( $widget )
238
239       Sets the root widget for the application's display. This must be a
240       subclass of Tickit::Widget.
241
242   tick
243          $tickit->tick( $flags )
244
245       Run a single round of IO events. Does not call "setup_term" or
246       "teardown_term".
247
248       $flags may optionally be a bitmask of the following exported constants:
249
250       RUN_NOHANG
251           Does not block waiting for IO; simply process whatever is available
252           then return immediately.
253
254       RUN_NOSETUP
255           Do not perform initial terminal setup before waiting on IO events.
256
257   run
258          $tickit->run
259
260       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
264   stop
265          $tickit->stop
266
267       Causes a currently-running "run" method to stop processing events and
268       return.
269

MISCELLANEOUS FUNCTIONS

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
278       These non-exported functions query the version of the libtickit library
279       that the module is linked to.
280

AUTHOR

282       Paul Evans <leonerd@leonerd.org.uk>
283
284
285
286perl v5.36.0                      2023-01-20                         Tickit(3)
Impressum