MEP22: 工具栏重写

状态

进度

分支和拉取请求

前期工作：

• matplotlib/matplotlib#1849

• matplotlib/matplotlib#2557

• matplotlib/matplotlib#2465

拉取请求：

• 移除 NavigationToolbar 类 matplotlib/matplotlib#2740 已关闭

• 保持 NavigationToolbar 类 matplotlib/matplotlib#2759 关闭

• 事件导航：matplotlib/matplotlib#3652

摘要

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

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

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

这种方法将使创建和共享工具在用户之间变得更加容易。在遥远的未来，我们甚至可以预见一种 工具 的 Marketplace，其中最受欢迎的工具可以被添加到主发行版中。

详细描述

工具栏的重新配置是复杂的，大多数情况下它需要一个自定义的后端。

自定义工具的创建有时会干扰工具栏，例如参见 matplotlib/matplotlib#2694 此外，快捷方式是硬编码的，并且同样不容易修改 matplotlib/matplotlib#2699

提出的解决方案是将操作从 Toolbar 中移出，将快捷方式从 Canvas 中移出。操作和快捷方式将以 Tool 的形式存在。

一个新的类 Navigation 将成为 Canvas 和 Toolbar 事件之间的桥梁，并将它们重定向到适当的 Tool。

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

• NavigationBase: 这个类为每个 FigureManager 实例化，并连接所有用户与工具的交互。

• ToolbarBase：这个现有类仅作为工具的GUI访问。

• ToolBase: 是工具的基本定义。

实现

ToolBase(对象)

工具可以有一个图形表示，如 SubplotTool ，或者甚至不在工具栏中出现，如 Quit 。

ToolBase 在定义时有以下类属性用于配置

• keymap = None: 用于触发工具的按键

• description = '': 工具的小描述

• image = None: 用于工具栏中的图像

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

• 名字

• 导航

方法

• trigger(self, event): 这是工具的主要方法，当工具被触发时调用。

  • 工具栏按钮点击

  • 与工具键映射关联的按键

  • 调用 navigation.trigger_tool(name)

• set_figure(self, figure): 设置图形和导航属性

• destroy(self, *args): 销毁 Tool 图形界面（如果存在）

可用工具

• 工具退出

• ToolEnableAllNavigation

• 工具启用导航

• 工具切换网格

• ToolToggleFullScreen

• ToolToggleYScale

• ToolToggleXScale

• 工具之家

• 工具背

• 工具转发

• SaveFigureBase

• 配置子图基础

ToolToggleBase(ToolBase)

ToolToggleBase 在定义时有以下类属性用于配置

• radio_group = None: 用于分组 'radio' 类工具的属性（互斥）

• cursor = None: 当工具激活时使用的光标

可切换 工具可以捕获按键、鼠标移动和鼠标按钮按下

方法

• enable(self, event): 由 ToolToggleBase.trigger 方法调用

• disable(self, event): 当工具未被选中时调用

• toggled: 属性 真或假

可用工具

• 工具缩放

• 工具面板

NavigationBase

定义了以下属性：

• 画布：

• 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): 属性 当前切换的工具或 None

• 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): 返回工具对象

ToolbarBase

方法（用于后端实现）

• 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 中移除一个工具项

向后兼容性

为了向后兼容，将 'navigation' 添加到 rcParams["toolbar"] (default: 'toolbar2') 支持的值列表中，该值用于 Navigation 类的实例化，而不是 NavigationToolbar 类。

通过这个参数，它使得使用现有后端的任何人都能透明地操作。

[@pelson 评论: 这也给了我们一个机会，避免在同一个PR中实现所有这些功能——一些后端可能在短期内不需要新的功能（但必须在某个时候完成）。]