:mod:`matplotlib.backend_managers`

.. automodule:: matplotlib.backend_managers

:members:

:undoc-members:

:show-inheritance:

:mod:`matplotlib.backend_tools`

.. automodule:: matplotlib.backend_tools

:members:

:undoc-members:

:show-inheritance:

backend_managers_api.rst

backend_tools_api.rst

Added "toolmanager" to "toolbar" possible values

The new value enables the use of ``ToolManager``

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::

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`

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')

fig.canvas.manager.toolmanager.add_tool('List', ListTools)

fig.canvas.manager.toolmanager.add_tool('Hide', GroupHideTool, gid='mygroup')

fig.canvas.manager.toolbar.add_tool('zoom', 'foo')

fig.canvas.manager.toolmanager.remove_tool('forward')

fig.canvas.manager.toolbar.add_tool('Hide', 'navigation', 1)

plt.show()