Apr 9, 2015 · Jan 23, 2014 · Jan 23, 2014 · Jan 24, 2014 · Jan 24, 2014 · Jan 26, 2014
diff --git a/doc/api/backend_managers_api.rst b/doc/api/backend_managers_api.rst

 :mod:`matplotlib.backend_managers`
 ===================================

 .. automodule:: matplotlib.backend_managers
   :members:
   :undoc-members:
   :show-inheritance:
diff --git a/doc/api/backend_tools_api.rst b/doc/api/backend_tools_api.rst

 :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
 .. 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
diff --git a/doc/users/whats_new/rcparams.rst b/doc/users/whats_new/rcparams.rst
 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``

diff --git a/doc/users/whats_new/toolmanager.rst b/doc/users/whats_new/toolmanager.rst
 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`
diff --git a/examples/user_interfaces/toolmanager.py b/examples/user_interfaces/toolmanager.py
 '''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()
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,8 @@

		:mod:`matplotlib.backend_managers`
		===================================

		.. automodule:: matplotlib.backend_managers
		:members:
		:undoc-members:
		:show-inheritance:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,8 @@

		:mod:`matplotlib.backend_tools`
		================================

		.. automodule:: matplotlib.backend_tools
		:members:
		:undoc-members:
		:show-inheritance:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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``
Original file line number	Diff line number	Diff line change
		@@ -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')
Copy link Member WeatherGodApr 3, 2015 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I get a little bit confused here. Why does the user have to interact with the toolmanager? Now that I see these examples, I wonder if the user should ever call methods upon toolmanager. I understand the functional importance of the toolmanager, but from the user's perspective, adding a tool involves interacting with two separate objects that appear (to them) to have very little to do with each other. Copy link MemberAuthor farizaApr 3, 2015 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Some tools don't need to have visual representation and others do (button for a toolbar). But at the end, is up to the user to determine what he wants in his toolbar. Copy link Member WeatherGodApr 3, 2015 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Right... good point. Might make sense in the future to add some convenience methods to make things easier for users, but I agree now that the user-facing distinction is necessary.


		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`
Copy link Member WeatherGodApr 3, 2015 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Don't have a section for a "Full Example" if it is just a link to an actual example. Just link it. Copy link MemberAuthor farizaApr 3, 2015 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. done
Original file line number	Diff line number	Diff line change
		@@ -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()