API¶

Contents

mpl_events
mpl_events.filters

mpl_events ¶

`mpl_events.MplEvent`	Defines enumeration for all actual matplotlib events
`mpl_events.MplEventConnection`	Implements the connection to matplotlib event
`mpl_events.MplEventDispatcher`	The base dispatcher class for connecting and handling all matplotlib events

class mpl_events.MplEvent(value)¶

Bases: Enum

Defines enumeration for all actual matplotlib events

Note

The values of enum items represent original matplotlib event names.

KEY_PRESS = 'key_press_event'¶: key is pressed

KEY_RELEASE = 'key_release_event'¶: key is released

MOUSE_BUTTON_PRESS = 'button_press_event'¶: mouse button is pressed

MOUSE_BUTTON_RELEASE = 'button_release_event'¶: mouse button is released

MOUSE_MOVE = 'motion_notify_event'¶: mouse motion

MOUSE_WHEEL_SCROLL = 'scroll_event'¶: mouse scroll wheel is rolled

FIGURE_RESIZE = 'resize_event'¶: figure canvas is resized

FIGURE_ENTER = 'figure_enter_event'¶: mouse enters a figure

FIGURE_LEAVE = 'figure_leave_event'¶: mouse leaves a figure

FIGURE_CLOSE = 'close_event'¶: a figure is closed

AXES_ENTER = 'axes_enter_event'¶: mouse enters a new axes

AXES_LEAVE = 'axes_leave_event'¶: mouse leaves an axes

PICK = 'pick_event'¶: an object in the canvas is selected

DRAW = 'draw_event'¶: canvas draw (but before screen update)

make_connection(mpl_obj: Union[Axes, Figure, FigureCanvasBase], handler: Callable[[Union[KeyEvent, MouseEvent, PickEvent, LocationEvent, ResizeEvent, CloseEvent, DrawEvent]], None], connect: bool = True) → MplEventConnection¶

Creates connection between event with this type and handler and returns instance of MplEventConnection

This method can be used as shortcut for MplEventConnection construction.

Parameters

mpl_objmpl.Figure, mpl.Axes, mpl.FigureCanvasBase: Matplotlib object: Figure, Axes or Canvas
handlercallable: Event handler function/callable with signature: handler(event: MplEvent_Type).
connectbool: If this flag is True, event and handler will be connected immediately

Returns

connMplEventConnection: Connection object

Raises

TypeError: If mpl_object has incorrect type.
ValueError: If mpl figure object has no a canvas.

See also

MplEventConnection

Examples

from matplotlib import pyplot as plt
from mpl_events import MplEvent

def close_handler(event):
    print('figure closing')

figure = plt.figure()
conn = MplEvent.FIGURE_CLOSE.make_connection(figure, close_handler)
plt.show()

class mpl_events.MplEventConnection(mpl_obj: Union[Axes, Figure, FigureCanvasBase], event: MplEvent, handler: Callable[[Union[KeyEvent, MouseEvent, PickEvent, LocationEvent, ResizeEvent, CloseEvent, DrawEvent]], None], connect: bool = True)¶

Bases: object

Implements the connection to matplotlib event

The class manages the connection between a matplotlib event and a handler callable.

This class is high level wrapper for canvas.mpl_connect/canvas.mpl_disconnect matplotlib API.

Parameters

mpl_objmpl.Figure, mpl.Axes, mpl.FigureCanvasBase: Matplotlib object: Figure, Axes or Canvas
eventMplEvent: Event type
handlercallable: Event handler function/callable with signature: handler(event: MplEvent_Type).
connectbool: If this flag is True, event and handler will be connected immediately

Raises

TypeError: If mpl_object has incorrect type.
ValueError: If mpl figure object has no a canvas.

Examples

from mpl_events import MplEventConnection, MplEvent, mpl

def close_handler(event: mpl.CloseEvent):
    print('figure closing')

figure = plt.figure()
conn = MplEventConnection(figure, MplEvent.FIGURE_CLOSE, close_handler)
plt.show()

Attributes

