MEP22: 工具栏重写

状态

进度

分支和 Pull requests

先前的工作:

• matplotlib/matplotlib#1849

• matplotlib/matplotlib#2557

• matplotlib/matplotlib#2465

Pull Requests:

• 移除 NavigationToolbar 类 matplotlib/matplotlib#2740 CLOSED

• 保留 NavigationToolbar 类 matplotlib/matplotlib#2759 CLOSED

• 通过事件导航:matplotlib/matplotlib#3652

摘要

此 MEP 的主要目标是更容易地修改(添加,更改,删除)用户与图形交互的方式.

用户与图形的交互与 Canvas 和 Toolbar 紧密集成.这使得进行任何修改都非常困难.

此 MEP 建议将这种交互分离为 Toolbar,Navigation 和 Tools,以提供独立的访问和重新配置.

这种方法将使创建和共享工具更容易.在遥远的未来,我们甚至可以预见到一种 Tool s 的市场,其中最受欢迎的可以添加到主要发行版中.

详细描述

Toolbar 的重新配置很复杂,大多数时候需要自定义后端.

创建自定义 Tool 有时会干扰 Toolbar,例如参见 matplotlib/matplotlib#2694,此外,快捷键是硬编码的,同样不容易修改 matplotlib/matplotlib#2699

建议的解决方案是将动作从 Toolbar 中移除,并将快捷键从 Canvas 中移除.动作和快捷键将以 Tool s 的形式存在.

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

最后,用户交互将被分为三个类:

• NavigationBase:此类为每个 FigureManager 实例化,并将所有用户交互与 Tools 连接起来

• ToolbarBase:这个现有的类仅作为 GUI 访问 Tools 的方式.

• ToolBase:是 Tools 的基本定义.

实施

ToolBase(object)

Tools 可以像 SubplotTool 一样具有图形表示,甚至可以像 Quit 一样不存在于 Toolbar 中.

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

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

• description = '': 工具的简短描述

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

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

• name

• navigation

方法

• trigger(self, event) :这是 Tool 的主要方法,当 Tool 被以下方式触发时调用:

  • 工具栏按钮点击

  • 与 Tool Keymap 关联的按键

  • 调用 navigation.trigger_tool(name)

• set_figure(self, figure) :设置 figure 和 navigation 属性

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

可用工具

• ToolQuit

• ToolEnableAllNavigation

• ToolEnableNavigation

• ToolToggleGrid

• ToolToggleFullScreen

• ToolToggleYScale

• ToolToggleXScale

• ToolHome

• ToolBack

• ToolForward

• SaveFigureBase

• ConfigureSubplotsBase

ToolToggleBase(ToolBase)

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

• radio_group = None:用于将"radio"类工具(互斥)分组的属性

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

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

方法

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

• disable(self, event) : 当工具被取消切换时调用

• toggled : 属性,True 或 False

可用工具

• ToolZoom

• ToolPan

NavigationBase

定义以下属性:

• canvas:

• 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 comment: 这也给了我们一个机会来避免在同一个 PR 中实现所有这些 - 一些后端可能会在短时间内存在而没有新功能(但必须在某个时候完成).]