1.164.2 Send methods

terminal_image ->initialise: width=int, height=int

Create a terminal_image of the given column/row size.

terminal_image ->geometry: x=[int], y=[int], width=[int], height=[int]

Move/resize the image.

terminal_image ->font: font=font, bold=[font], italic=[font], bold_italic=[font]

Change the regular font and its variants. A variant left at @default is derived from font, keeping its family and size. A variant that does not advance by the same amount as font is rejected with a message and set to @nil: the cell grid is measured from the regular font alone, so a variant of another pitch would not line up with it.

terminal_image ->compute:

Recompute the rendered image.

terminal_image ->scroll_vertical: direction={forwards,backwards,goto}, unit={file,page,line}, amount=int

Scroll request from the associated scroll_bar (also bound to keyboard navigation). Stops where the last line of the buffer is on the bottom row: there is nothing under it to show, so going further would only walk the text off the top.

terminal_image ->event: event

Top-level event dispatcher.

terminal_image ->input_focus: bool

The terminal gained (@on) or lost (@off) the keyboard focus. This is called from terminal_image->event on the activate_keyboard_focus and deactivate_keyboard_focus events. The default implementation enables or disables the platform text input (the input method), stops an incremental search -- it lives off the keyboard --, updates the caret and, if the client asked to be told about the focus (CSI ? 1004 h), sends it CSI I or CSI O.

A subclass may refine this to react on the terminal gaining or losing the focus. A refinement should call the super method to keep the above in sync.

Note that this is not graphical->keyboard_focus, which works the other way around: it asks the window to give the focus to this object.

terminal_image ->typed: event

Process a single keystroke. This takes these steps:

• If a focus function is active -- an incremental search -- the key goes to it, and we are done if it succeeds. This comes first: the search would otherwise lose its keys to the accelerators below, or to a process running on the terminal.
• If the event has the s (super, Apple ⌘) or the event has both shift and control modifiers active and the key is handled as an accelerator, we are done.
• If there is no attached foreground process running and the key is handled as an accelerator, we are done.
• Else, encode the event using the terminal escape sequences and send the resulting bytes to the client.

terminal_image ->insert: text=char_array

Insert text at the caret position.

terminal_image ->send: text=char_array

Send text to the connected process.

terminal_image ->copy: which=[{primary,clipboard}]

Copy the selected text to the primary selection or clipboard.

terminal_image ->paste: which=[{primary,clipboard}]

Paste the contents of the primary selection or clipboard.

terminal_image ->prompt_mark: kind={prompt,input,output,end}, continuation=[bool]

Called on OSC 133, the semantic prompt marks: A, B, C and D decoded to where a prompt starts, where the line the user edits starts, where that line was entered and its output begins, and where the output ends. continuation is the k=s of a secondary prompt, i.e. the client is collecting another line of an input it has not finished. The default implementation is what builds terminal_image<-blocks.

A subclass may refine this to act on what its client is doing; class prolog_terminal does, to fold the command before the one being entered. A refinement must not write to the terminal or destroy it: the escape sequence it arrived in is still being parsed, and output of its own would move the very lines and blocks that parse is holding.

terminal_image ->fold_all:

terminal_image ->unfold_all:

Hide the output of every command that has finished, or show it all again. See terminal_block->fold.

terminal_image ->select_all:

Select the entire buffer (including scroll-back).

terminal_image ->has_selection:

Succeeds if a non-empty selection exists.

terminal_image ->interrupt:

Interrupt the process running in the terminal by handing the tty its interrupt character. Fails if terminal_image<-foreground_process reports none, leaving the interrupt to a subclass whose client is not a process of its own.

terminal_image ->copy_or_interrupt:

Copy if there is selected text, otherwise call terminal_image->interrupt.

terminal_image ->selection: from=[int], to=[int]

Make [from, to) the selection. Both @default clears it, as does an empty region; a single @default reaches to that end of the buffer. Indices out of range are clamped, and endpoints that arrive the wrong way round are swapped.

