tessl/pypi-pygame-ce

Python Game Development library providing comprehensive multimedia functionality for creating games and interactive applications.

—

Pending

Overview

Eval results

Files

Event Handling

Name: tessl/pypi-pygame-ce
Author: tessl

Event system for processing user input and system events. Provides queued event handling with filtering capabilities and custom event creation for game logic.

Capabilities

Event Queue Management

Core functions for retrieving and processing events from the system event queue.

def get(eventtype: int | None = None, pump: bool = True) -> list[Event]:
    """
    Get events from the queue.
    
    Parameters:
        eventtype: Event type to filter for (None for all events)
        pump: Process event handlers internally before getting events
    
    Returns:
        list[Event]: List of events from queue
    """

def poll() -> Event:
    """
    Get single event from queue.
    
    Returns:
        Event: Single event or Event(NOEVENT) if queue empty
    """

def wait(timeout: int = 0) -> Event:
    """
    Wait for event.
    
    Parameters:
        timeout: Maximum wait time in milliseconds (0 for infinite)
    
    Returns:
        Event: Next event from queue
    """

def peek(eventtype: int | None = None, pump: bool = True) -> bool:
    """
    Test if events are in queue without removing them.
    
    Parameters:
        eventtype: Event type to check for (None for any event)
        pump: Process event handlers internally first
    
    Returns:
        bool: True if matching events exist in queue
    """

def clear(eventtype: int | None = None, pump: bool = True) -> None:
    """
    Remove events from queue.
    
    Parameters:
        eventtype: Event type to remove (None for all events)
        pump: Process event handlers internally first
    """

def pump() -> None:
    """
    Process pygame event handlers internally.
    Call this regularly if not calling other event functions.
    """

Event Creation and Posting

Functions for creating custom events and posting them to the event queue.

def post(event: Event) -> None:
    """
    Post event to queue.
    
    Parameters:
        event: Event to add to queue
    """

def custom_type() -> int:
    """
    Create custom user event type.
    
    Returns:
        int: New unique event type ID
    """

def event_name(type: int) -> str:
    """
    Get string name from event type.
    
    Parameters:
        type: Event type constant
    
    Returns:
        str: Human-readable event name
    """

Event Filtering

Functions to control which events are processed and queued.

def set_blocked(type: int | list[int] | None) -> None:
    """
    Block event types from appearing in queue.
    
    Parameters:
        type: Event type(s) to block, or None to block all
    """

def set_allowed(type: int | list[int] | None) -> None:
    """
    Allow only specified event types in queue.
    
    Parameters:
        type: Event type(s) to allow, or None to allow all
    """

def get_blocked(type: int) -> bool:
    """
    Check if event type is blocked.
    
    Parameters:
        type: Event type to check
    
    Returns:
        bool: True if event type is blocked
    """

Input Control

Functions for controlling input device behavior.

def set_grab(grab: bool) -> None:
    """
    Control input device sharing with other applications.
    
    Parameters:
        grab: True to grab input exclusively
    """

def get_grab() -> bool:
    """
    Get input grab state.
    
    Returns:
        bool: True if input is grabbed
    """

Event Object

The Event class represents all user input and system events.

class Event:
    def __init__(self, type: int, dict: dict | None = None):
        """
        Initialize event object.
        
        Parameters:
            type: Event type constant
            dict: Dictionary of event attributes
        """
    
    type: int  # Event type constant
    
    # Common attributes (varies by event type):
    # For KEYDOWN/KEYUP:
    key: int      # Key constant (K_a, K_SPACE, etc.)
    mod: int      # Modifier keys pressed
    unicode: str  # Unicode character (KEYDOWN only)
    scancode: int # Physical key scancode
    
    # For MOUSEBUTTONDOWN/MOUSEBUTTONUP:
    button: int   # Mouse button (1=left, 2=middle, 3=right, 4=wheel up, 5=wheel down)
    pos: tuple[int, int]  # Mouse position
    
    # For MOUSEMOTION:
    pos: tuple[int, int]      # Current mouse position  
    rel: tuple[int, int]      # Relative movement
    buttons: tuple[bool, bool, bool]  # Button states
    
    # For JOYAXISMOTION:
    joy: int      # Joystick ID
    axis: int     # Axis number
    value: float  # Axis value (-1.0 to 1.0)
    
    # For JOYBUTTONDOWN/JOYBUTTONUP:
    joy: int      # Joystick ID
    button: int   # Button number
    
    # For JOYHATMOTION:
    joy: int      # Joystick ID
    hat: int      # Hat number
    value: tuple[int, int]  # Hat position
    
    # For VIDEORESIZE:
    size: tuple[int, int]  # New window size
    w: int        # New width
    h: int        # New height
    
    # For user events (USEREVENT):
    code: int     # User-defined code

