Moved tooltriggerevents into the tool

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,7 @@ backends
 .. toctree::
 
    backend_bases_api.rst
+   backend_tools_api.rst
    backend_gtkagg_api.rst
    backend_qt4agg_api.rst
    backend_wxagg_api.rst

examples/user_interfaces/navigation.py

@@ -0,0 +1,63 @@
+import matplotlib
+matplotlib.use('GTK3Cairo')
+# matplotlib.use('TkAGG')
+matplotlib.rcParams['toolbar'] = 'navigation'
+import matplotlib.pyplot as plt
+from matplotlib.backend_tools import ToolBase
+
+
+# Create a simple tool to list all the tools
+class ListTools(ToolBase):
+    # keyboard shortcut
+    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.navigation.tools
+        for name in sorted(tools.keys()):
+            if not tools[name].description:
+                continue
+            keys = ', '.join(sorted(self.navigation.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.navigation.active_toggle.items():
+            print("{0:12} {1:45}").format(group, active)
+
+
+# A simple example of copy canvas
+# ref: at https://github.com/matplotlib/matplotlib/issues/1987
+class CopyToolGTK3(ToolBase):
+    keymap = 'ctrl+c'
+    description = 'Copy canvas'
+
+    def trigger(self, *args, **kwargs):
+        from gi.repository import Gtk, Gdk
+        clipboard = Gtk.Clipboard.get(Gdk.SELECTION_CLIPBOARD)
+        window = self.figure.canvas.get_window()
+        x, y, width, height = window.get_geometry()
+        pb = Gdk.pixbuf_get_from_window(window, x, y, width, height)
+        clipboard.set_image(pb)
+
+
+fig = plt.figure()
+plt.plot([1, 2, 3])
+
+# Add the custom tools that we created
+fig.canvas.manager.navigation.add_tool('List', ListTools)
+if matplotlib.rcParams['backend'] == 'GTK3Cairo':
+    fig.canvas.manager.navigation.add_tool('copy', CopyToolGTK3)
+
+# Uncomment to remove the forward button
+# fig.canvas.manager.navigation.remove_tool('forward')
+
+plt.show()