devices

eventsys.devices

eventsys.devices

Device classes for eventsys's Event System. May also be used with other applications. Devices are objects that poll for events and return them. They can be subscribed to and unsubscribed from to receive events.

Devices can be created with Broker.create_device() or by calling the constructor of the device class directly. Devices can be subscribed to with .subscribe() and unsubscribed from with .unsubscribe(). Devices can be polled for events with .poll(). Devices can be registered with a broker device with .register_device() and unregistered with .unregister_device(). Devices can be chained together by setting the .broker property of a device to another device.

Devices can be created with the following types: - types.BROKER: A device that polls multiple devices. - types.QUEUE: A device that returns multiple types of events. - types.TOUCH: A device that returns MOUSEBUTTONDOWN when touched, MOUSEMOTION when moved and MOUSEBUTTONUP when released. - types.ENCODER: A device that returns MOUSEWHEEL events when turned, MOUSEBUTTONDOWN when pressed. - types.KEYPAD: A device that returns KEYDOWN and KEYUP events when keys are pressed or released. - types.JOYSTICK: A device that returns joystick events (not implemented).

Classes

types

Device types for the Event System.

Device

Device(read=None, data=None, read2=None, data2=None)

Base class for devices. Must be subclassed. Should not be instantiated directly.

Attributes:

Name	Type	Description
type	Devices	The type of the device.
responses	list	The list of event types that the device can respond to.

Create a new device object.

Parameters:

Name	Type	Description	Default
read	callable	A function that returns an event or None. Defaults to None.	None
data	Any	Data to pass to the read function. Defaults to None.	None
read2	callable	A function that returns a value or None. Defaults to None.	None
data2	Any	Data to pass to the read2 function. Defaults to None.	None

Attributes

broker property writable

broker

The broker that manages this device.

user_data property writable

user_data

User data that can be set and retrieved by applications.

Methods:

poll

poll(*args)

Poll the device for events.

Parameters:

Name	Type	Description	Default
*args		Forwarded to the device read callback when applicable.	()

Returns:

Type	Description
	list | None: Matching events, or None if none were received.

subscribe

subscribe(callback, event_types=None)

Subscribe to events from the device.

Parameters:

Name	Type	Description	Default
callback	function	The function to call when an event is received.	required
event_types	list[int] | None	A list of event types to subscribe to.	None

Raises:

Type	Description
ValueError	If callback is not callable.
ValueError	If any event type in event_types is not a response from this device.

Example

def callback(event):
    print(event)

device.subscribe(callback, [events.MOUSEBUTTONDOWN, events.MOUSEBUTTONUP])

This will call callback when the device receives a MOUSEBUTTONDOWN or MOUSEBUTTONUP event.

unsubscribe

unsubscribe(callback, event_types=None)

Unsubscribes a callback function from one or more event types.

Parameters:

Name	Type	Description	Default
callback	function	The callback function to unsubscribe.	required
event_types	list	A list of event types to unsubscribe from.	None

Broker

Broker()

The Broker class is a device that polls multiple devices for events and forwards them to subscribers.

Attributes:

Name	Type	Description
type	Devices	The type of the device (set to types.BROKER).
responses	list	The list of event types that the device can respond to.
events	events	The events class for convenience. Applications can use Broker.events.KEYDOWN, etc.

Attributes

quit_func property writable

quit_func

The function to call when the window close button is clicked.

broker property writable

broker

The broker that manages this device.

user_data property writable

user_data

User data that can be set and retrieved by applications.

Methods:

subscribe

subscribe(callback, event_types=None, device_types=None)

Subscribes a callback function to receive events.

Parameters:

Name	Type	Description	Default
callback	function	The callback function to subscribe.	required
event_types	list	The list of event types to subscribe to. Defaults to None.	None
device_types	list	The list of device types to subscribe to. Defaults to None.	None

Raises:

Type	Description
ValueError	If the callback is not callable.
ValueError	If both device_types and event_types are provided.
ValueError	If neither device_types nor event_types are provided.

