far2l Terminal Extensions

https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/
Admin
far2l Terminal Extensions is a bidirectional APC escape sequence protocol that enables terminal...
Tokens:32,274
Snippets:169
Trust Score:7.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### FARTTY_INTERACT_GET_WINDOW_MAXSIZE (w)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Gets the maximum possible size of the window, in character cells. The client caches the first successful answer for the life of the process.

```APIDOC
## FARTTY_INTERACT_GET_WINDOW_MAXSIZE (w)

### Description
Gets the maximum possible size of the window, in character cells.

### Method
Request (client to server)

### Endpoint
Command letter: `w`

### Parameters
None.

### Response
#### Success Response
- **Height** (int16_t) - Maximum number of rows.
- **Width** (int16_t) - Maximum number of columns.

### Notes
- The client sends it with a non-zero ID and caches the first successful answer for the life of the process.
- If the terminal can be resized (e.g., to another monitor) the cached value goes stale.
```

--------------------------------

### FARTTY_INTERACT_GET_COLOR_PALETTE (p)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Gets the color palette. Reply is required.

```APIDOC
## FARTTY_INTERACT_GET_COLOR_PALETTE (p)

### Description
Gets the color palette.

### Method
Request (client to server)

### Endpoint
Command letter: `p`

### Parameters
None.

### Response
Reply is required.
```

--------------------------------

### WINDOW_RESTORE (m)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Restores the window from the maximized state. No return values.

```APIDOC
## WINDOW_RESTORE (m)

### Description
Restores the window from the maximized state.

### Method
Request (client to server)

### Endpoint
Command letter: `m`

### Parameters
None.

### Response
No return values.
```

--------------------------------

### CLIP_OPEN

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Documentation for the CLIP_OPEN command, which authorizes and opens the clipboard.

```APIDOC
## CLIP_OPEN

### Description
Authorizes the client and opens the clipboard for subsequent operations. The client identifies itself with a client ID (passcode) of 32-256 characters from [0-9a-z_-]. The server may prompt the user for authorization if the ID is not already known.

### Method
CLIP_OPEN

### Parameters
#### Request Body
- **client ID** (string) - Required - The client's passcode, 32-256 characters from [0-9a-z_-].

### Response
#### Success Response (status 1)
- **status** (int) - 1 if access is allowed, 0 if blocked, -1 if remote clipboard is required.
- **feature bitmask** (uint64_t) - Below the status on the stack. Bitmask of server features. Always sent by the far2l server, even when status is not 1.

#### Response Example
```
status: 1
feature bitmask: 0x00000003
```

### Notes
- The server does not nest opens; a second CLIP_OPEN while the clipboard is open is answered with status 0.
- The client should send exactly one CLIP_OPEN and one CLIP_CLOSE (with ID 0) after the last close.
- The reply may be delayed while the server asks the user for authorization.

### Server Features
| Feature | Value | Meaning |
|---------|-------|---------|
| FARTTY_FEATCLIP_DATA_ID | 0x00000001 | Server can provide data IDs for caching. |
| FARTTY_FEATCLIP_CHUNKED_SET | 0x00000002 | Server accepts CLIP_SETDATACHUNK. |
```

--------------------------------

### FARTTY_INTERACT_CLIPBOARD (`c`)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Documentation for the FARTTY_INTERACT_CLIPBOARD command, which handles all clipboard operations via sub-commands.

