Keys

Encode key events with the legacy encoding or the Kitty keyboard protocol. More...

Detailed Description

Encode key events with the legacy encoding or the Kitty keyboard protocol.

Encode key events into terminal escape sequences, with the legacy encoding or the Kitty Keyboard Protocol.

An encoder has to follow the terminal's modes. If you have a terminal, call ghostty_key_encoder_set_from_terminal() before you encode. You don't need a terminal to use this, but then you set the options yourself.

Example

int main() {
  // Create encoder
  GhosttyKeyEncoder encoder;
  GhosttyResult result = ghostty_key_encoder_new(NULL, &encoder);
  assert(result == GHOSTTY_SUCCESS);
 
  // Enable Kitty keyboard protocol with all features
  ghostty_key_encoder_set(encoder, GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS,
                             &(uint8_t){GHOSTTY_KITTY_KEY_ALL});
 
  // Create and configure key event for Ctrl+C press
  GhosttyKeyEvent event;
  result = ghostty_key_event_new(NULL, &event);
  assert(result == GHOSTTY_SUCCESS);
  result = ghostty_key_event_set_action(event, GHOSTTY_KEY_ACTION_PRESS);
  assert(result == GHOSTTY_SUCCESS);
  result = ghostty_key_event_set_key(event, GHOSTTY_KEY_C);
  assert(result == GHOSTTY_SUCCESS);
  result = ghostty_key_event_set_mods(event, GHOSTTY_MODS_CTRL);
  assert(result == GHOSTTY_SUCCESS);
  result = ghostty_key_event_set_unshifted_codepoint(event, 'c');
  assert(result == GHOSTTY_SUCCESS);
 
  // Encode the key event
  uint8_t buf[128];
  size_t written = 0;
  result = ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
  assert(result == GHOSTTY_SUCCESS);
 
  // Use the encoded sequence (e.g., write to terminal)
  fwrite(buf, 1, written, stdout);
 
  // Cleanup
  ghostty_key_event_free(event);
  ghostty_key_encoder_free(encoder);
  return 0;
}

Full program: c-vt-encode-key/src/main.c

The Input guide explains which modes matter and when to sync them.

Typedefs
typedef struct GhosttyKeyEncoderImpl *	GhosttyKeyEncoder
typedef uint8_t	GhosttyKittyKeyFlags
typedef struct GhosttyKeyEventImpl *	GhosttyKeyEvent
typedef uint16_t	GhosttyMods

