Provided by: libtickit-perl_0.65-4build1_amd64 bug

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.

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.

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;
          }

   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.

   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.

   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>