kovidgoyal/kitty
1
1
Fork 0
mirror of https://github.com/kovidgoyal/kitty.git synced 2024-08-16 10:00:24 +03:00
Code Issues Projects Releases Wiki Activity

Redirect old asciidoc pages to new website

Browse Source
This commit is contained in:
Kovid Goyal 2018-05-30 12:52:59 +05:30
parent 611d95f0f7
commit f6d0cadcc5
No known key found for this signature in database
GPG Key ID: 06BC317B515ACE7C
5 changed files with 4 additions and 808 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
README.asciidoc
View File

@ -3,12 +3,3 @@
See https://sw.kovidgoyal.net/kitty
image::https://travis-ci.org/kovidgoyal/kitty.svg?branch=master[Build status, link=https://travis-ci.org/kovidgoyal/kitty]
== Resources on terminal behavior
http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
https://en.wikipedia.org/wiki/C0_and_C1_control_codes
https://vt100.net/

391
graphics-protocol.asciidoc
View File

@ -1,390 +1 @@
= The terminal graphics protocol
:toc:
:toc-placement!:
The goal of this specification is to create a flexible and performant protocol
that allows the program running in the terminal, hereafter called the _client_,
to render arbitrary pixel (raster) graphics to the screen of the terminal
emulator. The major design goals are
* Should not require terminal emulators to understand image formats.
* Should allow specifying graphics to be drawn at individual pixel positions.
* The graphics should integrate with the text, in particular it should be possible to draw graphics
below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically.
* Should use optimizations when the client is running on the same computer as the terminal emulator.
For some discussion regarding the design choices, see link:../../issues/33[#33].
To see a quick demo, inside a kitty terminal run:
```
kitty icat path/to/some/image.png
```
You can also see a screenshot with more sophisticated features such as alpha-blending and text over graphics
link:https://github.com/kovidgoyal/kitty/issues/33#issuecomment-334436100[here].
Some programs that use the kitty graphics protocol:
* link:https://github.com/dsanson/termpdf[termdpf] - a terminal PDF/DJVU/CBR viewer
* link:https://github.com/ranger/ranger[ranger] - a terminal file manager, with image previews, see this link:https://github.com/ranger/ranger/pull/1077[PR]
* link:https://github.com/kovidgoyal/kitty/tree/master/kittens/diff[kitty-diff] - a side-by-side terminal diff program with support for images
toc::[]
== Getting the window size
In order to know what size of images to display and how to position them, the client must be able to get the
window size in pixels and the number of cells per row and column. This can be done by using the `TIOCGWINSZ` ioctl.
Some code to demonstrate its use
In C:
```C
struct ttysize ts;
ioctl(0, TIOCGWINSZ, &ts);
printf("number of columns: %i, number of rows: %i, screen width: %i, screen height: %i\n", sz.ws_col, sz.ws_row, sz.ws_xpixel, sz.ws_ypixel);
```
In Python:
```py
import array, fcntl, termios
buf = array.array('H', [0, 0, 0, 0])
fcntl.ioctl(sys.stdout, termios.TIOCGWINSZ, buf)
print('number of columns: {}, number of rows: {}, screen width: {}, screen height: {}'.format(*buf))
```
Note that some terminals return `0` for the width and height values. Such terminals should be modified to return the correct values.
Examples of terminals that return correct values: `kitty, xterm`
You can also use the *CSI t* escape code to get the screen size. Send `<ESC>[14t` to *stdout* and kitty will reply on *stdin* with
`<ESC>[4;<height>;<width>t` where *height* and *width* are the window size in pixels. This escape code is supported in many terminals,
not just kitty.
== The graphics escape code
All graphics escape codes are of the form:
```
<ESC>_G<control data>;<payload><ESC>\
```
This is a so-called _Application Programming Command (APC)_. Most terminal
emulators ignore APC codes, making it safe to use.
The control data is a comma-separated list of `key=value` pairs. The payload
is arbitrary binary data, base64-encoded to prevent interoperation problems
with legacy terminals that get confused by control codes within an APC code.
The meaning of the payload is interpreted based on the control data.
The first step is to transmit the actual image data.
== Transferring pixel data
The first consideration when transferring data between the client and the
terminal emulator is the format in which to do so. Since there is a vast and
growing number of image formats in existence, it does not make sense to have
every terminal emulator implement support for them. Instead, the client should
send simple pixel data to the terminal emulator. The obvious downside to this
is performance, especially when the client is running on a remote machine.
Techniques for remedying this limitation are discussed later. The terminal
emulator must understand pixel data in three formats, 24-bit RGB, 32-bit RGBA and
PNG. This is specified using the `f` key in the control data. `f=32` (which is the
default) indicates 32-bit RGBA data and `f=24` indicates 24-bit RGB data and `f=100`
indicates PNG data. The PNG format is supported for convenience and a compact way
of transmitting paletted images.
=== RGB and RGBA data
In these formats the pixel data is stored directly as 3 or 4 bytes per pixel, respectively.
When specifying images in this format, the image dimensions **must** be sent in the control data.
For example:
```
<ESC>_Gf=24,s=10,v=20;<payload><ESC>\
```
Here the width and height are specified using the `s` and `v` keys respectively. Since
`f=24` there are three bytes per pixel and therefore the pixel data must be `3 * 10 * 20 = 600`
bytes.
=== PNG data
In this format any PNG image can be transmitted directly. For example:
```
<ESC>_Gf=100;<payload><ESC>\
```
The PNG format is specified using the `f=100` key. The width and height of
the image will be read from the PNG data itself. Note that if you use both PNG and
compression, then you must provide the `S` key with the size of the PNG data.
=== Compression
The client can send compressed image data to the terminal emulator, by specifying the
`o` key. Currently, only zlib based deflate compression is supported, which is specified using
`o=z`. For example,
```
<ESC>_Gf=24,s=10,v=20,o=z;<payload><ESC>\
```
This is the same as the example from the RGB data section, except that the
payload is now compressed using deflate. The terminal emulator will decompress
it before rendering. You can specify compression for any format. The terminal
emulator will decompress before interpreting the pixel data.
=== The transmission medium
The transmission medium is specified using the `t` key. The `t` key defaults to `d`
and can take the values:
|===
| Value of `t` | Meaning
| d | Direct (the data is transmitted within the escape code itself)
| f | A simple file
| t | A temporary file, the terminal emulator will delete the file after reading the pixel data
| s | A http://man7.org/linux/man-pages/man7/shm_overview.7.html[POSIX shared memory object]. The terminal emulator will delete it after reading the pixel data
|===
==== Local client
First let us consider the local client techniques (files and shared memory). Some examples:
```
<ESC>_Gf=100,t=f;<encoded /path/to/file.png><ESC>\
```
Here we tell the terminal emulator to read PNG data from the specified file of
the specified size.
```
<ESC>_Gs=10,v=2,t=s,o=z;<encoded /some-shared-memory-name><ESC>\
```
Here we tell the terminal emulator to read compressed image data from
the specified shared memory object.
The client can also specify a size and offset to tell the terminal emulator
to only read a part of the specified file. The is done using the `S` and `O`
keys respectively. For example:
```
<ESC>_Gs=10,v=2,t=s,S=80,O=10;<encoded /some-shared-memory-name><ESC>\
```
This tells the terminal emulator to read `80` bytes starting from the offset `10`
inside the specified shared memory buffer.
==== Remote client
Remote clients, those that are unable to use the filesystem/shared memory to
transmit data, must send the pixel data directly using escape codes. Since
escape codes are of limited maximum length, the data will need to be chunked up
for transfer. This is done using the `m` key. The pixel data must first be
base64 encoded then chunked up into chunks no larger than `4096` bytes. The client
then sends the graphics escape code as usual, with the addition of an `m` key that
must have the value `1` for all but the last chunk, where it must be `0`. For example,
if the data is split into three chunks, the client would send the following
sequence of escape codes to the terminal emulator:
```
<ESC>_Gs=100,v=30,m=1;<encoded pixel data first chunk><ESC>\
<ESC>_Gm=1;<encoded pixel data second chunk><ESC>\
<ESC>_Gm=0;<encoded pixel data last chunk><ESC>\
```
Note that only the first escape code needs to have the full set of control
codes such as width, height, format etc. Subsequent chunks must have
only the `m` key. The client **must** finish sending all chunks for a single image
before sending any other graphics related escape codes.
=== Detecting available transmission mediums
Since a client has no a-priori knowledge of whether it shares a filesystem/shared memory
with the terminal emulator, it can send an id with the control data, using the `i` key
(which can be an arbitrary positive integer up to 4294967295, it must not be zero).
If it does so, the terminal emulator will reply after trying to load the image, saying
whether loading was successful or not. For example:
```
<ESC>_Gi=31,s=10,v=2,t=s;<encoded /some-shared-memory-name><ESC>\
```
to which the terminal emulator will reply (after trying to load the data):
```
<ESC>_Gi=31;error message or OK<ESC>\
```
Here the `i` value will be the same as was sent by the client in the original
request. The message data will be a ASCII encoded string containing only
printable characters and spaces. The string will be `OK` if reading the pixel
data succeeded or an error message.
Sometimes, using an id is not appropriate, for example, if you do not want to
replace a previously sent image with the same id, or if you are sending a dummy
image and do not want it stored by the terminal emulator. In that case, you can
use the *query action*, set `a=q`. Then the terminal emulator will try to load
the image and respond with either OK or an error, as above, but it will not
replace an existing image with the same id, nor will it store the image.
== Display images on screen
Every transmitted image can be displayed an arbitrary number of times on the
screen, in different locations, using different parts of the source image, as
needed. You can either simultaneously transmit and display an image using the
action `a=T`, or first transmit the image with a id, such as `i=10` and then display
it with `a=p,i=10` which will display the previously transmitted image at the current
cursor position. When specifying an image id, the terminal emulator will reply with an
acknowledgement code, which will be either:
```
<ESC>_Gi=<id>;OK<ESC>\
```
when the image referred to by id was found, or
```
<ESC>_Gi=<id>;ENOENT:<some detailed error msg><ESC>\
```
when the image with the specified id was not found. This is similar to the
scheme described above for querying available transmission media, except that
here we are querying if the image with the specified id is available or needs to
be re-transmitted.
=== Controlling displayed image layout
The image is rendered at the current cursor position, from the upper left corner of
the current cell. You can also specify extra `X=3` and `Y=4` pixel offsets to display from
a different origin within the cell. Note that the offsets must be smaller that the size of the cell.
By default, the entire image will be displayed (images wider than the available
width will be truncated on the right edge). You can choose a source rectangle (in pixels)
as the part of the image to display. This is done with the keys: `x, y, w, h` which specify
the top-left corner, width and height of the source rectangle.
You can also ask the terminal emulator to display the image in a specified rectangle
(num of columns / num of lines), using the control codes `c,r`. `c` is the number of columns
and `r` the number of rows. The image will be scaled (enlarged/shrunk) as needed to fit
the specified area. Note that if you specify a start cell offset via the `X,Y` keys, it is not
added to the number of rows/columns.
Finally, you can specify the image *z-index*, i.e. the vertical stacking order. Images
placed in the same location with different z-index values will be blended if
they are semi-transparent. You can specify z-index values using the `z` key.
Negative z-index values mean that the images will be drawn under the text. This
allows rendering of text on top of images.
== Deleting images
Images can be deleted by using the delete action `a=d`. If specified without any
other keys, it will delete all images visible on screen. To delete specific images,
use the `d` key as described in the table below. Note that each value of d has
both a lowercase and an uppercase variant. The lowercase variant only deletes the
images without necessarily freeing up the stored image data, so that the images can be
re-displayed without needing to resend the data. The uppercase variants will delete
the image data as well, provided that the image is not referenced elsewhere, such as in the
scrollback buffer. The values of the `x` and `y` keys are the same as cursor positions (i.e.
x=1, y=1 is the top left cell).
|===
| Value of `d` | Meaning
| `a` or `A` | Delete all images visible on screen
| `i` or `I` | Delete all images with the specified id, specified using the `i` key.
| `c` or `C` | Delete all images that intersect with the current cursor position.
| `p` or `P` | Delete all images that intersect a specific cell, the cell is specified using the `x` and `y` keys
| `q` or `Q` | Delete all images that intersect a specific cell having a specific z-index. The cell and z-index is specified using the `x`, `y` and `z` keys.
| `x` or `X` | Delete all images that intersect the specified column, specified using the `x` key.
| `y` or `Y` | Delete all images that intersect the specified row, specified using the `y` key.
| `z` or `Z` | Delete all images that have the specified z-index, specified using the `z` key.
|===
Some examples:
```
<ESC>_Ga=d<ESC>\ # delete all visible images
<ESC>_Ga=d,i=10<ESC>\ # delete the image with id=10
<ESC>_Ga=Z,z=-1<ESC>\ # delete the images with z-index -1, also freeing up image data
<ESC>_Ga=P,x=3,y=4<ESC>\ # delete all images that intersect the cell at (3, 4)
```
=== Image persistence and storage quotas
In order to avoid *Denial-of-Service* attacks, terminal emulators should have a
maximum storage quota for image data. It should allow at least a few full
screen images. For example the quota in kitty is 320MB per buffer. When adding
a new image, if the total size exceeds the quota, the terminal emulator should
delete older images to make space for the new one.
== Control data reference
The table below shows all the control data keys as well as what values they can
take, and the default value they take when missing. All integers are 32-bit.
[cols="^1,<3,^1,<6"]
|===
|Key | Value | Default | Description
| `a` | Single character. `(t, T, q, p, d)` | `t` | The overall action this graphics command is performing.
4+^.^h| Keys for image transmission
| `f` | Positive integer. `(24, 32, 100)`. | `32` | The format in which the image data is sent.
| `t` | Single character. `(d, f, t, s)`. | `d` | The transmission medium used.
| `s` | Positive integer. | `0` | The width of the image being sent.
| `v` | Positive integer. | `0` | The height of the image being sent.
| `S` | Positive integer. | `0` | The size of data to read from a file.
| `O` | Positive integer. | `0` | The offset from which to read data from a file.
| `i` | Positive integer. `(0 - 4294967295)` | `0` | The image id
| `o` | Single character. `only z` | `null` | The type of data compression.
| `m` | zero or one | `0` | Whether there is more chunked data available.
4+^.^h| Keys for image display
| `x` | Positive integer | `0` | The left edge (in pixels) of the image area to display
| `y` | Positive integer | `0` | The top edge (in pixels) of the image area to display
| `w` | Positive integer | `0` | The width (in pixels) of the image area to display. By default, the entire width is used.
| `h` | Positive integer | `0` | The height (in pixels) of the image area to display. By default, the entire height is used
| `X` | Positive integer | `0` | The x-offset within the first cell at which to start displaying the image
| `Y` | Positive integer | `0` | The y-offset within the first cell at which to start displaying the image
| `c` | Positive integer | `0` | The number of columns to display the image over
| `r` | Positive integer | `0` | The number of rows to display the image over
| `z` | Integer | `0` | The *z-index* vertical stacking order of the image
4+^.^h| Keys for deleting images
| `d` | Single character. `(a, A, c, C, p, P, q, Q, x, X, y, Y, z, Z)`. | `a` | What to delete.
|===
== Interaction with other terminal actions
When resetting the terminal, all images that are visible on the screen must be
cleared. When switching from the main screen to the alternate screen buffer
(1049 private mode) all images in the alternate screen must be cleared, just as
all text is cleared. The clear screen escape code (usually `<ESC>[2J`) should also
clear all images. This is so that the clear command works.
The other commands to erase text must have no effect on graphics.
The dedicated delete graphics commands must be used for those.
When scrolling the screen (such as when using index cursor movement commands,
or scrolling through the history buffer), images must be scrolled along with
text. When page margins are defined and the index commands are used, only
images that are entirely within the page area (between the margins) must be
scrolled. When scrolling them would cause them to extend outside the page area,
they must be clipped.
See https://sw.kovidgoyal.net/kitty/graphics-protocol.html

130
kittens/diff/README.asciidoc
View File

@ -1,129 +1 @@
= kitty-diff - A side-by-side diff tool with syntax highlighting and images
:toc:
:toc-placement!:
== Major Features
* Displays diffs side-by-side in the kitty terminal.
* Does syntax highlighting of displayed diffs
* Displays images as well as text diffs, even over SSH
* Does recursive directory diffing
image::../../screenshots/diff.png?raw=true[Screenshot, showing a sample diff]
toc::[]
== Installation
Simply install link:https://github.com/kovidgoyal/kitty[kitty]. You also need
to have either the link:https://git-scm.com/[git] program or the `diff` program
installed. Additionally, for syntax highlighting to work,
link:http://pygments.org/[pygments] must be installed (note that pygments is
included in the macOS kitty app).
== Usage
In the kitty terminal, run:
....
kitty +kitten diff file1 file2
....
to see the diff between file1 and file2.
Create an alias in your shell's startup file to shorten the command, for example:
```sh
alias d="kitty +kitten diff"
```
Now all you need to do to diff two files is:
```
d file1 file2
```
You can also pass directories instead of files to see the recursive diff of the
directory contents.
== Keyboard controls
|===
|Action |Shortcut
|Quit | `q, Ctrl+c`
|Scroll line up | `k, up`
|Scroll line down | `j, down`
|Scroll page up | `PgUp`
|Scroll page down | `PgDn`
|Scroll to top | `Home`
|Scroll to bottom | `End`
|Scroll to next page | `Space, PgDn`
|Scroll to previous page | `PgUp`
|Scroll to next change | `n`
|Scroll to previous change | `p`
|Increase lines of context | `+`
|Decrease lines of context | `-`
|All lines of context | `a`
|Restore context to default| `=`
|===
[options="header"]
== Configuring kitty-diff
You can configure the colors used, keyboard shortcut, the diff implementation,
the default lines of context, etc. by creating a diff.conf in your kitty
config folder. See the link:diff.conf[default diff.conf] for details.
== Integrating with git
Add the following to `~/.gitconfig`:
```gitconfig
[diff]
tool = kitty
guitool = kitty.gui
[difftool]
prompt = false
trustExitCode = true
[difftool "kitty"]
cmd = kitty +kitten diff $LOCAL $REMOTE
[difftool "kitty.gui"]
cmd = kitty kitty +kitten diff $LOCAL $REMOTE
```
Now to use kitty-diff to view git diffs, you can simply do:
```
git difftool --no-symlinks --dir-diff
```
Once again, creating an alias for this command is useful.
== Why does this work only in kitty?
The diff kitten makes use of various features that are
link:https://github.com/kovidgoyal/kitty/blob/master/protocol-extensions.asciidoc[kitty
only], such as the
link:https://github.com/kovidgoyal/kitty/blob/master/graphics-protocol.asciidoc[kitty
graphics protocol], the extended keyboard protocol, etc. It also leverages
terminal program infrastructure I created for all of kitty's other kittens to
reduce the amount of code needed (the entire implementation is under 2000 lines
of code).
And fundamentally, it's kitty only because I wrote it for myself, and I am
highly unlikely to use any other terminals :)
See https://sw.kovidgoyal.net/kitty/kittens/diff.html