unsubscribe

unsubscribe(callback, event_types=None, device_types=None)

Unsubscribes a callback function from receiving events.

Parameters:

Name	Type	Description	Default
callback	function	The callback function to unsubscribe.	required
event_types	list	The list of event types to unsubscribe from. Defaults to None.	None
device_types	list	The list of device types to unsubscribe from. Defaults to None.	None

Raises:

Type	Description
ValueError	If both device_types and event_types are provided.
ValueError	If neither device_types nor event_types are provided.

create_device

create_device(type=types.QUEUE, **kwargs)

Create a device object.

Parameters:

Name	Type	Description	Default
type	int	The type of device to create. Defaults to types.QUEUE.	QUEUE
**kwargs	Any	Arbitrary keyword arguments for the class constructor.	{}

Returns:

Name	Type	Description
Device	Device	The created device object.

Raises:

Type	Description
ValueError	If the device type is invalid.

register_device

register_device(dev)

Register a device to be polled.

Parameters:

Name	Type	Description	Default
dev	Device	The device object to register.	required

unregister_device

unregister_device(dev)

Unregister a device.

Parameters:

Name	Type	Description	Default
dev	Device	The device object to unregister.	required

quit

quit()

Handle a window-close (QUIT) event. This runs for every front end (LVGL or not), since the QUIT event is handled here in eventsys.

If the application installed a custom quit_func, it is called first for app-specific cleanup. If it returns (for example because sys.exit was swallowed when quit was invoked from a timer or micropython.schedule callback), cleanup falls through to the registered display driver's quit(). With no display registered, the broker's fallback quit_func is used.

poll

poll(*args)

Poll the device for events.

Parameters:

Name	Type	Description	Default
*args		Forwarded to the device read callback when applicable.	()

Returns:

Type	Description
	list | None: Matching events, or None if none were received.

QueueDevice

QueueDevice(*args, **kwargs)

Represents a queue device.

Attributes:

Name	Type	Description
type	str	The type of the device.
responses	list	The list of events that the device can respond to.

Attributes

broker property writable

broker

The broker that manages this device.

user_data property writable

user_data

User data that can be set and retrieved by applications.

Methods:

poll

poll(*args)

Poll the device for events.

Parameters:

Name	Type	Description	Default
*args		Forwarded to the device read callback when applicable.	()

Returns:

Type	Description
	list | None: Matching events, or None if none were received.

subscribe

subscribe(callback, event_types=None)

Subscribe to events from the device.

Parameters:

Name	Type	Description	Default
callback	function	The function to call when an event is received.	required
event_types	list[int] | None	A list of event types to subscribe to.	None

Raises:

Type	Description
ValueError	If callback is not callable.
ValueError	If any event type in event_types is not a response from this device.

Example

def callback(event):
    print(event)

device.subscribe(callback, [events.MOUSEBUTTONDOWN, events.MOUSEBUTTONUP])

This will call callback when the device receives a MOUSEBUTTONDOWN or MOUSEBUTTONUP event.

unsubscribe

unsubscribe(callback, event_types=None)

Unsubscribes a callback function from one or more event types.

Parameters:

Name	Type	Description	Default
callback	function	The callback function to unsubscribe.	required
event_types	list	A list of event types to unsubscribe from.	None

TouchDevice

TouchDevice(*args, **kwargs)

Represents a touch input device.

This class handles touch input events and provides methods to read touch data from the underlying touch driver. It supports reporting mouse button 1 events such as mouse motion, mouse button down, and mouse button up.

Attributes:

Name	Type	Description
type	str	The type of the device (set to types.TOUCH).
responses	tuple	The supported event types for the device.

Parameters:

Name	Type	Description	Default
*args	Any	Variable length argument list.	()
**kwargs	Any	Arbitrary keyword arguments.	{}

Attributes

rotation property writable

rotation

Get the rotation value of the touch device.

Returns:

