1/**
2 * @file focus.h
3 *
4 * Focus encoding - encode focus in/out events into terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_FOCUS_H
8#define GHOSTTY_VT_FOCUS_H
9
10/** @defgroup focus Focus Encoding
11 *
12 * Utilities for encoding focus gained/lost events into terminal escape
13 * sequences (CSI I / CSI O) for focus reporting mode (mode 1004).
14 *
15 * ## Basic Usage
16 *
17 * Use ghostty_focus_encode() to encode a focus event into a caller-provided
18 * buffer. If the buffer is too small, the function returns
19 * GHOSTTY_OUT_OF_SPACE and sets the required size in the output parameter.
20 *
21 * ## Example
22 *
23 * @snippet c-vt-encode-focus/src/main.c focus-encode
24 *
25 * @{
26 */
27
28#include <stddef.h>
29#include <ghostty/vt/types.h>
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/**
36 * Focus event types for focus reporting mode (mode 1004).
37 */
38typedef enum GHOSTTY_ENUM_TYPED {
39 /** Terminal window gained focus */
40 GHOSTTY_FOCUS_GAINED = 0,
41 /** Terminal window lost focus */
42 GHOSTTY_FOCUS_LOST = 1,
43 GHOSTTY_FOCUS_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
44} GhosttyFocusEvent;
45
46/**
47 * Encode a focus event into a terminal escape sequence.
48 *
49 * Encodes a focus gained (CSI I) or focus lost (CSI O) report into the
50 * provided buffer.
51 *
52 * If the buffer is too small, the function returns GHOSTTY_OUT_OF_SPACE
53 * and writes the required buffer size to @p out_written. The caller can
54 * then retry with a sufficiently sized buffer.
55 *
56 * @param event The focus event to encode
57 * @param buf Output buffer to write the encoded sequence into (may be NULL)
58 * @param buf_len Size of the output buffer in bytes
59 * @param[out] out_written On success, the number of bytes written. On
60 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
61 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
62 * is too small
63 */
64GHOSTTY_API GhosttyResult ghostty_focus_encode(
65 GhosttyFocusEvent event,
66 char* buf,
67 size_t buf_len,
68 size_t* out_written);
69
70#ifdef __cplusplus
71}
72#endif
73
74/** @} */
75
76#endif /* GHOSTTY_VT_FOCUS_H */