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