mouse.py

Sub-module providing mouse event handling.

class MouseEvent(button_value: int, x: int, y: int, released: bool, shift: bool, meta: bool, ctrl: bool, is_motion: bool, is_wheel: bool)

Mouse event with button, coordinates, and modifier information.

A unified mouse event structure that supports both legacy and SGR mouse protocols. Provides a dynamic button property that returns human-readable button names like “LEFT”, “SCROLL_UP”, “CTRL_LEFT”, etc.

Variables:

• button_value (int) – Raw button number (0=left, 1=middle, 2=right, 64=scroll up, 65=scroll down, or higher for extended buttons).

• x (int) – Horizontal position (0-indexed, in cells or pixels depending on mode).

• y (int) – Vertical position (0-indexed, in cells or pixels depending on mode).

• released (bool) – True if this is a button release event.

• shift (bool) – True if Shift modifier is pressed.

• meta (bool) – True if Meta/Alt modifier is pressed.

• ctrl (bool) – True if Ctrl modifier is pressed.

• is_motion (bool) – True if motion is being reported (drag or all- motion mode).

• is_wheel (bool) – True if this is a scroll wheel event.

Initialize a MouseEvent.

Parameters:

• button_value (int) – Raw button number.

• x (int) – Horizontal position.

• y (int) – Vertical position.

• released (bool) – Whether this is a button release event.

• shift (bool) – Whether Shift modifier is pressed.

• meta (bool) – Whether Meta/Alt modifier is pressed.

• ctrl (bool) – Whether Ctrl modifier is pressed.

• is_motion (bool) – Whether motion is being reported.

• is_wheel (bool) – Whether this is a scroll wheel event.

property button: str

Return human-readable button name.

Generates button names that include modifiers, button type, motion/release state: - “LEFT”, “MIDDLE”, “RIGHT” for standard mouse buttons - “LEFT_RELEASED”, “MIDDLE_RELEASED”, “RIGHT_RELEASED” for button releases - “SCROLL_UP”, “SCROLL_DOWN” for wheel events - “MOTION” for mouse movement with no button pressed - “LEFT_MOTION”, “MIDDLE_MOTION”, “RIGHT_MOTION” for drag events - “CTRL_LEFT”, “SHIFT_SCROLL_UP”, “CTRL_SHIFT_META_MOTION” with modifiers - “BUTTON_6”, “BUTTON_7”, etc. for extended mouse buttons

Return type:

str

Returns:

Button name with modifiers, button type, and motion/release state.

classmethod from_sgr_match(match: Match[str]) → MouseEvent

Parse SGR mouse event from regex match.

Handles both SGR (mode 1006) and SGR-Pixels (mode 1016) since they use identical wire formats: CSI < b;x;y m/M. The difference is semantic: - Mode 1006: coordinates represent character cell positions - Mode 1016: coordinates represent pixel positions Applications must interpret x,y coordinates based on which mode was enabled.

The protocol sends 1-indexed coordinates (top-left is 1,1), but we convert to 0-indexed (top-left is 0,0) to match blessed’s terminal movement functions.

Parameters:

match (Match) – Regex match object with groups ‘b’, ‘x’, ‘y’, ‘type’.

Return type:

MouseEvent

Returns:

Parsed MouseEvent instance.

classmethod from_legacy_match(match: Match[str]) → MouseEvent

Parse legacy mouse event (X10/1000/1002/1003) from regex match.

The protocol sends 1-indexed coordinates (top-left is 1,1), but we convert to 0-indexed (top-left is 0,0) to match blessed’s terminal movement functions.

Parameters:

match (Match) – Regex match object with groups ‘cb’, ‘cx’, ‘cy’.

Return type:

MouseEvent

Returns:

Parsed MouseEvent instance.

MouseSGREvent

alias of MouseEvent

MouseLegacyEvent

alias of MouseEvent