171
protocol-extensions.asciidoc
View File

@ -1,170 +1 @@
= Extensions to the xterm protocol
:toc:
:toc-placement!:
kitty has a few extensions to the xterm protocol, to enable advanced features.
These are typically in the form of new or re-purposed escape codes. While these
extensions are currently kitty specific, it would be nice to get some of them
adopted more broadly, to push the state of terminal emulators forward.
The goal of these extensions is to be as small an unobtrusive as possible,
while filling in some gaps in the existing xterm protocol. In particular, one
of the goals of this specification is explicitly not to "re-imagine" the tty.
The tty should remain what it is -- a device for efficiently processing text
received as a simple byte stream. Another objective is to only move the minimum
possible amount of extra functionality into the terminal program itself. This
is to make it as easy to implement these protocol extensions as possible,
thereby hopefully encouraging their widespread adoption.
If you wish to discuss these extensions, propose additions/changes to them
please do so by opening issues in the github bug tracker.
toc::[]
== Colored and styled underlines
kitty supports colored and styled (wavy) underlines. This is of particular use
in terminal editors such as vim and emacs to display red, wavy underlines under
mis-spelled words and/or syntax errors. This is done by re-purposing some SGR escape codes
that are not used in modern terminals (https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_codes)
To set the underline style:
```
<ESC>[4:0m # this is no underline
<ESC>[4:1m # this is a straight underline
<ESC>[4:2m # this is a double underline
<ESC>[4:3m # this is a curly underline
<ESC>[4:4m # this is a dotted underline (not implemented in kitty)
<ESC>[4:5m # this is a dashed underline (not implemented in kitty)
<ESC>[4m # this is a straight underline (for backwards compat)
<ESC>[24m # this is no underline (for backwards compat)
```
To set the underline color (this is reserved and as far as I can tell not actually used for anything):
```
<ESC>[58...m
```
This works exactly like the codes `38, 48` that are used to set foreground and
background color respectively.
To reset the underline color (also previously reserved and unused):
```
<ESC>[59m
```
To detect support for this feature in a terminal emulator, query the terminfo database
for the `Su` boolean capability.
== Graphics rendering
See link:graphics-protocol.asciidoc[Graphics Protocol] for a description
of this protocol to enable drawing of arbitrary raster images in the terminal.
== Keyboard handling
There are various problems with the current state of keyboard handling. They
include:
* No way to use modifiers other than `Ctrl` and `Alt`
* No way to use multiple modifier keys, other than, `Shift+Alt`.
* No way to handle different types of keyboard events, such as press, release or repeat
* No reliable way to distinguish single `Esc` keypresses from the
start of a escape sequence. Currently, client programs use
fragile timing related hacks for this, leading to bugs, for example:
link:https://github.com/neovim/neovim/issues/2035[neovim #2035]
There are already two distinct keyboard handling modes, _normal mode_ and
_application mode_. These modes generate different escape sequences for the
various special keys (arrow keys, function keys, home/end etc.) Most terminals
start out in normal mode, however, most shell programs like `bash` switch them to
application mode. We propose adding a third mode, named _full mode_ that addresses
the shortcomings listed above.
Switching to the new _full mode_ is accomplished using the standard private
mode DECSET escape sequence
```
<ESC>[?2017h
```
and to leave _full mode_, use DECRST
```
<ESC>[?2017l
```
The number `2017` above is not used for any existing modes, as far as I know.
Client programs can query if the terminal emulator is in _full mode_ by using
the standard link:http://vt100.net/docs/vt510-rm/DECRQM[DECRQM] escape sequence.
The new mode works as follows:
* All printable key presses without modifier keys are sent just as in the
_normal mode_. This means all printable ASCII characters and in addition,
`Enter`, `Space` and `Backspace`. Also any unicode characters generated by
platform specific extended input modes, such as using the `AltGr` key. This
is done so that client programs that are not aware of this mode can still
handle basic text entry, so if a _full mode_ using program crashes and does
not reset, the user can still issue a `reset` command in the shell to restore
normal key handling. Note that this includes pressing the `Shift` modifier
and printable keys. Note that this means there are no repeat and release
events for these keys and also for the left and right shift keys.
* For non printable keys and key combinations including one or more modifiers,
an escape sequence encoding the key event is sent. For details on the
escape sequence, see below.
The escape sequence encodes the following properties:
* Type of event: `press,repeat,release`
* Modifiers pressed at the time of the event
* The actual key being pressed
```
<ESC>_K<type><modifiers><key><ESC>\
```
Where `<type>` is one of `p` -- press, `r` -- release and `t` -- repeat.
Modifiers is a bitmask represented as a single base64 digit. Shift -- `0x1`,
Alt -- `0x2`, Control -- `0x4` and Super -- `0x8`. `<key>` is a number
(encoded in base85) corresponding to the key pressed. The key name to number
mapping is defined in link:key_encoding.asciidoc[this table].
For example:
```
<ESC>_KpGp<ESC>\ is <Ctrl>+<Alt>+x (press)
<ESC>_KrP8<ESC>\ is <Ctrl>+<Alt>+<Shift>+<Super>+PageUp (release)
```
This encoding means each key event is represented by 8 or 9 printable ascii
only bytes, for maximum robustness.
== Setting text styles/colors in arbitrary regions of the screen
There already exists an escape code to set *some* text attributes in arbitrary
regions of the screen,
link:https://vt100.net/docs/vt510-rm/DECCARA.html[DECCARA]. However, it is
limited to only a few attributes. kitty extends this to work with *all* SGR
attributes. So, for example, this can be used to set the background color in
an arbitrary region of the screen.
The motivation for this extension is the various problems with the existing
solution for erasing to background color, namely the *background color erase
(bce)* capability. See
link:https://github.com/kovidgoyal/kitty/issues/160#issuecomment-346470545[this discussion]
and link:http://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches[this FAQ]
for a summary of problems with *bce*.
For example, to set the background color to blue in a
rectangular region of the screen from (3, 4) to (10, 11), you use:
```
<ESC>[2*x<ESC>[4;3;11;10;44$r<ESC>[*x
```
See https://sw.kovidgoyal.net/kitty/protocol-extensions.html

