Mouse

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, must not be NULL
	event	The mouse 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 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

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, must not be NULL
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. Must not be NULL.

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

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.