2 Virtual Terminal

8.16.0.4

2 Virtual Terminal🔗ℹ

Dominik Pantůček <dominik.pantucek@trustica.cz>

These modules provide an abstraction layer on top of the underlying VT-capable terminal. The infrastructure provided decodes the incoming keys, mouse events and terminal type and size changes.

2.1 Geometry Handling🔗ℹ

(require tui/term/geometry)

package: tui-term

This module provides basic data structures for handling rectangular geometry in Cartesian coordinates on the terminal grid.

struct
(struct tpoint (x y))
x : exact-integer?
y : exact-integer?

Represents a single cell coordinates on the terminal.

struct
(struct tsize (w h))
w : exact-nonnegative-integer?
h : exact-nonnegative-integer?

Represents the size of a rectangular area on screen.

2.2 Messages🔗ℹ

(require tui/term/messages)

package: tui-term

All the incoming information including decoded keystrokes, mouse movement and window size changes are reported as messages defined in this module. A generic "command" message is defined as well to be used by the application layer.

struct
(struct tmsg (ts))
ts : real?

Basic structure used for deriving all other message structures. Only the accessor tmsg-ts is intended for application usage.

Use make-tmsg to construct it - although this base struct does not provide any further functionality other than the time when the message was emitted.

procedure
(make-tmsg) → tmsg?

Creates new tmsg with the (current-inexact-milliseconds) timestamp.

struct
(struct tkeymsg tmsg (key mods))
key : (or/c char? symbol?)
mods : (listof symbol?)

A message representing a key press - either a character or a special key represented by symbol such as 'f1.

procedure
(tkeymsg=? km
[ #:key key
#:mods mods
#:char char]) → boolean?
  km : tkeymsg?
  key : (or/c #f char? symbol?) = #f
  mods : (or/c #f (listof (or/c 'ctrl 'alt 'shift))) = #f
  char : (or/c #f char?) = #f

Convenience comparator of tkeymsg? with optional fields. If given field keyword argument is not specified, that comparison does not have any influence on the result. As a side effect, if no keyword arguments are specified, this procedure always returns #f for any km given.

procedure
(make-tkeymsg key [mods]) → tkeymsg?
key : (or/c char? symbol?)
mods : (listof symbol?) = '()

Constructor of tkeymsg which fill-in the current timestamp like the make-tmsg does.

struct
(struct tmousemsg tmsg (kind pos left right middle button))
   kind :
(or/c 'move
      'button-down 'button-up
      'wheel-up 'wheel-down)
  pos : any/c
  left : boolean?
  right : boolean?
  middle : boolean?
  button : (or/c #f 'left 'right 'middle)

Mouse events are reported as an instance of this message. The event kinds referenced in the contract are only informative and the application layer may use other symbols (for example create a mouse "leave" event for a widget). However the terminal implementation from this package is guaranteed to report only the mouse message kinds listed here.

pos - TODO after porting tpoint/geometry

The left, right and middle fields are #t if particular mouse button is held down when this message was generated.

In case of 'button-down or 'button-up kinds of an event, the button field holds the information about the button being pushed or released.

procedure
(make-tmousemsg kind
pos
left
right
middle
[ button]) → tmousemsg?
  kind : symbol?
  pos : any/c
  left : boolean?
  right : boolean?
  middle : boolean?
  button : (or/c #f 'left 'right 'middle) = #f

Creates a tmousemsg instance with the current timestamp.

struct
(struct tsizemsg tmsg (cols rows))
cols : exact-nonnegative-integer?
rows : exact-nonnegative-integer?

This message represents terminal size change. The order of the fields is the number of columns first.

procedure
(make-tsizemsg cols rows) → tsizemsg?
cols : exact-nonnegative-integer?
rows : exact-nonnegative-integer?

Construct a tsizemsg with the current timestamp.

struct
(struct tcmdmsg tmsg (cmd info))
cmd : any/c
info : any/c

Arbitrary command message that is intended to be injected in the message queue (and consumed as well) by the application layer.

procedure
(make-tcmdmsg cmd [info]) → tcmdmsg?
cmd : any/c
info : any/c = #f

Creates a tcmdmsg with the current timestamp.

procedure
(make-tmousemsg-leave msg) → tmousemsg?
msg : tmousemsg?

Returns a copy of given msg with the kind field changed to 'leave.

2.3 VT Input Port🔗ℹ

(require tui/term/vt-input-port)

package: tui-term

Input port wrapper converting stream of ANSI/ECMA (VT) sequences into appropriate messages.

procedure
(vt-input-port? v) → boolean?
v : any/c

Returns #t if given value v is an VT input port.

procedure
(make-vt-input-port queue [in]) → vt-input-port?
queue : tqueue?
in : input-port = (current-input-port)

Creates new VT input port on top of underlying input port in. The mandatory queue argument has to be provided by the caller as the caller needs to create the queue before passing to this procedure in order to allow adding window resize messages as they arrive.

parameter
(vt-esc-timeout) → exact-nonnegative-integer?
(vt-esc-timeout ms) → void?
ms : exact-nonnegative-integer?
= 10

Timeout specifying how quickly a lonely ESC should be reported as a single escape key press.

procedure
(vt-input-port-enqueue! msg [in]) → void?
msg : tmsg?
in : vt-input-port? = (current-input-port)

Enqueues given message msg into the internal queue of given in VT input port.

2.4 VT Output Port🔗ℹ

(require tui/term/vt-output-port)

package: tui-term

This module contains convenience procedures that allow for easy setup and usage of various ANSI/ECMA VT features.

procedure
(term-gotoxy x y) → void?
x : fixnum?
y : fixnum?

Moves the cursor at specified location. The upper left corner has both coordinates 0.

procedure
(term-clrscr) → void?

Clears the terminal screen.

procedure
(term-enable-mouse) → void?

Turns on mouse events reporting.

May use platform hook to alter the settings of local input terminal - currently only on Windows.

procedure
(term-disable-mouse) → void?

Turns off mouse events reporting.

May use platform hook to alter the settings of local input terminal - currently only on Windows.

procedure
(term-alternate-screen) → void?

Switches the terminal to alternate screen.

procedure
(term-normal-screen) → void?

Switches the terminal back to normal screen.

procedure
(term-hide-cursor) → void?

Hides the terminal text cursor.

procedure
(term-show-cursor) → void?

Shows the terminal text cursor.

procedure
(set-term-title title) → void?
title : string?

Sets terminal window title to given string.

1	Utilities
2	Virtual Terminal
3	Network Virtual Terminal
4	Tele TYpe Terminal

2.1	Geometry Handling
2.2	Messages
2.3	VT Input Port
2.4	VT Output Port