Kitty Graphics Protocol in OCaml
anil.recoil.org
terminal
graphics
ocaml
1(** Image Deletion Target
2
3 Specifies which images or placements to delete.
4
5 {2 Protocol Details}
6
7 Deletion is performed with action [a=d] and the [d] key specifies
8 the deletion type. The [d] key uses single characters:
9
10 {v
11 | Char | Meaning |
12 |------|--------------------------------------------------------|
13 | a/A | All placements visible on screen |
14 | i/I | By image ID (with optional placement ID) |
15 | n/N | By image number (newest with that number) |
16 | c/C | At current cursor position |
17 | p/P | At specific cell coordinates (x, y) |
18 | q/Q | At specific cell with z-index (x, y, z) |
19 | x/X | All in specific column |
20 | y/Y | All in specific row |
21 | z/Z | All with specific z-index |
22 | r/R | By image ID range (min_id to max_id) |
23 | f/F | Animation frames only |
24 v}
25
26 {2 Placements vs Image Data}
27
28 Each deletion type can optionally free image data (controlled by the
29 [~free] parameter in the delete command):
30 - {b Without free}: Removes placements only. The image data remains in
31 memory and can be displayed again later. (Protocol: lowercase char)
32 - {b With free}: Removes placements AND frees the image data. The
33 image cannot be displayed again without retransmitting. (Protocol:
34 uppercase char)
35
36 {2 Placement IDs}
37
38 When deleting by image ID or number, an optional placement ID can be
39 specified to delete only a specific placement. If [None], all placements
40 of that image are deleted.
41
42 {2 Coordinate-Based Deletion}
43
44 For [{`At_cell}] and [{`At_cell_z}], coordinates are 0-based cell
45 positions (not pixel positions). Only placements that intersect the
46 specified cell are deleted.
47
48 {2 Virtual Placements}
49
50 Virtual placements (used for Unicode placeholder mode) are only affected
51 by: [{`By_id}], [{`By_number}], and [{`By_id_range}]. Other deletion
52 commands do not affect virtual placements. *)
53
54type t =
55 [ `All_visible
56 | `By_id of int * int option
57 | `By_number of int * int option
58 | `At_cursor
59 | `At_cell of int * int
60 | `At_cell_z of int * int * int
61 | `By_column of int
62 | `By_row of int
63 | `By_z_index of int
64 | `By_id_range of int * int
65 | `Frames ]
66(** Deletion target specification.
67
68 {b Screen-based:}
69 - [`All_visible] - All placements currently visible on screen
70 - [`At_cursor] - Placements at current cursor position
71 - [`At_cell (x, y)] - Placements intersecting cell at column x, row y
72 - [`At_cell_z (x, y, z)] - Like [`At_cell] but only with z-index z
73 - [`By_column x] - All placements intersecting column x
74 - [`By_row y] - All placements intersecting row y
75 - [`By_z_index z] - All placements with z-index z
76
77 {b ID-based:}
78 - [`By_id (id, placement_id)] - By image ID. If [placement_id] is
79 [Some p], only that specific placement; if [None], all placements.
80 - [`By_number (n, placement_id)] - By image number (newest image
81 with that number). Placement ID works as above.
82 - [`By_id_range (min, max)] - All images with IDs in range [min..max]
83
84 {b Animation:}
85 - [`Frames] - Animation frames only (not the base image)
86
87 Use the [~free] parameter in the delete command to also release
88 image data from memory. *)
89
90val to_char : free:bool -> t -> char
91(** Convert to protocol character for the delete command.
92
93 Returns the character used in the [d=] control data key.
94 @param free If true, returns uppercase (frees data); if false,
95 returns lowercase (keeps data). *)