1Tickit::Term(3pm) User Contributed Perl Documentation Tickit::Term(3pm)
2
6 "Tickit::Term" - terminal formatting abstraction
7
10 Provides terminal control primitives for Tickit; a number of methods
11 that control the terminal by writing control strings. This object
12 itself performs no actual IO work; it writes bytes to a delegated
13 object given to the constructor called the writer.
14 This object is not normally constructed directly by the containing
16 application; instead it is used indirectly by other parts of the
17 "Tickit" distribution.
18 Note that a given program may contain multiple objects in this class
20 that all refer to the same underlying "TickitTerm" instance from the C
21 library. This is especially true of the first argument provided to
22 event binding callbacks. This class overloads numify and stringify
23 operations, so that instances may be compared using the "==" or "eq"
24 operators, or used as keys in hashes, and they will act as expected. Do
25 not rely on plain "refaddr" comparison however as you may get incorrect
26 results.
27
29 new
30 $term = Tickit::Term->new( %params )
31 Constructs a new "Tickit::Term" object.
33 Takes the following named arguments at construction time:
35 UTF8 => BOOL
37 If defined, overrides locale detection to enable or disable
38 UTF-8 mode. If not defined then this will be detected from the
39 locale by using Perl's "${^UTF8LOCALE}" variable.
40 writer => OBJECT
42 An object delegated to for sending strings of terminal control
43 bytes to the terminal itself. This object must support a single
44 method, "write", taking a string of bytes.
45 $writer->write( $data )
47 Such an interface is supported by an "IO::Handle" object.
49 output_handle => HANDLE
51 Optional. If supplied, will be used as the terminal filehandle
52 for querying the size. Even if supplied, all writing operations
53 will use the "writer" function rather than performing IO
54 operations on this filehandle.
55 input_handle => HANDLE
57 Optional. If supplied, will be used as the terminal filehandle
58 for reading keypress and other events.
59 open_stdio
61 $term = Tickit::Term->open_stdio
62 Convenient shortcut for obtaining a Tickit::Term instance bound to the
64 STDIN and STDOUT streams of the process.
65
67 get_input_handle
68 $fh = $term->get_input_handle
69 Returns the input handle set by the "input_handle" constructor arg.
71 Note that because Tickit::Term merely wraps an object provided by the
73 lower-level libtickit C library, it is no longer guaranteed that this
74 method will return the same perl-level object that was given to the
75 constructor. The object may be newly-constructed to represent a new
76 perl-level readable filehandle on the same file number.
77 get_output_handle
79 $fh = $term->get_output_handle
80 Returns the output handle set by the "output_handle" constructor arg.
82 Note that because Tickit::Term merely wraps an object provided by the
84 lower-level libtickit C library, it is no longer guaranteed that this
85 method will return the same perl-level object that was given to the
86 constructor. The object may be newly-constructed to represent a new
87 perl-level writable filehandle on the same file number.
88 set_output_buffer
90 $term->set_output_buffer( $len )
91 Sets the size of the output buffer
93 await_started
95 $term->await_started( $timeout )
96 Waits for the terminal startup process to complete, up to the timeout
98 given in seconds.
99 pause
101 $term->pause
102 Suspends operation of the terminal by resetting it to its default
104 state.
105 resume
107 $term->resume
108 Resumes operation of the terminal after a "pause".
110 Typically these two methods are used together, either side of a
112 blocking wait around a "SIGSTOP".
113 sub suspend
115 {
116 $term->pause;
117 kill STOP => $$;
118 $term->resume;
119 $rootwin->expose;
120 }
121 teardown
123 $term->teardown
124 Shuts down operation of the terminal entirely, in preparation for
126 terminating the process.
127 flush
129 $term->flush
130 Flushes the output buffer to the terminal
132 bind_event
134 $id = $term->bind_event( $ev, $code, $data )
135 Installs a new event handler to watch for the event specified by $ev,
137 invoking the $code reference when it occurs. $code will be invoked with
138 the given terminal, the event name, an event information object, and
139 the $data value it was installed with. "bind_event" returns an ID value
140 that may be used to remove the handler by calling "unbind_event_id".
141 $ret = $code->( $term, $ev, $info, $data )
143 The type of $info will depend on the kind of event that was received,
145 as indicated by $ev. The information structure types are documented in
146 Tickit::Event.
147 bind_event (with flags)
149 $id = $term->bind_event( $ev, $flags, $code, $data )
150 The $code argument may optionally be preceded by an integer of flag
152 values. This should be zero to apply default semantics, or a bitmask of
153 one or more of the following constants:
154 TICKIT_BIND_FIRST
156 Inserts this event handler first in the chain, before any existing
157 ones.
158 TICKIT_BIND_ONESHOT
160 Remove the event handler after it has been invoked the first time.
161 unbind_event_id
163 $term->unbind_event_id( $id )
164 Removes an event handler that returned the given $id value.
166 refresh_size
168 $term->refresh_size
169 If a filehandle was supplied to the constructor, fetch the size of the
171 terminal and update the cached sizes in the object. May invoke
172 "on_resize" if the new size is different.
173 set_size
175 $term->set_size( $lines, $cols )
176 Defines the size of the terminal. Invoke "on_resize" if the new size is
178 different.
179 lines
181 cols
182 $lines = $term->lines
183 $cols = $term->cols
185 Query the size of the terminal, as set by the most recent
187 "refresh_size" or "set_size" operation.
188 goto
190 $success = $term->goto( $line, $col )
191 Move the cursor to the given position on the screen. If only one
193 parameter is defined, does not alter the other. Both $line and $col are
194 0-based.
195 Note that not all terminals can support these partial moves. This
197 method returns a boolean indicating success; if the terminal could not
198 perform the move it will need to be retried using a fully-specified
199 call.
200 move
202 $term->move( $downward, $rightward )
203 Move the cursor relative to where it currently is.
205 scrollrect
207 $success = $term->scrollrect( $top, $left, $lines, $cols, $downward, $rightward )
208 Attempt to scroll the rectangle of the screen defined by the first four
210 parameters by an amount given by the latter two. Since most terminals
211 cannot perform arbitrary rectangle scrolling, this method returns a
212 boolean to indicate if it was successful. The caller should test this
213 return value and fall back to another drawing strategy if the attempt
214 was unsuccessful.
215 The cursor may move as a result of calling this method; its location is
217 undefined if this method returns successful.
218 chpen
220 $term->chpen( $pen )
221 $term->chpen( %attrs )
223 Changes the current pen attributes to those given. Any attribute whose
225 value is given as "undef" is reset. Any attributes not named are
226 unchanged.
227 For details of the supported pen attributes, see Tickit::Pen.
229 setpen
231 $term->setpen( $pen )
232 $term->setpen( %attrs )
234 Similar to "chpen", but completely defines the state of the terminal
236 pen. Any attribute not given will be reset to its default value.
237 print
239 $term->print( $text, [ $pen ] )
240 Print the given text to the terminal at the current cursor position.
242 An optional "Tickit::Pen" may be provided; if present it will be set as
244 if given to "setpen" first.
245 clear
247 $term->clear( [ $pen ] )
248 Erase the entire screen.
250 An optional "Tickit::Pen" may be provided; if present it will be set as
252 if given to "setpen" first.
253 erasech
255 $term->erasech( $count, $moveend, [ $pen ] )
256 Erase $count characters forwards. If $moveend is true, the cursor is
258 moved to the end of the erased region. If defined but false, the cursor
259 will remain where it is. If undefined, the terminal will perform
260 whichever of these behaviours is more efficient, and the cursor will
261 end at some undefined location.
262 Using $moveend may be more efficient than separate "erasech" and "goto"
264 calls on terminals that do not have an erase function, as it will be
265 implemented by printing spaces. This removes the need for two cursor
266 jumps.
267 An optional "Tickit::Pen" may be provided; if present it will be set as
269 if given to "setpen" first.
270 getctl_int
272 setctl_int
273 $value = $term->getctl_int( $ctl )
274 $success = $term->setctl_int( $ctl, $value )
276 Gets or sets the value of an integer terminal control option. $ctl
278 should be one of the following options. They can be specified either as
279 integers, using the following named constants, or as strings giving the
280 part following "TERMCTL_" in lower-case.
281 On failure, each method returns "undef".
283 TERMCTL_ALTSCREEN
285 Enables DEC Alternate Screen mode
286 TERMCTL_CURSORVIS
288 Enables cursor visible mode
289 TERMCTL_CURSORBLINK
291 Enables cursor blinking mode
292 TERMCTL_CURSORSHAPE
294 Sets the shape of the cursor. $value should be one of
295 "CURSORSHAPE_BLOCK", "CURSORSHAPE_UNDER" or
296 "CURSORSHAPE_LEFT_BAR".
297 TERMCTL_KEYPAD_APP
299 Enables keypad application mode
300 TERMCTL_MOUSE
302 Enables mouse tracking mode. $vaule should be one of
303 "TERM_MOUSEMODE_CLICK", "TERM_MOUSEMODE_DRAG",
304 "TERM_MOUSEMODE_MOVE" or "TERM_MOUSEMODE_OFF".
305 setctl_str
307 $success = $term->setctl_str( $ctl, $value )
308 Sets the value of a string terminal control option. $ctrl should be one
310 of the following options. They can be specified either as integers or
311 strings, as for "setctl_int".
312 TERMCTL_ICON_TEXT
314 TERMCTL_TITLE_TEXT
315 TERMCTL_ICONTITLE_TEXT
316 Sets the terminal window icon text, title, or both.
317 getctl
319 setctl
320 $value = $term->getctl( $ctl )
321 $success = $term->setctl( $ctl, $value )
323 A newer form of the various typed get and set methods above. This
325 version will interpret the given value as appropriate, depending on the
326 control type.
327 input_push_bytes
329 $term->input_push_bytes( $bytes )
330 Feeds more bytes of input. May result in "key" or "mouse" events.
332 input_readable
334 $term->input_readable
335 Informs the term that the input handle may be readable. Attempts to
337 read more bytes of input. May result in "key" or "mouse" events.
338 input_wait
340 $term->input_wait( $timeout )
341 Block until some input is available, and process it. Returns after one
343 round of input has been processed. May result in "key" or "mouse"
344 events. If $timeout is defined, it will wait a period of time no longer
345 than this time before returning, even if no input events were received.
346 check_timeout
348 $timeout = $term->check_timeout
349 Returns a number in seconds to represent when the next timeout should
351 occur on the terminal, or "undef" if nothing is waiting. May invoke
352 expired timeouts, and cause a "key" event to occur.
353 emit_key
355 $term->emit_key(
356 type => $type, str => $str, [ mod => $mod ]
357 )
358 Invokes the key event handlers as if an event with the given info had
360 just been received. The "mod" argument is optional, a default of 0 will
361 apply if it is missing.
362 emit_mouse
364 $term->emit_mouse(
365 type => $type, button => $button, line => $line, col => $col,
366 [ mod => $mod ]
367 )
368 Invokes the mouse event handlers as if an event with the given info had
370 just been received. The "mod" argument is optional, a default of 0 will
371 apply if it is missing.
372
374 The following event types are emitted and may be observed by
375 "bind_event".
376 resize
378 Emitted when the terminal itself has been resized.
379 key
381 Emitted when a key on the keyboard is pressed.
382 mouse
384 Emitted when a mouse button is pressed or released, the cursor moved
385 while a button is held (a dragging event), or the wheel is scrolled.
386 Behaviour of events involving more than one mouse button is not well-
388 specified by terminals.
389
391 • Track cursor position, and optimise (or eliminate entirely) "goto"
392 calls.
393
395 Paul Evans <leonerd@leonerd.org.uk>
396perl v5.38.0 2023-07-21 Tickit::Term(3pm)