Kitty Graphics Protocol in OCaml
anil.recoil.org
terminal
graphics
ocaml
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Cursor Movement Behavior
7
8 Controls cursor position after displaying an image.
9
10 {2 Protocol Details}
11
12 Cursor movement is specified via the [C] key in the control data:
13 - [C=0] or no [C] key: move cursor after display (default)
14 - [C=1]: keep cursor in place (static)
15
16 This key was added in Kitty 0.20.0.
17
18 {2 Default Behavior}
19
20 By default ([{`Move}]), after displaying an image the cursor advances:
21 - Right by the number of columns the image occupies
22 - Down by the number of rows the image occupies
23
24 This matches how the cursor moves after printing text, allowing images to
25 flow naturally with text content.
26
27 {2 Static Cursor}
28
29 With [{`Static}], the cursor remains at its original position. This is
30 useful when:
31 - Overlaying images on existing content
32 - Positioning multiple images relative to the same starting point
33 - Implementing custom cursor management
34
35 {2 Relative Placements}
36
37 Note: When using relative placements (positioning images relative to other
38 placements), the cursor never moves regardless of this setting. *)
39
40type t = [ `Move | `Static ]
41(** Cursor movement behavior.
42
43 - [`Move] - Advance cursor past the displayed image (default). Cursor moves
44 right by the number of columns and down by the number of rows occupied by
45 the image.
46 - [`Static] - Keep cursor at its original position. The image is displayed
47 but cursor position is unchanged. *)
48
49val to_int : t -> int
50(** Convert to protocol integer.
51
52 Returns 0 for [`Move] or 1 for [`Static]. These values are used in the [C=]
53 control data key. *)