figure: Returns the reference to the related matplotlib figure
event: Returns matplotlib event type as MplEvent enum item
handler: Returns the event handler callable
id: Returns matplotlib event connection id
valid: Retuns True if the connection is valid
connected: Returns True if the handler is connected to the event

property figure: Optional[Figure]¶

Returns the reference to the related matplotlib figure

Returns

figureFigure: Matplotlib figure that is related to this connection

property event: MplEvent¶

Returns matplotlib event type as MplEvent enum item

Returns

eventMplEvent: Event type that is related to this connection

property handler: Callable[[Union[KeyEvent, MouseEvent, PickEvent, LocationEvent, ResizeEvent, CloseEvent, DrawEvent]], None]¶

Returns the event handler callable

Returns

handlercallable: Event handler callable that is related to this connection

property id: int¶

Returns matplotlib event connection id

Returns

idint: Matplotlib connection identifier

property valid: bool¶

Retuns True if the connection is valid

The connection is valid if the related matplotlib figure has not been destroyed.

Returns

validbool: True if the connection is valid

property connected: bool¶

Returns True if the handler is connected to the event

Returns

connectedbool: True if the handler is connected to the event

connect()¶: Connects the handler to the event

disconnect()¶: Disconnects the handler from the event

class mpl_events.MplEventDispatcher(mpl_obj: Union[Axes, Figure, FigureCanvasBase], connect: bool = True)¶

Bases: object

The base dispatcher class for connecting and handling all matplotlib events

You can use this class as base class for your matplotlib event dispatcher.

MplEventDispatcher class provides API (handler methods interface) for all matplotlib events. You may override and implement some of these methods for handling corresponding events.

Parameters

mpl_objmpl.Figure, mpl.Axes, mpl.FigureCanvasBase: Matplotlib object: Figure, Axes or Canvas
connectbool: If this flag is True (default), all events and handlers will be connected immediately

Raises

TypeError: If mpl_object has incorrect type.
ValueError: If mpl figure object has no a canvas.

Examples

from matplotlib import pyplot as plt
from mpl_events import MplEventDispatcher, mpl

class KeyEventDispatcher(MplEventDispatcher):

    disable_default_handlers = True

    def on_key_press(self, event: mpl.KeyEvent):
        print(f'Pressed key {event.key}')

    def on_key_release(self, event: mpl.KeyEvent):
        print(f'Released key {event.key}')

figure = plt.figure()
dispatcher = KeyEventDispatcher(figure)
plt.show()

Attributes

figure: Returns the reference to the related matplotlib figure
valid: Retuns True if the dispatcher is valid
mpl_connections: Returns the mapping for all connections for this event dispatcher instance
event_filter

disable_default_handlers: bool = False¶

If flag is True default handlers will be disabled

See also

disable_default_key_press_handler

property figure: Optional[Figure]¶

Returns the reference to the related matplotlib figure

Returns

figureFigure: Matplotlib figure that is related to this dispatcher

property valid: bool¶

Retuns True if the dispatcher is valid

The dispatcher is valid if the related matplotlib figure has not been destroyed.

Returns

validbool: True if the dispatcher is valid

property mpl_connections: Dict[MplEvent, MplEventConnection]¶

Returns the mapping for all connections for this event dispatcher instance

Returns mapping in this form:

{
    event_type1: connection1,
    event_type2: connection2,
}

Returns

mpl_connectionsDict[MplEvent, MplEventConnection]: The mapping for all connections for this event dispatcher instance

property event_filters: List[Callable[[MplEventDispatcher, Union[KeyEvent, MouseEvent, PickEvent, LocationEvent, ResizeEvent, CloseEvent, DrawEvent]], Optional[bool]]]¶

Returns list of event filters that have been set for this dispatcher

Returns

event_filters: List[callable]: List of event filter callables

mpl_connect()¶: Connects the implemented event handlers to the related matplotlib events for this instance

mpl_disconnect()¶: Disconnects the implemented handlers from the related matplotlib events for this instance

add_event_filter(filter_obj: Callable[[MplEventDispatcher, Union[KeyEvent, MouseEvent, PickEvent, LocationEvent, ResizeEvent, CloseEvent, DrawEvent]], Optional[bool]], prepend: bool = False)¶

