0
# Event Handling
1
2
Event system for processing user input and system events. Provides queued event handling with filtering capabilities and custom event creation for game logic.
3
4
## Capabilities
5
6
### Event Queue Management
7
8
Core functions for retrieving and processing events from the system event queue.
9
10
```python { .api }
11
def get(eventtype: int | None = None, pump: bool = True) -> list[Event]:
12
"""
13
Get events from the queue.
14
15
Parameters:
16
eventtype: Event type to filter for (None for all events)
17
pump: Process event handlers internally before getting events
18
19
Returns:
20
list[Event]: List of events from queue
21
"""
22
23
def poll() -> Event:
24
"""
25
Get single event from queue.
26
27
Returns:
28
Event: Single event or Event(NOEVENT) if queue empty
29
"""
30
31
def wait(timeout: int = 0) -> Event:
32
"""
33
Wait for event.
34
35
Parameters:
36
timeout: Maximum wait time in milliseconds (0 for infinite)
37
38
Returns:
39
Event: Next event from queue
40
"""
41
42
def peek(eventtype: int | None = None, pump: bool = True) -> bool:
43
"""
44
Test if events are in queue without removing them.
45
46
Parameters:
47
eventtype: Event type to check for (None for any event)
48
pump: Process event handlers internally first
49
50
Returns:
51
bool: True if matching events exist in queue
52
"""
53
54
def clear(eventtype: int | None = None, pump: bool = True) -> None:
55
"""
56
Remove events from queue.
57
58
Parameters:
59
eventtype: Event type to remove (None for all events)
60
pump: Process event handlers internally first
61
"""
62
63
def pump() -> None:
64
"""
65
Process pygame event handlers internally.
66
Call this regularly if not calling other event functions.
67
"""
68
```
69
70
### Event Creation and Posting
71
72
Functions for creating custom events and posting them to the event queue.
73
74
```python { .api }
75
def post(event: Event) -> None:
76
"""
77
Post event to queue.
78
79
Parameters:
80
event: Event to add to queue
81
"""
82
83
def custom_type() -> int:
84
"""
85
Create custom user event type.
86
87
Returns:
88
int: New unique event type ID
89
"""
90
91
def event_name(type: int) -> str:
92
"""
93
Get string name from event type.
94
95
Parameters:
96
type: Event type constant
97
98
Returns:
99
str: Human-readable event name
100
"""
101
```
102
103
### Event Filtering
104
105
Functions to control which events are processed and queued.
106
107
```python { .api }
108
def set_blocked(type: int | list[int] | None) -> None:
109
"""
110
Block event types from appearing in queue.
111
112
Parameters:
113
type: Event type(s) to block, or None to block all
114
"""
115
116
def set_allowed(type: int | list[int] | None) -> None:
117
"""
118
Allow only specified event types in queue.
119
120
Parameters:
121
type: Event type(s) to allow, or None to allow all
122
"""
123
124
def get_blocked(type: int) -> bool:
125
"""
126
Check if event type is blocked.
127
128
Parameters:
129
type: Event type to check
130
131
Returns:
132
bool: True if event type is blocked
133
"""
134
```
135
136
### Input Control
137
138
Functions for controlling input device behavior.
139
140
```python { .api }
141
def set_grab(grab: bool) -> None:
142
"""
143
Control input device sharing with other applications.
144
145
Parameters:
146
grab: True to grab input exclusively
147
"""
148
149
def get_grab() -> bool:
150
"""
151
Get input grab state.
152
153
Returns:
154
bool: True if input is grabbed
155
"""
156
```
157
158
### Event Object
159
160
The Event class represents all user input and system events.
161
162
```python { .api }
163
class Event:
164
def __init__(self, type: int, dict: dict | None = None):
165
"""
166
Initialize event object.
167
168
Parameters:
169
type: Event type constant
170
dict: Dictionary of event attributes
171
"""
172
173
type: int # Event type constant
174
175
# Common attributes (varies by event type):
176
# For KEYDOWN/KEYUP:
177
key: int # Key constant (K_a, K_SPACE, etc.)
178
mod: int # Modifier keys pressed
179
unicode: str # Unicode character (KEYDOWN only)
180
scancode: int # Physical key scancode
181
182
# For MOUSEBUTTONDOWN/MOUSEBUTTONUP:
183
button: int # Mouse button (1=left, 2=middle, 3=right, 4=wheel up, 5=wheel down)
184
pos: tuple[int, int] # Mouse position
185
186
# For MOUSEMOTION:
187
pos: tuple[int, int] # Current mouse position
188
rel: tuple[int, int] # Relative movement
189
buttons: tuple[bool, bool, bool] # Button states
190
191
# For JOYAXISMOTION:
192
joy: int # Joystick ID
193
axis: int # Axis number
194
value: float # Axis value (-1.0 to 1.0)
195
196
# For JOYBUTTONDOWN/JOYBUTTONUP:
197
joy: int # Joystick ID
198
button: int # Button number
199
200
# For JOYHATMOTION:
201
joy: int # Joystick ID
202
hat: int # Hat number
203
value: tuple[int, int] # Hat position
204
205
# For VIDEORESIZE:
206
size: tuple[int, int] # New window size
207
w: int # New width
208
h: int # New height
209
210
# For user events (USEREVENT):
211
code: int # User-defined code
212
```
213
214
## Usage Examples
215
216
### Basic Event Loop
217
218
```python
219
import pygame
220
221
pygame.init()
222
screen = pygame.display.set_mode((800, 600))
223
clock = pygame.time.Clock()
224
running = True
225
226
while running:
227
# Process all events in queue
228
for event in pygame.event.get():
229
if event.type == pygame.QUIT:
230
running = False
231
elif event.type == pygame.KEYDOWN:
232
if event.key == pygame.K_ESCAPE:
233
running = False
234
elif event.key == pygame.K_SPACE:
235
print("Space key pressed!")
236
elif event.type == pygame.MOUSEBUTTONDOWN:
237
if event.button == 1: # Left click
238
print(f"Left click at {event.pos}")
239
240
# Update display
241
pygame.display.flip()
242
clock.tick(60)
243
244
pygame.quit()
245
```
246
247
### Custom Events
248
249
```python
250
import pygame
251
252
pygame.init()
253
254
# Create custom event type
255
CUSTOM_EVENT = pygame.event.custom_type()
256
257
# Post custom event with data
258
custom_event = pygame.event.Event(CUSTOM_EVENT, {"message": "Hello", "value": 42})
259
pygame.event.post(custom_event)
260
261
# Handle custom event
262
for event in pygame.event.get():
263
if event.type == CUSTOM_EVENT:
264
print(f"Custom event: {event.message}, value: {event.value}")
265
```
266
267
### Event Filtering
268
269
```python
270
import pygame
271
272
pygame.init()
273
274
# Block mouse motion events to reduce noise
275
pygame.event.set_blocked(pygame.MOUSEMOTION)
276
277
# Only allow essential events
278
pygame.event.set_allowed([pygame.QUIT, pygame.KEYDOWN, pygame.KEYUP])
279
280
# Check if event type is blocked
281
if pygame.event.get_blocked(pygame.MOUSEMOTION):
282
print("Mouse motion events are blocked")
283
```
284
285
### Timer Events
286
287
```python
288
import pygame
289
290
pygame.init()
291
292
# Create timer event every 1000ms (1 second)
293
TIMER_EVENT = pygame.event.custom_type()
294
pygame.time.set_timer(TIMER_EVENT, 1000)
295
296
running = True
297
while running:
298
for event in pygame.event.get():
299
if event.type == pygame.QUIT:
300
running = False
301
elif event.type == TIMER_EVENT:
302
print("Timer event triggered!")
303
304
pygame.quit()
305
```
306
307
## Constants
308
309
Event type constants:
310
311
```python { .api }
312
# System events
313
NOEVENT: int # No event
314
QUIT: int # Window close button pressed
315
ACTIVEEVENT: int # Window focus changed
316
SYSWMEVENT: int # System window manager event
317
318
# Keyboard events
319
KEYDOWN: int # Key pressed
320
KEYUP: int # Key released
321
322
# Mouse events
323
MOUSEMOTION: int # Mouse moved
324
MOUSEBUTTONDOWN: int # Mouse button pressed
325
MOUSEBUTTONUP: int # Mouse button released
326
327
# Joystick events
328
JOYAXISMOTION: int # Joystick axis moved
329
JOYBALLMOTION: int # Joystick trackball moved
330
JOYHATMOTION: int # Joystick hat moved
331
JOYBUTTONDOWN: int # Joystick button pressed
332
JOYBUTTONUP: int # Joystick button released
333
334
# Display events
335
VIDEORESIZE: int # Window resized
336
VIDEOEXPOSE: int # Window needs redraw
337
338
# User events
339
USEREVENT: int # First user event type (use custom_type() for additional)
340
341
# Key constants (selection)
342
K_ESCAPE: int # Escape key
343
K_SPACE: int # Space bar
344
K_RETURN: int # Enter/Return key
345
K_BACKSPACE: int # Backspace key
346
K_TAB: int # Tab key
347
K_DELETE: int # Delete key
348
349
# Arrow keys
350
K_UP: int # Up arrow
351
K_DOWN: int # Down arrow
352
K_LEFT: int # Left arrow
353
K_RIGHT: int # Right arrow
354
355
# Letter keys (K_a through K_z)
356
K_a: int
357
# ... (all letter keys available)
358
K_z: int
359
360
# Number keys (K_0 through K_9)
361
K_0: int
362
# ... (all number keys available)
363
K_9: int
364
365
# Modifier key constants
366
KMOD_NONE: int # No modifiers
367
KMOD_LSHIFT: int # Left shift
368
KMOD_RSHIFT: int # Right shift
369
KMOD_SHIFT: int # Either shift
370
KMOD_LCTRL: int # Left control
371
KMOD_RCTRL: int # Right control
372
KMOD_CTRL: int # Either control
373
KMOD_LALT: int # Left alt
374
KMOD_RALT: int # Right alt
375
KMOD_ALT: int # Either alt
376
KMOD_LMETA: int # Left meta (Windows/Cmd key)
377
KMOD_RMETA: int # Right meta
378
KMOD_META: int # Either meta
379
KMOD_CAPS: int # Caps lock
380
KMOD_NUM: int # Num lock
381
382
# Hat position constants
383
HAT_CENTERED: tuple[int, int] # (0, 0)
384
HAT_UP: tuple[int, int] # (0, 1)
385
HAT_DOWN: tuple[int, int] # (0, -1)
386
HAT_LEFT: tuple[int, int] # (-1, 0)
387
HAT_RIGHT: tuple[int, int] # (1, 0)
388
HAT_LEFTUP: tuple[int, int] # (-1, 1)
389
HAT_RIGHTUP: tuple[int, int] # (1, 1)
390
HAT_LEFTDOWN: tuple[int, int] # (-1, -1)
391
HAT_RIGHTDOWN: tuple[int, int] # (1, -1)
392
```