111
remote-control.asciidoc
View File

@ -1,110 +1 @@
= Controlling kitty from scripts or the shell
kitty can be controlled from scripts or the shell prompt. You can open new
windows, send arbitrary text input to any window, name windows and tabs, etc.
Let's walk through a few examples of controlling kitty.
Start by running kitty as:
kitty -o allow_remote_control=yes --window-layout tall
In order for control to work, `allow_remote_control` must be enabled in
kitty.conf. Here we turn it on explicitly at the command line.
Now, in the new kitty window, enter the command:
kitty @ new-window --title Output --keep-focus cat
This will open a new window, running the ``cat`` program that will appear next
to the current window.
Let's send some text to this new window:
kitty @ send-text --match cmdline:cat Hello, World
This will make `Hello, World` show up in the window running the `cat` program.
The `--match` option is very powerful, it allows selecting windows by their
titles, the command line of the program running in the window, the working
directory of the program running in the window, etc. See `kitty @ send-text
--help` for details.
More usefully, you can pipe the output of a command running in one window to
another window, for example:
ls | kitty @ send-text --match title:Output --stdin
This will show the output of ls in the output window instead of the current
window. You can use this technique to, for example, show the output of running
`make` in your editor in a different window. The possibilities are endless.
You can even have things you type show up in a different window. Run:
kitty @ send-text --match title:Output --stdin
And type some text, it will show up in the output window, instead of the current
window. Type `Ctrl+D` when you are ready to stop.
Now, let's open a new tab.
kitty @ new-window --new-tab --tab-title "My Tab" --keep-focus bash
This will open a new tab running the bash shell with the title "My Tab".
We can change the title of the tab with:
kitty @ set-tab-title --match title:My New Title
Let's change the title of the current tab:
kitty @ set-tab-title Master Tab
Now lets switch to the newly opened tab:
kitty @ focus-tab --match title:New
Similarly, to focus the previously opened output window (which will also switch
back to the old tab, automatically):
kitty @ focus-window --match title:Output
You can get a listing of available tabs and windows, by running:
kitty @ ls
This outputs a tree of data in JSON format. The top level of the tree is all
operating system kitty windows. Each OS window has an id and a list of tabs.
Each tab has its own id, a title and a list of windows. Each window has an id,
title, current working directory, process id (PID) and command-line of the
process running in the window. You can use this information with `--match`
to control individual windows.
As you can see, it is very easy to control kitty using the
`kitty @` messaging system. This tutorial touches only the
surface of what is possible. See `kitty @ --help` for more details.
Note that in the example's above, `kitty @` messaging works only when run inside a kitty window,
not anywhere. But, within a kitty window it even works over SSH. If you want to control
kitty from programs/scripts not running inside a kitty window, you have to implement a couple of
extra steps. First start kitty as:
kitty -o allow_remote_control=yes --listen-on unix:/tmp/mykitty
The `--listen-on` option tells kitty to listen for control messages at the
specified path. See `kitty --help` for details. Now you can control this
instance of kitty using the `--to` command line argument to `kitty @`. For example:
kitty @ --to unix:/tmp/mykitty ls
Note that is all you want to do is run a single kitty "daemon" and have subsequent
kitty invocations appear as new top-level windows, you can use the simpler `--single-instance`
option, see `kitty --help` for that.
== The builtin kitty shell
You can explore the kitty command language more easily using the builtin kitty
shell. Run `kitty @` with no arguments and you will be dropped into the kitty
shell with completion for kitty command names and options.
You can even open the kitty shell inside a running kitty using a simple
keyboard shortcut (`ctrl+shift+escape` by default). This has the added
advantage that you dont need to use `allow_remote_control` to make it work.
See https://sw.kovidgoyal.net/kitty/remote-control.html