Mouse Encoding

Detailed Description

Utilities for encoding mouse events into terminal escape sequences, supporting X10, UTF-8, SGR, URxvt, and SGR-Pixels mouse protocols.

Basic Usage

1. Create an encoder instance with ghostty_mouse_encoder_new().
2. Configure encoder options with ghostty_mouse_encoder_setopt() or ghostty_mouse_encoder_setopt_from_terminal().
3. For each mouse event:
   • Create a mouse event with ghostty_mouse_event_new().
   • Set event properties (action, button, modifiers, position).
   • Encode with ghostty_mouse_encoder_encode().
   • Free the event with ghostty_mouse_event_free() or reuse it.
4. Free the encoder with ghostty_mouse_encoder_free() when done.

For a complete working example, see example/c-vt-mouse-encode in the repository.

Example

#include <assert.h>
#include <stdio.h>
#include <ghostty/vt.h>
 
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_setopt(encoder, GHOSTTY_MOUSE_ENCODER_OPT_EVENT,
      &(GhosttyMouseTrackingMode){GHOSTTY_MOUSE_TRACKING_NORMAL});
  ghostty_mouse_encoder_setopt(encoder, GHOSTTY_MOUSE_ENCODER_OPT_FORMAT,
      &(GhosttyMouseFormat){GHOSTTY_MOUSE_FORMAT_SGR});
 
  // Set terminal geometry for coordinate mapping
  ghostty_mouse_encoder_setopt(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);
  ghostty_mouse_event_set_action(event, GHOSTTY_MOUSE_ACTION_PRESS);
  ghostty_mouse_event_set_button(event, GHOSTTY_MOUSE_BUTTON_LEFT);
  ghostty_mouse_event_set_position(event,
      (GhosttyMousePosition){.x = 50.0f, .y = 40.0f});
 
  // Encode the mouse event
  char 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;
}

Example: Encoding with Terminal State

When you have a GhosttyTerminal, you can sync its tracking mode and output format into the encoder automatically:

// Create a terminal and feed it some VT data that enables mouse tracking
GhosttyTerminal terminal;
ghostty_terminal_new(NULL, &terminal,
    (GhosttyTerminalOptions){.cols = 80, .rows = 24, .max_scrollback = 0});
 
// Application might write data that enables mouse reporting, etc.
ghostty_terminal_vt_write(terminal, vt_data, vt_len);
 
// Create an encoder and sync its options from the terminal
GhosttyMouseEncoder encoder;
ghostty_mouse_encoder_new(NULL, &encoder);
ghostty_mouse_encoder_setopt_from_terminal(encoder, terminal);
 
// Encode a mouse event using the terminal-derived options
char buf[128];
size_t written = 0;
ghostty_mouse_encoder_encode(encoder, event, buf, sizeof(buf), &written);
 
ghostty_mouse_encoder_free(encoder);
ghostty_terminal_free(terminal);

Typedefs
typedef struct GhosttyMouseEncoder *	GhosttyMouseEncoder
typedef struct GhosttyMouseEvent *	GhosttyMouseEvent

Enumerations
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 }
enum	GhosttyMouseFormat
enum	GhosttyMouseEncoderOption {   GHOSTTY_MOUSE_ENCODER_OPT_EVENT = 0 , GHOSTTY_MOUSE_ENCODER_OPT_FORMAT = 1 , GHOSTTY_MOUSE_ENCODER_OPT_SIZE = 2 , GHOSTTY_MOUSE_ENCODER_OPT_ANY_BUTTON_PRESSED = 3 ,   GHOSTTY_MOUSE_ENCODER_OPT_TRACK_LAST_CELL = 4 }
enum	GhosttyMouseAction { GHOSTTY_MOUSE_ACTION_PRESS = 0 , GHOSTTY_MOUSE_ACTION_RELEASE = 1 , GHOSTTY_MOUSE_ACTION_MOTION = 2 }
enum	GhosttyMouseButton

