vtterm.mouse

Tell the program on a terminal where it was clicked or touched.

A full-screen program asks for mouse reports with an escape code, and from then on a terminal sends it bytes for each press, release and drag. Mouse makes those bytes from a touchscreen’s points or a desktop’s mouse events, and returns None while no program has asked, so it’s safe to feed all the time.

What a program can ask for, each with ESC [ ? n h:

  • 9: presses only.

  • 1000: presses and releases, and the wheel.

  • 1002: the same, and movement while a button or finger is down.

  • 1003: the same, and all movement.

  • 1006: reports in the SGR form, ESC [ < b ; x ; y M, which has no limit on the column and row. Without it reports are the three bytes after ESC [ M, which stop at column and row 223.

Example

>>> from vtterm.mouse import Mouse
>>> mouse = Mouse(terminal)
>>> report = mouse.touch(120, 64, True)   # a finger lands
>>> if report:
...     link.write(report)
vtterm.mouse.LEFT = 0

Button numbers in a report.

vtterm.mouse.NONE = 3

movement with nothing held.

Type:

No button

vtterm.mouse.mouse_bytes(screen, button, col, row, pressed=True, moved=False)[source]

Return the report for one mouse event, or None if the program didn’t ask for it.

Parameters:
  • screen (Screen) – Its mouse and mouse_sgr modes pick what is reported and in which form.

  • button (int) – LEFT, MIDDLE, RIGHT, WHEEL_UP, WHEEL_DOWN, or NONE for movement with no button held.

  • col (int) – Column of the cell, from 0.

  • row (int) – Row of the cell, from 0.

  • pressed (bool) – False for a release.

  • moved (bool) – The pointer moved to this cell with button held.

Returns:

bytes – What to send the program, or None.

class vtterm.mouse.Mouse(terminal, x=0, y=0)[source]

Bases: object

Turns touches and mouse events on a terminal’s display into reports.

Parameters:
  • terminal (Terminal) – The terminal that was touched.

  • x (int) – Left edge of the terminal’s display, in the coordinates the touches and events use. 0 when it fills the panel.

  • y (int) – Top edge, the same way.

cell

The (col, row) last touched or pointed at.

Type:

tuple

touch(x, y, down)[source]

Report a finger on the display, as the left button.

Call it with each reading of the touchscreen. A finger landing is a press, moving to another cell is a drag, and lifting is a release.

Parameters:
  • x (int) – Pixel column of the touch. Ignored when down is false.

  • y (int) – Pixel row of the touch.

  • down (bool) – Whether a finger is on the display.

Returns:

bytes – What to send the program, or None.

event(e)[source]

Report a mouse event from a display’s get_events.

Parameters:

e – An event with a type. Button events have pos and button (1 left, 2 middle, 3 right), motion events have pos, and wheel events have y, positive away from you.

Returns:

bytes – What to send the program, or None, also for an event that isn’t from a mouse.