```APIDOC
## FARTTY_INTERACT_CLIPBOARD (`c`)

### Description
All clipboard operations are one command, `c`, whose first argument is a sub-command letter. After the ID, the command letter `c` and the sub-command letter, the arguments follow.

### Method
Command

### Endpoint
`c`

### Parameters
#### Sub-command
- `o` (string) - Required - `CLIP_OPEN`: client ID
- `c` (none) - Required - `CLIP_CLOSE`
- `e` (none) - Required - `CLIP_EMPTY`
- `a` (uint32_t) - Required - `CLIP_ISAVAIL`: format
- `S` (uint16_t, raw data) - Required - `CLIP_SETDATACHUNK`: size >> 8; raw data
- `s` (uint32_t, uint32_t, raw data) - Required - `CLIP_SETDATA`: format; size; raw data
- `g` (uint32_t) - Required - `CLIP_GETDATA`: format
- `i` (uint32_t) - Required - `CLIP_GETDATAID`: format
- `r` (string) - Required - `CLIP_REGISTER_FORMAT`: format name

### Response
#### Success Response
- `int8_t` status: `1` success, `0` failure, `-1` the clipboard is not open (for `CLIP_OPEN`: access denied, use your own clipboard)
- `uint64_t` server features (for `CLIP_OPEN`)
- `int8_t` available (for `CLIP_ISAVAIL`)
- `uint64_t` data ID (for `CLIP_SETDATA`, `CLIP_GETDATA`, `CLIP_GETDATAID`)
- `uint32_t` size; raw data (for `CLIP_GETDATA`)
- `uint32_t` format ID (for `CLIP_REGISTER_FORMAT`)

### Notes
- The "Out" column is in pop order. Conditions under which a value is present are described below.
- `FarTTY.h` describes `CLIP_GETDATAID` in its overview as returning a status and an ID; the code returns the ID alone.
- `CLIP_CLOSE` and `CLIP_EMPTY` do not wait (ID 0).
- `CLIP_SETDATACHUNK` waits only every 16th chunk.
```

--------------------------------

### WINDOW_MAXIMIZE (M)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Maximizes the window. No return values.

```APIDOC
## WINDOW_MAXIMIZE (M)

### Description
Maximizes the window.

### Method
Request (client to server)

### Endpoint
Command letter: `M`

### Parameters
None.

### Response
No return values.
```

--------------------------------

### CONSOLE_ADHOC_QEDIT (e)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Turns the left mouse button press that is in progress into a selection of text on the screen, as if quick edit mode were on. No return values.

```APIDOC
## CONSOLE_ADHOC_QEDIT (e)

### Description
Turns the left mouse button press that is in progress into a selection of text on the screen, as if the quick edit mode were on. The selection starts at the position of the last mouse click and is copied to the clipboard the usual way.

### Method
Request (client to server)

### Endpoint
Command letter: `e`

### Parameters
None.

### Response
No return values.

### Notes
- In the wx backend, the request is ignored if a selection is already going on or the middle or right button is held.
- If the left button is held, a release of the left button is queued for the application and the selection starts at the position of the last click.
```

--------------------------------

### FARTTY_INTERACT_GET_COLOR_PALETTE (`p`)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Asks how many colors the terminal can show.

```APIDOC
## FARTTY_INTERACT_GET_COLOR_PALETTE (`p`)

### Description
Asks how many colors the terminal can show. The far2l client sends it with a non-zero ID, and asks every time it needs the answer; if `--norgb` is given or GNU screen is detected (`TERM=screen*`) it answers `4` by itself without asking. When the extensions are not available, far2l guesses: if `COLORTERM` is set, `truecolor` or `24bit` gives 24 bits and any other value 8 bits (`TERM` is then not looked at); otherwise a `TERM` that contains `256` gives 8 bits, and anything else 4.

### Method
FARTTY_INTERACT_GET_COLOR_PALETTE

### Endpoint
`p`

### Parameters
No input parameters.

### Response
#### Success Response
- **Color bits** (uint8_t) - The maximum supported color resolution in bits: `4` (16 colors), `8` (256 colors), `24` (true color).
- **Reserved** (uint8_t) - Zero. A client has to ignore it.
```

--------------------------------

### FARTTY_INTERACT_CLIPBOARD (c)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Clipboard operations with sub-commands. Reply depends on the sub-command.