Adds the event filter for this dispatcher

The event filters can be used for filtering mpl events in a dispatcher class.

Parameters

filter_obj: callable: Event filter callable
prepend: bool: Add filter to begin of list instead of append to end

Raises

TypeErrorIf filter_obj is not callable

Examples

class Dispatcher(MplEventDispatcher):
    def on_key_press(self, event: mpl.KeyEvent):
        pass
    def on_key_release(self, event: mpl.KeyEvent):
        pass

def event_filter(obj: MplEventDispatcher, event: MplEvent_Type):
    if isinstance(obj, Dispatcher) and event.name == MplEvent.KEY_PRESS.value:
        # do something...

        # If the filter returns True, the handler for the event
        # in "Dispatcher" class will not be called
        return True

dispatcher = Dispatcher(figure)
dispatcher.add_event_filter(event_filter)

remove_event_filter(filter_obj: Callable[[MplEventDispatcher, Union[KeyEvent, MouseEvent, PickEvent, LocationEvent, ResizeEvent, CloseEvent, DrawEvent]], Optional[bool]])¶

Removes the event filter for this dispatcher

The request is ignored if such an event filter has not been added.

Parameters

filter_obj: callable: Event filter callable

on_key_press(event: KeyEvent)¶: KeyEvent – key is pressed

on_key_release(event: KeyEvent)¶: KeyEvent – key is released

on_mouse_button_press(event: MouseEvent)¶: MouseEvent – mouse button is pressed

on_mouse_button_release(event: MouseEvent)¶: MouseEvent – mouse button is released

on_mouse_move(event: MouseEvent)¶: MouseEvent – mouse motion

on_mouse_wheel_scroll(event: MouseEvent)¶: MouseEvent – mouse scroll wheel is rolled

on_figure_resize(event: ResizeEvent)¶: ResizeEvent – figure canvas is resized

on_figure_enter(event: LocationEvent)¶: LocationEvent – mouse enters a new figure

on_figure_leave(event: LocationEvent)¶: LocationEvent – mouse leaves a figure

on_figure_close(event: CloseEvent)¶: CloseEvent – a figure is closed

on_axes_enter(event: LocationEvent)¶: LocationEvent – mouse enters a new axes

on_axes_leave(event: LocationEvent)¶: LocationEvent – mouse leaves an axes

on_pick(event: PickEvent)¶: PickEvent – an object in the canvas is selected

on_draw(event: DrawEvent)¶: DrawEvent – canvas draw (but before screen update)

mpl_events.mpl_event_handler(event_type: MplEvent)¶

Marks the decorated method as given matplotlib event handler

Note

This decorator should be used only for methods of classes that inherited from MplEventDispatcher class.

This decorator can be used for reassignment event handlers in a dispatcher class.

Examples

from mpl_events import MplEventDispatcher, mpl_event_handler, mpl

class MyEventDispatcher(MplEventDispatcher):
    @mpl_event_handler(MplEvent.KEY_PRESS)
    def on_my_key_press(self, event: mpl.KeyPress):
        pass

mpl_events.disable_default_key_press_handler(mpl_obj: Union[Axes, Figure, FigureCanvasBase])¶

Disables default key_press handling for given figure/canvas

The default key handler using the toolmanager.

Parameters

mpl_objmpl.Figure, mpl.Axes, mpl.FigureCanvasBase: Matplotlib object: Figure, Axes or Canvas

mpl_events.filters ¶

The module contains some event filters that can be useful

class mpl_events.filters.LoggingEventFilter¶

Logging events

The filter logs all events that will be handled.

Note

This event filter should be append to end of of event filters list.

class mpl_events.filters.MouseDoubleClickReleaseEventFilter¶

Sets correct value of dblclick flag to MOUSE_BUTTON_RELEASE event

The filter adds true dblclick flag to MOUSE_BUTTON_RELEASE event if dblclick is True in previous MOUSE_BUTTON_PRESS event.

API¶

mpl_events ¶

mpl_events.filters ¶

mpl-events

Navigation

Related Topics

API¶

mpl_events¶

mpl_events.filters¶

mpl_events ¶

mpl_events.filters ¶