Name	Type	Description
rotation	int	The rotation value in degrees.

rotation_table property writable

rotation_table

Get the rotation table of the touch device.

Returns:

Type	Description
list	The rotation table.

broker property writable

broker

The broker that manages this device.

user_data property writable

user_data

User data that can be set and retrieved by applications.

Methods:

poll

poll(*args)

Poll the device for events.

Parameters:

Name	Type	Description	Default
*args		Forwarded to the device read callback when applicable.	()

Returns:

Type	Description
	list | None: Matching events, or None if none were received.

subscribe

subscribe(callback, event_types=None)

Subscribe to events from the device.

Parameters:

Name	Type	Description	Default
callback	function	The function to call when an event is received.	required
event_types	list[int] | None	A list of event types to subscribe to.	None

Raises:

Type	Description
ValueError	If callback is not callable.
ValueError	If any event type in event_types is not a response from this device.

Example

def callback(event):
    print(event)

device.subscribe(callback, [events.MOUSEBUTTONDOWN, events.MOUSEBUTTONUP])

This will call callback when the device receives a MOUSEBUTTONDOWN or MOUSEBUTTONUP event.

unsubscribe

unsubscribe(callback, event_types=None)

Unsubscribes a callback function from one or more event types.

Parameters:

Name	Type	Description	Default
callback	function	The callback function to unsubscribe.	required
event_types	list	A list of event types to unsubscribe from.	None

EncoderDevice

EncoderDevice(*args, **kwargs)

A class representing an encoder device.

Attributes:

Name	Type	Description
type	str	The type of the device (ENCODER).
responses	tuple	The events that the device can respond to (MOUSEWHEEL, MOUSEBUTTONDOWN, MOUSEBUTTONUP).

Initializes a new instance of the EncoderDevice class.

Parameters:

Name	Type	Description	Default
*args	Any	Variable length argument list.	()
**kwargs	Any	Arbitrary keyword arguments.	{}

Notes

• self._data is the mouse button number to report for the switch. Default is 2 (middle mouse button). If the mouse button number is even, the wheel will report vertical (y) movement. If the mouse button number is odd, the wheel will report horizontal (x) movement. This corresponds to a typical mouse wheel being button 2 and the wheel moving vertically. It also corresponds to scrolling horizontally on a touchpad with two-finger scrolling and using the right button.

Attributes

broker property writable

broker

The broker that manages this device.

user_data property writable

user_data

User data that can be set and retrieved by applications.

Methods:

poll

poll(*args)

Poll the device for events.

Parameters:

Name	Type	Description	Default
*args		Forwarded to the device read callback when applicable.	()

Returns:

Type	Description
	list | None: Matching events, or None if none were received.

subscribe

subscribe(callback, event_types=None)

Subscribe to events from the device.

Parameters:

Name	Type	Description	Default
callback	function	The function to call when an event is received.	required
event_types	list[int] | None	A list of event types to subscribe to.	None

Raises:

Type	Description
ValueError	If callback is not callable.
ValueError	If any event type in event_types is not a response from this device.

Example

def callback(event):
    print(event)

device.subscribe(callback, [events.MOUSEBUTTONDOWN, events.MOUSEBUTTONUP])

This will call callback when the device receives a MOUSEBUTTONDOWN or MOUSEBUTTONUP event.

unsubscribe

unsubscribe(callback, event_types=None)

Unsubscribes a callback function from one or more event types.

Parameters:

Name	Type	Description	Default
callback	function	The callback function to unsubscribe.	required
event_types	list	A list of event types to unsubscribe from.	None

KeypadDevice

KeypadDevice(*args, **kwargs)

Represents a keypad device.

Attributes:

Name	Type	Description
type	Devices	The type of the device (set to types.KEYPAD).
responses	tuple	The types of events that the device can respond to (set to (events.KEYDOWN, events.KEYUP)).

Methods:

Name	Description
_poll	Polls the keypad for key events.

Attributes

broker property writable

broker