Selecting text says what to look for as well as what to copy. The other places the selected text occurs on the screen are painted in terminal_image<-isearch_other_style, the way the other matches of an incremental search are, so that picking out a variable or an atom finds the rest of them without typing it again; terminal_image<->exact_case and terminal_image<->search_word decide what counts as one. What it reports -- through visual->report, like a search -- says which of the matches the selection is and how many there are, as Selection: X (2/5), counted over the whole buffer while what is painted is the page.

Double clicking picks a word, and that says to look for the word rather than for the letters it happens to be made of: matching is whole-word for such a selection whatever terminal_image<->search_word stands at (see terminal_image<-match_word), so a double click on Bar passes over Barn while dragging over the same three characters does not. It also makes a one-character word worth looking for.

Not every selection is looked for, and terminal_image<-selection_string says which are. A selection that occurs nowhere else says nothing and is painted as a plain selection. Neither is one that is blank, that runs over a line break, that is longer than 100 characters, or that is a single character while terminal_image<-match_word is @off -- each of those would light up most of the screen. Nor is anything looked for on the alternate screen, whose lines are not in the buffer.

What is looked for is the text under the selection as it is now: a client that repaints or erases the screen changes what a selection holds without moving it, and the matches follow.

terminal_image ->isearch_selection_forward:

terminal_image ->isearch_selection_backward:

Start an incremental search for what the selection holds, from where the selection is, and step to the next resp. previous match at once -- so the matches that are already lit up (see terminal_image->selection) are the ones this walks. From there it is the ordinary search below, ^S and ^R included. \C-s and \C-r are bound to these.

Fails when there is no such selection, and a binding that fails hands the key on: without one, ^S and ^R mean to whatever is reading from the terminal what they always meant, which for the line editor is its own history search.

^G gives back the view and the selection the search started from, so a search one did not mean to start costs nothing.

terminal_image ->scroll_to: index=int

Scroll the line holding index into view, moving as little as possible and doing nothing while the line is already on the screen. Fails on the alternate screen and on an index out of range.

terminal_image ->isearch_forward:

terminal_image ->isearch_backward:

Start an Emacs style incremental search, towards the end of the buffer or towards its start. \C-\S-f is bound to terminal_image->isearch_backward, as a terminal's history lies behind the caret. While the search runs it has every key (see terminal_image<-focus_function):

The hit is painted in terminal_image<-isearch_style and the other matches on the screen in terminal_image<-isearch_other_style. A search owns that feedback while it runs, so the selection's own matches (see terminal_image->selection) are not shown as well; leaving a search with the hit selected hands them straight over. What it reports as it goes -- through visual->report, so where that lands is the window's business -- says which of the matches it is on and how many there are, as (3/4). Those are counted over the whole buffer, and from its start whichever way the search is going, so a search backwards begins at the last of them and counts down. Every place the string occurs counts, overlapping ones included: a repeat steps a single character, so those are places the search can get to.

^S, ^R	The next hit, forwards resp. backwards
Backspace	Drop a character and search again
^W	Take the word behind the hit into the search string, along with whatever separates the two, so that pressing it again walks on word by word. Not across a line: a search string with a line break in it matches almost nothing
M-c	Turn terminal_image<->exact_case on or off
M-w	Turn whole-word matching on or off, as terminal_image<-match_word reports it
^G	Give back the view and the selection the search started from
Escape, Return	Leave the search with the hit selected
Any other key	Leaves the search, and then means what it usually means

A search that started from a selection (terminal_image->isearch_selection_backward) differs in one way: ^G puts that selection back rather than leaving none.

Two things differ from editor->isearch_forward. Escape and Return are swallowed rather than passed on: an unhandled key here reaches the process on the terminal, and leaving a search is no reason to submit a line to a shell. ^C is the exception that proves it -- it ends the search and then interrupts, or a search started over a running program would trap the interrupt.

Running out of hits only says so; the attempt after that starts over at the far end of the buffer. A search refuses to start on the alternate screen, whose lines are not in the buffer, and an application that claims the screen ends one that is running.

terminal_image ->window_label: char_array

Set the enclosing frame's label, e.g. from an OSC 0 sequence.