Display

Display window management for multiple backends.

This module provides backend-agnostic window management for pygame, psychopy, and pyglet. The tracker creates and owns the display window, which users can access directly or through helper methods.

Backend classes are imported lazily to avoid ImportError when backend not installed.

class pyelink.display.BaseDisplay(settings, shutdown_handler=None)[source]

Bases: ABC

Abstract base class for display window management.

Provides unified interface for window creation, event handling, and drawing across pygame, psychopy, and pyglet backends. Each backend implements this interface with backend-specific window management.

The display owns the window throughout the experiment lifecycle. Users can: - Access raw backend window via window property (Option A: direct access) - Use backend-agnostic helper methods (Option B: abstraction layer)

Parameters:
__init__(settings, shutdown_handler=None)[source]

Initialize display and create window.

Parameters:

  • settings (object) – Settings object containing BACKEND, FULLSCREEN, DISPLAY_INDEX, SCREEN_RES

  • shutdown_handler (object) – Callable to invoke when Ctrl+C detected (for graceful shutdown)

Return type:

None

property window: Any

Get raw backend-specific window object.

This provides direct access to the underlying window for backend-specific operations (Option A).

Returns:

  • pygame: pygame.Surface

  • psychopy: psychopy.visual.Window

  • pyglet: pyglet.window.Window

Return type:

Backend window object

abstract property backend_name: str

Get backend identifier string.

Returns:

“pygame”, “psychopy”, or “pyglet”

Return type:

Backend name

abstractmethod flip()[source]

Update display to show drawn content.

Equivalent to: - pygame: pygame.display.flip() - psychopy: win.flip() - pyglet: window.flip()

Return type:

None

abstractmethod close()[source]

Close window and clean up display resources.

Called during tracker cleanup in end_experiment().

Return type:

None

abstractmethod get_events()[source]

Poll for keyboard and mouse events.

Returns unified event dictionaries that abstract backend differences.

Returns:

  • ‘type’: ‘keydown’, ‘keyup’, ‘quit’, ‘mousebuttondown’, etc.

  • ’key’: key name string (for keyboard events)

  • ’unicode’: unicode character (for keyboard events)

  • ’pos’: (x, y) tuple (for mouse events)

  • ’button’: button number (for mouse events)

Return type:

list[dict[str, Any]]

abstractmethod fill(color)[source]

Fill entire window with specified RGB color.

Parameters:

color (tuple[int, int, int]) – RGB tuple (0-255, 0-255, 0-255)

Return type:

None

Example

display.fill((128, 128, 128)) # Gray background

abstractmethod clear()[source]

Clear window to black.

Convenience method equivalent to fill((0, 0, 0)).

Return type:

None

abstractmethod get_size()[source]

Get window dimensions.

Return type:

tuple[int, int]

Returns:

(width, height) in pixels

abstractmethod draw_text(text, pos=None, center=False, size=24, color=(255, 255, 255))[source]

Draw text on window.

Parameters:

  • text (str) – Text string to display

  • pos (tuple[int, int] | None) – (x, y) position in pixels, None if center=True

  • center (bool) – If True, center text on screen (ignores pos)

  • size (int) – Font size in points

  • color (tuple[int, int, int]) – RGB color tuple (0-255, 0-255, 0-255)

Return type:

None

Example

display.draw_text(“Fixate +”, center=True, size=48) display.draw_text(“Press SPACE”, pos=(100, 100))

abstractmethod draw_image(image_path, pos=None, center=False, scale=None)[source]

Draw image on window.

Parameters:

  • image_path (str | Path) – Path to image file

  • pos (tuple[int, int] | None) – (x, y) position in pixels, None if center=True

  • center (bool) – If True, center image on screen (ignores pos)

  • scale (float | None) – Scale factor (1.0 = original size, 2.0 = double size, etc.)

Return type:

None

Example

display.draw_image(“stimulus.png”, center=True) display.draw_image(“cue.png”, pos=(100, 100), scale=0.5)

wait_for_key(key=None, timeout=None)[source]

Wait for keyboard input.

Helper method that polls events until key pressed or timeout.

Parameters:

  • key (str | None) – Specific key to wait for (e.g., ‘space’, ‘return’), or None for any key

  • timeout (float | None) – Maximum time to wait in seconds, or None to wait indefinitely

Return type:

str | None

Returns:

Key name that was pressed, or None if timeout

wait(duration)[source]

Wait for specified duration while handling events.

Prevents event queue buildup during delays.

Parameters:

duration (float) – Time to wait in seconds

Return type:

None

Base Display

Base display abstraction for window management across backends.

This module provides the abstract interface that all display backends must implement. The abstraction enables backend-agnostic experiment code while maintaining direct access to backend-specific windows when needed.

class pyelink.display.base.BaseDisplay(settings, shutdown_handler=None)[source]