Functions
GhosttyResult	ghostty_mouse_encoder_new (const GhosttyAllocator *allocator, GhosttyMouseEncoder *encoder)
void	ghostty_mouse_encoder_free (GhosttyMouseEncoder encoder)
void	ghostty_mouse_encoder_setopt (GhosttyMouseEncoder encoder, GhosttyMouseEncoderOption option, const void *value)
void	ghostty_mouse_encoder_setopt_from_terminal (GhosttyMouseEncoder encoder, GhosttyTerminal terminal)
void	ghostty_mouse_encoder_reset (GhosttyMouseEncoder encoder)
GhosttyResult	ghostty_mouse_encoder_encode (GhosttyMouseEncoder encoder, GhosttyMouseEvent event, char *out_buf, size_t out_buf_size, size_t *out_len)
GhosttyResult	ghostty_mouse_event_new (const GhosttyAllocator *allocator, GhosttyMouseEvent *event)
void	ghostty_mouse_event_free (GhosttyMouseEvent event)
void	ghostty_mouse_event_set_action (GhosttyMouseEvent event, GhosttyMouseAction action)
GhosttyMouseAction	ghostty_mouse_event_get_action (GhosttyMouseEvent event)
void	ghostty_mouse_event_set_button (GhosttyMouseEvent event, GhosttyMouseButton button)
void	ghostty_mouse_event_clear_button (GhosttyMouseEvent event)
bool	ghostty_mouse_event_get_button (GhosttyMouseEvent event, GhosttyMouseButton *out_button)
void	ghostty_mouse_event_set_mods (GhosttyMouseEvent event, GhosttyMods mods)
GhosttyMods	ghostty_mouse_event_get_mods (GhosttyMouseEvent event)
void	ghostty_mouse_event_set_position (GhosttyMouseEvent event, GhosttyMousePosition position)
GhosttyMousePosition	ghostty_mouse_event_get_position (GhosttyMouseEvent event)

Data Structures
struct	GhosttyMouseEncoderSize
struct	GhosttyMousePosition

Typedef Documentation

GhosttyMouseEncoder

typedef struct GhosttyMouseEncoder* 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-mouse-encode/src/main.c.

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

GhosttyMouseEvent

typedef struct GhosttyMouseEvent* 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-mouse-encode/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 46 of file mouse/event.h.

GhosttyMouseEncoderOption

enum GhosttyMouseEncoderOption

Mouse encoder option identifiers.

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

Enumerator
GHOSTTY_MOUSE_ENCODER_OPT_EVENT	Mouse tracking mode (value: GhosttyMouseTrackingMode).
GHOSTTY_MOUSE_ENCODER_OPT_FORMAT	Mouse output format (value: GhosttyMouseFormat).
GHOSTTY_MOUSE_ENCODER_OPT_SIZE	Renderer size context (value: GhosttyMouseEncoderSize).
GHOSTTY_MOUSE_ENCODER_OPT_ANY_BUTTON_PRESSED	Whether any mouse button is currently pressed (value: bool).
GHOSTTY_MOUSE_ENCODER_OPT_TRACK_LAST_CELL	Whether to enable motion deduplication by last cell (value: bool).

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

GhosttyMouseFormat

enum GhosttyMouseFormat

Mouse output format.

Examples

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

Definition at line 55 of file mouse/encoder.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-mouse-encode/src/main.c.

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

Function Documentation

ghostty_mouse_encoder_encode()

GhosttyResult ghostty_mouse_encoder_encode	(	GhosttyMouseEncoder	encoder,
		GhosttyMouseEvent	event,
		char *	out_buf,
		size_t	out_buf_size,
		size_t *	out_len )

Encode a mouse event into a terminal escape sequence.

Not all mouse events produce output. In such cases this returns GHOSTTY_SUCCESS with out_len set to 0.

If the output buffer is too small, this returns GHOSTTY_OUT_OF_MEMORY and out_len contains the required size.

Parameters

