Event handling

Overview

The plotpy.events module provides classes to handle events on a plotpy.plot.PlotWidget.

The following classes are available:

Reference

class plotpy.events.StatefulEventFilter(parent: BasePlot)[source]

State machine for handling events of a plot’s canvas

Parameters:

parent – plot on which to install the event filter

eventFilter(_obj: QObject, event: QEvent) → bool[source]

The eventfilter callback for Qt

set_state(state: int, event: QEvent) → None[source]

Change the current state. Can be called by handlers to cancel a state change

Parameters:

  • state – new state

  • event – event that triggered the state change

new_state() → int[source]

Create (reserve) a new state number

Returns:

New state number

add_event(state: int, match: EventMatch, call: callable, next_state: int = None) → int[source]

Add a transition to the state machine. If next_state is provided, it must correspond to an existing state, otherwise a new destination state is created

Parameters:

  • state – current state

  • match – event matcher

  • call – callable to execute when the event matches

  • next_state – next state to go to when the event matches

Returns:

Next state number

nothing(filter: StatefulEventFilter, event: QEvent) → None[source]

A nothing filter, provided to help removing duplicate handlers

Parameters:

  • filter – event filter that contains the BasePlot instance

  • event – event that triggered the action

set_cursor(cursor: CursorShape, *states: int) → None[source]

Associate a cursor with one or more states

Parameters:

  • cursor – cursor shape

  • states – state numbers

get_cursor(_event: QEvent) → CursorShape | None[source]

Get the cursor associated with a given state/event

Returns:

Cursor shape or None if no cursor is associated with the state

mouse_press(btn: int, modifiers: int = 0) → MouseEventMatch[source]

Create a filter for the MousePress event

Parameters:

  • btn – button to match

  • modifiers – keyboard modifiers to match

Returns:

An instance of MouseEventMatch that matches the MousePress event

mouse_move(btn: int, modifiers: int = 0) → MouseEventMatch[source]

Create a filter for the MouseMove event

Parameters:

  • btn – button to match

  • modifiers – keyboard modifiers to match

Returns:

An instance of MouseEventMatch that matches the MouseMove event

mouse_release(btn: int, modifiers: int = 0) → MouseEventMatch[source]

Create a filter for the MouseRelease event

Parameters:

  • btn – The button to match

  • modifiers – The keyboard modifiers to match

Returns:

An instance of MouseEventMatch that matches the MouseRelease event

gesture(kind: int, state: int) → GestureEventMatch[source]

Create a filter for the gesture event

Parameters:

  • kind – The type of gesture

  • state – The state of the gesture

Returns:

An instance of GestureEventMatch that matches the gesture event

wheel(modifiers: int = 0) → WheelEventMatch[source]

Create a filter for wheel events

Parameters:

modifiers – The keyboard modifiers to use with the wheel event

Returns:

An instance of WheelEventMatch that matches the wheel event

class plotpy.events.KeyEventMatch(keys: list[int | tuple[int, int]])[source]

A callable returning True if it matches a key event

Parameters:

keys – list of keys or couples (key, modifier)

get_event_types() → frozenset[int][source]

Return the set of event types handled by this event match

class plotpy.events.StandardKeyMatch(keysequence: int)[source]

A callable returning True if it matches a key event

Parameters:

keysequence – QKeySequence.StandardKey integer

get_event_types() → frozenset[int][source]

Return the set of event types handled by this event match

class plotpy.events.MouseEventMatch(evt_type: int, btn: int, modifiers: int = 0)[source]

Base class for matching mouse events

Parameters:

  • evt_type – event type

  • btn – button to match

  • modifiers – keyboard modifiers to match

get_event_types() → frozenset[int][source]

Return the set of event types handled by this event match

class plotpy.events.GestureEventMatch(gesture_type: int, gesture_state: int)[source]

Base class for matching gesture events

get_event_types() → frozenset[int][source]

Return the set of event types handled by this event match

class plotpy.events.DragHandler(filter: StatefulEventFilter, btn: int, mods: int = 0, start_state: int = 0)[source]

Base class for click-drag-release event handlers.

Parameters:

  • filter – The StatefulEventFilter instance.

  • btn – The mouse button to match.

  • mods – The keyboard modifiers to match. (default: QC.Qt.NoModifier)

  • start_state – The starting state. (default: 0)

get_move_state(filter: StatefulEventFilter, pos: QPointF) → tuple[float, float][source]

Get the movement state based on the current filter and position

Parameters:

  • filter – The StatefulEventFilter instance

  • pos – The current position

Returns:

A tuple containing the movement state in the x and y directions