The broker that manages this device.

user_data property writable

user_data

User data that can be set and retrieved by applications.

Methods:

poll

poll(*args)

Poll the device for events.

Parameters:

Name	Type	Description	Default
*args		Forwarded to the device read callback when applicable.	()

Returns:

Type	Description
	list | None: Matching events, or None if none were received.

subscribe

subscribe(callback, event_types=None)

Subscribe to events from the device.

Parameters:

Name	Type	Description	Default
callback	function	The function to call when an event is received.	required
event_types	list[int] | None	A list of event types to subscribe to.	None

Raises:

Type	Description
ValueError	If callback is not callable.
ValueError	If any event type in event_types is not a response from this device.

Example

def callback(event):
    print(event)

device.subscribe(callback, [events.MOUSEBUTTONDOWN, events.MOUSEBUTTONUP])

This will call callback when the device receives a MOUSEBUTTONDOWN or MOUSEBUTTONUP event.

unsubscribe

unsubscribe(callback, event_types=None)

Unsubscribes a callback function from one or more event types.

Parameters:

Name	Type	Description	Default
callback	function	The callback function to unsubscribe.	required
event_types	list	A list of event types to unsubscribe from.	None

JoystickDevice

JoystickDevice(*args, joystick_driver, emulate_digital=None, digital_threshold=0.5, **kwargs)

Represents a joystick device.

Attributes:

Name	Type	Description
type	Devices	The type of the device, set to types.JOYSTICK.
responses	tuple	A tuple of event types that this device can respond to.

Methods:

Name	Description
_poll	Polls the device for events.

Parameters:

Name	Type	Description	Default
joystick_driver	JoystickDriver	The joystick driver to use.	required
emulate_digital [(int,int)]		Emulate digital buttons for the given axis pairs. If set, a hat will be added for each axis pair. The hats will be added after any true hats.	required
digital_threshold	float	The threshold to use for digital emulation.	0.5

Raises: NotImplementedError: If any of the joystick driver methods are not implemented. ValueError: If a hat has an invalid value, e.g. both up and down are true.

Attributes

broker property writable

broker

The broker that manages this device.

user_data property writable

user_data

User data that can be set and retrieved by applications.

Methods:

poll

poll(*args)

Poll the device for events.

Parameters:

Name	Type	Description	Default
*args		Forwarded to the device read callback when applicable.	()

Returns:

Type	Description
	list | None: Matching events, or None if none were received.

subscribe

subscribe(callback, event_types=None)

Subscribe to events from the device.

Parameters:

Name	Type	Description	Default
callback	function	The function to call when an event is received.	required
event_types	list[int] | None	A list of event types to subscribe to.	None

Raises:

Type	Description
ValueError	If callback is not callable.
ValueError	If any event type in event_types is not a response from this device.

Example

def callback(event):
    print(event)

device.subscribe(callback, [events.MOUSEBUTTONDOWN, events.MOUSEBUTTONUP])

This will call callback when the device receives a MOUSEBUTTONDOWN or MOUSEBUTTONUP event.

unsubscribe

unsubscribe(callback, event_types=None)

Unsubscribes a callback function from one or more event types.

Parameters:

Name	Type	Description	Default
callback	function	The callback function to unsubscribe.	required
event_types	list	A list of event types to unsubscribe from.	None

Functions:

custom_type

custom_type(type_name, responses)

Create a new device type with a list of responses.

Parameters:

Name	Type	Description	Default
type_name	str	The name of the device type.	required
responses	list[int]	A list of event types that the device can return.	required

Returns:

Type	Description
Device	The newly created device type.

Raises:

Type	Description
ValueError	If type_name is not a string, responses is not a list, or any response is not an integer.
ValueError	If a device type with the same name already exists in the types class.
ValueError	If a device class with the same name already exists.

Example

To create a custom device type and device class:

from eventsys import devices, events

MyDevice = devices.custom_type("MINE", [events.KEYDOWN, events.KEYUP])