MEP22：工具栏重写#

状态 #

进步

分支和拉取请求 #

之前的工作：

拉取请求：

删除 NavigationToolbar 类 https://github.com/matplotlib/matplotlib/pull/2740已关闭
保持 NavigationToolbar 类https://github.com/matplotlib/matplotlib/pull/2759 关闭
按事件导航：https ://github.com/matplotlib/matplotlib/pull/3652

摘要 #

此 MEP 的主要目标是使用户与图形交互的方式更容易修改（添加、更改、删除）。

用户与图形的交互深度集成在画布和工具栏中。使进行任何修改变得极其困难。

本 MEP 建议将此交互分离为工具栏、导航和工具，以提供独立的访问和重新配置。

这种方法将更容易在用户之间创建和共享工具。在遥远的未来，我们甚至可以预见一种市场，Tool其中最受欢迎的可以添加到主要分布中。

详细说明 #

Toolbar 的重新配置很复杂，大多数情况下它需要自定义后端。

自定义工具的创建有时会干扰工具栏，例如参见https://github.com/matplotlib/matplotlib/issues/2694快捷方式也是硬编码的，并且不容易修改 https://github.com/matplotlib/matplotlib /问题/2699

建议的解决方案是Toolbar从Canvas. 动作和快捷方式将采用Tools 的形式。

一个新的类Navigation将成为来自 Canvasand的事件之间的桥梁Toolbar，并将它们重定向到适当的Tool.

最后，用户交互将分为三类：

NavigationBase：为每个 FigureManager 实例化此类，并将所有用户交互与工具连接起来
ToolbarBase：这个现有的类仅被降级为对工具的 GUI 访问。
ToolBase：是Tools的基本定义。

实施 #

工具库（对象）#

工具可以具有图形表示形式，SubplotTool也可以不存在于工具栏中Quit。

ToolBase具有以下用于在定义时进行配置的类属性

keymap = None：用于触发工具的键
description = ''：工具的小描述
image = None：工具栏中使用的图像

以下实例属性在实例化时设置：

姓名
导航

方法 #

trigger(self, event): 这是 Tool 的主要方法，当 Tool 被触发时调用：
- 工具栏按钮单击
- 与工具键盘映射关联的按键
- 调用 navigation.trigger_tool(name)
set_figure(self, figure)：设置图形和导航属性
destroy(self, *args)：销毁Tool图形界面（如果存在）

可用工具 #

工具退出
ToolEnableAllNavigation
工具启用导航
工具切换网格
工具切换全屏
ToolToggleYScale
ToolToggleXScale
工具之家
工具返回
工具转发
保存图基
配置子图基

ToolToggleBase(ToolBase) #

ToolToggleBase具有以下用于在定义时进行配置的类属性

radio_group = None：用于对类似工具的“收音机”进行分组的属性（互斥）
cursor = None：工具激活时使用的光标

Toggleable Tools，可以捕获按键、鼠标移动和鼠标按钮按下

方法 #

enable(self, event):ToolToggleBase.trigger方法调用
disable(self, event)：当工具未切换时调用
toggled:属性True 或 False

可用工具 #

工具缩放
工具盘

导航库 #

定义以下属性：

帆布：
keypresslock：锁定以知道是否canvas key_press_event可用并处理它
messagelock：锁定以知道消息是否可以写入

方法（针对最终用户）#

nav_connect(self, s, func): 连接到事件导航
nav_disconnect(self, cid): 断开导航事件
message_event(self, message, sender=None): 发出 tool_message_event 事件
active_toggle(self):属性当前切换的工具或无
get_tool_keymap(self, name)：返回与工具关联的键列表
set_tool_keymap(self, name, ``*keys)``: 设置给定工具的键
remove_tool(self, name)：从导航控件中删除工具。
add_tools(self, tools): 添加多个工具Navigation
add_tool(self, name, tool, group=None, position=None): 添加一个工具到Navigation
tool_trigger_event(self, name, sender=None, canvasevent=None, data=None)：触发工具并触发事件
tools:属性带有可用工具的字典，带有相应的键盘映射、描述和对象
get_tool(self, name)：返回工具对象

工具栏库 #

方法（用于后端实现）#

add_toolitem(self, name, group, position, image, description, toggle)：将工具项添加到工具栏。此方法是来自 tool_added_event（由导航发出）的回调
set_message(self, s)：在工具栏或状态栏中显示消息
toggle_toolitem(self, name)：在不触发事件的情况下切换工具项。
remove_toolitem(self, name)：从Toolbar

向后兼容性 #

为了向后兼容，在rcParams["toolbar"]（默认值：）支持的值列表中添加了“导航” 'toolbar2'，用于Navigation类实例化而不是 NavigationToolbar 类

使用此参数，它对使用现有后端的任何人都是透明的。

[@pelson 评论：这也让我们有机会避免需要在同一个 PR 中实现所有这些——一些后端可能会在短时间内没有新功能而存在（但必须在某个时候完成）。]