NAME

Tickit::Term - terminal formatting abstraction

SYNOPSIS

DESCRIPTION

Provides terminal control primitives for Tickit; a number of methods that control the terminal by writing control strings. This object itself performs no actual 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.

Note that a given program may contain multiple objects in this class that all refer to the same underlying TickitTerm instance from the C library. This is especially true of the first argument provided to event binding callbacks. This class overloads numify and stringify operations, so that instances may be compared using the == or eq operators, or used as keys in hashes, and they will act as expected. Do not rely on plain refaddr comparison however as you may get incorrect results.

CONSTRUCTOR

new

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

Constructs a new Tickit::Term object.

Takes the following named arguments at construction time:

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.

open_stdio

$term = Tickit::Term->open_stdio

Convenient shortcut for obtaining a Tickit::Term instance bound to the STDIN and STDOUT streams of the process.

METHODS

get_input_handle

$fh = $term->get_input_handle

Returns the input handle set by the input_handle constructor arg.

Note that because Tickit::Term merely wraps an object provided by the lower-level libtickit C library, it is no longer guaranteed that this method will return the same perl-level object that was given to the constructor. The object may be newly-constructed to represent a new perl-level readable filehandle on the same file number.

get_output_handle

$fh = $term->get_output_handle

Returns the output handle set by the output_handle constructor arg.

Note that because Tickit::Term merely wraps an object provided by the lower-level libtickit C library, it is no longer guaranteed that this method will return the same perl-level object that was given to the constructor. The object may be newly-constructed to represent a new perl-level writable filehandle on the same file number.

set_output_buffer

$term->set_output_buffer( $len )

Sets the size of the output buffer

await_started

$term->await_started( $timeout )

Waits for the terminal startup process to complete, up to the timeout given in seconds.

pause

$term->pause

Suspends operation of the terminal by resetting it to its default state.

resume

$term->resume

Resumes operation of the terminal after a "pause".

Typically these two methods are used together, either side of a blocking wait around a SIGSTOP.

sub suspend
{
   $term->pause;
   kill STOP => $$;
   $term->resume;
   $rootwin->expose;
}

teardown

$term->teardown

Shuts down operation of the terminal entirely, in preparation for terminating the process.

flush

$term->flush

Flushes the output buffer to the terminal

bind_event

$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 terminal, the event name, an event information object, and the $data value it was installed with. bind_event returns an ID value that may be used to remove the handler by calling unbind_event_id.

$ret = $code->( $term, $ev, $info, $data )

The type of $info will depend on the kind of event that was received, as indicated by $ev. The information structure types are documented in Tickit::Event.

bind_event (with flags)

$id = $term->bind_event( $ev, $flags, $code, $data )

The $code argument may optionally be preceded by an integer of flag values. This should be zero to apply default semantics, or a bitmask of one or more of the following constants:

TICKIT_BIND_FIRST

Inserts this event handler first in the chain, before any existing ones.

TICKIT_BIND_ONESHOT

Remove the event handler after it has been invoked the first time.

unbind_event_id

$term->unbind_event_id( $id )

Removes an event handler that returned the given $id value.

refresh_size

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

set_size

$term->set_size( $lines, $cols )

Defines the size of the terminal. Invoke on_resize if the new size is different.

lines

cols

$lines = $term->lines

$cols = $term->cols

Query the size of the terminal, as set by the most recent refresh_size or set_size operation.

goto

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

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.

move

$term->move( $downward, $rightward )

Move the cursor relative to where it currently is.

scrollrect

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

chpen

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

setpen

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

print

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

clear

$term->clear( [ $pen ] )

Erase the entire screen.

An optional Tickit::Pen may be provided; if present it will be set as if given to setpen first.

erasech

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

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.

An optional Tickit::Pen may be provided; if present it will be set as if given to setpen first.

getctl_int

setctl_int

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

On failure, each method returns undef.

TERMCTL_ALTSCREEN

Enables DEC Alternate Screen mode

TERMCTL_CURSORVIS

Enables cursor visible mode

TERMCTL_CURSORBLINK

Enables cursor blinking mode

TERMCTL_CURSORSHAPE

Sets the shape of the cursor. $value should be one of CURSORSHAPE_BLOCK, CURSORSHAPE_UNDER or CURSORSHAPE_LEFT_BAR.

TERMCTL_KEYPAD_APP

Enables keypad application mode

TERMCTL_MOUSE

Enables mouse tracking mode. $vaule should be one of TERM_MOUSEMODE_CLICK, TERM_MOUSEMODE_DRAG, TERM_MOUSEMODE_MOVE or TERM_MOUSEMODE_OFF.

setctl_str

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

TERMCTL_ICON_TEXT

TERMCTL_TITLE_TEXT

TERMCTL_ICONTITLE_TEXT

Sets the terminal window icon text, title, or both.

getctl

setctl

$value = $term->getctl( $ctl )

$success = $term->setctl( $ctl, $value )

A newer form of the various typed get and set methods above. This version will interpret the given value as appropriate, depending on the control type.

input_push_bytes

$term->input_push_bytes( $bytes )

Feeds more bytes of input. May result in key or mouse events.

input_readable

$term->input_readable

Informs the term that the input handle may be readable. Attempts to read more bytes of input. May result in key or mouse events.

input_wait

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

check_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 key event to occur.

emit_key

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

emit_mouse

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

EVENTS

The following event types are emitted and may be observed by "bind_event".

resize

Emitted when the terminal itself has been resized.

key

Emitted when a key on the keyboard is pressed.

mouse

Emitted when a mouse button is pressed or released, the cursor moved while a button is held (a dragging event), or the wheel is scrolled.

Behaviour of events involving more than one mouse button is not well-specified by terminals.

TODO

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

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Tickit

perl -MCPAN -e shell
install Tickit