Bases: ABC

Abstract base class for display window management.

Provides unified interface for window creation, event handling, and drawing across pygame, psychopy, and pyglet backends. Each backend implements this interface with backend-specific window management.

The display owns the window throughout the experiment lifecycle. Users can: - Access raw backend window via window property (Option A: direct access) - Use backend-agnostic helper methods (Option B: abstraction layer)

Parameters:
__init__(settings, shutdown_handler=None)[source]

Initialize display and create window.

Parameters:

  • settings (object) – Settings object containing BACKEND, FULLSCREEN, DISPLAY_INDEX, SCREEN_RES

  • shutdown_handler (object) – Callable to invoke when Ctrl+C detected (for graceful shutdown)

Return type:

None

property window: Any

Get raw backend-specific window object.

This provides direct access to the underlying window for backend-specific operations (Option A).

Returns:

  • pygame: pygame.Surface

  • psychopy: psychopy.visual.Window

  • pyglet: pyglet.window.Window

Return type:

Backend window object

abstract property backend_name: str

Get backend identifier string.

Returns:

“pygame”, “psychopy”, or “pyglet”

Return type:

Backend name

abstractmethod flip()[source]

Update display to show drawn content.

Equivalent to: - pygame: pygame.display.flip() - psychopy: win.flip() - pyglet: window.flip()

Return type:

None

abstractmethod close()[source]

Close window and clean up display resources.

Called during tracker cleanup in end_experiment().

Return type:

None

abstractmethod get_events()[source]

Poll for keyboard and mouse events.

Returns unified event dictionaries that abstract backend differences.

Returns:

  • ‘type’: ‘keydown’, ‘keyup’, ‘quit’, ‘mousebuttondown’, etc.

  • ’key’: key name string (for keyboard events)

  • ’unicode’: unicode character (for keyboard events)

  • ’pos’: (x, y) tuple (for mouse events)

  • ’button’: button number (for mouse events)

Return type:

list[dict[str, Any]]

abstractmethod fill(color)[source]

Fill entire window with specified RGB color.

Parameters:

color (tuple[int, int, int]) – RGB tuple (0-255, 0-255, 0-255)

Return type:

None

Example

display.fill((128, 128, 128)) # Gray background

abstractmethod clear()[source]

Clear window to black.

Convenience method equivalent to fill((0, 0, 0)).

Return type:

None

abstractmethod get_size()[source]

Get window dimensions.

Return type:

tuple[int, int]

Returns:

(width, height) in pixels

abstractmethod draw_text(text, pos=None, center=False, size=24, color=(255, 255, 255))[source]

Draw text on window.

Parameters:

  • text (str) – Text string to display

  • pos (tuple[int, int] | None) – (x, y) position in pixels, None if center=True

  • center (bool) – If True, center text on screen (ignores pos)

  • size (int) – Font size in points

  • color (tuple[int, int, int]) – RGB color tuple (0-255, 0-255, 0-255)

Return type:

None

Example

display.draw_text(“Fixate +”, center=True, size=48) display.draw_text(“Press SPACE”, pos=(100, 100))

abstractmethod draw_image(image_path, pos=None, center=False, scale=None)[source]

Draw image on window.

Parameters:

  • image_path (str | Path) – Path to image file

  • pos (tuple[int, int] | None) – (x, y) position in pixels, None if center=True

  • center (bool) – If True, center image on screen (ignores pos)

  • scale (float | None) – Scale factor (1.0 = original size, 2.0 = double size, etc.)

Return type:

None

Example

display.draw_image(“stimulus.png”, center=True) display.draw_image(“cue.png”, pos=(100, 100), scale=0.5)

wait_for_key(key=None, timeout=None)[source]

Wait for keyboard input.

Helper method that polls events until key pressed or timeout.

Parameters:

  • key (str | None) – Specific key to wait for (e.g., ‘space’, ‘return’), or None for any key

  • timeout (float | None) – Maximum time to wait in seconds, or None to wait indefinitely

Return type:

str | None

Returns:

Key name that was pressed, or None if timeout

wait(duration)[source]

Wait for specified duration while handling events.

Prevents event queue buildup during delays.

Parameters:

duration (float) – Time to wait in seconds

Return type:

None

Pygame Display

Pygame display backend implementation.

class pyelink.display.pygame_display.PygameDisplay(settings, shutdown_handler=None)[source]

Bases: BaseDisplay

Pygame implementation of display window management.

Manages pygame window creation, event handling, and drawing operations. Provides both direct access to pygame.Surface and backend-agnostic helpers.

Parameters:
property backend_name: str

Get backend identifier.

flip()[source]

Update display.

Return type:

None

close()[source]

Close pygame window and quit.

Return type:

None

get_events()[source]

Get pygame events as unified dicts.

Return type:

list[dict[str, Any]]

Returns:

List of event dicts with unified keys

fill(color)[source]

Fill window with color.

Parameters:

color (tuple[int, int, int]) – RGB tuple (0-255, 0-255, 0-255)

Return type:

None

clear()[source]

Clear window to black.

Return type:

None

get_size()[source]

Get window dimensions.

Return type:

tuple[int, int]

Returns:

(width, height) in pixels

draw_text(text, pos=None, center=False, size=24, color=(255, 255, 255))[source]

Draw text on window.

Parameters:

  • text (str) – Text string to display

  • pos (tuple[int, int] | None) – (x, y) position in pixels

  • center (bool) – If True, center text on screen

  • size (int) – Font size in points

  • color (tuple[int, int, int]) – RGB color tuple

Return type:

None

draw_image(image_path, pos=None, center=False, scale=None)[source]

Draw image on window.

Parameters:

  • image_path (str | Path) – Path to image file

  • pos (tuple[int, int] | None) – (x, y) position in pixels

  • center (bool) – If True, center image on screen

  • scale (float | None) – Scale factor for image size

Return type:

None

PsychoPy Display

PsychoPy display backend implementation.

class pyelink.display.psychopy_display.PsychopyDisplay(settings, shutdown_handler=None)[source]

Bases: BaseDisplay

PsychoPy implementation of display window management.

Manages PsychoPy Window creation, event handling, and drawing operations. Provides both direct access to visual.Window and backend-agnostic helpers.

Parameters:
property backend_name: str

Get backend identifier.

flip()[source]

Update display.

Return type:

None

close()[source]

Close PsychoPy window.

Return type:

None

get_events()[source]

Get PsychoPy events as unified dicts.

Return type:

list[dict[str, Any]]

Returns:

List of event dicts with unified keys

fill(color)[source]

Fill window with color.

PsychoPy uses normalized RGB (-1 to 1), so we convert from 0-255.

Parameters:

color (tuple[int, int, int]) – RGB tuple (0-255, 0-255, 0-255)

Return type:

None

clear()[source]

Clear window to black.

Return type:

None

get_size()[source]

Get window dimensions.

Return type:

tuple[int, int]

Returns:

(width, height) in pixels

draw_text(text, pos=None, center=False, size=24, color=(255, 255, 255))[source]

Draw text on window.

Parameters:

  • text (str) – Text string to display

  • pos (tuple[int, int] | None) – (x, y) position in pixels

  • center (bool) – If True, center text on screen

  • size (int) – Font size in points

  • color (tuple[int, int, int]) – RGB color tuple (0-255, 0-255, 0-255)

Return type:

None

draw_image(image_path, pos=None, center=False, scale=None)[source]

Draw image on window.

Parameters:

  • image_path (str | Path) – Path to image file

  • pos (tuple[int, int] | None) – (x, y) position in pixels

  • center (bool) – If True, center image on screen

  • scale (float | None) – Scale factor for image size

Return type:

None

Pyglet Display

Pyglet display backend implementation.

class pyelink.display.pyglet_display.PygletDisplay(settings, shutdown_handler=None)[source]

Bases: BaseDisplay

Pyglet implementation of display window management.

Manages pyglet Window creation, event handling, and drawing operations. Provides both direct access to pyglet.window.Window and backend-agnostic helpers.

Parameters:
__init__(settings, shutdown_handler=None)[source]

Initialize pyglet display.

Parameters:

  • settings (object) – Settings object with display configuration

  • shutdown_handler (object) – Callable for graceful shutdown (optional)

Return type:

None

property backend_name: str

Get backend identifier.

flip()[source]

Update display.

Return type:

None

close()[source]

Close pyglet window.

Return type:

None

get_events()[source]

Get pyglet events as unified dicts.

Return type:

list[dict[str, Any]]

Returns:

List of event dicts with unified keys

fill(color)[source]

Fill window with color.

Parameters:

color (tuple[int, int, int]) – RGB tuple (0-255, 0-255, 0-255)

Return type:

None

clear()[source]

Clear window to black.

Return type:

None

get_size()[source]

Get window dimensions.

Return type:

tuple[int, int]

Returns:

(width, height) in pixels

draw_text(text, pos=None, center=False, size=24, color=(255, 255, 255))[source]

Draw text on window.

Parameters:

  • text (str) – Text string to display

  • pos (tuple[int, int] | None) – (x, y) position in pixels

  • center (bool) – If True, center text on screen

  • size (int) – Font size in points

  • color (tuple[int, int, int]) – RGB color tuple

Return type:

None

draw_image(image_path, pos=None, center=False, scale=None)[source]

Draw image on window.

Parameters:

  • image_path (str | Path) – Path to image file

  • pos (tuple[int, int] | None) – (x, y) position in pixels

  • center (bool) – If True, center image on screen

  • scale (float | None) – Scale factor for image size

Return type:

None