Events

Handling Keyboard Events

Each time a key is pressed, Counterweight calls the on_key event handler of every element with a KeyPressed event that holds information about which key was pressed.

counterweight.events.KeyPressed dataclass

KeyPressed(key: str)

key instance-attribute

key: str

Handling Mouse Events

Each time the state of the mouse changes, Counterweight emits a single mouse event, one of MouseMoved, MouseDown, MouseUp, MouseScrolledDown, or MouseScrolledUp.

counterweight.events.MouseEvent module-attribute

MouseEvent = Union[
    MouseMoved,
    MouseDown,
    MouseUp,
    MouseScrolledDown,
    MouseScrolledUp,
]

counterweight.events.MouseMoved dataclass

MouseMoved(absolute: Position, button: int | None)

absolute instance-attribute

absolute: Position

The absolute position on the screen that the mouse moved to.

button instance-attribute

button: int | None

The button that was held during the motion, or None if no button was pressed.

counterweight.events.MouseDown dataclass

MouseDown(absolute: Position, button: int)

absolute instance-attribute

absolute: Position

The absolute position on the screen that the mouse moved to.

button instance-attribute

button: int

The mouse button that was pressed during the motion.

counterweight.events.MouseUp dataclass

MouseUp(absolute: Position, button: int)

absolute instance-attribute

absolute: Position

The absolute position on the screen that the mouse moved to.

button instance-attribute

button: int

The mouse button that was released during the motion.

counterweight.events.MouseScrolledDown dataclass

MouseScrolledDown(absolute: Position, direction: int = 1)

absolute instance-attribute

absolute: Position

The absolute position on the screen that the mouse moved to.

direction class-attribute instance-attribute

direction: int = 1

The direction that the mouse was scrolled as an integer offset; -1 for up, +1 for down.

counterweight.events.MouseScrolledUp dataclass

MouseScrolledUp(absolute: Position, direction: int = -1)

absolute instance-attribute

absolute: Position

The absolute position on the screen that the mouse moved to.

direction class-attribute instance-attribute

direction: int = -1

The direction that the mouse was scrolled as an integer offset; -1 for up, +1 for down.

For example, consider the following series of mouse actions and corresponding events:

Action	Event
Mouse starts at position (0, 0)	No event emitted
Mouse moves to position (1, 0)	MouseMoved(position=Position(x=1, y=0), button=None)
Mouse button 1 is pressed	MouseDown(position=Position(x=1, y=0), button=1)
Mouse moves to position (1, 1)	MouseMoved(position=Position(x=1, y=1), button=1)
Mouse button 1 is released	MouseUp(position=Position(x=1, y=1), button=1)
Mouse button 3 is pressed	MouseDown(position=Position(x=1, y=1), button=3)
Mouse moves to position (2, 2) and mouse button 3 is released simultaneously	MouseUp(position=Position(x=2, y=2), button=3)

Mouse Button Identifiers

Mouse buttons are identified by numbers instead of names (e.g., "left", "middle", "right") because the button numbers are the same regardless of whether the mouse is configured for left-handed or right-handed use.

Number	Button for Right-Handed Mouse	Button for Left-Handed Mouse
1	Left	Right
2	Middle	Middle
3	Right	Left

You should always use the numbers instead of names to refer to mouse buttons to ensure that your application works as expected for both left-handed and right-handed users.

Counterweight calls the on_mouse event handler of each element whose border rectangle contains the new mouse position or the previous mouse position with the relevant mouse event object.

use_mouse vs. on_mouse

use_mouse and on_mouse provide similar functionality, but use_mouse is a hook and on_mouse is an event handler. use_mouse is more efficient when a component depends only on the current state of the mouse (e.g., the current position, or whether a button is currently pressed), while on_mouse is more convenient when a component needs to respond to changes in the mouse state, (e.g., a button release MouseUp).