0
# Event Handling and Input
1
2
Event queue management and input handling system. Pygame's event system provides a unified way to handle all input from keyboard, mouse, joystick, and system events like window closing or resizing.
3
4
## Capabilities
5
6
### Event Queue Management
7
8
Control the event queue and retrieve events for processing.
9
10
```python { .api }
11
def pump() -> None:
12
"""
13
Process events internally without removing them from queue.
14
Call this if not using other event functions to keep system responsive.
15
"""
16
17
def get(eventtype = None, pump: bool = True, exclude = None) -> list[pygame.event.Event]:
18
"""
19
Get list of events from the queue.
20
21
Args:
22
eventtype: Event type(s) to get (None for all, int/list for specific)
23
pump (bool): Whether to pump events first
24
exclude: Event type(s) to exclude
25
26
Returns:
27
list[pygame.event.Event]: List of events
28
"""
29
30
def poll() -> pygame.event.Event:
31
"""
32
Get single event from the queue.
33
34
Returns:
35
pygame.event.Event: Next event or event with type NOEVENT if queue empty
36
"""
37
38
def wait(timeout: int = 0) -> pygame.event.Event:
39
"""
40
Wait for a single event.
41
42
Args:
43
timeout (int): Maximum time to wait in milliseconds (0 = wait forever)
44
45
Returns:
46
pygame.event.Event: Next event
47
"""
48
49
def peek(eventtype = None, pump: bool = True) -> bool:
50
"""
51
Check if events are waiting in the queue.
52
53
Args:
54
eventtype: Event type(s) to check for
55
pump (bool): Whether to pump events first
56
57
Returns:
58
bool: True if matching events are in queue
59
"""
60
61
def clear(eventtype = None, pump: bool = True) -> None:
62
"""
63
Remove all events from the queue.
64
65
Args:
66
eventtype: Event type(s) to remove (None for all)
67
pump (bool): Whether to pump events first
68
"""
69
```
70
71
### Event Filtering
72
73
Control which events are allowed in or blocked from the queue.
74
75
```python { .api }
76
def set_blocked(eventtype = None) -> None:
77
"""
78
Block events from appearing in the queue.
79
80
Args:
81
eventtype: Event type(s) to block (None for all)
82
"""
83
84
def set_allowed(eventtype = None) -> None:
85
"""
86
Allow events to appear in the queue.
87
88
Args:
89
eventtype: Event type(s) to allow (None for all)
90
"""
91
92
def get_blocked(eventtype: int) -> bool:
93
"""
94
Check if an event type is blocked.
95
96
Args:
97
eventtype (int): Event type to check
98
99
Returns:
100
bool: True if event type is blocked
101
"""
102
```
103
104
### Event Creation
105
106
Create and post custom events to the queue.
107
108
```python { .api }
109
def post(event: pygame.event.Event) -> bool:
110
"""
111
Post an event to the queue.
112
113
Args:
114
event (pygame.event.Event): Event to post
115
116
Returns:
117
bool: True if event was posted successfully
118
"""
119
120
def Event(type: int, **attributes) -> pygame.event.Event:
121
"""
122
Create a new event object.
123
124
Args:
125
type (int): Event type constant
126
**attributes: Event-specific attributes
127
128
Returns:
129
pygame.event.Event: New event object
130
"""
131
132
def custom_type() -> int:
133
"""
134
Create a new custom event type.
135
136
Returns:
137
int: New event type constant for custom events
138
"""
139
140
def event_name(type: int) -> str:
141
"""
142
Get name string for an event type.
143
144
Args:
145
type (int): Event type constant
146
147
Returns:
148
str: Event type name
149
"""
150
```
151
152
### Input Control
153
154
Control input grabbing and keyboard behavior.
155
156
```python { .api }
157
def set_grab(bool) -> None:
158
"""
159
Control input event grabbing.
160
161
Args:
162
bool (bool): True to grab input, False to release
163
"""
164
165
def get_grab() -> bool:
166
"""
167
Check if input is grabbed.
168
169
Returns:
170
bool: True if input is grabbed
171
"""
172
173
def set_keyboard_grab(bool) -> None:
174
"""
175
Control keyboard grabbing.
176
177
Args:
178
bool (bool): True to grab keyboard, False to release
179
"""
180
181
def get_keyboard_grab() -> bool:
182
"""
183
Check if keyboard is grabbed.
184
185
Returns:
186
bool: True if keyboard is grabbed
187
"""
188
```
189
190
## Event Types and Objects
191
192
### Event Class
193
194
```python { .api }
195
class Event:
196
def __init__(self, type: int, **attributes):
197
"""
198
Event object representing an input or system event.
199
200
Args:
201
type (int): Event type constant
202
**attributes: Event-specific data
203
"""
204
205
type: int # Event type constant
206
207
# Common event attributes (vary by event type):
208
# key: int - Key code for KEYDOWN/KEYUP
209
# unicode: str - Unicode character for KEYDOWN
210
# mod: int - Key modifier flags
211
# pos: tuple[int, int] - Mouse position for mouse events
212
# button: int - Mouse button number
213
# rel: tuple[int, int] - Mouse relative movement
214
# size: tuple[int, int] - New window size for VIDEORESIZE
215
# joy: int - Joystick device index
216
# axis: int - Joystick axis number
217
# value: float - Joystick axis value
218
```
219
220
### Event Type Constants
221
222
```python { .api }
223
# System events
224
NOEVENT: int # No event (returned by poll() when queue empty)
225
QUIT: int # User clicked window close button
226
227
# Keyboard events
228
KEYDOWN: int # Key was pressed
229
KEYUP: int # Key was released
230
TEXTINPUT: int # Text input (Unicode)
231
TEXTEDITING: int # Text editing (IME)
232
233
# Mouse events
234
MOUSEBUTTONDOWN: int # Mouse button pressed
235
MOUSEBUTTONUP: int # Mouse button released
236
MOUSEMOTION: int # Mouse moved
237
MOUSEWHEEL: int # Mouse wheel scrolled
238
239
# Joystick events
240
JOYAXISMOTION: int # Joystick axis moved
241
JOYBUTTONDOWN: int # Joystick button pressed
242
JOYBUTTONUP: int # Joystick button released
243
JOYHATMOTION: int # Joystick hat moved
244
JOYDEVICEADDED: int # Joystick connected
245
JOYDEVICEREMOVED: int # Joystick disconnected
246
247
# Window events
248
VIDEORESIZE: int # Window was resized
249
VIDEOEXPOSE: int # Window was exposed and needs refresh
250
WINDOWSHOWN: int # Window was shown
251
WINDOWHIDDEN: int # Window was hidden
252
WINDOWMOVED: int # Window was moved
253
WINDOWFOCUSGAINED: int # Window gained focus
254
WINDOWFOCUSLOST: int # Window lost focus
255
256
# User events
257
USEREVENT: int # First user event type (use for custom events)
258
```
259
260
## Usage Examples
261
262
### Basic Event Loop
263
264
```python
265
import pygame
266
import sys
267
268
pygame.init()
269
screen = pygame.display.set_mode((800, 600))
270
clock = pygame.time.Clock()
271
272
running = True
273
while running:
274
# Process all events
275
for event in pygame.event.get():
276
if event.type == pygame.QUIT:
277
running = False
278
elif event.type == pygame.KEYDOWN:
279
if event.key == pygame.K_ESCAPE:
280
running = False
281
print(f"Key pressed: {pygame.key.name(event.key)}")
282
elif event.type == pygame.MOUSEBUTTONDOWN:
283
print(f"Mouse clicked at {event.pos}")
284
285
# Game logic here...
286
287
clock.tick(60)
288
289
pygame.quit()
290
sys.exit()
291
```
292
293
### Advanced Event Handling
294
295
```python
296
import pygame
297
298
pygame.init()
299
screen = pygame.display.set_mode((800, 600))
300
301
# Only allow specific events to save processing
302
pygame.event.set_blocked(None) # Block all events
303
pygame.event.set_allowed([pygame.QUIT, pygame.KEYDOWN, pygame.MOUSEBUTTONDOWN])
304
305
running = True
306
while running:
307
# Check for events without removing them
308
if pygame.event.peek(pygame.QUIT):
309
running = False
310
break
311
312
# Get only keyboard events
313
key_events = pygame.event.get(pygame.KEYDOWN)
314
for event in key_events:
315
if event.key == pygame.K_SPACE:
316
print(f"Space pressed! Unicode: {event.unicode}")
317
print(f"Modifiers: {event.mod}")
318
319
# Poll for single event (non-blocking)
320
event = pygame.event.poll()
321
if event.type == pygame.MOUSEBUTTONDOWN:
322
print(f"Mouse button {event.button} at {event.pos}")
323
324
pygame.display.flip()
325
326
pygame.quit()
327
```
328
329
### Custom Events
330
331
```python
332
import pygame
333
334
pygame.init()
335
screen = pygame.display.set_mode((800, 600))
336
337
# Create custom event types
338
PLAYER_HIT = pygame.event.custom_type()
339
POWER_UP = pygame.event.custom_type()
340
341
# Set timer to post events
342
pygame.time.set_timer(PLAYER_HIT, 2000) # Every 2 seconds
343
344
running = True
345
score = 0
346
347
while running:
348
for event in pygame.event.get():
349
if event.type == pygame.QUIT:
350
running = False
351
352
elif event.type == PLAYER_HIT:
353
print("Player was hit!")
354
score -= 10
355
356
# Post another custom event
357
power_event = pygame.event.Event(POWER_UP, {'type': 'health', 'value': 5})
358
pygame.event.post(power_event)
359
360
elif event.type == POWER_UP:
361
print(f"Power up! Type: {event.type}, Value: {event.value}")
362
score += event.value
363
364
elif event.type == pygame.KEYDOWN:
365
if event.key == pygame.K_p:
366
# Manually post custom event
367
hit_event = pygame.event.Event(PLAYER_HIT, {'damage': 25})
368
pygame.event.post(hit_event)
369
370
print(f"Score: {score}")
371
pygame.display.flip()
372
373
pygame.quit()
374
```
375
376
### Event Queue Management
377
378
```python
379
import pygame
380
381
pygame.init()
382
screen = pygame.display.set_mode((800, 600))
383
384
running = True
385
frame_count = 0
386
387
while running:
388
frame_count += 1
389
390
# Every 60 frames, clear all events except QUIT
391
if frame_count % 60 == 0:
392
quit_events = pygame.event.get(pygame.QUIT)
393
pygame.event.clear() # Clear all other events
394
for event in quit_events:
395
pygame.event.post(event) # Put QUIT events back
396
397
# Process events
398
for event in pygame.event.get():
399
if event.type == pygame.QUIT:
400
running = False
401
402
# Check event name for debugging
403
event_name = pygame.event.event_name(event.type)
404
print(f"Event: {event_name}")
405
406
# Pump events if not using get/poll/wait
407
# pygame.event.pump()
408
409
pygame.display.flip()
410
411
pygame.quit()
412
```
413
414
### Input Grabbing
415
416
```python
417
import pygame
418
419
pygame.init()
420
screen = pygame.display.set_mode((800, 600))
421
422
# Grab input to keep it within window
423
grab_input = False
424
425
running = True
426
while running:
427
for event in pygame.event.get():
428
if event.type == pygame.QUIT:
429
running = False
430
431
elif event.type == pygame.KEYDOWN:
432
if event.key == pygame.K_g:
433
# Toggle input grabbing
434
grab_input = not grab_input
435
pygame.event.set_grab(grab_input)
436
print(f"Input grab: {'ON' if grab_input else 'OFF'}")
437
438
elif event.key == pygame.K_k:
439
# Toggle keyboard grabbing
440
kb_grab = not pygame.event.get_keyboard_grab()
441
pygame.event.set_keyboard_grab(kb_grab)
442
print(f"Keyboard grab: {'ON' if kb_grab else 'OFF'}")
443
444
elif event.type == pygame.MOUSEMOTION:
445
print(f"Mouse at: {event.pos}, Movement: {event.rel}")
446
447
pygame.display.flip()
448
449
pygame.quit()
450
```