475 lines
12 KiB
C
475 lines
12 KiB
C
/**
|
|
* @file event.h
|
|
*
|
|
* Key event representation and manipulation.
|
|
*/
|
|
|
|
#ifndef GHOSTTY_VT_KEY_EVENT_H
|
|
#define GHOSTTY_VT_KEY_EVENT_H
|
|
|
|
#include <stdbool.h>
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
#include <ghostty/vt/result.h>
|
|
#include <ghostty/vt/allocator.h>
|
|
|
|
/**
|
|
* Opaque handle to a key event.
|
|
*
|
|
* This handle represents a keyboard input event containing information about
|
|
* the physical key pressed, modifiers, and generated text.
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
typedef struct GhosttyKeyEvent *GhosttyKeyEvent;
|
|
|
|
/**
|
|
* Keyboard input event types.
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
typedef enum {
|
|
/** Key was released */
|
|
GHOSTTY_KEY_ACTION_RELEASE = 0,
|
|
/** Key was pressed */
|
|
GHOSTTY_KEY_ACTION_PRESS = 1,
|
|
/** Key is being repeated (held down) */
|
|
GHOSTTY_KEY_ACTION_REPEAT = 2,
|
|
} GhosttyKeyAction;
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
typedef uint16_t GhosttyMods;
|
|
|
|
/** Shift key is pressed */
|
|
#define GHOSTTY_MODS_SHIFT (1 << 0)
|
|
/** Control key is pressed */
|
|
#define GHOSTTY_MODS_CTRL (1 << 1)
|
|
/** Alt/Option key is pressed */
|
|
#define GHOSTTY_MODS_ALT (1 << 2)
|
|
/** Super/Command/Windows key is pressed */
|
|
#define GHOSTTY_MODS_SUPER (1 << 3)
|
|
/** Caps Lock is active */
|
|
#define GHOSTTY_MODS_CAPS_LOCK (1 << 4)
|
|
/** Num Lock is active */
|
|
#define GHOSTTY_MODS_NUM_LOCK (1 << 5)
|
|
|
|
/**
|
|
* Right shift is pressed (0 = left, 1 = right).
|
|
* Only meaningful when GHOSTTY_MODS_SHIFT is set.
|
|
*/
|
|
#define GHOSTTY_MODS_SHIFT_SIDE (1 << 6)
|
|
/**
|
|
* Right ctrl is pressed (0 = left, 1 = right).
|
|
* Only meaningful when GHOSTTY_MODS_CTRL is set.
|
|
*/
|
|
#define GHOSTTY_MODS_CTRL_SIDE (1 << 7)
|
|
/**
|
|
* Right alt is pressed (0 = left, 1 = right).
|
|
* Only meaningful when GHOSTTY_MODS_ALT is set.
|
|
*/
|
|
#define GHOSTTY_MODS_ALT_SIDE (1 << 8)
|
|
/**
|
|
* Right super is pressed (0 = left, 1 = right).
|
|
* Only meaningful when GHOSTTY_MODS_SUPER is set.
|
|
*/
|
|
#define GHOSTTY_MODS_SUPER_SIDE (1 << 9)
|
|
|
|
/**
|
|
* 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
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
typedef enum {
|
|
GHOSTTY_KEY_UNIDENTIFIED = 0,
|
|
|
|
// Writing System Keys (W3C § 3.1.1)
|
|
GHOSTTY_KEY_BACKQUOTE,
|
|
GHOSTTY_KEY_BACKSLASH,
|
|
GHOSTTY_KEY_BRACKET_LEFT,
|
|
GHOSTTY_KEY_BRACKET_RIGHT,
|
|
GHOSTTY_KEY_COMMA,
|
|
GHOSTTY_KEY_DIGIT_0,
|
|
GHOSTTY_KEY_DIGIT_1,
|
|
GHOSTTY_KEY_DIGIT_2,
|
|
GHOSTTY_KEY_DIGIT_3,
|
|
GHOSTTY_KEY_DIGIT_4,
|
|
GHOSTTY_KEY_DIGIT_5,
|
|
GHOSTTY_KEY_DIGIT_6,
|
|
GHOSTTY_KEY_DIGIT_7,
|
|
GHOSTTY_KEY_DIGIT_8,
|
|
GHOSTTY_KEY_DIGIT_9,
|
|
GHOSTTY_KEY_EQUAL,
|
|
GHOSTTY_KEY_INTL_BACKSLASH,
|
|
GHOSTTY_KEY_INTL_RO,
|
|
GHOSTTY_KEY_INTL_YEN,
|
|
GHOSTTY_KEY_A,
|
|
GHOSTTY_KEY_B,
|
|
GHOSTTY_KEY_C,
|
|
GHOSTTY_KEY_D,
|
|
GHOSTTY_KEY_E,
|
|
GHOSTTY_KEY_F,
|
|
GHOSTTY_KEY_G,
|
|
GHOSTTY_KEY_H,
|
|
GHOSTTY_KEY_I,
|
|
GHOSTTY_KEY_J,
|
|
GHOSTTY_KEY_K,
|
|
GHOSTTY_KEY_L,
|
|
GHOSTTY_KEY_M,
|
|
GHOSTTY_KEY_N,
|
|
GHOSTTY_KEY_O,
|
|
GHOSTTY_KEY_P,
|
|
GHOSTTY_KEY_Q,
|
|
GHOSTTY_KEY_R,
|
|
GHOSTTY_KEY_S,
|
|
GHOSTTY_KEY_T,
|
|
GHOSTTY_KEY_U,
|
|
GHOSTTY_KEY_V,
|
|
GHOSTTY_KEY_W,
|
|
GHOSTTY_KEY_X,
|
|
GHOSTTY_KEY_Y,
|
|
GHOSTTY_KEY_Z,
|
|
GHOSTTY_KEY_MINUS,
|
|
GHOSTTY_KEY_PERIOD,
|
|
GHOSTTY_KEY_QUOTE,
|
|
GHOSTTY_KEY_SEMICOLON,
|
|
GHOSTTY_KEY_SLASH,
|
|
|
|
// Functional Keys (W3C § 3.1.2)
|
|
GHOSTTY_KEY_ALT_LEFT,
|
|
GHOSTTY_KEY_ALT_RIGHT,
|
|
GHOSTTY_KEY_BACKSPACE,
|
|
GHOSTTY_KEY_CAPS_LOCK,
|
|
GHOSTTY_KEY_CONTEXT_MENU,
|
|
GHOSTTY_KEY_CONTROL_LEFT,
|
|
GHOSTTY_KEY_CONTROL_RIGHT,
|
|
GHOSTTY_KEY_ENTER,
|
|
GHOSTTY_KEY_META_LEFT,
|
|
GHOSTTY_KEY_META_RIGHT,
|
|
GHOSTTY_KEY_SHIFT_LEFT,
|
|
GHOSTTY_KEY_SHIFT_RIGHT,
|
|
GHOSTTY_KEY_SPACE,
|
|
GHOSTTY_KEY_TAB,
|
|
GHOSTTY_KEY_CONVERT,
|
|
GHOSTTY_KEY_KANA_MODE,
|
|
GHOSTTY_KEY_NON_CONVERT,
|
|
|
|
// Control Pad Section (W3C § 3.2)
|
|
GHOSTTY_KEY_DELETE,
|
|
GHOSTTY_KEY_END,
|
|
GHOSTTY_KEY_HELP,
|
|
GHOSTTY_KEY_HOME,
|
|
GHOSTTY_KEY_INSERT,
|
|
GHOSTTY_KEY_PAGE_DOWN,
|
|
GHOSTTY_KEY_PAGE_UP,
|
|
|
|
// Arrow Pad Section (W3C § 3.3)
|
|
GHOSTTY_KEY_ARROW_DOWN,
|
|
GHOSTTY_KEY_ARROW_LEFT,
|
|
GHOSTTY_KEY_ARROW_RIGHT,
|
|
GHOSTTY_KEY_ARROW_UP,
|
|
|
|
// Numpad Section (W3C § 3.4)
|
|
GHOSTTY_KEY_NUM_LOCK,
|
|
GHOSTTY_KEY_NUMPAD_0,
|
|
GHOSTTY_KEY_NUMPAD_1,
|
|
GHOSTTY_KEY_NUMPAD_2,
|
|
GHOSTTY_KEY_NUMPAD_3,
|
|
GHOSTTY_KEY_NUMPAD_4,
|
|
GHOSTTY_KEY_NUMPAD_5,
|
|
GHOSTTY_KEY_NUMPAD_6,
|
|
GHOSTTY_KEY_NUMPAD_7,
|
|
GHOSTTY_KEY_NUMPAD_8,
|
|
GHOSTTY_KEY_NUMPAD_9,
|
|
GHOSTTY_KEY_NUMPAD_ADD,
|
|
GHOSTTY_KEY_NUMPAD_BACKSPACE,
|
|
GHOSTTY_KEY_NUMPAD_CLEAR,
|
|
GHOSTTY_KEY_NUMPAD_CLEAR_ENTRY,
|
|
GHOSTTY_KEY_NUMPAD_COMMA,
|
|
GHOSTTY_KEY_NUMPAD_DECIMAL,
|
|
GHOSTTY_KEY_NUMPAD_DIVIDE,
|
|
GHOSTTY_KEY_NUMPAD_ENTER,
|
|
GHOSTTY_KEY_NUMPAD_EQUAL,
|
|
GHOSTTY_KEY_NUMPAD_MEMORY_ADD,
|
|
GHOSTTY_KEY_NUMPAD_MEMORY_CLEAR,
|
|
GHOSTTY_KEY_NUMPAD_MEMORY_RECALL,
|
|
GHOSTTY_KEY_NUMPAD_MEMORY_STORE,
|
|
GHOSTTY_KEY_NUMPAD_MEMORY_SUBTRACT,
|
|
GHOSTTY_KEY_NUMPAD_MULTIPLY,
|
|
GHOSTTY_KEY_NUMPAD_PAREN_LEFT,
|
|
GHOSTTY_KEY_NUMPAD_PAREN_RIGHT,
|
|
GHOSTTY_KEY_NUMPAD_SUBTRACT,
|
|
GHOSTTY_KEY_NUMPAD_SEPARATOR,
|
|
GHOSTTY_KEY_NUMPAD_UP,
|
|
GHOSTTY_KEY_NUMPAD_DOWN,
|
|
GHOSTTY_KEY_NUMPAD_RIGHT,
|
|
GHOSTTY_KEY_NUMPAD_LEFT,
|
|
GHOSTTY_KEY_NUMPAD_BEGIN,
|
|
GHOSTTY_KEY_NUMPAD_HOME,
|
|
GHOSTTY_KEY_NUMPAD_END,
|
|
GHOSTTY_KEY_NUMPAD_INSERT,
|
|
GHOSTTY_KEY_NUMPAD_DELETE,
|
|
GHOSTTY_KEY_NUMPAD_PAGE_UP,
|
|
GHOSTTY_KEY_NUMPAD_PAGE_DOWN,
|
|
|
|
// Function Section (W3C § 3.5)
|
|
GHOSTTY_KEY_ESCAPE,
|
|
GHOSTTY_KEY_F1,
|
|
GHOSTTY_KEY_F2,
|
|
GHOSTTY_KEY_F3,
|
|
GHOSTTY_KEY_F4,
|
|
GHOSTTY_KEY_F5,
|
|
GHOSTTY_KEY_F6,
|
|
GHOSTTY_KEY_F7,
|
|
GHOSTTY_KEY_F8,
|
|
GHOSTTY_KEY_F9,
|
|
GHOSTTY_KEY_F10,
|
|
GHOSTTY_KEY_F11,
|
|
GHOSTTY_KEY_F12,
|
|
GHOSTTY_KEY_F13,
|
|
GHOSTTY_KEY_F14,
|
|
GHOSTTY_KEY_F15,
|
|
GHOSTTY_KEY_F16,
|
|
GHOSTTY_KEY_F17,
|
|
GHOSTTY_KEY_F18,
|
|
GHOSTTY_KEY_F19,
|
|
GHOSTTY_KEY_F20,
|
|
GHOSTTY_KEY_F21,
|
|
GHOSTTY_KEY_F22,
|
|
GHOSTTY_KEY_F23,
|
|
GHOSTTY_KEY_F24,
|
|
GHOSTTY_KEY_F25,
|
|
GHOSTTY_KEY_FN,
|
|
GHOSTTY_KEY_FN_LOCK,
|
|
GHOSTTY_KEY_PRINT_SCREEN,
|
|
GHOSTTY_KEY_SCROLL_LOCK,
|
|
GHOSTTY_KEY_PAUSE,
|
|
|
|
// Media Keys (W3C § 3.6)
|
|
GHOSTTY_KEY_BROWSER_BACK,
|
|
GHOSTTY_KEY_BROWSER_FAVORITES,
|
|
GHOSTTY_KEY_BROWSER_FORWARD,
|
|
GHOSTTY_KEY_BROWSER_HOME,
|
|
GHOSTTY_KEY_BROWSER_REFRESH,
|
|
GHOSTTY_KEY_BROWSER_SEARCH,
|
|
GHOSTTY_KEY_BROWSER_STOP,
|
|
GHOSTTY_KEY_EJECT,
|
|
GHOSTTY_KEY_LAUNCH_APP_1,
|
|
GHOSTTY_KEY_LAUNCH_APP_2,
|
|
GHOSTTY_KEY_LAUNCH_MAIL,
|
|
GHOSTTY_KEY_MEDIA_PLAY_PAUSE,
|
|
GHOSTTY_KEY_MEDIA_SELECT,
|
|
GHOSTTY_KEY_MEDIA_STOP,
|
|
GHOSTTY_KEY_MEDIA_TRACK_NEXT,
|
|
GHOSTTY_KEY_MEDIA_TRACK_PREVIOUS,
|
|
GHOSTTY_KEY_POWER,
|
|
GHOSTTY_KEY_SLEEP,
|
|
GHOSTTY_KEY_AUDIO_VOLUME_DOWN,
|
|
GHOSTTY_KEY_AUDIO_VOLUME_MUTE,
|
|
GHOSTTY_KEY_AUDIO_VOLUME_UP,
|
|
GHOSTTY_KEY_WAKE_UP,
|
|
|
|
// Legacy, Non-standard, and Special Keys (W3C § 3.7)
|
|
GHOSTTY_KEY_COPY,
|
|
GHOSTTY_KEY_CUT,
|
|
GHOSTTY_KEY_PASTE,
|
|
} GhosttyKey;
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param allocator Pointer to the allocator to use for memory management, or NULL to use the default allocator
|
|
* @param event Pointer to store the created key event handle
|
|
* @return GHOSTTY_SUCCESS on success, or an error code on failure
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
GhosttyResult ghostty_key_event_new(const GhosttyAllocator *allocator, 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.
|
|
*
|
|
* @param event The key event handle to free (may be NULL)
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
void ghostty_key_event_free(GhosttyKeyEvent event);
|
|
|
|
/**
|
|
* Set the key action (press, release, repeat).
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @param action The action to set
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
void ghostty_key_event_set_action(GhosttyKeyEvent event, GhosttyKeyAction action);
|
|
|
|
/**
|
|
* Get the key action (press, release, repeat).
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @return The key action
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
GhosttyKeyAction ghostty_key_event_get_action(GhosttyKeyEvent event);
|
|
|
|
/**
|
|
* Set the physical key code.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @param key The physical key code to set
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
void ghostty_key_event_set_key(GhosttyKeyEvent event, GhosttyKey key);
|
|
|
|
/**
|
|
* Get the physical key code.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @return The physical key code
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
GhosttyKey ghostty_key_event_get_key(GhosttyKeyEvent event);
|
|
|
|
/**
|
|
* Set the modifier keys bitmask.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @param mods The modifier keys bitmask to set
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
void ghostty_key_event_set_mods(GhosttyKeyEvent event, GhosttyMods mods);
|
|
|
|
/**
|
|
* Get the modifier keys bitmask.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @return The modifier keys bitmask
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
GhosttyMods ghostty_key_event_get_mods(GhosttyKeyEvent event);
|
|
|
|
/**
|
|
* Set the consumed modifiers bitmask.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @param consumed_mods The consumed modifiers bitmask to set
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
void ghostty_key_event_set_consumed_mods(GhosttyKeyEvent event, GhosttyMods consumed_mods);
|
|
|
|
/**
|
|
* Get the consumed modifiers bitmask.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @return The consumed modifiers bitmask
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
GhosttyMods ghostty_key_event_get_consumed_mods(GhosttyKeyEvent event);
|
|
|
|
/**
|
|
* Set whether the key event is part of a composition sequence.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @param composing Whether the key event is part of a composition sequence
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
void ghostty_key_event_set_composing(GhosttyKeyEvent event, bool composing);
|
|
|
|
/**
|
|
* Get whether the key event is part of a composition sequence.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @return Whether the key event is part of a composition sequence
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
bool ghostty_key_event_get_composing(GhosttyKeyEvent event);
|
|
|
|
/**
|
|
* Set the UTF-8 text generated by the key event.
|
|
*
|
|
* The key event does NOT take ownership of the text pointer. The caller
|
|
* must ensure the string remains valid for the lifetime needed by the event.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @param utf8 The UTF-8 text to set (or NULL for empty)
|
|
* @param len Length of the UTF-8 text in bytes
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
void ghostty_key_event_set_utf8(GhosttyKeyEvent event, const char *utf8, size_t len);
|
|
|
|
/**
|
|
* Get the UTF-8 text generated by the key event.
|
|
*
|
|
* The returned pointer is valid until the event is freed or the UTF-8 text is modified.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @param len Pointer to store the length of the UTF-8 text in bytes (may be NULL)
|
|
* @return The UTF-8 text (or NULL for empty)
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
const char *ghostty_key_event_get_utf8(GhosttyKeyEvent event, size_t *len);
|
|
|
|
/**
|
|
* Set the unshifted Unicode codepoint.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @param codepoint The unshifted Unicode codepoint to set
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
void ghostty_key_event_set_unshifted_codepoint(GhosttyKeyEvent event, uint32_t codepoint);
|
|
|
|
/**
|
|
* Get the unshifted Unicode codepoint.
|
|
*
|
|
* @param event The key event handle, must not be NULL
|
|
* @return The unshifted Unicode codepoint
|
|
*
|
|
* @ingroup key
|
|
*/
|
|
uint32_t ghostty_key_event_get_unshifted_codepoint(GhosttyKeyEvent event);
|
|
|
|
#endif /* GHOSTTY_VT_KEY_EVENT_H */
|