Encode mouse events with the X10, UTF-8, SGR, URxvt, or SGR-Pixels protocols. More...

Detailed Description

Encode mouse events with the X10, UTF-8, SGR, URxvt, or SGR-Pixels protocols.

Encode mouse events into terminal escape sequences, in the X10, UTF-8, SGR, URxvt, and SGR-Pixels formats.

An encoder has to follow the terminal's modes. If you have a terminal, call ghostty_mouse_encoder_set_from_terminal() before you encode.

Example

int main() {
  // Create encoder
  GhosttyMouseEncoder encoder;
  GhosttyResult result = ghostty_mouse_encoder_new(NULL, &encoder);
  assert(result == GHOSTTY_SUCCESS);
 
  // Configure SGR format with normal tracking
  ghostty_mouse_encoder_set(encoder, GHOSTTY_MOUSE_ENCODER_OPT_EVENT,
      &(GhosttyMouseTrackingMode){GHOSTTY_MOUSE_TRACKING_NORMAL});
  ghostty_mouse_encoder_set(encoder, GHOSTTY_MOUSE_ENCODER_OPT_FORMAT,
      &(GhosttyMouseFormat){GHOSTTY_MOUSE_FORMAT_SGR});
 
  // Set terminal geometry for coordinate mapping
  ghostty_mouse_encoder_set(encoder, GHOSTTY_MOUSE_ENCODER_OPT_SIZE,
      &(GhosttyMouseEncoderSize){
          .size = sizeof(GhosttyMouseEncoderSize),
          .screen_width = 800, .screen_height = 600,
          .cell_width = 10, .cell_height = 20,
      });
 
  // Create and configure a left button press event
  GhosttyMouseEvent event;
  result = ghostty_mouse_event_new(NULL, &event);
  assert(result == GHOSTTY_SUCCESS);
  result = ghostty_mouse_event_set_action(event, GHOSTTY_MOUSE_ACTION_PRESS);
  assert(result == GHOSTTY_SUCCESS);
  result = ghostty_mouse_event_set_button(event, GHOSTTY_MOUSE_BUTTON_LEFT);
  assert(result == GHOSTTY_SUCCESS);
  result = ghostty_mouse_event_set_position(event,
      (GhosttyMousePosition){.x = 50.0f, .y = 40.0f});
  assert(result == GHOSTTY_SUCCESS);
 
  // Encode the mouse event
  uint8_t buf[128];
  size_t written = 0;
  result = ghostty_mouse_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_mouse_event_free(event);
  ghostty_mouse_encoder_free(encoder);
  return 0;
}

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

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

Typedefs
typedef struct GhosttyMouseEncoderImpl *	GhosttyMouseEncoder
typedef struct GhosttyMouseEventImpl *	GhosttyMouseEvent