Enumerations
enum	GhosttyOptionAsAlt { GHOSTTY_OPTION_AS_ALT_FALSE = 0 , GHOSTTY_OPTION_AS_ALT_TRUE = 1 , GHOSTTY_OPTION_AS_ALT_LEFT = 2 , GHOSTTY_OPTION_AS_ALT_RIGHT = 3 , GHOSTTY_OPTION_AS_ALT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyKeyEncoderOption {   GHOSTTY_KEY_ENCODER_OPT_INVALID = 0 , GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION = 1 , GHOSTTY_KEY_ENCODER_OPT_KEYPAD_KEY_APPLICATION = 2 , GHOSTTY_KEY_ENCODER_OPT_IGNORE_KEYPAD_WITH_NUMLOCK = 3 ,   GHOSTTY_KEY_ENCODER_OPT_ALT_ESC_PREFIX = 4 , GHOSTTY_KEY_ENCODER_OPT_MODIFY_OTHER_KEYS_STATE_2 = 5 , GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS = 6 , GHOSTTY_KEY_ENCODER_OPT_MACOS_OPTION_AS_ALT = 7 ,   GHOSTTY_KEY_ENCODER_OPT_BACKARROW_KEY_MODE = 8 , GHOSTTY_KEY_ENCODER_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyKeyAction { GHOSTTY_KEY_ACTION_RELEASE = 0 , GHOSTTY_KEY_ACTION_PRESS = 1 , GHOSTTY_KEY_ACTION_REPEAT = 2 , GHOSTTY_KEY_ACTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyKey

Functions
GHOSTTY_API GhosttyResult	ghostty_key_encoder_new (const GhosttyAllocator *allocator, GhosttyKeyEncoder *encoder)
GHOSTTY_API void	ghostty_key_encoder_free (GhosttyKeyEncoder encoder)
GHOSTTY_API GhosttyResult	ghostty_key_encoder_set (GhosttyKeyEncoder encoder, GhosttyKeyEncoderOption option, const void *value)
GHOSTTY_API GhosttyResult	ghostty_key_encoder_set_from_terminal (GhosttyKeyEncoder encoder, GhosttyTerminal terminal)
GHOSTTY_API GhosttyResult	ghostty_key_encoder_encode (GhosttyKeyEncoder encoder, GhosttyKeyEvent event, uint8_t *buf, size_t buf_len, size_t *out_written)
GHOSTTY_API GhosttyResult	ghostty_key_event_new (const GhosttyAllocator *allocator, GhosttyKeyEvent *event)
GHOSTTY_API void	ghostty_key_event_free (GhosttyKeyEvent event)
GHOSTTY_API GhosttyResult	ghostty_key_event_set_action (GhosttyKeyEvent event, GhosttyKeyAction action)
GHOSTTY_API GhosttyKeyAction	ghostty_key_event_get_action (GhosttyKeyEvent event)
GHOSTTY_API GhosttyResult	ghostty_key_event_set_key (GhosttyKeyEvent event, GhosttyKey key)
GHOSTTY_API GhosttyKey	ghostty_key_event_get_key (GhosttyKeyEvent event)
GHOSTTY_API GhosttyResult	ghostty_key_event_set_mods (GhosttyKeyEvent event, GhosttyMods mods)
GHOSTTY_API GhosttyMods	ghostty_key_event_get_mods (GhosttyKeyEvent event)
GHOSTTY_API GhosttyResult	ghostty_key_event_set_consumed_mods (GhosttyKeyEvent event, GhosttyMods consumed_mods)
GHOSTTY_API GhosttyMods	ghostty_key_event_get_consumed_mods (GhosttyKeyEvent event)
GHOSTTY_API GhosttyResult	ghostty_key_event_set_composing (GhosttyKeyEvent event, bool composing)
GHOSTTY_API bool	ghostty_key_event_get_composing (GhosttyKeyEvent event)
GHOSTTY_API GhosttyResult	ghostty_key_event_set_utf8 (GhosttyKeyEvent event, GhosttyString utf8)
GHOSTTY_API GhosttyString	ghostty_key_event_get_utf8 (GhosttyKeyEvent event)
GHOSTTY_API GhosttyResult	ghostty_key_event_set_unshifted_codepoint (GhosttyKeyEvent event, uint32_t codepoint)
GHOSTTY_API uint32_t	ghostty_key_event_get_unshifted_codepoint (GhosttyKeyEvent event)

Macros
#define	GHOSTTY_KITTY_KEY_DISABLED   0
#define	GHOSTTY_KITTY_KEY_DISAMBIGUATE   (1 << 0)
#define	GHOSTTY_KITTY_KEY_REPORT_EVENTS   (1 << 1)
#define	GHOSTTY_KITTY_KEY_REPORT_ALTERNATES   (1 << 2)
#define	GHOSTTY_KITTY_KEY_REPORT_ALL   (1 << 3)
#define	GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED   (1 << 4)
#define	GHOSTTY_KITTY_KEY_ALL   (GHOSTTY_KITTY_KEY_DISAMBIGUATE | GHOSTTY_KITTY_KEY_REPORT_EVENTS | GHOSTTY_KITTY_KEY_REPORT_ALTERNATES | GHOSTTY_KITTY_KEY_REPORT_ALL | GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED)
#define	GHOSTTY_MODS_SHIFT   (1 << 0)
#define	GHOSTTY_MODS_CTRL   (1 << 1)
#define	GHOSTTY_MODS_ALT   (1 << 2)
#define	GHOSTTY_MODS_SUPER   (1 << 3)
#define	GHOSTTY_MODS_CAPS_LOCK   (1 << 4)
#define	GHOSTTY_MODS_NUM_LOCK   (1 << 5)
#define	GHOSTTY_MODS_SHIFT_SIDE   (1 << 6)
#define	GHOSTTY_MODS_CTRL_SIDE   (1 << 7)
#define	GHOSTTY_MODS_ALT_SIDE   (1 << 8)
#define	GHOSTTY_MODS_SUPER_SIDE   (1 << 9)

Typedef Documentation

GhosttyKeyEncoder

typedef struct GhosttyKeyEncoderImpl* GhosttyKeyEncoder

Opaque handle to a key encoder instance.

This handle represents a key encoder that converts key events into terminal escape sequences.

Examples

c-vt-encode-key/src/main.c.

Definition at line 25 of file key/encoder.h.

GhosttyKeyEvent

typedef struct GhosttyKeyEventImpl* GhosttyKeyEvent

Opaque handle to a key event.

This handle represents a keyboard input event containing information about the physical key pressed, modifiers, and generated text.

Examples

c-vt-encode-key/src/main.c.

Definition at line 24 of file key/event.h.

GhosttyKittyKeyFlags

typedef uint8_t GhosttyKittyKeyFlags

Kitty keyboard protocol flags.

Bitflags representing the various modes of the Kitty keyboard protocol. These can be combined using bitwise OR operations. Valid values all start with GHOSTTY_KITTY_KEY_.

Definition at line 36 of file key/encoder.h.

GhosttyMods

typedef uint16_t GhosttyMods

Keyboard modifier keys bitmask.

A bitmask representing all keyboard modifiers. This tracks which modifier keys are pressed and, where supported by the platform, which side (left or right) of each modifier is active.

Use the GHOSTTY_MODS_* constants to test and set individual modifiers.

Modifier side bits are only meaningful when the corresponding modifier bit is set. Not all platforms support distinguishing between left and right modifier keys and Ghostty is built to expect that some platforms may not provide this information.

Definition at line 57 of file key/event.h.

Enumeration Type Documentation

GhosttyKey

enum GhosttyKey

Physical key codes.

The set of key codes that Ghostty is aware of. These represent physical keys on the keyboard and are layout-independent. For example, the "a" key on a US keyboard is the same as the "ф" key on a Russian keyboard, but both will report the same key_a value.

Layout-dependent strings are provided separately as UTF-8 text and are produced by the platform. These values are based on the W3C UI Events KeyboardEvent code standard. See: https://www.w3.org/TR/uievents-code

Definition at line 115 of file key/event.h.

GhosttyKeyAction

enum GhosttyKeyAction

Keyboard input event types.

Enumerator
GHOSTTY_KEY_ACTION_RELEASE	Key was released
GHOSTTY_KEY_ACTION_PRESS	Key was pressed
GHOSTTY_KEY_ACTION_REPEAT	Key is being repeated (held down)

Definition at line 31 of file key/event.h.

GhosttyKeyEncoderOption

enum GhosttyKeyEncoderOption

Key encoder option identifiers.

These values are used with ghostty_key_encoder_set() to configure the behavior of the key encoder.

Enumerator
GHOSTTY_KEY_ENCODER_OPT_INVALID	Not a real option. ghostty_key_encoder_set() returns GHOSTTY_INVALID_VALUE for it. Its value is 0, so a zeroed or uninitialized variable is never mistaken for a real option.
GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION	Terminal DEC mode 1: cursor key application mode (value: bool, default: false)
GHOSTTY_KEY_ENCODER_OPT_KEYPAD_KEY_APPLICATION	Terminal DEC mode 66: keypad key application mode (value: bool, default: false)
GHOSTTY_KEY_ENCODER_OPT_IGNORE_KEYPAD_WITH_NUMLOCK	Terminal DEC mode 1035: ignore keypad with numlock (value: bool, default: false)
GHOSTTY_KEY_ENCODER_OPT_ALT_ESC_PREFIX	Terminal DEC mode 1036: alt sends escape prefix (value: bool, default: false)
GHOSTTY_KEY_ENCODER_OPT_MODIFY_OTHER_KEYS_STATE_2	xterm modifyOtherKeys mode 2 (value: bool, default: false)
GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS	Kitty keyboard protocol flags (value: GhosttyKittyKeyFlags bitmask, default: GHOSTTY_KITTY_KEY_DISABLED)
GHOSTTY_KEY_ENCODER_OPT_MACOS_OPTION_AS_ALT	macOS option-as-alt setting (value: GhosttyOptionAsAlt, default: GHOSTTY_OPTION_AS_ALT_FALSE)
GHOSTTY_KEY_ENCODER_OPT_BACKARROW_KEY_MODE	Backarrow key mode (value: bool) See https://vt100.net/dec/ek-vt3xx-tp-002.pdf page 170 If false (the default), backspace emits 0x7f If true, backspace emits 0x08

Definition at line 87 of file key/encoder.h.

GhosttyOptionAsAlt

enum GhosttyOptionAsAlt

macOS option key behavior.

Determines whether the "option" key on macOS is treated as "alt" or not. See the Ghostty macos-option-as-alt configuration option for more details.

Enumerator
GHOSTTY_OPTION_AS_ALT_FALSE	Option key is not treated as alt
GHOSTTY_OPTION_AS_ALT_TRUE	Option key is treated as alt
GHOSTTY_OPTION_AS_ALT_LEFT	Only left option key is treated as alt
GHOSTTY_OPTION_AS_ALT_RIGHT	Only right option key is treated as alt

Definition at line 67 of file key/encoder.h.

Function Documentation

ghostty_key_encoder_encode()

GHOSTTY_API GhosttyResult ghostty_key_encoder_encode	(	GhosttyKeyEncoder	encoder,
		GhosttyKeyEvent	event,
		uint8_t *	buf,
		size_t	buf_len,
		size_t *	out_written )

Encode a key event into a terminal escape sequence.

Converts a key event into the appropriate terminal escape sequence based on the encoder's current options. The sequence is written to the provided buffer.

Not all key events produce output. For example, unmodified modifier keys typically don't generate escape sequences. For those events this returns GHOSTTY_SUCCESS with out_written set to 0.

If buf is too small, this returns GHOSTTY_OUT_OF_SPACE and sets out_written to the size needed. The buffer may then hold part of the sequence, which you should discard. To get the size without encoding anything, pass NULL for buf and 0 for buf_len. An event with no output still returns GHOSTTY_SUCCESS in that case, because it needs no space.

Parameters

