1/**
2 * @file event.h
3 *
4 * Mouse event representation and manipulation.
5 */
6
7#ifndef GHOSTTY_VT_MOUSE_EVENT_H
8#define GHOSTTY_VT_MOUSE_EVENT_H
9
10#include <stdbool.h>
11#include <ghostty/vt/allocator.h>
12#include <ghostty/vt/key/event.h>
13#include <ghostty/vt/types.h>
14
15/**
16 * Opaque handle to a mouse event.
17 *
18 * This handle represents a normalized mouse input event containing
19 * action, button, modifiers, and surface-space position.
20 *
21 * @ingroup mouse
22 */
23typedef struct GhosttyMouseEventImpl *GhosttyMouseEvent;
24
25/**
26 * Mouse event action type.
27 *
28 * @ingroup mouse
29 */
30typedef enum GHOSTTY_ENUM_TYPED {
31 /** Mouse button was pressed. */
32 GHOSTTY_MOUSE_ACTION_PRESS = 0,
33
34 /** Mouse button was released. */
35 GHOSTTY_MOUSE_ACTION_RELEASE = 1,
36
37 /** Mouse moved. */
38 GHOSTTY_MOUSE_ACTION_MOTION = 2,
39 GHOSTTY_MOUSE_ACTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
40} GhosttyMouseAction;
41
42/**
43 * Mouse button identity.
44 *
45 * @ingroup mouse
46 */
47typedef enum GHOSTTY_ENUM_TYPED {
48 GHOSTTY_MOUSE_BUTTON_UNKNOWN = 0,
49 GHOSTTY_MOUSE_BUTTON_LEFT = 1,
50 GHOSTTY_MOUSE_BUTTON_RIGHT = 2,
51 GHOSTTY_MOUSE_BUTTON_MIDDLE = 3,
52 GHOSTTY_MOUSE_BUTTON_FOUR = 4,
53 GHOSTTY_MOUSE_BUTTON_FIVE = 5,
54 GHOSTTY_MOUSE_BUTTON_SIX = 6,
55 GHOSTTY_MOUSE_BUTTON_SEVEN = 7,
56 GHOSTTY_MOUSE_BUTTON_EIGHT = 8,
57 GHOSTTY_MOUSE_BUTTON_NINE = 9,
58 GHOSTTY_MOUSE_BUTTON_TEN = 10,
59 GHOSTTY_MOUSE_BUTTON_ELEVEN = 11,
60 GHOSTTY_MOUSE_BUTTON_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
61} GhosttyMouseButton;
62
63/**
64 * Mouse position in surface-space pixels.
65 *
66 * @ingroup mouse
67 */
68typedef struct {
69 float x;
70 float y;
71} GhosttyMousePosition;
72
73/**
74 * Create a new mouse event instance.
75 *
76 * @param allocator Pointer to allocator, or NULL to use the default allocator
77 * @param event Pointer to store the created event handle
78 * @return GHOSTTY_SUCCESS on success, or an error code on failure
79 *
80 * @ingroup mouse
81 */
82GHOSTTY_API GhosttyResult ghostty_mouse_event_new(const GhosttyAllocator *allocator,
83 GhosttyMouseEvent *event);
84
85/**
86 * Free a mouse event instance.
87 *
88 * @param event The mouse event handle to free (may be NULL)
89 *
90 * @ingroup mouse
91 */
92GHOSTTY_API void ghostty_mouse_event_free(GhosttyMouseEvent event);
93
94/**
95 * Set the event action.
96 *
97 * @param event The event handle, must not be NULL
98 * @param action The action to set
99 *
100 * @ingroup mouse
101 */
102GHOSTTY_API void ghostty_mouse_event_set_action(GhosttyMouseEvent event,
103 GhosttyMouseAction action);
104
105/**
106 * Get the event action.
107 *
108 * @param event The event handle, must not be NULL
109 * @return The event action
110 *
111 * @ingroup mouse
112 */
113GHOSTTY_API GhosttyMouseAction ghostty_mouse_event_get_action(GhosttyMouseEvent event);
114
115/**
116 * Set the event button.
117 *
118 * This sets a concrete button identity for the event.
119 * To represent "no button" (for motion events), use
120 * ghostty_mouse_event_clear_button().
121 *
122 * @param event The event handle, must not be NULL
123 * @param button The button to set
124 *
125 * @ingroup mouse
126 */
127GHOSTTY_API void ghostty_mouse_event_set_button(GhosttyMouseEvent event,
128 GhosttyMouseButton button);
129
130/**
131 * Clear the event button.
132 *
133 * This sets the event button to "none".
134 *
135 * @param event The event handle, must not be NULL
136 *
137 * @ingroup mouse
138 */
139GHOSTTY_API void ghostty_mouse_event_clear_button(GhosttyMouseEvent event);
140
141/**
142 * Get the event button.
143 *
144 * @param event The event handle, must not be NULL
145 * @param out_button Output pointer for the button value (may be NULL)
146 * @return true if a button is set, false if no button is set
147 *
148 * @ingroup mouse
149 */
150GHOSTTY_API bool ghostty_mouse_event_get_button(GhosttyMouseEvent event,
151 GhosttyMouseButton *out_button);
152
153/**
154 * Set keyboard modifiers held during the event.
155 *
156 * @param event The event handle, must not be NULL
157 * @param mods Modifier bitmask
158 *
159 * @ingroup mouse
160 */
161GHOSTTY_API void ghostty_mouse_event_set_mods(GhosttyMouseEvent event,
162 GhosttyMods mods);
163
164/**
165 * Get keyboard modifiers held during the event.
166 *
167 * @param event The event handle, must not be NULL
168 * @return Modifier bitmask
169 *
170 * @ingroup mouse
171 */
172GHOSTTY_API GhosttyMods ghostty_mouse_event_get_mods(GhosttyMouseEvent event);
173
174/**
175 * Set the event position in surface-space pixels.
176 *
177 * @param event The event handle, must not be NULL
178 * @param position The position to set
179 *
180 * @ingroup mouse
181 */
182GHOSTTY_API void ghostty_mouse_event_set_position(GhosttyMouseEvent event,
183 GhosttyMousePosition position);
184
185/**
186 * Get the event position in surface-space pixels.
187 *
188 * @param event The event handle, must not be NULL
189 * @return The current event position
190 *
191 * @ingroup mouse
192 */
193GHOSTTY_API GhosttyMousePosition ghostty_mouse_event_get_position(GhosttyMouseEvent event);
194
195#endif /* GHOSTTY_VT_MOUSE_EVENT_H */