Usage Examples

Basic Event Loop

import pygame

pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()
running = True

while running:
    # Process all events in queue
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == pygame.KEYDOWN:
            if event.key == pygame.K_ESCAPE:
                running = False
            elif event.key == pygame.K_SPACE:
                print("Space key pressed!")
        elif event.type == pygame.MOUSEBUTTONDOWN:
            if event.button == 1:  # Left click
                print(f"Left click at {event.pos}")
    
    # Update display
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Custom Events

import pygame

pygame.init()

# Create custom event type
CUSTOM_EVENT = pygame.event.custom_type()

# Post custom event with data
custom_event = pygame.event.Event(CUSTOM_EVENT, {"message": "Hello", "value": 42})
pygame.event.post(custom_event)

# Handle custom event
for event in pygame.event.get():
    if event.type == CUSTOM_EVENT:
        print(f"Custom event: {event.message}, value: {event.value}")

Event Filtering

import pygame

pygame.init()

# Block mouse motion events to reduce noise
pygame.event.set_blocked(pygame.MOUSEMOTION)

# Only allow essential events
pygame.event.set_allowed([pygame.QUIT, pygame.KEYDOWN, pygame.KEYUP])

# Check if event type is blocked
if pygame.event.get_blocked(pygame.MOUSEMOTION):
    print("Mouse motion events are blocked")

Timer Events

import pygame

pygame.init()

# Create timer event every 1000ms (1 second)
TIMER_EVENT = pygame.event.custom_type()
pygame.time.set_timer(TIMER_EVENT, 1000)

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == TIMER_EVENT:
            print("Timer event triggered!")

pygame.quit()

Constants

Event type constants:

# System events
NOEVENT: int         # No event
QUIT: int            # Window close button pressed
ACTIVEEVENT: int     # Window focus changed
SYSWMEVENT: int      # System window manager event

# Keyboard events  
KEYDOWN: int         # Key pressed
KEYUP: int           # Key released

# Mouse events
MOUSEMOTION: int     # Mouse moved
MOUSEBUTTONDOWN: int # Mouse button pressed
MOUSEBUTTONUP: int   # Mouse button released

# Joystick events
JOYAXISMOTION: int   # Joystick axis moved
JOYBALLMOTION: int   # Joystick trackball moved
JOYHATMOTION: int    # Joystick hat moved
JOYBUTTONDOWN: int   # Joystick button pressed
JOYBUTTONUP: int     # Joystick button released

# Display events
VIDEORESIZE: int     # Window resized
VIDEOEXPOSE: int     # Window needs redraw

# User events
USEREVENT: int       # First user event type (use custom_type() for additional)

# Key constants (selection)
K_ESCAPE: int        # Escape key
K_SPACE: int         # Space bar
K_RETURN: int        # Enter/Return key
K_BACKSPACE: int     # Backspace key
K_TAB: int           # Tab key
K_DELETE: int        # Delete key

# Arrow keys
K_UP: int            # Up arrow
K_DOWN: int          # Down arrow  
K_LEFT: int          # Left arrow
K_RIGHT: int         # Right arrow

# Letter keys (K_a through K_z)
K_a: int
# ... (all letter keys available)
K_z: int

# Number keys (K_0 through K_9)
K_0: int
# ... (all number keys available)
K_9: int

# Modifier key constants
KMOD_NONE: int       # No modifiers
KMOD_LSHIFT: int     # Left shift
KMOD_RSHIFT: int     # Right shift
KMOD_SHIFT: int      # Either shift
KMOD_LCTRL: int      # Left control
KMOD_RCTRL: int      # Right control
KMOD_CTRL: int       # Either control
KMOD_LALT: int       # Left alt
KMOD_RALT: int       # Right alt
KMOD_ALT: int        # Either alt
KMOD_LMETA: int      # Left meta (Windows/Cmd key)
KMOD_RMETA: int      # Right meta
KMOD_META: int       # Either meta
KMOD_CAPS: int       # Caps lock
KMOD_NUM: int        # Num lock

# Hat position constants  
HAT_CENTERED: tuple[int, int]  # (0, 0)
HAT_UP: tuple[int, int]        # (0, 1)
HAT_DOWN: tuple[int, int]      # (0, -1)
HAT_LEFT: tuple[int, int]      # (-1, 0)
HAT_RIGHT: tuple[int, int]     # (1, 0)
HAT_LEFTUP: tuple[int, int]    # (-1, 1)
HAT_RIGHTUP: tuple[int, int]   # (1, 1)
HAT_LEFTDOWN: tuple[int, int]  # (-1, -1)
HAT_RIGHTDOWN: tuple[int, int] # (1, -1)

Install with Tessl CLI