Enumerations
enum	GhosttyMouseShape
enum	GhosttyMouseTrackingMode { GHOSTTY_MOUSE_TRACKING_NONE = 0 , GHOSTTY_MOUSE_TRACKING_X10 = 1 , GHOSTTY_MOUSE_TRACKING_NORMAL = 2 , GHOSTTY_MOUSE_TRACKING_BUTTON = 3 , GHOSTTY_MOUSE_TRACKING_ANY = 4 , GHOSTTY_MOUSE_TRACKING_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyMouseFormat
enum	GhosttyMouseEncoderOption { GHOSTTY_MOUSE_ENCODER_OPT_INVALID = 0 , GHOSTTY_MOUSE_ENCODER_OPT_EVENT = 1 , GHOSTTY_MOUSE_ENCODER_OPT_FORMAT = 2 , GHOSTTY_MOUSE_ENCODER_OPT_SIZE = 3 , GHOSTTY_MOUSE_ENCODER_OPT_ANY_BUTTON_PRESSED = 4 , GHOSTTY_MOUSE_ENCODER_OPT_TRACK_LAST_CELL = 5 , GHOSTTY_MOUSE_ENCODER_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyMouseAction { GHOSTTY_MOUSE_ACTION_PRESS = 0 , GHOSTTY_MOUSE_ACTION_RELEASE = 1 , GHOSTTY_MOUSE_ACTION_MOTION = 2 , GHOSTTY_MOUSE_ACTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyMouseButton

Functions
GHOSTTY_API GhosttyResult	ghostty_mouse_encoder_new (const GhosttyAllocator allocator, GhosttyMouseEncoder encoder)
GHOSTTY_API void	ghostty_mouse_encoder_free (GhosttyMouseEncoder encoder)
GHOSTTY_API GhosttyResult	ghostty_mouse_encoder_set (GhosttyMouseEncoder encoder, GhosttyMouseEncoderOption option, const void *value)
GHOSTTY_API GhosttyResult	ghostty_mouse_encoder_set_from_terminal (GhosttyMouseEncoder encoder, GhosttyTerminal terminal)
GHOSTTY_API GhosttyResult	ghostty_mouse_encoder_reset (GhosttyMouseEncoder encoder)
GHOSTTY_API GhosttyResult	ghostty_mouse_encoder_encode (GhosttyMouseEncoder encoder, GhosttyMouseEvent event, uint8_t buf, size_t buf_len, size_t out_written)
GHOSTTY_API GhosttyResult	ghostty_mouse_event_new (const GhosttyAllocator allocator, GhosttyMouseEvent event)
GHOSTTY_API void	ghostty_mouse_event_free (GhosttyMouseEvent event)
GHOSTTY_API GhosttyResult	ghostty_mouse_event_set_action (GhosttyMouseEvent event, GhosttyMouseAction action)
GHOSTTY_API GhosttyMouseAction	ghostty_mouse_event_get_action (GhosttyMouseEvent event)
GHOSTTY_API GhosttyResult	ghostty_mouse_event_set_button (GhosttyMouseEvent event, GhosttyMouseButton button)
GHOSTTY_API GhosttyResult	ghostty_mouse_event_clear_button (GhosttyMouseEvent event)
GHOSTTY_API GhosttyResult	ghostty_mouse_event_get_button (GhosttyMouseEvent event, GhosttyMouseButton *out_button)
GHOSTTY_API GhosttyResult	ghostty_mouse_event_set_mods (GhosttyMouseEvent event, GhosttyMods mods)
GHOSTTY_API GhosttyMods	ghostty_mouse_event_get_mods (GhosttyMouseEvent event)
GHOSTTY_API GhosttyResult	ghostty_mouse_event_set_position (GhosttyMouseEvent event, GhosttyMousePosition position)
GHOSTTY_API GhosttyMousePosition	ghostty_mouse_event_get_position (GhosttyMouseEvent event)

Data Structures
struct	GhosttyMouseEncoderSize
struct	GhosttyMousePosition

Typedef Documentation

◆ GhosttyMouseEncoder

typedef struct GhosttyMouseEncoderImpl* GhosttyMouseEncoder

Opaque handle to a mouse encoder instance.

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

Examples: c-vt-encode-mouse/src/main.c.

Definition at line 26 of file mouse/encoder.h.

◆ GhosttyMouseEvent

typedef struct GhosttyMouseEventImpl* GhosttyMouseEvent

Opaque handle to a mouse event.

This handle represents a normalized mouse input event containing action, button, modifiers, and surface-space position.

Examples: c-vt-encode-mouse/src/main.c.

Definition at line 23 of file mouse/event.h.

Enumeration Type Documentation

◆ GhosttyMouseAction

enum GhosttyMouseAction

Mouse event action type.

Enumerator
GHOSTTY_MOUSE_ACTION_PRESS	Mouse button was pressed.
GHOSTTY_MOUSE_ACTION_RELEASE	Mouse button was released.
GHOSTTY_MOUSE_ACTION_MOTION	Mouse moved.

Definition at line 30 of file mouse/event.h.

◆ GhosttyMouseButton

enum GhosttyMouseButton

Mouse button identity.

Definition at line 47 of file mouse/event.h.

◆ GhosttyMouseEncoderOption

enum GhosttyMouseEncoderOption

Mouse encoder option identifiers.

These values are used with ghostty_mouse_encoder_set() to configure the behavior of the mouse encoder.

Enumerator
GHOSTTY_MOUSE_ENCODER_OPT_INVALID	Not a real option. ghostty_mouse_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_MOUSE_ENCODER_OPT_EVENT	Mouse tracking mode (value: GhosttyMouseTrackingMode, default: GHOSTTY_MOUSE_TRACKING_NONE).
GHOSTTY_MOUSE_ENCODER_OPT_FORMAT	Mouse output format (value: GhosttyMouseFormat, default: GHOSTTY_MOUSE_FORMAT_X10).
GHOSTTY_MOUSE_ENCODER_OPT_SIZE	Renderer size context (value: GhosttyMouseEncoderSize, default: a 1x1 pixel screen with 1x1 pixel cells and no padding).
GHOSTTY_MOUSE_ENCODER_OPT_ANY_BUTTON_PRESSED	Whether any mouse button is currently pressed (value: bool, default: false).
GHOSTTY_MOUSE_ENCODER_OPT_TRACK_LAST_CELL	Whether to enable motion deduplication by last cell (value: bool, default: false).

Definition at line 113 of file mouse/encoder.h.

◆ GhosttyMouseFormat

enum GhosttyMouseFormat

Mouse output format.

Examples: c-vt-encode-mouse/src/main.c.

Definition at line 56 of file mouse/encoder.h.

◆ GhosttyMouseShape

enum GhosttyMouseShape

Mouse pointer shapes based on the W3C cursor names.

Hosts map these values to their native pointer shapes; not every platform supports every shape. These are pointer shapes, not terminal text cursors.

Definition at line 42 of file mouse.h.

◆ GhosttyMouseTrackingMode

enum GhosttyMouseTrackingMode

Mouse tracking mode.

Enumerator
GHOSTTY_MOUSE_TRACKING_NONE	Mouse reporting disabled.
GHOSTTY_MOUSE_TRACKING_X10	X10 mouse mode.
GHOSTTY_MOUSE_TRACKING_NORMAL	Normal mouse mode (button press/release only).
GHOSTTY_MOUSE_TRACKING_BUTTON	Button-event tracking mode.
GHOSTTY_MOUSE_TRACKING_ANY	Any-event tracking mode.

Examples: c-vt-encode-mouse/src/main.c.

Definition at line 33 of file mouse/encoder.h.

Function Documentation

◆ ghostty_mouse_encoder_encode()

GHOSTTY_API GhosttyResult ghostty_mouse_encoder_encode	(	GhosttyMouseEncoder	encoder,
		GhosttyMouseEvent	event,
		uint8_t *	buf,
		size_t	buf_len,
		size_t *	out_written )

Encode a mouse event into a terminal escape sequence.

Not all mouse events produce output. In such cases 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.

A 128-byte buffer is enough for typical events:

uint8_t buf[128];
size_t written = 0;
if (ghostty_mouse_encoder_encode(encoder, event, buf, sizeof(buf),
                                 &written) == GHOSTTY_SUCCESS &&
    written > 0) {
  write(pty_fd, buf, written);
}

Parameters