```APIDOC
## FARTTY_INTERACT_CLIPBOARD (c)

### Description
Clipboard operations with sub-commands.

### Method
Request (client to server)

### Endpoint
Command letter: `c`

### Parameters
None.

### Response
Reply depends on the sub-command.
```

--------------------------------

### CLIP_ISAVAIL

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Documentation for the CLIP_ISAVAIL command, which checks clipboard availability.

```APIDOC
## CLIP_ISAVAIL

### Description
Checks whether the clipboard is available. Does not require authorization and is not refused without an open clipboard, but the answer comes from the clipboard backend and may be 0 if the clipboard is not open.

### Method
CLIP_ISAVAIL

### Parameters
None.

### Response
- **status** (int) - 1 if available, 0 if not available.
```

--------------------------------

### IMAGE_SET (`s`)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Documentation for the IMAGE_SET operation, which displays a new image or changes an existing one.

```APIDOC
## IMAGE_SET (`s`)

### Description
Displays a new image, or changes an existing one. The image is identified by an Image ID; setting an existing identity replaces the image (or modifies it, with the attach flags).

### Method
IMAGE_SET (opcode `s`)

### Endpoint
IMAGE_SET

### Parameters
#### Input Parameters
- **Image ID** (`string`) - Required - The identity of the image. Setting an existing identity replaces the image (or modifies it, with the attach flags).
- **Flags** (`uint64_t`) - Required - The format, the attach mode and other options: `WP_IMG_*`, see below.
- **Left** (`int16_t`) - Required - Cell column of the left edge, or `-1`.
- **Top** (`int16_t`) - Required - Cell row of the top edge, or `-1`.
- **Right** (`int16_t`) - Required - Cell column of the right edge, or an extra pixel offset, or `-1`.
- **Bottom** (`int16_t`) - Required - Cell row of the bottom edge, or an extra pixel offset, or `-1`.
- **Width** (`uint32_t`) - Required - Width in pixels for RGB and RGBA, the size in bytes of the encoded data for PNG and JPEG.
- **Height** (`uint32_t`) - Required - Height in pixels for RGB and RGBA, `1` for PNG and JPEG.
- **Data** (raw) - Required - `Width * Height * 3` bytes for RGB, `Width * Height * 4` bytes for RGBA (rows top to bottom, bytes `R G B [A]` without padding), `Width` bytes for PNG and JPEG.

### Flags
| Flag | Value | Meaning |
| ---- | ----- | ------- |
| `WP_IMG_RGBA` | `0` | Pixels `R G B A`. Needs `WP_IMGCAP_RGBA`. |
| `WP_IMG_RGB` | `1` | Pixels `R G B`. Needs `WP_IMGCAP_RGBA`. |
| `WP_IMG_PNG` | `2` | A PNG file. Needs `WP_IMGCAP_PNG`. |
| `WP_IMG_JPG` | `3` | A JPEG file. Needs `WP_IMGCAP_JPG`. |
| `WP_IMG_ATTACH_LEFT` | `0x010000` | Attach the given image at the left edge of the existing one. Needs `WP_IMGCAP_ATTACH`. |
| `WP_IMG_ATTACH_RIGHT` | `0x020000` | Attach at the right edge. |
| `WP_IMG_ATTACH_TOP` | `0x030000` | Attach at the top edge. |
| `WP_IMG_ATTACH_BOTTOM` | `0x040000` | Attach at the bottom edge. |
| `WP_IMG_SCROLL` | `0x080000` | With an attach flag: the image keeps its size; the existing content moves to the side opposite to the edge where the new part was attached, so that the new part fits in. Needs `WP_IMGCAP_SCROLL`. |
| `WP_IMG_PIXEL_OFFSET` | `0x100000` | The image is not scaled; `Right` and `Bottom` are pixel offsets, see below. |

### Response
#### Success Response
- **Success** (`uint8_t`) - `1` if the image was loaded and is displayed, `0` if not.

### Notes
- The fields `Left`, `Top`, `Right` and `Bottom` are `int16_t` (`-1` is `0xFFFF`). `Width` and `Height` are popped in this order, each one is a `uint32_t`. A server with `Width` or `Height` equal to zero answers `0` without reading the rest. An unknown format in the flags makes the far2l server fail the request with an empty reply.
- The format is the low 16 bits (mask `WP_IMG_MASK_FMT` = `0x00FFFF`), which is **a number, not a set of bits**. The attach mode is the value in bits 16 to 18 (mask `WP_IMG_MASK_ATTACH` = `0x070000`), which is also a number: `1` to `4` shifted left by 16; the four values are **not** independent bits. `WP_IMG_SCROLL` and `WP_IMG_PIXEL_OFFSET` are ordinary bits. The attach values were named `WP_IMG_SCROLL_AT_LEFT`, `_RIGHT`, `_TOP` and `_BOTTOM` (with the mask `WP_IMG_MASK_SCROLL`) in the first versions of the image API of November 2025; the values `0x10000` to `0x40000` are the same.
- **Position and size on the screen.** If the four numbers are given and `WP_IMG_PIXEL_OFFSET` is not set, the image is stretched over the cells from (`Left`, `Top`) to (`Right`, `Bottom`), inclusive. With `WP_IMG_PIXEL_OFFSET`, the image is not scaled: it is drawn at its own size at the top-left corner of the cell (`Left`, `Top`), moved by `Right` pixels to the right and `Bottom` pixels down (if these are greater than zero). A value of `-1` in `Right` (`Bottom`) means that the width (height) is the natural size of the image in pixels; the two axes are handled independently. In the wx backend `-1` in any field of an existing image means "keep the current value" (so the "own size" of an axis cannot be restored once set); the SDL backend takes `Left` and `Top` from the cursor in that case. For a new image the far2l GUI backends use the cursor position if `Left` and `Top` are `-1`; the column is the current one, and the row is chosen so that the image ends at the current cursor row (the cursor row minus the number of rows the image takes, but not less than 0). Clients that care should always give `Left` and `Top` explicitly.
- **Attaching.** Attaching is defined only for an existing image with the same identity. In the far2l GUI, with `ATTACH_LEFT` or `ATTACH_RIGHT` the new piece has to have the same height in pixels as the existing image; with `ATTACH_TOP` or `ATTACH_BOTTOM` the same width; otherwise the request fails. Without `WP_IMG_SCROLL` the image grows by the size of the piece; with it the size is kept and the content moves. This is how far2l's image viewer scrolls a large image without sending it again. Through the far2l extensions an "empty" attach (a request with zero size used to only move an image) is not possible because of the zero size rule above; use `IMAGE_TRANSFORM` to move.
```

