Merge pull request matplotlib#3652 from fariza/navigation-by-events

MEP22: Navigation by events

Author: WeatherGod

doc/api/backend_managers_api.rst

@@ -0,0 +1,8 @@
+
+:mod:`matplotlib.backend_managers`
+===================================
+
+.. automodule:: matplotlib.backend_managers
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/backend_tools_api.rst

@@ -0,0 +1,8 @@
+
+:mod:`matplotlib.backend_tools`
+================================
+
+.. automodule:: matplotlib.backend_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/index_backend_api.rst

@@ -5,6 +5,8 @@ backends
 .. toctree::
 
    backend_bases_api.rst
+   backend_managers_api.rst
+   backend_tools_api.rst
    backend_gtkagg_api.rst
    backend_qt4agg_api.rst
    backend_wxagg_api.rst

doc/users/whats_new/rcparams.rst

@@ -15,9 +15,17 @@ Added "figure.titlesize" and "figure.titleweight" keys to rcParams
 Two new keys were added to rcParams to control the default font size and weight
 used by the figure title (as emitted by ``pyplot.suptitle()``).
 
+
 ``image.composite_image`` added to rcParams
 ```````````````````````````````````````````
 Controls whether vector graphics backends (i.e. PDF, PS, and SVG) combine
 multiple images on a set of axes into a single composite image.  Saving each
 image individually can be useful if you generate vector graphics files in
 matplotlib and then edit the files further in Inkscape or other programs.
+
+
+Added "toolmanager" to "toolbar" possible values
+````````````````````````````````````````````````
+
+The new value enables the use of ``ToolManager``
+

doc/users/whats_new/toolmanager.rst

@@ -0,0 +1,68 @@
+ToolManager
+-----------
+
+Federico Ariza wrote the new `matplotlib.backend_managers.ToolManager` that comes as replacement for `NavigationToolbar2`
+
+`ToolManager` offers a new way of looking at the user interactions with the figures.
+Before we had the `NavigationToolbar2` with its own tools like `zoom/pan/home/save/...` and also we had the shortcuts like
+`yscale/grid/quit/....`
+`Toolmanager` relocate all those actions as `Tools` (located in `matplotlib.backend_tools`), and defines a way to `access/trigger/reconfigure` them.
+
+The `Toolbars` are replaced for `ToolContainers` that are just GUI interfaces to `trigger` the tools. But don't worry the default backends include a `ToolContainer` called `toolbar`
+
+
+.. note::
+	For the moment the `ToolManager` is working only with `GTK3` and `Tk` backends.
+	Make sure you are using one of those.
+	Port for the rest of the backends is comming soon.
+	
+	To activate the `ToolManager` include the following at the top of your file:
+	
+	 >>> matplotlib.rcParams['toolbar'] = 'toolmanager'
+	
+
+Interact with the ToolContainer
+```````````````````````````````
+
+The most important feature is the ability to easily reconfigure the ToolContainer (aka toolbar).
+For example, if we want to remove the "forward" button we would just do.
+
+ >>> fig.canvas.manager.toolmanager.remove_tool('forward')
+
+Now if you want to programmatically trigger the "home" button
+
+ >>> fig.canvas.manager.toolmanager.trigger_tool('home')
+
+
+New Tools
+`````````
+
+It is possible to add new tools to the ToolManager
+
+A very simple tool that prints "You're awesome" would be::
+
+    from matplotlib.backend_tools import ToolBase
+    class AwesomeTool(ToolBase):
+        def trigger(self, *args, **kwargs):
+            print("You're awesome")
+
+
+To add this tool to `ToolManager`
+
+ >>> fig.canvas.manager.toolmanager.add_tool('Awesome', AwesomeTool)
+
+If we want to add a shortcut ("d") for the tool
+
+ >>> fig.canvas.manager.toolmanager.update_keymap('Awesome', 'd')
+
+
+To add it to the toolbar inside the group 'foo'
+
+ >>> fig.canvas.manager.toolbar.add_tool('Awesome', 'foo')
+
+
+There is a second class of tools, "Toggleable Tools", this are almost the same as our basic tools, just that belong to a group, and are mutually exclusive inside that group.
+For tools derived from `ToolToggleBase` there are two basic methods `enable` and `disable` that are called automatically whenever it is toggled.
+
+
+A full example is located in :ref:`user_interfaces-toolmanager`

examples/user_interfaces/toolmanager.py

@@ -0,0 +1,92 @@
+'''This example demonstrates how to:
+* Modify the Toolbar
+* Create tools
+* Add tools
+* Remove tools
+Using `matplotlib.backend_managers.ToolManager`
+'''
+
+
+from __future__ import print_function
+import matplotlib
+matplotlib.use('GTK3Cairo')
+matplotlib.rcParams['toolbar'] = 'toolmanager'
+import matplotlib.pyplot as plt
+from matplotlib.backend_tools import ToolBase, ToolToggleBase
+from gi.repository import Gtk, Gdk
+
+
+class ListTools(ToolBase):
+    '''List all the tools controlled by the `ToolManager`'''
+    # keyboard shortcut
+    default_keymap = 'm'
+    description = 'List Tools'
+
+    def trigger(self, *args, **kwargs):
+        print('_' * 80)
+        print("{0:12} {1:45} {2}".format('Name (id)',
+                                         'Tool description',
+                                         'Keymap'))
+        print('-' * 80)
+        tools = self.toolmanager.tools
+        for name in sorted(tools.keys()):
+            if not tools[name].description:
+                continue
+            keys = ', '.join(sorted(self.toolmanager.get_tool_keymap(name)))
+            print("{0:12} {1:45} {2}".format(name,
+                                             tools[name].description,
+                                             keys))
+        print('_' * 80)
+        print("Active Toggle tools")
+        print("{0:12} {1:45}".format("Group", "Active"))
+        print('-' * 80)
+        for group, active in self.toolmanager.active_toggle.items():
+            print("{0:12} {1:45}".format(group, active))
+
+
+class GroupHideTool(ToolToggleBase):
+    '''Hide lines with a given gid'''
+    default_keymap = 'G'
+    description = 'Hide by gid'
+
+    def __init__(self, *args, **kwargs):
+        self.gid = kwargs.pop('gid')
+        ToolToggleBase.__init__(self, *args, **kwargs)
+
+    def enable(self, *args):
+        self.set_lines_visibility(False)
+
+    def disable(self, *args):
+        self.set_lines_visibility(True)
+
+    def set_lines_visibility(self, state):
+        gr_lines = []
+        for ax in self.figure.get_axes():
+            for line in ax.get_lines():
+                if line.get_gid() == self.gid:
+                    line.set_visible(state)
+        self.figure.canvas.draw()
+
+
+fig = plt.figure()
+plt.plot([1, 2, 3], gid='mygroup')
+plt.plot([2, 3, 4], gid='unknown')
+plt.plot([3, 2, 1], gid='mygroup')
+
+# Add the custom tools that we created
+fig.canvas.manager.toolmanager.add_tool('List', ListTools)
+fig.canvas.manager.toolmanager.add_tool('Hide', GroupHideTool, gid='mygroup')
+
+
+# Add an existing tool to new group `foo`.
+# It can be added as many times as we want
+fig.canvas.manager.toolbar.add_tool('zoom', 'foo')
+
+# Remove the forward button
+fig.canvas.manager.toolmanager.remove_tool('forward')
+
+# To add a custom tool to the toolbar at specific location inside
+# the navigation group
+fig.canvas.manager.toolbar.add_tool('Hide', 'navigation', 1)
+
+plt.show()