Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 55 additions & 35 deletions doc/devel/MEP/MEP22.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ Pull Requests:
* Removing the NavigationToolbar classes
https://github.com/matplotlib/matplotlib/pull/2740 **CLOSED**
* Keeping the NavigationToolbar classes https://github.com/matplotlib/matplotlib/pull/2759 **CLOSED**
* Navigation by events: https://github.com/matplotlib/matplotlib/pull/3652
* Navigation by events: https://github.com/matplotlib/matplotlib/pull/3652 **MERGED**
* Implementation for QT https://github.com/matplotlib/matplotlib/pull/9934

Abstract
========
Expand Down Expand Up @@ -62,11 +63,12 @@ the `Canvas` and `Toolbar` and redirect them to the appropiate `Tool`.

At the end the user interaction will be divided into three classes:

* NavigationBase: This class is instantiated for each FigureManager
* ToolManager: This class is instantiated for each FigureManager
and connect the all user interactions with the Tools
* ToolbarBase: This existing class is relegated only as a GUI access
* ToolContainerBase: This class is relegated only as a GUI access
to Tools.
* ToolBase: Is the basic definition of Tools.
* ToolBase and ToolToggleBase: Are the basic definition of Tools.
* StatusbarBase: This class is instatiated for each FigureManager, used to display messages


Implementation
Expand All @@ -79,35 +81,45 @@ Tools can have a graphical representation as the `SubplotTool` or not even be pr

The `ToolBase` has the following class attributes for configuration at definition time

* keymap = None: Key(s) to be used to trigger the tool
* default_keymap = None: Key(s) to be used to trigger the tool
* description = '': Small description of the tool
* image = None: Image that is used in the toolbar

The following instance attributes are set at instantiation:
* name
* navigation
* toolmanager

**Methods**
* trigger(self, event): This is the main method of the Tool, it is called when the Tool is triggered by:
* trigger(self, sender, event, data=None): This is the main method of the Tool, it is called when the Tool is triggered by:
* Toolbar button click
* keypress associated with the Tool Keymap
* Call to navigation.trigger_tool(name)
* set_figure(self, figure): Set the figure and navigation attributes
* ``destroy(self, *args)``: Destroy the `Tool` graphical interface (if exists)
* Call to toolmanager.trigger_tool(name)
* figure (property):
* getter: returns the current figure that the tool is associated to
* setter: Set the figure
* ``destroy(self)``: Destroy the `Tool` graphical interface (if exists)

**Available Tools**
* ToolQuit
* ToolEnableAllNavigation
* ToolEnableNavigation
* ToolToggleGrid
* ToolToggleFullScreen
* ToolToggleYScale
* ToolToggleXScale
* ToolHome
* ToolBack
* ToolForward
* SaveFigureBase
* ConfigureSubplotsBase
* ToolHome
* ToolBack
* ToolForward
* ToolZoom
* ToolPan
* ToolConfigureSubplots
* ToolSaveFigure
* ToolGrid
* ToolMinorGrid
* ToolFullScreen,
* ToolQuit
* ToolQuitAll
* ToolEnableAllNavigation
* ToolEnableNavigation
* ToolXScale
* ToolYScale
* ToolCursorPosition
* ToolViewsPositions
* ToolSetCursor
* ToolRubberband


ToolToggleBase(ToolBase)
Expand All @@ -119,6 +131,7 @@ configuration at definition time
* radio_group = None: Attribute to group 'radio' like tools (mutually
exclusive)
* cursor = None: Cursor to use when the tool is active
* default_toggled = False: Initial state of the toggle

The **Toggleable** Tools, can capture keypress, mouse moves, and mouse
button press
Expand All @@ -132,51 +145,58 @@ It defines the following methods
* ToolZoom
* ToolPan

NavigationBase
--------------

ToolManager
-----------

Defines the following attributes
* canvas:
* keypresslock: Lock to know if the `canvas` key_press_event` is
available and process it
* messagelock: Lock to know if the message is available to write
* figure (property):
* getter: returns the current figure
* setter: Set the figure

Public methods for **User use**:
* nav_connect(self, s, func): Connect to to navigation for events
* nav_disconnect(self, cid): Disconnect from navigation event
* toolmanager_connect(self, s, func): Connect to toolmanager for events
* toolmanager_disconnect(self, cid): Disconnect from navigation event
* message_event(self, message, sender=None): Emit a
tool_message_event event
* active_toggle(self): **Property** The currently toggled tools or
None
* get_tool_keymap(self, name): Return a list of keys that are
associated with the tool
* set_tool_keymap(self, name, ``*keys``): Set the keys for the given tool
* update_keymap(self, name, ``*keys``): Set the keys for the given tool
* remove_tool(self, name): Removes tool from the navigation control.
* add_tools(self, tools): Add multiple tools to `Navigation`
* add_tool(self, name, tool, group=None, position=None): Add a tool
to the Navigation
* tool_trigger_event(self, name, sender=None, canvasevent=None,
* add_tool(self, name, tool, *args, **kwargs): Add tool to ToolManager
* trigger_tool(self, name, sender=None, canvasevent=None,
data=None): Trigger a tool and fire the event

* tools(self) **Property**: Return a dict with available tools with
corresponding keymaps, descriptions and objects
* get_tool(self, name): Return the tool object



ToolbarBase
-----------
ToolContainerBase
-----------------

Methods for **Backend implementation**
* add_toolitem(self, name, group, position, image, description,
toggle): Add a toolitem to the toolbar. This method is a callback
from `tool_added_event` (emited by navigation)
* set_message(self, s): Display a message on toolbar or in status bar
* toggle_toolitem(self, name): Toggle the toolitem without firing
event.
* remove_toolitem(self, name): Remove a toolitem from the `Toolbar`


StatusbarBase
-------------
Methods for **Backend implementation**
* set_message(self, s): Display a message in the status bar



Backward compatibility
======================

Expand Down