encoder	The encoder handle, must not be NULL
event	The mouse event to encode, must not be NULL
out_buf	Buffer to write encoded bytes to, or NULL to query required size
out_buf_size	Size of out_buf in bytes
out_len	Pointer to store bytes written (or required bytes on failure)

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY if buffer is too small, or another error code

Examples

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

ghostty_mouse_encoder_free()

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-mouse-encode/src/main.c.

ghostty_mouse_encoder_new()

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

Create a new mouse encoder instance.

Parameters

Memory Management	Pointer to allocator, 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-mouse-encode/src/main.c.

ghostty_mouse_encoder_reset()

void ghostty_mouse_encoder_reset

(

GhosttyMouseEncoder

encoder

)

Reset internal encoder state.

This clears motion deduplication state (last tracked cell).

Parameters

encoder

The encoder handle (may be NULL)

ghostty_mouse_encoder_setopt()

void ghostty_mouse_encoder_setopt	(	GhosttyMouseEncoder	encoder,
		GhosttyMouseEncoderOption	option,
		const void *	value )

Set an option on the mouse encoder.

A null pointer value does nothing. It does not reset to defaults.

Parameters

encoder	The encoder handle, must not be NULL
option	The option to set
value	Pointer to option value (type depends on option)

Examples

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

ghostty_mouse_encoder_setopt_from_terminal()

void ghostty_mouse_encoder_setopt_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 does not modify size or any-button state.

Parameters

encoder	The encoder handle, must not be NULL
Terminal	The terminal handle, must not be NULL

ghostty_mouse_event_clear_button()

void ghostty_mouse_event_clear_button

(

GhosttyMouseEvent

event

)

Clear the event button.

This sets the event button to "none".

Parameters

event

The event handle, must not be NULL

ghostty_mouse_event_free()

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-mouse-encode/src/main.c.

ghostty_mouse_event_get_action()

GhosttyMouseAction ghostty_mouse_event_get_action

(

GhosttyMouseEvent

event

)

Get the event action.

Parameters

event

The event handle, must not be NULL

Returns

The event action

ghostty_mouse_event_get_button()

bool ghostty_mouse_event_get_button	(	GhosttyMouseEvent	event,
		GhosttyMouseButton *	out_button )

Get the event button.

Parameters

event	The event handle, must not be NULL
out_button	Output pointer for the button value (may be NULL)

Returns

true if a button is set, false if no button is set

ghostty_mouse_event_get_mods()

GhosttyMods ghostty_mouse_event_get_mods

(

GhosttyMouseEvent

event

)

Get keyboard modifiers held during the event.

Parameters

event

The event handle, must not be NULL

Returns

Modifier bitmask

ghostty_mouse_event_get_position()

GhosttyMousePosition ghostty_mouse_event_get_position

(

GhosttyMouseEvent

event

)

Get the event position in surface-space pixels.

Parameters

event

The event handle, must not be NULL

Returns

The current event position

ghostty_mouse_event_new()

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

Create a new mouse event instance.

Parameters

Memory Management	Pointer to allocator, or NULL to use the default allocator
event	Pointer to store the created event handle

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

Examples

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

ghostty_mouse_event_set_action()

void ghostty_mouse_event_set_action	(	GhosttyMouseEvent	event,
		GhosttyMouseAction	action )

Set the event action.

Parameters

event	The event handle, must not be NULL
action	The action to set

Examples

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

ghostty_mouse_event_set_button()

void 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, must not be NULL
button	The button to set

Examples

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

ghostty_mouse_event_set_mods()

void ghostty_mouse_event_set_mods	(	GhosttyMouseEvent	event,
		GhosttyMods	mods )

Set keyboard modifiers held during the event.

Parameters

event	The event handle, must not be NULL
mods	Modifier bitmask

ghostty_mouse_event_set_position()

void ghostty_mouse_event_set_position	(	GhosttyMouseEvent	event,
		GhosttyMousePosition	position )

Set the event position in surface-space pixels.

Parameters

event	The event handle, must not be NULL
position	The position to set

Examples

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