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