| 1 |
NAME |
| 2 |
|
| 3 |
Tickit - Terminal Interface Construction KIT |
| 4 |
|
| 5 |
SYNOPSIS |
| 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 |
|
| 25 |
DESCRIPTION |
| 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 |
|
| 39 |
CONSTRUCTOR |
| 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 |
|
| 74 |
METHODS |
| 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 |
|
| 298 |
MISCELLANEOUS 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 |
|
| 313 |
AUTHOR |
| 314 |
|
| 315 |
Paul Evans <[email protected]> |
| 316 |
|