matplotlib · fariza · Jan 23, 2014 · Jan 23, 2014 · Jan 23, 2014 · Jan 24, 2014
diff --git a/doc/api/backend_tools_api.rst b/doc/api/backend_tools_api.rst
@@ -0,0 +1,8 @@
+
+:mod:`matplotlib.backend_tools`
+================================
+
+.. automodule:: matplotlib.backend_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/index_backend_api.rst b/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

diff --git a/examples/user_interfaces/navigation.py b/examples/user_interfaces/navigation.py
@@ -0,0 +1,59 @@
+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, event):
+        tools = self.navigation.get_tools()
+
+        print ('_' * 80)
+        print ("{0:12} {1:45} {2}".format('Name (id)',
+                                          'Tool description',
+                                          'Keymap'))
+        print ('_' * 80)
+        for name in sorted(tools.keys()):
+            keys = ', '.join(sorted(tools[name]['keymap']))
+            print ("{0:12} {1:45} {2}".format(name,
+                                              tools[name]['description'],
+                                              keys))
+        print ('_' * 80)
+
+
+# A simple example of copy canvas
+# ref: at https://github.com/matplotlib/matplotlib/issues/1987
+class CopyToolGTK3(ToolBase):
+    keymap = 'ctrl+c'
+    description = 'Copy canvas'
+    # It is not added to the toolbar as a button
+    intoolbar = False
+
+    def trigger(self, event):
+        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)
+
+# Just for fun, lets remove the forward button
+fig.canvas.manager.navigation.remove_tool('Forward')
+
+plt.show()