0
# Input Handling
1
2
Comprehensive input system supporting keyboard, mouse, joystick, and gamepad input with both polling and callback-based event handling for interactive applications.
3
4
## Capabilities
5
6
### Event Processing
7
8
Process input events and window system messages.
9
10
```python { .api }
11
def poll_events() -> None:
12
"""
13
Process all pending events.
14
15
This function processes only those events that are already in the
16
event queue and then returns immediately.
17
"""
18
19
def wait_events() -> None:
20
"""
21
Wait until events are queued and processes them.
22
23
This function puts the calling thread to sleep until at least
24
one event is available in the event queue.
25
"""
26
27
def wait_events_timeout(timeout: float) -> None:
28
"""
29
Wait with timeout until events are queued and processes them.
30
31
Parameters:
32
timeout: Maximum time to wait, in seconds
33
"""
34
35
def post_empty_event() -> None:
36
"""
37
Post an empty event to the event queue.
38
39
This function posts an empty event from the current thread
40
to the event queue, causing wait_events to return.
41
"""
42
```
43
44
### Input Modes
45
46
Configure input behavior for windows.
47
48
```python { .api }
49
def get_input_mode(window, mode: int) -> int:
50
"""
51
Get the value of an input option for the window.
52
53
Parameters:
54
window: Window to query
55
mode: Input mode to query
56
57
Returns:
58
int: Current mode value
59
"""
60
61
def set_input_mode(window, mode: int, value: int) -> None:
62
"""
63
Set an input option for the window.
64
65
Parameters:
66
window: Window to configure
67
mode: Input mode to set
68
value: New mode value
69
"""
70
```
71
72
#### Input Mode Constants
73
74
```python { .api }
75
# Input modes
76
CURSOR: int = 0x00033001
77
STICKY_KEYS: int = 0x00033002
78
STICKY_MOUSE_BUTTONS: int = 0x00033003
79
LOCK_KEY_MODS: int = 0x00033004
80
RAW_MOUSE_MOTION: int = 0x00033005
81
82
# Cursor mode values
83
CURSOR_NORMAL: int = 0x00034001
84
CURSOR_HIDDEN: int = 0x00034002
85
CURSOR_DISABLED: int = 0x00034003
86
CURSOR_CAPTURED: int = 0x00034004
87
```
88
89
### Keyboard Input
90
91
Handle keyboard input with both polling and callbacks.
92
93
```python { .api }
94
def get_key(window, key: int) -> int:
95
"""
96
Get the last reported state of a keyboard key.
97
98
Parameters:
99
window: Window to query
100
key: Keyboard key constant
101
102
Returns:
103
int: PRESS, RELEASE, or REPEAT
104
"""
105
106
def get_key_name(key: int, scancode: int) -> str:
107
"""
108
Get the localized name of the specified printable key.
109
110
Parameters:
111
key: Key constant, or KEY_UNKNOWN
112
scancode: Platform-specific scancode
113
114
Returns:
115
str: Key name, or None if unavailable
116
"""
117
118
def get_key_scancode(key: int) -> int:
119
"""
120
Get the platform-specific scancode of the key.
121
122
Parameters:
123
key: Key constant
124
125
Returns:
126
int: Platform-specific scancode
127
"""
128
129
def set_key_callback(window, cbfun) -> callable:
130
"""
131
Set the key callback.
132
133
Parameters:
134
cbfun: Callback function or None
135
Signature: callback(window, key: int, scancode: int,
136
action: int, mods: int)
137
"""
138
139
def set_char_callback(window, cbfun) -> callable:
140
"""
141
Set the Unicode character callback.
142
143
Parameters:
144
cbfun: Callback function or None
145
Signature: callback(window, codepoint: int)
146
"""
147
148
def set_char_mods_callback(window, cbfun) -> callable:
149
"""
150
Set the Unicode character with modifiers callback.
151
152
Parameters:
153
cbfun: Callback function or None
154
Signature: callback(window, codepoint: int, mods: int)
155
"""
156
```
157
158
#### Keyboard Constants
159
160
```python { .api }
161
# Key actions
162
RELEASE: int = 0
163
PRESS: int = 1
164
REPEAT: int = 2
165
166
# Modifier key bits
167
MOD_SHIFT: int = 0x0001
168
MOD_CONTROL: int = 0x0002
169
MOD_ALT: int = 0x0004
170
MOD_SUPER: int = 0x0008
171
MOD_CAPS_LOCK: int = 0x0010
172
MOD_NUM_LOCK: int = 0x0020
173
174
# Key constants (selection - 100+ available)
175
KEY_UNKNOWN: int = -1
176
KEY_SPACE: int = 32
177
KEY_APOSTROPHE: int = 39 # '
178
KEY_COMMA: int = 44 # ,
179
KEY_MINUS: int = 45 # -
180
KEY_PERIOD: int = 46 # .
181
KEY_SLASH: int = 47 # /
182
183
# Number keys
184
KEY_0: int = 48
185
KEY_1: int = 49
186
# ... through KEY_9: int = 57
187
188
# Letter keys
189
KEY_A: int = 65
190
KEY_B: int = 66
191
# ... through KEY_Z: int = 90
192
193
# Function keys
194
KEY_F1: int = 290
195
KEY_F2: int = 291
196
# ... through KEY_F25: int = 314
197
198
# Arrow keys
199
KEY_RIGHT: int = 262
200
KEY_LEFT: int = 263
201
KEY_DOWN: int = 264
202
KEY_UP: int = 265
203
204
# Common special keys
205
KEY_ESCAPE: int = 256
206
KEY_ENTER: int = 257
207
KEY_TAB: int = 258
208
KEY_BACKSPACE: int = 259
209
KEY_INSERT: int = 260
210
KEY_DELETE: int = 261
211
KEY_HOME: int = 268
212
KEY_END: int = 269
213
214
# Modifier keys
215
KEY_LEFT_SHIFT: int = 340
216
KEY_LEFT_CONTROL: int = 341
217
KEY_LEFT_ALT: int = 342
218
KEY_LEFT_SUPER: int = 343
219
KEY_RIGHT_SHIFT: int = 344
220
KEY_RIGHT_CONTROL: int = 345
221
KEY_RIGHT_ALT: int = 346
222
KEY_RIGHT_SUPER: int = 347
223
```
224
225
### Mouse Input
226
227
Handle mouse button and cursor input.
228
229
```python { .api }
230
def get_mouse_button(window, button: int) -> int:
231
"""
232
Get the last reported state of a mouse button.
233
234
Parameters:
235
window: Window to query
236
button: Mouse button constant
237
238
Returns:
239
int: PRESS or RELEASE
240
"""
241
242
def get_cursor_pos(window) -> tuple[float, float]:
243
"""
244
Get the cursor position relative to the window's client area.
245
246
Parameters:
247
window: Window to query
248
249
Returns:
250
tuple: (x, y) cursor position
251
"""
252
253
def set_cursor_pos(window, xpos: float, ypos: float) -> None:
254
"""
255
Set the cursor position relative to the window's client area.
256
257
Parameters:
258
window: Window to modify
259
xpos: New x-coordinate
260
ypos: New y-coordinate
261
"""
262
263
def raw_mouse_motion_supported() -> bool:
264
"""
265
Check whether raw mouse motion is supported.
266
267
Returns:
268
bool: True if raw mouse motion is supported
269
"""
270
```
271
272
#### Mouse Button Constants
273
274
```python { .api }
275
# Mouse buttons
276
MOUSE_BUTTON_1: int = 0
277
MOUSE_BUTTON_2: int = 1
278
MOUSE_BUTTON_3: int = 2
279
MOUSE_BUTTON_4: int = 3
280
MOUSE_BUTTON_5: int = 4
281
MOUSE_BUTTON_6: int = 5
282
MOUSE_BUTTON_7: int = 6
283
MOUSE_BUTTON_8: int = 7
284
MOUSE_BUTTON_LAST: int = MOUSE_BUTTON_8
285
286
# Mouse button aliases
287
MOUSE_BUTTON_LEFT: int = MOUSE_BUTTON_1
288
MOUSE_BUTTON_RIGHT: int = MOUSE_BUTTON_2
289
MOUSE_BUTTON_MIDDLE: int = MOUSE_BUTTON_3
290
```
291
292
### Mouse Callbacks
293
294
Register callbacks for mouse events.
295
296
```python { .api }
297
def set_mouse_button_callback(window, cbfun) -> callable:
298
"""
299
Set the mouse button callback.
300
301
Parameters:
302
cbfun: Callback function or None
303
Signature: callback(window, button: int, action: int, mods: int)
304
"""
305
306
def set_cursor_pos_callback(window, cbfun) -> callable:
307
"""
308
Set the cursor position callback.
309
310
Parameters:
311
cbfun: Callback function or None
312
Signature: callback(window, xpos: float, ypos: float)
313
"""
314
315
def set_cursor_enter_callback(window, cbfun) -> callable:
316
"""
317
Set the cursor enter/exit callback.
318
319
Parameters:
320
cbfun: Callback function or None
321
Signature: callback(window, entered: int)
322
"""
323
324
def set_scroll_callback(window, cbfun) -> callable:
325
"""
326
Set the scroll callback.
327
328
Parameters:
329
cbfun: Callback function or None
330
Signature: callback(window, xoffset: float, yoffset: float)
331
"""
332
```
333
334
### Cursor Management
335
336
Create and manage custom cursors.
337
338
```python { .api }
339
def create_cursor(image, xhot: int, yhot: int):
340
"""
341
Create a custom cursor from an image.
342
343
Parameters:
344
image: Image data or PIL Image object
345
xhot: X-coordinate of cursor hotspot
346
yhot: Y-coordinate of cursor hotspot
347
348
Returns:
349
GLFWcursor: Cursor handle
350
"""
351
352
def create_standard_cursor(shape: int):
353
"""
354
Create a cursor with a standard shape.
355
356
Parameters:
357
shape: Standard cursor shape constant
358
359
Returns:
360
GLFWcursor: Cursor handle
361
"""
362
363
def destroy_cursor(cursor) -> None:
364
"""
365
Destroy a cursor.
366
367
Parameters:
368
cursor: Cursor to destroy
369
"""
370
371
def set_cursor(window, cursor) -> None:
372
"""
373
Set the cursor for the window.
374
375
Parameters:
376
window: Window to modify
377
cursor: Cursor to set, or None for default
378
"""
379
```
380
381
#### Cursor Shape Constants
382
383
```python { .api }
384
# Standard cursor shapes
385
ARROW_CURSOR: int = 0x00036001
386
IBEAM_CURSOR: int = 0x00036002
387
CROSSHAIR_CURSOR: int = 0x00036003
388
HAND_CURSOR: int = 0x00036004
389
POINTING_HAND_CURSOR: int = 0x00036004
390
HRESIZE_CURSOR: int = 0x00036005
391
RESIZE_EW_CURSOR: int = 0x00036005
392
VRESIZE_CURSOR: int = 0x00036006
393
RESIZE_NS_CURSOR: int = 0x00036006
394
RESIZE_NWSE_CURSOR: int = 0x00036007
395
RESIZE_NESW_CURSOR: int = 0x00036008
396
RESIZE_ALL_CURSOR: int = 0x00036009
397
NOT_ALLOWED_CURSOR: int = 0x0003600A
398
```
399
400
### Joystick Input
401
402
Query and handle joystick/controller input.
403
404
```python { .api }
405
def joystick_present(joy: int) -> int:
406
"""
407
Check whether the specified joystick is present.
408
409
Parameters:
410
joy: Joystick ID (JOYSTICK_1 through JOYSTICK_16)
411
412
Returns:
413
int: 1 if present, 0 if not present
414
"""
415
416
def get_joystick_axes(joy: int) -> tuple:
417
"""
418
Get the values of all axes of the specified joystick.
419
420
Parameters:
421
joy: Joystick ID
422
423
Returns:
424
tuple: (axes_array, count) - axes values and count
425
"""
426
427
def get_joystick_buttons(joy: int) -> tuple:
428
"""
429
Get the state of all buttons of the specified joystick.
430
431
Parameters:
432
joy: Joystick ID
433
434
Returns:
435
tuple: (buttons_array, count) - button states and count
436
"""
437
438
def get_joystick_hats(joystick_id: int) -> tuple:
439
"""
440
Get the state of all hats of the specified joystick.
441
442
Parameters:
443
joystick_id: Joystick ID
444
445
Returns:
446
tuple: (hats_array, count) - hat states and count
447
"""
448
449
def get_joystick_name(joy: int) -> bytes:
450
"""
451
Get the name of the specified joystick.
452
453
Parameters:
454
joy: Joystick ID
455
456
Returns:
457
bytes: Joystick name
458
"""
459
460
def get_joystick_guid(joystick_id: int) -> bytes:
461
"""
462
Get the SDL compatible GUID of the specified joystick.
463
464
Parameters:
465
joystick_id: Joystick ID
466
467
Returns:
468
bytes: Joystick GUID
469
"""
470
471
def set_joystick_user_pointer(joystick_id: int, pointer) -> None:
472
"""Set user data for the joystick."""
473
474
def get_joystick_user_pointer(joystick_id: int):
475
"""Get user data for the joystick."""
476
477
def set_joystick_callback(cbfun) -> callable:
478
"""
479
Set the joystick configuration callback.
480
481
Parameters:
482
cbfun: Callback function or None
483
Signature: callback(joy: int, event: int)
484
"""
485
```
486
487
#### Joystick Constants
488
489
```python { .api }
490
# Joystick IDs
491
JOYSTICK_1: int = 0
492
JOYSTICK_2: int = 1
493
# ... through JOYSTICK_16: int = 15
494
JOYSTICK_LAST: int = JOYSTICK_16
495
496
# Joystick events
497
CONNECTED: int = 0x00040001
498
DISCONNECTED: int = 0x00040002
499
500
# Hat states
501
HAT_CENTERED: int = 0
502
HAT_UP: int = 1
503
HAT_RIGHT: int = 2
504
HAT_DOWN: int = 4
505
HAT_LEFT: int = 8
506
HAT_RIGHT_UP: int = HAT_RIGHT | HAT_UP
507
HAT_RIGHT_DOWN: int = HAT_RIGHT | HAT_DOWN
508
HAT_LEFT_UP: int = HAT_LEFT | HAT_UP
509
HAT_LEFT_DOWN: int = HAT_LEFT | HAT_DOWN
510
```
511
512
### Gamepad Support
513
514
High-level gamepad interface with standardized button mapping.
515
516
```python { .api }
517
def joystick_is_gamepad(joystick_id: int) -> bool:
518
"""
519
Check whether the specified joystick has a gamepad mapping.
520
521
Parameters:
522
joystick_id: Joystick ID
523
524
Returns:
525
bool: True if joystick has gamepad mapping
526
"""
527
528
def get_gamepad_state(joystick_id: int):
529
"""
530
Get the state of the specified joystick remapped as a gamepad.
531
532
Parameters:
533
joystick_id: Joystick ID
534
535
Returns:
536
GLFWgamepadstate: Gamepad state, or None if not available
537
"""
538
539
def get_gamepad_name(joystick_id: int) -> str:
540
"""
541
Get the human-readable gamepad name for the specified joystick.
542
543
Parameters:
544
joystick_id: Joystick ID
545
546
Returns:
547
str: Gamepad name, or None if not available
548
"""
549
550
def update_gamepad_mappings(string: str) -> int:
551
"""
552
Add the specified SDL_GameControllerDB gamepad mappings.
553
554
Parameters:
555
string: Gamepad mappings string
556
557
Returns:
558
int: 1 if successful, 0 if failed
559
"""
560
```
561
562
#### Gamepad Constants
563
564
```python { .api }
565
# Gamepad buttons
566
GAMEPAD_BUTTON_A: int = 0
567
GAMEPAD_BUTTON_B: int = 1
568
GAMEPAD_BUTTON_X: int = 2
569
GAMEPAD_BUTTON_Y: int = 3
570
GAMEPAD_BUTTON_LEFT_BUMPER: int = 4
571
GAMEPAD_BUTTON_RIGHT_BUMPER: int = 5
572
GAMEPAD_BUTTON_BACK: int = 6
573
GAMEPAD_BUTTON_START: int = 7
574
GAMEPAD_BUTTON_GUIDE: int = 8
575
GAMEPAD_BUTTON_LEFT_THUMB: int = 9
576
GAMEPAD_BUTTON_RIGHT_THUMB: int = 10
577
GAMEPAD_BUTTON_DPAD_UP: int = 11
578
GAMEPAD_BUTTON_DPAD_RIGHT: int = 12
579
GAMEPAD_BUTTON_DPAD_DOWN: int = 13
580
GAMEPAD_BUTTON_DPAD_LEFT: int = 14
581
GAMEPAD_BUTTON_LAST: int = GAMEPAD_BUTTON_DPAD_LEFT
582
583
# PlayStation-style aliases
584
GAMEPAD_BUTTON_CROSS: int = GAMEPAD_BUTTON_A
585
GAMEPAD_BUTTON_CIRCLE: int = GAMEPAD_BUTTON_B
586
GAMEPAD_BUTTON_SQUARE: int = GAMEPAD_BUTTON_X
587
GAMEPAD_BUTTON_TRIANGLE: int = GAMEPAD_BUTTON_Y
588
589
# Gamepad axes
590
GAMEPAD_AXIS_LEFT_X: int = 0
591
GAMEPAD_AXIS_LEFT_Y: int = 1
592
GAMEPAD_AXIS_RIGHT_X: int = 2
593
GAMEPAD_AXIS_RIGHT_Y: int = 3
594
GAMEPAD_AXIS_LEFT_TRIGGER: int = 4
595
GAMEPAD_AXIS_RIGHT_TRIGGER: int = 5
596
GAMEPAD_AXIS_LAST: int = GAMEPAD_AXIS_RIGHT_TRIGGER
597
```
598
599
### Clipboard
600
601
Access system clipboard for text data.
602
603
```python { .api }
604
def set_clipboard_string(window, string: str) -> None:
605
"""
606
Set the clipboard to the specified string.
607
608
Parameters:
609
window: Window (deprecated, can be None)
610
string: String to set in clipboard
611
"""
612
613
def get_clipboard_string(window) -> bytes:
614
"""
615
Get the contents of the clipboard as a string.
616
617
Parameters:
618
window: Window (deprecated, can be None)
619
620
Returns:
621
bytes: Clipboard contents
622
"""
623
```
624
625
### Drag and Drop
626
627
Handle file drag and drop operations.
628
629
```python { .api }
630
def set_drop_callback(window, cbfun) -> callable:
631
"""
632
Set the file drop callback.
633
634
Parameters:
635
cbfun: Callback function or None
636
Signature: callback(window, paths: list[str])
637
"""
638
```
639
640
## Usage Examples
641
642
### Basic Input Polling
643
644
```python
645
import glfw
646
647
glfw.init()
648
window = glfw.create_window(640, 480, "Input Example", None, None)
649
glfw.make_context_current(window)
650
651
while not glfw.window_should_close(window):
652
glfw.poll_events()
653
654
# Check for escape key
655
if glfw.get_key(window, glfw.KEY_ESCAPE) == glfw.PRESS:
656
glfw.set_window_should_close(window, True)
657
658
# Check mouse button
659
if glfw.get_mouse_button(window, glfw.MOUSE_BUTTON_LEFT) == glfw.PRESS:
660
x, y = glfw.get_cursor_pos(window)
661
print(f"Mouse clicked at {x}, {y}")
662
663
glfw.swap_buffers(window)
664
665
glfw.terminate()
666
```
667
668
### Input Callbacks
669
670
```python
671
import glfw
672
673
def key_callback(window, key, scancode, action, mods):
674
if key == glfw.KEY_ESCAPE and action == glfw.PRESS:
675
glfw.set_window_should_close(window, True)
676
elif action == glfw.PRESS:
677
print(f"Key {key} pressed")
678
679
def mouse_button_callback(window, button, action, mods):
680
if button == glfw.MOUSE_BUTTON_LEFT and action == glfw.PRESS:
681
x, y = glfw.get_cursor_pos(window)
682
print(f"Left mouse button pressed at {x}, {y}")
683
684
glfw.init()
685
window = glfw.create_window(640, 480, "Callbacks", None, None)
686
687
# Set callbacks
688
glfw.set_key_callback(window, key_callback)
689
glfw.set_mouse_button_callback(window, mouse_button_callback)
690
691
# Main loop...
692
```
693
694
### Gamepad Input
695
696
```python
697
import glfw
698
699
glfw.init()
700
window = glfw.create_window(640, 480, "Gamepad", None, None)
701
702
while not glfw.window_should_close(window):
703
glfw.poll_events()
704
705
# Check for connected gamepads
706
for joy in range(glfw.JOYSTICK_1, glfw.JOYSTICK_LAST + 1):
707
if glfw.joystick_present(joy) and glfw.joystick_is_gamepad(joy):
708
state = glfw.get_gamepad_state(joy)
709
if state:
710
# Check A button
711
if state.buttons[glfw.GAMEPAD_BUTTON_A]:
712
print("A button pressed")
713
714
# Check left stick
715
left_x = state.axes[glfw.GAMEPAD_AXIS_LEFT_X]
716
left_y = state.axes[glfw.GAMEPAD_AXIS_LEFT_Y]
717
if abs(left_x) > 0.1 or abs(left_y) > 0.1:
718
print(f"Left stick: {left_x}, {left_y}")
719
720
glfw.swap_buffers(window)
721
722
glfw.terminate()
723
```