	encoder	The encoder handle (NULL returns GHOSTTY_INVALID_VALUE)
	event	The mouse event to encode (NULL returns GHOSTTY_INVALID_VALUE)
	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. NULL returns GHOSTTY_INVALID_VALUE.

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if buffer is too small, or another error code

Examples: c-vt-encode-mouse/src/main.c.

◆ ghostty_mouse_encoder_free()

GHOSTTY_API void ghostty_mouse_encoder_free ( GhosttyMouseEncoder encoder )

Free a mouse encoder instance.

Parameters

encoder The encoder handle to free (may be NULL)

Examples: c-vt-encode-mouse/src/main.c.

◆ ghostty_mouse_encoder_new()

GHOSTTY_API GhosttyResult ghostty_mouse_encoder_new	(	const GhosttyAllocator *	allocator,
		GhosttyMouseEncoder *	encoder )

Create a new mouse encoder instance.

Parameters

allocator	Pointer to allocator, or NULL to use the default allocator
encoder	Pointer to store the created encoder handle (NULL returns GHOSTTY_INVALID_VALUE)

Returns: GHOSTTY_SUCCESS on success, or an error code on failure

Examples: c-vt-encode-mouse/src/main.c.

◆ ghostty_mouse_encoder_reset()

GHOSTTY_API GhosttyResult ghostty_mouse_encoder_reset ( GhosttyMouseEncoder encoder )

Reset internal encoder state.

This clears motion deduplication state (last tracked cell).

Parameters

encoder The encoder handle

Returns: GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if encoder is NULL.

◆ ghostty_mouse_encoder_set()

GHOSTTY_API GhosttyResult ghostty_mouse_encoder_set	(	GhosttyMouseEncoder	encoder,
		GhosttyMouseEncoderOption	option,
		const void *	value )

Set an option on the mouse encoder.

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 GhosttyMouseEncoderOption.

GhosttyMouseFormat format = GHOSTTY_MOUSE_FORMAT_SGR;
GhosttyResult result = ghostty_mouse_encoder_set(
    encoder, GHOSTTY_MOUSE_ENCODER_OPT_FORMAT, &format);

Parameters

encoder	The encoder handle (NULL returns GHOSTTY_INVALID_VALUE)
option	The option to set
value	Pointer to option value (type depends on 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 not valid (an unknown tracking mode or format, or a size that is too small or has a zero cell dimension), or GHOSTTY_UNSUPPORTED if option is not known to this version of the library

Examples: c-vt-encode-mouse/src/main.c.

◆ ghostty_mouse_encoder_set_from_terminal()

GHOSTTY_API GhosttyResult ghostty_mouse_encoder_set_from_terminal	(	GhosttyMouseEncoder	encoder,
		GhosttyTerminal	terminal )

Set encoder options from a terminal's current state.

This sets tracking mode and output format from terminal state. It also clears the last-cell state, as ghostty_mouse_encoder_reset() does, so the next motion event isn't dropped as a repeat of the last cell. It does not modify size or any-button state.

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_mouse_event_clear_button()

GHOSTTY_API GhosttyResult ghostty_mouse_event_clear_button ( GhosttyMouseEvent event )

Clear the event button.

This sets the event button to "none".

Parameters

event The event handle

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

◆ ghostty_mouse_event_free()

GHOSTTY_API void ghostty_mouse_event_free ( GhosttyMouseEvent event )

Free a mouse event instance.

Parameters

event The mouse event handle to free (may be NULL)

Examples: c-vt-encode-mouse/src/main.c.

◆ ghostty_mouse_event_get_action()

GHOSTTY_API GhosttyMouseAction ghostty_mouse_event_get_action ( GhosttyMouseEvent event )

Get the event action.

Parameters

event The event handle

Returns: The event action, or GHOSTTY_MOUSE_ACTION_PRESS if event is NULL

◆ ghostty_mouse_event_get_button()

GHOSTTY_API GhosttyResult ghostty_mouse_event_get_button	(	GhosttyMouseEvent	event,
		GhosttyMouseButton *	out_button )

Get the event button.

A new event has no button, and ghostty_mouse_event_clear_button() removes the button from an event. Having no button is normal, for example when the mouse moves with no button held. It is not an error, so check for GHOSTTY_NO_VALUE separately:

GhosttyMouseButton button;
switch (ghostty_mouse_event_get_button(event, &button)) {
case GHOSTTY_SUCCESS:
    // `button` holds the event's button.
    break;
case GHOSTTY_NO_VALUE:
    // The event has no button. `button` was not written.
    break;
default:
    // `event` or the output pointer was NULL.
    break;
}

Parameters

event	The event handle
out_button	Where to write the button. NULL returns GHOSTTY_INVALID_VALUE.

Returns: GHOSTTY_SUCCESS if the event has a button, GHOSTTY_NO_VALUE if it has none, or GHOSTTY_INVALID_VALUE if event or out_button is NULL. out_button is written only on GHOSTTY_SUCCESS.

◆ ghostty_mouse_event_get_mods()

GHOSTTY_API GhosttyMods ghostty_mouse_event_get_mods ( GhosttyMouseEvent event )

Get keyboard modifiers held during the event.

Parameters

event The event handle

Returns: Modifier bitmask, or 0 (no modifiers) if event is NULL

◆ ghostty_mouse_event_get_position()

GHOSTTY_API GhosttyMousePosition ghostty_mouse_event_get_position ( GhosttyMouseEvent event )

Get the event position in surface-space pixels.

Parameters

event The event handle

Returns: The current event position, or (0, 0) if event is NULL

◆ ghostty_mouse_event_new()

GHOSTTY_API GhosttyResult ghostty_mouse_event_new	(	const GhosttyAllocator *	allocator,
		GhosttyMouseEvent *	event )

Create a new mouse event instance.

Parameters

allocator	Pointer to allocator, or NULL to use the default allocator
event	Pointer to store the created event handle (NULL returns GHOSTTY_INVALID_VALUE)

Returns: GHOSTTY_SUCCESS on success, or an error code on failure

Examples: c-vt-encode-mouse/src/main.c.

◆ ghostty_mouse_event_set_action()

GHOSTTY_API GhosttyResult ghostty_mouse_event_set_action	(	GhosttyMouseEvent	event,
		GhosttyMouseAction	action )

Set the event action.

Parameters

event	The 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 GhosttyMouseAction value this version of the library knows. On error the event is not changed.

Examples: c-vt-encode-mouse/src/main.c.

◆ ghostty_mouse_event_set_button()

GHOSTTY_API GhosttyResult ghostty_mouse_event_set_button	(	GhosttyMouseEvent	event,
		GhosttyMouseButton	button )

Set the event button.

This sets a concrete button identity for the event. To represent "no button" (for motion events), use ghostty_mouse_event_clear_button().

Parameters

event	The event handle
button	The button to set

Returns: GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if event is NULL or button is not a GhosttyMouseButton value this version of the library knows. On error the event is not changed.

Examples: c-vt-encode-mouse/src/main.c.

◆ ghostty_mouse_event_set_mods()

GHOSTTY_API GhosttyResult ghostty_mouse_event_set_mods	(	GhosttyMouseEvent	event,
		GhosttyMods	mods )

Set keyboard modifiers held during the event.

Parameters

event	The event handle
mods	Modifier bitmask

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

◆ ghostty_mouse_event_set_position()

GHOSTTY_API GhosttyResult ghostty_mouse_event_set_position	(	GhosttyMouseEvent	event,
		GhosttyMousePosition	position )

Set the event position in surface-space pixels.

Parameters

event	The event handle
position	The position 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-mouse/src/main.c.

Detailed Description

Example

Typedefs

Enumerations

Functions

Data Structures

Typedef Documentation

◆ GhosttyMouseEncoder

◆ GhosttyMouseEvent

Enumeration Type Documentation

◆ GhosttyMouseAction

◆ GhosttyMouseButton

◆ GhosttyMouseEncoderOption

◆ GhosttyMouseFormat

◆ GhosttyMouseShape

◆ GhosttyMouseTrackingMode

Function Documentation

◆ ghostty_mouse_encoder_encode()

◆ ghostty_mouse_encoder_free()

◆ ghostty_mouse_encoder_new()

◆ ghostty_mouse_encoder_reset()

◆ ghostty_mouse_encoder_set()

◆ ghostty_mouse_encoder_set_from_terminal()

◆ ghostty_mouse_event_clear_button()

◆ ghostty_mouse_event_free()

◆ ghostty_mouse_event_get_action()

◆ ghostty_mouse_event_get_button()

◆ ghostty_mouse_event_get_mods()

◆ ghostty_mouse_event_get_position()

◆ ghostty_mouse_event_new()

◆ ghostty_mouse_event_set_action()

◆ ghostty_mouse_event_set_button()

◆ ghostty_mouse_event_set_mods()

◆ ghostty_mouse_event_set_position()