--------------------------------

### Clipboard Commands

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Commands for writing and reading the clipboard in the far2l protocol. These are low-level commands sent from the far2l client to the server.

```APIDOC
## CLIP_OPEN

### Description
Opens the clipboard for reading or writing. The far2l client sends this command to the server, which returns the status and features.

### Method
CLIP_OPEN

### Parameters
#### Request Body
- **passcode** (string) - Required - The passcode for accessing the clipboard.

### Response
#### Success Response
- **status** (integer) - The status of the operation.
- **features** (integer) - Bitmask of supported features (e.g., FARTTY_FEATCLIP_DATA_ID, FARTTY_FEATCLIP_CHUNKED_SET).

### Response Example
```
status, features
```

## CLIP_EMPTY

### Description
Removes all formats from the clipboard. The far2l client does not wait for a reply.

### Method
CLIP_EMPTY

### Parameters
None.

### Response
None (the far2l client does not wait).

## CLIP_SETDATA

### Description
Puts the data of one format on the clipboard. The server forwards it to the clipboard of its host with the semantics of the Win32 SetClipboardData. The reply holds a uint64_t data ID below the status, and only if the status is 1.

### Method
CLIP_SETDATA

### Parameters
#### Request Body
- **format** (integer) - Required - The clipboard format identifier.
- **size** (integer) - Required - The size of the data in bytes.
- **data** (raw) - Required - The data to set.

### Response
#### Success Response
- **status** (integer) - The status of the operation.
- **data ID** (uint64_t) - Optional - Present only if the status is 1 and the server reported FARTTY_FEATCLIP_DATA_ID.

### Response Example
```
status, [data ID]
```

## CLIP_CLOSE

### Description
Closes the clipboard. The far2l client does not wait for a reply.

### Method
CLIP_CLOSE

### Parameters
None.

### Response
None (the far2l client does not wait).

## CLIP_SETDATACHUNK

### Description
Sends a chunk of data for a chunked upload. The server accumulates chunks in order, and the next CLIP_SETDATA prepends them to its own data. A chunk with size zero cancels the transfer. This command has no return values.

### Method
CLIP_SETDATACHUNK

### Parameters
#### Request Body
- **Encoded size** (uint16_t) - Required - The size of the chunk divided by 256. The chunk size is always a multiple of 256, and is this value shifted left by 8 bits. Zero means throw away all chunks collected so far.
- **Data** (raw) - Required - The chunk data.

### Response
None (no return values).

## CLIP_ISAVAIL

### Description
Checks whether a format is available on the clipboard. This is optional and needs no open clipboard.

### Method
CLIP_ISAVAIL

### Parameters
#### Request Body
- **format** (integer) - Required - The clipboard format identifier.

### Response
#### Success Response
- **available** (boolean) - Whether the format is available.

### Response Example
```
available
```

## CLIP_GETDATAID

### Description
Gets the data ID for a format. This is optional and only available when the server reported FARTTY_FEATCLIP_DATA_ID.

### Method
CLIP_GETDATAID

### Parameters
#### Request Body
- **format** (integer) - Required - The clipboard format identifier.

### Response
#### Success Response
- **data ID** (uint64_t) - The data ID.

### Response Example
```
data ID
```

## CLIP_GETDATA

### Description
Reads the data of a format from the clipboard. Returns the whole data in one reply; there is no chunked download.

### Method
CLIP_GETDATA

### Parameters
#### Request Body
- **format** (integer) - Required - The clipboard format identifier.

### Response
#### Success Response
- **size** (uint32_t) - The size of the data in bytes. 0 if no data, read not allowed, or operation failed; 0xFFFFFFFF if clipboard not open.
- **data** (raw) - The data, if size > 0.
- **data ID** (uint64_t) - Optional - Present only if the server reported FARTTY_FEATCLIP_DATA_ID and the clipboard is open.

### Response Example
```
size, data, [data ID]
```
```

--------------------------------

### CLIP_SETDATA

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Documentation for the CLIP_SETDATA command, which sets clipboard data.

```APIDOC
## CLIP_SETDATA

### Description
Sets clipboard data. Requires an open clipboard; answers -1 if the clipboard is not open. May include data IDs if the server supports FARTTY_FEATCLIP_DATA_ID.

### Method
CLIP_SETDATA

### Parameters
#### Request Body
- **format** (format ID) - Required - The clipboard format.
- **data** (bytes) - Required - The data to set.
- **data ID** (optional) - If the server supports FARTTY_FEATCLIP_DATA_ID, an ID for caching.

### Response
- **status** (int) - 1 on success, -1 if the clipboard is not open.
```

--------------------------------

### FARTTY_INTERACT_SET_FKEY_TITLES (f)

Source: https://raw.githubusercontent.com/unxed/far2l/refs/heads/extsdocs/VTExts.md

Sets function key titles. Reply needed only the first time.

```APIDOC
## FARTTY_INTERACT_SET_FKEY_TITLES (f)

### Description
Sets function key titles.

### Method
Request (client to server)

### Endpoint
Command letter: `f`

### Parameters
None.

### Response
Reply needed only the first time.
```
Tokens:
Raw