start_tracking(_filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Start tracking the mouse movement

Parameters:

  • _filter – The StatefulEventFilter instance

  • event – The mouse event

start_moving(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Start moving the mouse

Parameters:

  • filter – The StatefulEventFilter instance

  • event – The mouse event

stop_tracking(_filter: StatefulEventFilter, _event: QMouseEvent) → None[source]

Stop tracking the mouse movement

Parameters:

  • _filter – The StatefulEventFilter instance

  • _event – The mouse event

stop_notmoving(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Stop tracking the mouse movement when the mouse is not moving.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

stop_moving(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Stop moving the mouse

Parameters:

  • filter – The StatefulEventFilter instance

  • event – The mouse event

move(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Move the mouse

Parameters:

  • filter – The StatefulEventFilter instance

  • event – The mouse event

class plotpy.events.ClickHandler(filter: StatefulEventFilter, btn: int, mods: int = 0, start_state: int = 0)[source]

Base class for click-release event handlers.

Parameters:

  • filter – The StatefulEventFilter instance.

  • btn – The mouse button to match.

  • mods – The keyboard modifiers to match. (default: QC.Qt.NoModifier)

  • start_state – The starting state. (default: 0)

Signals:

SIG_CLICK_EVENT: Signal emitted by ClickHandler on mouse click

click(filter: StatefulEventFilter, event: QEvent) → None[source]

Handle the click event.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

class plotpy.events.PanHandler(filter: StatefulEventFilter, btn: int, mods: int = 0, start_state: int = 0)[source]
move(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Move the mouse.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

class plotpy.events.ZoomHandler(filter: StatefulEventFilter, btn: int, mods: int = 0, start_state: int = 0)[source]
move(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Move the mouse.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

class plotpy.events.GestureHandler(filter: StatefulEventFilter, start_state: int = 0)[source]

Base class used to handle gestures.

Parameters:

  • filter – event filter into which to add the handler instance.

  • start_state – start state to use in the event filter state machine. Defaults to 0.

get_glob_position(event: QGestureEvent) → QPointF[source]

Returns the hotspot global position of the gesture event.

Parameters:

event – event from which to get the position

Returns:

event hotspot poisition in global coordinates.

get_gesture(event: QGestureEvent) → QGesture[source]

Returns the gesture from the event.

Parameters:

event – event from which to get the gesture.

Returns:

gesture from the event.

start_tracking(filter: StatefulEventFilter, event: QGestureEvent) → None[source]

Handles the start of the gesture tracking.

Parameters:

  • filter – event filter that contains the BasePlot instance

  • event – event that triggered the start of the tracking, used to get a position.

start_moving(filter: StatefulEventFilter, event: QGestureEvent) → None[source]

Handles the start of the gesture moving.

Parameters:

  • filter – event filter that contains the BasePlot instance

  • event – event that triggered the start of the moving

stop_tracking(_filter: StatefulEventFilter, _event: QGestureEvent) → None[source]

Handles the stop of the gesture tracking.

Parameters:

  • _filter – event filter that contains the BasePlot instance

  • _event – event that triggered the stop of the tracking

move(filter: StatefulEventFilter, event: QGestureEvent) → None[source]

Handles the movement of the gesture.

Parameters:

  • filter – event filter that contains the BasePlot instance

  • event – event that triggered the movement

class plotpy.events.PinchPanGestureHandler(filter: StatefulEventFilter, start_state=0)[source]

Class used to handle pinch and pan gestures.

Parameters:

  • filter – event filter into which to add the handler instance.

  • start_state – start state to use in the event filter state machine. Defaults to 0.

get_pan_param(plot: BasePlot, pos: QPoint) → tuple[tuple[float, float, float, float], tuple[float, float, float, float]][source]

Returns the parameters to use for panning the plot.

Parameters:

  • plot – instance of BasePlot to use as a reference.

  • pos – position on the plot canvas of the current hotspot.

Returns:

Returns two tuples of four floats each, representing the parameters used by BasePlot.do_pan_view.

get_zoom_param(plot: BasePlot, pos: QPoint, factor: float) → tuple[tuple[float, float, float, float], tuple[float, float, float, float]][source]

Returns the parameters to use for zooming on the plot.

Parameters:

  • plot – instance of BasePlot to use as a reference.

  • pos – position on the plot canvas of the current hotspot.

  • factor – factor by which to zoom (zero-centered).

Returns:

Returns two tuples of four floats each, representing the parameters used by BasePlot.do_zoom_view.

start_tracking(filter: StatefulEventFilter, event: QGestureEvent) → None[source]

Overrides the GestureHandler.start_tracking method to add a marker at the hostpot of the pinch gesture.

Parameters:

  • filter – event filter that contains the BasePlot instance

  • event – Gesture event that triggered the start of the tracking, used to get a position.

move(filter: StatefulEventFilter, event: QGestureEvent) → None[source]

Overrides the GestureHandler.move method to handle the pinch and pan gesture.

Parameters:

  • filter – event filter that contains the BasePlot instance

  • event – event that triggered the move, used to get the hotspot position.

stop_tracking(_filter: StatefulEventFilter, _event: QGestureEvent) → None[source]

Overrides the GestureHandler.stop_tracking method to remove the marker when the gesture tracking stops.

Parameters:

  • _filter – event filter that contains the BasePlot instance

  • _event – event that triggered the stop, not used.

class plotpy.events.MenuHandler(filter: StatefulEventFilter, btn: int, mods: int = 0, start_state: int = 0)[source]

Class to handle context menu events.

click(filter: StatefulEventFilter, event: QEvent) → None[source]

Handles the click event.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The QC.QEvent instance.

class plotpy.events.QtDragHandler(filter: StatefulEventFilter, btn: int, mods: int = 0, start_state: int = 0)[source]

Class to handle drag events using Qt signals.

start_tracking(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Starts tracking the drag event.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The QC.QEvent instance.

stop_notmoving(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Stops tracking when the drag event is not moving.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The QC.QEvent instance.

stop_moving(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Stops the movement of the drag event.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The QC.QEvent instance

move(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Handles the move event.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The QC.QEvent instance.

class plotpy.events.AutoZoomHandler(filter: StatefulEventFilter, btn: int, mods: int = 0, start_state: int = 0)[source]

Class to handle auto-zoom events.

click(filter: StatefulEventFilter, _event: QEvent) → None[source]

Handles the click event.

Parameters:

  • filter – The StatefulEventFilter instance.

  • _event – The QC.QEvent instance.

class plotpy.events.MoveHandler(filter: StatefulEventFilter, btn: MouseButton = 0, mods: KeyboardModifiers = 0, start_state: int = 0)[source]

Class to handle moving events.

Parameters:

  • filter – The StatefulEventFilter instance.

  • btn – The mouse button to match.

  • mods – The keyboard modifiers to match. (default: QC.Qt.NoModifier)

  • start_state – The starting state. (default: 0)

move(filter: StatefulEventFilter, event: QGestureEvent) → None[source]

Handles the move event.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The QGestureEvent instance.

class plotpy.events.ObjectHandler(filter: StatefulEventFilter, btn: int, mods: KeyboardModifiers = 0, start_state: int = 0, multiselection: bool = False)[source]

Base class for handling objects.

Parameters:

  • filter – The StatefulEventFilter instance.

  • btn – The mouse button to match.

  • mods – The keyboard modifiers to match. (default: QC.Qt.NoModifier)

  • start_state – The starting state. (default: 0)

  • multiselection – Whether to allow multiple selections. (default: False)

property active: Any

Return active object

add_undo_move_action(undo_action: Any) → None[source]

Add undo action to undo stack

undo(filter: StatefulEventFilter, event: QEvent) → None[source]

Undo the last action.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The event triggering the undo action.

redo(filter: StatefulEventFilter, event: QEvent) → None[source]

Redo the last action.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The event triggering the redo action.

start_tracking(filter: StatefulEventFilter, event: QEvent) → None[source]

Starts tracking the mouse movement for selection and interaction.

Parameters:

  • filter – The filter object.

  • event – The mouse event.

move(filter: StatefulEventFilter, event: QEvent) → None[source]

Move the object.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

stop_tracking(filter: StatefulEventFilter, event: QEvent) → None[source]

Stop tracking the object.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

class plotpy.events.RectangularSelectionHandler(filter: StatefulEventFilter, btn: int, mods: KeyboardModifiers = 0, start_state: int = 0)[source]

Base class for handling rectangular selections.

Parameters:

  • filter – The StatefulEventFilter instance.

  • btn – The mouse button to match.

  • mods – The keyboard modifiers to match. (default: QC.Qt.NoModifier)

  • start_state – The starting state. (default: 0)

set_shape(shape: Any, h0: Any, h1: Any, setup_shape_cb: Callable | None = None, avoid_null_shape: bool = False) → None[source]

Set the shape.

Parameters:

  • shape – The shape.

  • h0 – The first handle.

  • h1 – The second handle.

  • setup_shape_cb – The setup shape callback.

  • avoid_null_shape – Whether to avoid null shape.

start_tracking(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Start tracking the mouse movement for selection and interaction.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

start_moving(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Start moving the object.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

start_moving_action(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Start moving the object.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

move(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Move the object.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

move_action(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Move the object.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

stop_moving(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Stop moving the object.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

stop_moving_action(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Stop moving the object.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

class plotpy.events.PointSelectionHandler(filter: StatefulEventFilter, btn: int, mods: KeyboardModifiers = 0, start_state: int = 0)[source]

Class to handle point selections.

stop_notmoving(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Stop the point selection when the point is not moving.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.

class plotpy.events.ZoomRectHandler(filter: StatefulEventFilter, btn: int, mods: KeyboardModifiers = 0, start_state: int = 0)[source]

Class to handle zoom rectangles.

stop_moving_action(filter: StatefulEventFilter, event: QMouseEvent) → None[source]

Stop moving the object.

Parameters:

  • filter – The StatefulEventFilter instance.

  • event – The mouse event.