Skip to content

Mep22

Jump to bottom Edit New page
Federico Ariza edited this page Jan 29, 2014 · 46 revisions

.. contents:: Table of Contents

.. author:: Federico Ariza

.. date:: January 7, 2014

Status

Progress

Branches and Pull requests

Previous work

Pull Requests:

Abstract

The main goal of this MEP is to make it easier to modify (add, change, remove) the way the user interacts with the figures.

The user interaction with the figure is deeply integrated within the Canvas and Toolbar. Making extremely difficult to do any modification.

This MEP proposes the separation of this interaction into Toolbar, Navigation and Tools to provide independent access and reconfiguration.

This approach will make easier to create and share tools among users. In the far future, we can even foresee a kind of Marketplace for Tools where the most popular can be added into the main distribution.

Detailed description

The reconfiguration of the Toolbar is complex, most of the time it requires a custom backend.

The creation of custom Tools sometimes interferes with the Toolbar, as example see https://github.com/matplotlib/matplotlib/issues/2694 also the shortcuts are hardcoded and again not easily modifiable https://github.com/matplotlib/matplotlib/issues/2699

The proposed solution is to take the actions out of the Toolbar and the shortcuts out of the Canvas. This actions and shortcuts will be in the form of Tools.

A new class Navigation will be the bridge between the events from 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 and connect the all user interactions with the Tools
  • ToolbarBase: This existing class is relegated only as a GUI access to Tools.
  • ToolBase: Is the basic definition of Tools.

Implementation

ToolBase(object)

Tools can have a graphical representation as the SubplotTool or not even be present in the Toolbar as Quit

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

  • keymap = None: Key(s) to be used to trigger the tool
  • position = None: Where is it positionned in the toolbar. -1 = at the end, None = Not in the toolbar. The default tools are all ordered by their position in the Navigation _default_tools array. This argument is mainly used by User created tools that are added after the Toolbar creation.
  • description = '': Small description of the tool
  • name = None: Short string that is used as reference (ID)
  • image = None: Image that is used in the toolbar
  • toggle = False: Is a toggleable tool
  • persistent = False: If True, the instance of the Tool is registered with Navigation for reuse. This is needed because some tools are keept alive in the background, for example SubplotTool.
  • cursor = None: Cursor to use when the tool is active

The following instance attributes are set at instantiation:

  • figure
  • navigation

Methods

  • trigger(self, event): 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)

For ToolBase Tools, the tool.trigger method is called during ToolBase.__init__. The Tool object is only created when the tool is triggered.

Available Tools

  • ToolQuit
  • ToolEnableAllNavigation
  • ToolEnableNavigation
  • ToolToggleGrid
  • ToolToggleFullScreen
  • ToolToggleYScale
  • ToolToggleXScale
  • ToolHome
  • ToolBack
  • ToolForward
  • SaveFigureBase

ToolPersistentBase(ToolBase)

The main difference between ToolPersistentBase and ToolBase is that ToolPersistentBase.__init__ method is called only the first time the tool is triggered. And its object is automatically registered with Navigation. After that, every time the tool is triggered only tool.trigger method is called.

ToolPersistentBase add the following methods

  • unregister(self, *args): Unregisters self from navigation tools instances. After a tool is unregistered, the next time it is triggered the __init__ method will be called (and registered....).

Available Tools

  • ConfigureSubplotsBase

ToolToggleBase(ToolPersistentBase)

The Toggleable Tools, can capture keypress, mouse moves, and mouse button press

It defines the following methods

  • enable(self, event): Called by ToolToggleBase.trigger method
  • disable(self, event): Called when the tool is untoggled
  • toggled : Property True or False

Available Tools

  • ToolZoom
  • ToolPan

NavigationBase

Defines the following attributes

  • canvas:
  • toolbar: Instance of the toolbar or None
  • views: Stack of view limits
  • positions: Stack of positions
  • 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

[@tacaswell, reduced to 2 locks, that navigation actually needs, all the rest is to be handled directly by the tool]

Public methods for User use:

  • remove_tool(self, name): Removes tool from the navigation control.
  • add_tool(self, callback_class): Add a tool to the Navigation
  • list_tools(self): List the available tools with corresponding keymaps
  • active_toggle(self): Property The currently toggled tool or None
  • instances(self): Property dictionary with the persistent tools instances that are registered
  • 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
  • click_tool(self, name): convenient method to programatically click on Tools

Public methods for Tool use:

  • unregister(self, name): Removes the instance associated with name from the persistent tools. used by Tools and not directly by the User
  • remove_rubberband(self, *args): Remove the rubberband. (Before the tools to remove the rubberband called release, but this was kind of confusing)

Private methods to be aware of for Backend implementaiton

  • _toolbar_callback(self, name): Called by the toolbar when button associated with name is pressed

Methods from old NavigationToolbarBase

  • update(self)
  • draw(self)
  • dynamic_update(self)
  • set_cursor(self, cursor)
  • update_view(self)
  • push_current(self)
  • draw_rubberband(self, event, x0, y0, x1, y1)

ToolbarBase

Public methods for User use:

  • add_separator(self, pos): Add a separator to the toolbarbackends
  • move_toolitem(self, pos_ini, pos_fin): Move a toolitem from pos_ini to pos_fin
  • set_toolitem_visibility(self, name, visible): Toggle the visibility of a toolitem

Methods for Backend implementaiton

  • _add_toolitem(self, name, description, image_file, position, toggle): Add a toolitem to the toolbar. This method is called from navigation.add_tool method
  • set_message(self, s): (From old NavigationToolbar)
  • _toggle(self, name, callback=False): Toggle a toggle button, if callback==False don't call navigation._toolbar_callback when toggling the button. This method is called from private method navigation._handle_toggle
  • _remove_toolitem(self, name): Remove toolitem from toolbar. This method is called from navigation.remove_tool

Backward compatibility

For backward compatibility added a 'navigation' key to rcsetup.validate_toolbar, that is used for Navigation classes instantiation instead of the NavigationToolbar classes

With this parameter, it makes it transparent to anyone using the existing backends.

[@pelson comment: This also gives us an opportunity to avoid needing to implement all of this in the same PR - some backends can potentially exist without the new functionality for a short while (but it must be done at some point).]

Alternatives

Add a custom footer
Add a custom sidebar
Clone this wiki locally