	encoder	The encoder handle, must not be NULL
	event	The key event to encode, must not be NULL
	buf	Buffer to write the sequence into. May be NULL if buf_len is 0.
	buf_len	Size of buf in bytes
[out]	out_written	The number of bytes written, or the size needed if the result is GHOSTTY_OUT_OF_SPACE. Must not be NULL.

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if buffer too small, or other error code

Example: Calculate required buffer size

// Query the required size with a NULL buffer
size_t required = 0;
GhosttyResult result = ghostty_key_encoder_encode(encoder, event, NULL, 0, &required);
if (result == GHOSTTY_SUCCESS) {
  // This event produces no output, so there is nothing to send
  return;
}
assert(result == GHOSTTY_OUT_OF_SPACE);
 
// Allocate buffer of required size
uint8_t *buf = malloc(required);
 
// Encode with properly sized buffer
size_t written = 0;
result = ghostty_key_encoder_encode(encoder, event, buf, required, &written);
assert(result == GHOSTTY_SUCCESS);
 
// Use the encoded sequence...
 
free(buf);

Example: Direct encoding with static buffer

// Most escape sequences are short, so a static buffer often suffices
uint8_t buf[128];
size_t written = 0;
GhosttyResult result = ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
 
if (result == GHOSTTY_SUCCESS) {
  // Write the encoded sequence to the terminal
  write(pty_fd, buf, written);
} else if (result == GHOSTTY_OUT_OF_SPACE) {
  // Buffer too small, written contains required size
  uint8_t *dynamic_buf = malloc(written);
  result = ghostty_key_encoder_encode(encoder, event, dynamic_buf, written, &written);
  assert(result == GHOSTTY_SUCCESS);
  write(pty_fd, dynamic_buf, written);
  free(dynamic_buf);
}

Examples

c-vt-encode-key/src/main.c.

ghostty_key_encoder_free()

GHOSTTY_API void ghostty_key_encoder_free

(

GhosttyKeyEncoder

encoder

)

Free a key encoder instance.

Releases all resources associated with the key encoder. After this call, the encoder handle becomes invalid and must not be used.

Parameters

encoder

The encoder handle to free (may be NULL)

Examples

c-vt-encode-key/src/main.c.

ghostty_key_encoder_new()

GHOSTTY_API GhosttyResult ghostty_key_encoder_new	(	const GhosttyAllocator *	allocator,
		GhosttyKeyEncoder *	encoder )

Create a new key encoder instance.

Creates a new key encoder with default options. The encoder can be configured using ghostty_key_encoder_set() and must be freed using ghostty_key_encoder_free() when no longer needed.

Parameters

allocator	Pointer to the allocator to use for memory management, or NULL to use the default allocator
encoder	Pointer to store the created encoder handle

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

Examples

c-vt-encode-key/src/main.c.

ghostty_key_encoder_set()

GHOSTTY_API GhosttyResult ghostty_key_encoder_set	(	GhosttyKeyEncoder	encoder,
		GhosttyKeyEncoderOption	option,
		const void *	value )

Set an option on the key encoder.

Configures the behavior of the key encoder. Options control various aspects of encoding such as terminal modes (cursor key application mode, keypad mode), protocol selection (Kitty keyboard protocol flags), and platform-specific behaviors (macOS option-as-alt).

If you are using a terminal instance, you can set the key encoding options based on the active terminal state (e.g. legacy vs Kitty mode and associated flags) with ghostty_key_encoder_set_from_terminal().

Passing NULL for value resets the option to its default, the same value a new encoder starts with. Each option's default is listed on GhosttyKeyEncoderOption.

bool enabled = true;
ghostty_key_encoder_set(
    encoder, GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION, &enabled);
 
// Later, put the option back to its default (false).
ghostty_key_encoder_set(
    encoder, GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION, NULL);

Parameters

encoder	The encoder handle, must not be NULL
option	The option to set
value	Pointer to the value to set (type depends on the option), or NULL to reset the option to its default

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if encoder is NULL or the value is out of range (such as an unknown GhosttyOptionAsAlt), or GHOSTTY_UNSUPPORTED if option is not known to this version of the library

Examples

c-vt-encode-key/src/main.c.

ghostty_key_encoder_set_from_terminal()

GHOSTTY_API GhosttyResult ghostty_key_encoder_set_from_terminal	(	GhosttyKeyEncoder	encoder,
		GhosttyTerminal	terminal )

Set encoder options from a terminal's current state.

Reads the terminal's current modes and flags and applies them to the encoder's options. This sets cursor key application mode, keypad mode, backarrow key mode, ignore-keypad-with-numlock, alt escape prefix, modifyOtherKeys state, and Kitty keyboard protocol flags from the terminal state.

Note that the macos_option_as_alt option cannot be determined from terminal state and is reset to GHOSTTY_OPTION_AS_ALT_FALSE by this call. Use ghostty_key_encoder_set() to set it afterward if needed.

Parameters

encoder	The encoder handle
terminal	The terminal handle

Returns

GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if encoder or Terminal is NULL. On error the encoder is not changed.

ghostty_key_event_free()

GHOSTTY_API void ghostty_key_event_free

(

GhosttyKeyEvent

event

)

Free a key event instance.

Releases all resources associated with the key event. After this call, the event handle becomes invalid and must not be used.

Parameters

event

The key event handle to free (may be NULL)

Examples

c-vt-encode-key/src/main.c.

ghostty_key_event_get_action()

GHOSTTY_API GhosttyKeyAction ghostty_key_event_get_action

(

GhosttyKeyEvent

event

)

Get the key action (press, release, repeat).

Parameters

event

The key event handle

Returns

The key action, or GHOSTTY_KEY_ACTION_RELEASE if event is NULL

ghostty_key_event_get_composing()

GHOSTTY_API bool ghostty_key_event_get_composing

(

GhosttyKeyEvent

event

)

Get whether the key event is part of a composition sequence.

Parameters

event

The key event handle

Returns

Whether the key event is part of a composition sequence, or false if event is NULL

ghostty_key_event_get_consumed_mods()

GHOSTTY_API GhosttyMods ghostty_key_event_get_consumed_mods

(

GhosttyKeyEvent

event

)

Get the consumed modifiers bitmask.

Parameters

event

The key event handle

Returns

The consumed modifiers bitmask, or 0 (no modifiers) if event is NULL

ghostty_key_event_get_key()

GHOSTTY_API GhosttyKey ghostty_key_event_get_key

(

GhosttyKeyEvent

event

)

Get the physical key code.

Parameters

event

The key event handle

Returns

The physical key code, or GHOSTTY_KEY_UNIDENTIFIED if event is NULL

ghostty_key_event_get_mods()

GHOSTTY_API GhosttyMods ghostty_key_event_get_mods

(

GhosttyKeyEvent

event

)

Get the modifier keys bitmask.

Parameters

event

The key event handle

Returns

The modifier keys bitmask, or 0 (no modifiers) if event is NULL

ghostty_key_event_get_unshifted_codepoint()

GHOSTTY_API uint32_t ghostty_key_event_get_unshifted_codepoint

(

GhosttyKeyEvent

event

)

Get the unshifted Unicode codepoint.

Parameters

event

The key event handle

Returns

The unshifted Unicode codepoint, or 0 if event is NULL

ghostty_key_event_get_utf8()

GHOSTTY_API GhosttyString ghostty_key_event_get_utf8

(

GhosttyKeyEvent

event

)

Get the UTF-8 text generated by the key event.

The event does not copy its text, so the returned string points at the same bytes that were passed to ghostty_key_event_set_utf8(). It stays valid while those bytes do, until the event is freed or its text is set again.

The bytes are not null-terminated. Always use the length:

GhosttyString text = ghostty_key_event_get_utf8(event);
printf("%.*s\n", (int)text.len, (const char *)text.ptr);

Parameters

event

The key event handle

Returns

The UTF-8 text. If the event has no text or event is NULL, the string has a length of zero.

ghostty_key_event_new()

GHOSTTY_API GhosttyResult ghostty_key_event_new	(	const GhosttyAllocator *	allocator,
		GhosttyKeyEvent *	event )

Create a new key event instance.

Creates a new key event with default values. The event must be freed using ghostty_key_event_free() when no longer needed.

Parameters

allocator	Pointer to the allocator to use for memory management, or NULL to use the default allocator
event	Pointer to store the created key event handle

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

Examples

c-vt-encode-key/src/main.c.

ghostty_key_event_set_action()

GHOSTTY_API GhosttyResult ghostty_key_event_set_action	(	GhosttyKeyEvent	event,
		GhosttyKeyAction	action )

Set the key action (press, release, repeat).

Parameters

event	The key event handle
action	The action to set

Returns

GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if event is NULL or action is not a GhosttyKeyAction value this version of the library knows. On error the event is not changed.

Examples

c-vt-encode-key/src/main.c.

ghostty_key_event_set_composing()

GHOSTTY_API GhosttyResult ghostty_key_event_set_composing	(	GhosttyKeyEvent	event,
		bool	composing )

Set whether the key event is part of a composition sequence.

Parameters

event	The key event handle
composing	Whether the key event is part of a composition sequence

Returns

GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if event is NULL. On error the event is not changed.

ghostty_key_event_set_consumed_mods()

GHOSTTY_API GhosttyResult ghostty_key_event_set_consumed_mods	(	GhosttyKeyEvent	event,
		GhosttyMods	consumed_mods )

Set the consumed modifiers bitmask.

Parameters

event	The key event handle
consumed_mods	The consumed modifiers bitmask to set

Returns

GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if event is NULL. On error the event is not changed.

ghostty_key_event_set_key()

GHOSTTY_API GhosttyResult ghostty_key_event_set_key	(	GhosttyKeyEvent	event,
		GhosttyKey	key )

Set the physical key code.

Parameters

event	The key event handle
key	The physical key code to set

Returns

GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if event is NULL or Keys is not a GhosttyKey value this version of the library knows. On error the event is not changed.

Examples

c-vt-encode-key/src/main.c.

ghostty_key_event_set_mods()

GHOSTTY_API GhosttyResult ghostty_key_event_set_mods	(	GhosttyKeyEvent	event,
		GhosttyMods	mods )

Set the modifier keys bitmask.

Parameters

event	The key event handle
mods	The modifier keys bitmask to set

Returns

GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if event is NULL. On error the event is not changed.

Examples

c-vt-encode-key/src/main.c.

ghostty_key_event_set_unshifted_codepoint()

GHOSTTY_API GhosttyResult ghostty_key_event_set_unshifted_codepoint	(	GhosttyKeyEvent	event,
		uint32_t	codepoint )

Set the unshifted Unicode codepoint.

Parameters

event	The key event handle
codepoint	The unshifted Unicode codepoint to set

Returns

GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if event is NULL. On error the event is not changed.

Examples

c-vt-encode-key/src/main.c.

ghostty_key_event_set_utf8()

GHOSTTY_API GhosttyResult ghostty_key_event_set_utf8	(	GhosttyKeyEvent	event,
		GhosttyString	utf8 )

Set the UTF-8 text generated by the key for the current keyboard layout.

Must contain the unmodified character before any Ctrl/Meta transformations. The encoder derives modifier sequences from the logical key and mods bitmask, not from this text. Do not pass C0 control characters (U+0000-U+001F, U+007F) or platform function key codes (e.g. macOS PUA U+F700-U+F8FF). For those keys, pass an empty string and the encoder will use the logical key instead.

A string with a length of zero clears the text. The library does not read its pointer, so the pointer may be NULL.

The key event does not copy the text. The bytes must stay valid until the event is freed or its text is set again. String literals and buffers that outlive the event are both fine.

// Set the text for a key that produced "a".
const char *text = "a";
GhosttyString utf8 = {
    .ptr = (const uint8_t *)text,
    .len = strlen(text),
};
GhosttyResult result = ghostty_key_event_set_utf8(event, utf8);
 
// Clear the text, for example for a function key.
result = ghostty_key_event_set_utf8(event, (GhosttyString){0});

Parameters

event	The key event handle
utf8	The UTF-8 text to set. It does not need to be null-terminated.

Returns

GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if event is NULL. On error the event is not changed.

Macro Definition Documentation

GHOSTTY_KITTY_KEY_ALL

#define GHOSTTY_KITTY_KEY_ALL   (GHOSTTY_KITTY_KEY_DISAMBIGUATE | GHOSTTY_KITTY_KEY_REPORT_EVENTS | GHOSTTY_KITTY_KEY_REPORT_ALTERNATES | GHOSTTY_KITTY_KEY_REPORT_ALL | GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED)

All Kitty keyboard protocol flags enabled.

Examples

c-vt-encode-key/src/main.c.

Definition at line 57 of file key/encoder.h.

GHOSTTY_KITTY_KEY_DISABLED

#define GHOSTTY_KITTY_KEY_DISABLED   0

Kitty keyboard protocol disabled (all flags off).

Definition at line 39 of file key/encoder.h.

GHOSTTY_KITTY_KEY_DISAMBIGUATE

#define GHOSTTY_KITTY_KEY_DISAMBIGUATE   (1 << 0)

Disambiguate escape codes.

Definition at line 42 of file key/encoder.h.

GHOSTTY_KITTY_KEY_REPORT_ALL

#define GHOSTTY_KITTY_KEY_REPORT_ALL   (1 << 3)

Report all key events including those normally handled by the terminal.

Definition at line 51 of file key/encoder.h.

GHOSTTY_KITTY_KEY_REPORT_ALTERNATES

#define GHOSTTY_KITTY_KEY_REPORT_ALTERNATES   (1 << 2)

Report alternate key codes.

Definition at line 48 of file key/encoder.h.

GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED

#define GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED   (1 << 4)

Report associated text with key events.

Definition at line 54 of file key/encoder.h.

GHOSTTY_KITTY_KEY_REPORT_EVENTS

#define GHOSTTY_KITTY_KEY_REPORT_EVENTS   (1 << 1)

Report key press and release events.

Definition at line 45 of file key/encoder.h.

GHOSTTY_MODS_ALT

#define GHOSTTY_MODS_ALT   (1 << 2)

Alt/Option key is pressed.

Definition at line 64 of file key/event.h.

GHOSTTY_MODS_ALT_SIDE

#define GHOSTTY_MODS_ALT_SIDE   (1 << 8)

Right alt is pressed (0 = left, 1 = right). Only meaningful when GHOSTTY_MODS_ALT is set.

Definition at line 92 of file key/event.h.

GHOSTTY_MODS_CAPS_LOCK

#define GHOSTTY_MODS_CAPS_LOCK   (1 << 4)

Caps Lock is active.

Definition at line 68 of file key/event.h.

GHOSTTY_MODS_CTRL

#define GHOSTTY_MODS_CTRL   (1 << 1)

Control key is pressed.

Examples

c-vt-encode-key/src/main.c.

Definition at line 62 of file key/event.h.

GHOSTTY_MODS_CTRL_SIDE

#define GHOSTTY_MODS_CTRL_SIDE   (1 << 7)

Right ctrl is pressed (0 = left, 1 = right). Only meaningful when GHOSTTY_MODS_CTRL is set.

Definition at line 85 of file key/event.h.

GHOSTTY_MODS_NUM_LOCK

#define GHOSTTY_MODS_NUM_LOCK   (1 << 5)

Num Lock is active.

Definition at line 70 of file key/event.h.

GHOSTTY_MODS_SHIFT

#define GHOSTTY_MODS_SHIFT   (1 << 0)

Shift key is pressed.

Definition at line 60 of file key/event.h.

GHOSTTY_MODS_SHIFT_SIDE

#define GHOSTTY_MODS_SHIFT_SIDE   (1 << 6)

Right shift is pressed (0 = left, 1 = right). Only meaningful when GHOSTTY_MODS_SHIFT is set.

Definition at line 78 of file key/event.h.

GHOSTTY_MODS_SUPER

#define GHOSTTY_MODS_SUPER   (1 << 3)

Super/Command/Windows key is pressed.

Definition at line 66 of file key/event.h.

GHOSTTY_MODS_SUPER_SIDE

#define GHOSTTY_MODS_SUPER_SIDE   (1 << 9)

Right super is pressed (0 = left, 1 = right). Only meaningful when GHOSTTY_MODS_SUPER is set.

Definition at line 99 of file key/event.h.