Tickit::Term - terminal formatting abstraction
Tickit::Term
Provides terminal control primatives for Tickit; a number of methods that control the terminal by writing control strings. This object itself performs no acutal IO work; it writes bytes to a delegated object given to the constructor called the writer.
This object is not normally constructed directly by the containing application; instead it is used indirectly by other parts of the Tickit distribution.
Tickit
$term = Tickit::Term->find_for_term( %params )
Attempts to load and construct a subclass determined by the current terminal type (as given by $ENV{TERM}). If this fails, returns a normal Tickit::Term instead.
$ENV{TERM}
$term = Tickit::Term->new( %params )
Constructs a new Tickit::Term object.
Takes the following named arguments at construction time:
If defined, overrides locale detection to enable or disable UTF-8 mode. If not defined then this will be detected from the locale by using Perl's ${^UTF8LOCALE} variable.
${^UTF8LOCALE}
An object delegated to for sending strings of terminal control bytes to the terminal itself. This object must support a single method, write, taking a string of bytes.
write
$writer->write( $data )
Such an interface is supported by an IO::Handle object.
IO::Handle
Optional. If supplied, will be used as the terminal filehandle for querying the size. Even if supplied, all writing operations will use the writer function rather than performing IO operations on this filehandle.
writer
Optional. If supplied, will be used as the terminal filehandle for reading keypress and other events.
$fh = $term->get_input_handle
Returns the input handle set by the input_handle constructor arg.
input_handle
$fh = $term->get_output_handle
Returns the output handle set by the output_handle constructor arg.
output_handle
$term->set_output_buffer( $len )
Sets the size of the output buffer
$term->await_started( $timeout )
Waits for the terminal startup process to complete, up to the timeout given in seconds.
$term->flush
Flushes the output buffer to the terminal
$id = $term->bind_event( $ev, $code, $data )
Installs a new event handler to watch for the event specified by $ev, invoking the $code reference when it occurs. $code will be invoked with the given the terminal, the event name, a HASH reference containing event arguments, and the $data value. It returns an ID value that may be used to remove the handler by calling unbind_event_id.
$ev
$code
HASH
$data
unbind_event_id
$ret = $code->( $term, $ev, $args, $data )
The $args hash will contain keys depending on the event type:
$args
The hash will contain type (a dualvar giving the key event type as an integer or string event name, text or key), str (a string containing the key event string), and mod (an integer bitmask indicating the modifier state).
type
text
key
str
mod
The hash will contain type (a dualvar giving the mouse event type as an integer or string event name, press, drag, release or wheel), button (an integer for non-wheel events, or a dualvar for wheel events giving the wheel direction as up or down), line and col as integers, and mod (an integer bitmask indicating the modifier state).
press
drag
release
wheel
button
up
down
line
col
The hash will contain lines and cols as integers.
lines
cols
This method is aliased as bind_event_default for forward compatibility to account for "bind_event_with_flags" being renamed to simply bind_event.
bind_event_default
bind_event
$id = $term->bind_event_with_flags( $ev, $flags, $code, $data )
Similar to "bind_event" but passes the $flags argument too. This should be zero to apply default semantics, or a bitmask of one or more of the following constants:
$flags
Inserts this event handler first in the chain, before any existing ones.
$term->unbind_event_id( $id )
Removes an event handler that returned the given $id value.
$id
$term->refresh_size
If a filehandle was supplied to the constructor, fetch the size of the terminal and update the cached sizes in the object. May invoke on_resize if the new size is different.
on_resize
$term->set_size( $lines, $cols )
Defines the size of the terminal. Invoke on_resize if the new size is different.
$lines = $term->lines $cols = $term->cols
Query the size of the terminal, as set by the most recent refresh_size or set_size operation.
refresh_size
set_size
$success = $term->goto( $line, $col )
Move the cursor to the given position on the screen. If only one parameter is defined, does not alter the other. Both $line and $col are 0-based.
$line
$col
Note that not all terminals can support these partial moves. This method returns a boolean indicating success; if the terminal could not perform the move it will need to be retried using a fully-specified call.
$term->move( $downward, $rightward )
Move the cursor relative to where it currently is.
$success = $term->scrollrect( $top, $left, $lines, $cols, $downward, $rightward )
Attempt to scroll the rectangle of the screen defined by the first four parameters by an amount given by the latter two. Since most terminals cannot perform arbitrary rectangle scrolling, this method returns a boolean to indicate if it was successful. The caller should test this return value and fall back to another drawing strategy if the attempt was unsuccessful.
The cursor may move as a result of calling this method; its location is undefined if this method returns successful.
$term->chpen( $pen ) $term->chpen( %attrs )
Changes the current pen attributes to those given. Any attribute whose value is given as undef is reset. Any attributes not named are unchanged.
undef
For details of the supported pen attributes, see Tickit::Pen.
$term->setpen( $pen ) $term->setpen( %attrs )
Similar to chpen, but completely defines the state of the terminal pen. Any attribute not given will be reset to its default value.
chpen
$term->print( $text, [ $pen ] )
Print the given text to the terminal at the current cursor position.
An optional Tickit::Pen may be provided; if present it will be set as if given to setpen first.
Tickit::Pen
setpen
$term->clear( [ $pen ] )
Erase the entire screen.
$term->erasech( $count, $moveend, [ $pen ] )
Erase $count characters forwards. If $moveend is true, the cursor is moved to the end of the erased region. If defined but false, the cursor will remain where it is. If undefined, the terminal will perform whichever of these behaviours is more efficient, and the cursor will end at some undefined location.
$count
$moveend
Using $moveend may be more efficient than separate erasech and goto calls on terminals that do not have an erase function, as it will be implemented by printing spaces. This removes the need for two cursor jumps.
erasech
goto
$value = $term->getctl_int( $ctl ) $success = $term->setctl_int( $ctl, $value )
Gets or sets the value of an integer terminal control option. $ctl should be one of the following options. They can be specified either as integers, using the following named constants, or as strings giving the part following TERMCTL_ in lower-case.
$ctl
TERMCTL_
On failure, each method returns undef.
Enables DEC Alternate Screen mode
Enables cursor visible mode
Enables cursor blinking mode
Sets the shape of the cursor. $value should be one of CURSORSHAPE_BLOCK, CURSORSHAPE_UNDER or CURSORSHAPE_LEFT_BAR.
$value
CURSORSHAPE_BLOCK
CURSORSHAPE_UNDER
CURSORSHAPE_LEFT_BAR
Enables keypad application mode
Enables mouse tracking mode. $vaule should be one of TERM_MOUSEMODE_CLICK, TERM_MOUSEMODE_DRAG, TERM_MOUSEMODE_MOVE or TERM_MOUSEMODE_OFF.
$vaule
TERM_MOUSEMODE_CLICK
TERM_MOUSEMODE_DRAG
TERM_MOUSEMODE_MOVE
TERM_MOUSEMODE_OFF
$success = $term->setctl_str( $ctl, $value )
Sets the value of a string terminal control option. $ctrl should be one of the following options. They can be specified either as integers or strings, as for setctl_int.
$ctrl
setctl_int
Sets the terminal window icon text, title, or both.
$term->input_push_bytes( $bytes )
Feeds more bytes of input. May result in on_key or on_mouse events.
on_key
on_mouse
$term->input_readable
Informs the term that the input handle may be readable. Attempts to read more bytes of input. May result in on_key or on_mouse events.
$term->input_wait( $timeout )
Block until some input is available, and process it. Returns after one round of input has been processed. May result in on_key or on_mouse events. If $timeout is defined, it will wait a period of time no longer than this time before returning, even if no input events were received.
$timeout
$timeout = $term->check_timeout
Returns a number in seconds to represent when the next timeout should occur on the terminal, or undef if nothing is waiting. May invoke expired timeouts, and cause a on_key event to occur.
$term->emit_key( type => $type, str => $str, [ mod => $mod ] )
Invokes the key event handlers as if an event with the given info had just been received. The mod argument is optional, a default of 0 will apply if it is missing.
$term->emit_mouse( type => $type, button => $button, line => $line, col => $col, [ mod => $mod ] )
Invokes the mouse event handlers as if an event with the given info had just been received. The mod argument is optional, a default of 0 will apply if it is missing.
Track cursor position, and optimise (or eliminate entirely) goto calls.
Paul Evans <leonerd@leonerd.org.uk>
To install Tickit, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tickit
CPAN shell
perl -MCPAN -e shell install Tickit
For more information on module installation, please visit the detailed CPAN module installation guide.