/ 
Tickit-0.17
River stage two • 35 direct dependents • 41 total dependents
/ Tickit::Term

NAME

Tickit::Term - terminal formatting abstraction

SYNOPSIS

DESCRIPTION

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.

CONSTRUCTOR

$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.

$term = Tickit::Term->new( %params )

Constructs a new Tickit::Term object.

Takes the following named arguments at construction time:

encoding => STRING

Optional. If supplied, applies the named encoding to the Unicode string supplied to the print method.

UTF8 => BOOL

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.

writer => OBJECT

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.

$writer->write( $data )

Such an interface is supported by an IO::Handle object.

output_handle => 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.

input_handle => HANDLE

Optional. If supplied, will be used as the terminal filehandle for reading keypress and other events.

on_resize => CODE

Optional. Event handler function for when the terminal window is resized. Will be passed the Tickit::Term instance, and the new size.

$on_resize->( $term, $lines, $cols )
on_key => CODE

Optional. Event handler function for when a key is pressed. Will be passed the Tickit::Term instance, a type string (either text for unmodified Unicode or key for special keys or modified Unicode), a string containing a representation of the text or key, and the underlying Term::TermKey::Key event.

$on_key->( $term, $type, $str, $key )
on_mouse => CODE

Optional. Event handler function for when a mouse button is pressed or released, or the cursor dragged with a button pressed. Will be passed the Tickit::Term instance, a string indicating press, drag, release or wheel, the button number or wheel direction, and the 0-based line and column index. For wheel events, the direction will be one of up or down.

$on_mouse->( $term, $ev, $button_dir, $line, $col )

METHODS

$fh = $term->get_input_handle

Returns the input handle set by the input_handle constructor arg.

$fh = $term->get_output_handle

Returns the output handle set by the output_handle constructor arg.

$term->set_on_resize( $on_resize )

$term->set_on_key( $on_key )

$term->set_on_mouse( $on_mouse )

Set a new CODE references to handle events.

$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.

$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.

$term->print( $text )

Print the given text to the terminal at the current cursor position

$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.

$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.

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.

$term->clear

Erase the entire screen

$term->erasech( $count, $moveend )

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.

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.

$term->mode_altscreen( $on )

Set or clear the DEC Alternate Screen mode

$term->mode_cursorvis( $on )

Set or clear the cursor visible mode

$term->mode_mouse( $on )

Set or clear the mouse tracking mode

$term->input_push_bytes( $bytes )

Feeds more bytes of input. May result in on_key or on_mouse events.

$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

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.

$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.

TODO

  • Track cursor position, and optimise (or eliminate entirely) goto calls.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>