Matplotlib 自定义按钮状态反馈实现方法

本文介绍如何使用 `ToolToggleBase` 为 Matplotlib 工具栏添加具备视觉状态反馈（如按下/弹起、高亮/灰暗）的自定义按钮，使其行为与内置缩放、平移等工具一致。

在 Matplotlib 中，当启用 toolmanager 后台（通过 matplotlib.rcParams["toolbar"] = "toolmanager"），默认的导航按钮（如缩放、平移）均具有“切换式”交互：点击激活时按钮呈按下态（背景变深、边框加粗），再次点击则恢复常态。若你希望自定义工具按钮也具备相同的状态可视化能力，不应继承 ToolBase——它仅提供无状态的单次触发逻辑；而应继承 ToolToggleBase，这是 Matplotlib 专为实现“开关型”工具设计的基类。

ToolToggleBase 内置了状态管理与 UI 同步机制：它自动维护 self._active 属性，并在调用 super().trigger() 时触发工具栏按钮的视觉更新（包括图标颜色、背景色及 pressed 状态）。关键要点如下：

• ✅ 必须调用 super().trigger(sender, event, data) —— 这是触发 UI 状态同步的核心；
• ✅ 设置 radio_group = 'default' 可使该按钮与内置的 Zoom/Pan 工具组成互斥单选组（即启用本工具时自动关闭其他同类工具）；若需独立多选（如多个绘图模式可同时开启），可设为 None 或自定义字符串（如 'draw_modes'）；
• ✅ self._active 属性由 ToolToggleBase 自动维护，反映当前是否处于“激活态”，推荐直接使用该属性替代手动维护 points_enabled（更健壮、与 UI 严格同步）；
• ⚠️ 不要重写 enable() / disable() 方法，除非有特殊需求；默认实现已确保与 toolbar 生命周期一致。

以下是优化后的完整示例，支持标准切换视觉反馈，并附带清晰注释：

import matplotlib
import matplotlib.pyplot as plt
from matplotlib.backend_tools import ToolToggleBase

matplotlib.rcParams["toolbar"] = "toolmanager"

class DrawPointsTool(ToolToggleBase):
    # 将按钮加入默认单选组（与Zoom/Pan互斥）
    radio_group = 'default'

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # 可选：设置工具描述，将显示在状态栏提示中
        self.description = "Toggle point drawing mode"

    def trigger(self, sender, event, data=None):
        # 【关键】必须调用父类 trigger 以同步 UI 状态
        super().trigger(sender, event, data)

        # 此时 self._active 已准确反映最新状态
        if self._active:
            print("✅ Drawing points enabled")
            # 在此处添加实际绘图逻辑，例如连接鼠标事件：
            # fig.canvas.mpl_connect('button_press_event', self.on_click)
        else:
            print("❌ Drawing points disabled")
            # 清理事件监听或重置状态
            # if hasattr(self, '_cid') and self._cid:
            #     fig.canvas.mpl_disconnect(self._cid)

if __name__ == "__main__":
    fig, ax = plt.subplots(2, 1, figsize=(8, 6))
    ax[0].set_title('Toggle Draw Points (Click the button above)')
    ax[0].plot([0, 1, 2], [0, 1, 0], 'o-', label='Sample data')
    ax[0].legend()
    ax[1].text(0.1, 0.5, 
               "? Tip: Button appearance changes automatically\n   when toggled — no manual styling needed.",
               fontsize=10, transform=ax[1].transAxes, va='center')

    # 注册并添加工具到工具栏
    tm = fig.canvas.manager.toolmanager
    tm.add_tool('draw_points', DrawPointsTool)
    fig.canvas.manager.toolbar.add_tool('draw_points', 'toolgroup')

    plt.tight_layout()
    plt.show()

注意事项：

• 若你的 Matplotlib 版本低于 3.3，ToolToggleBase 可能不可用，请升级至 ≥3.3；
• 某些后端（如 TkAgg）对 toolbar 图标渲染更稳定，若遇到状态不刷新，可尝试更换后端；
• 如需完全自定义图标，可通过 tm.add_tool(..., image=...) 传入 PIL.Image 或路径，但状态色变仍由 ToolToggleBase 自动处理。

通过 ToolToggleBase，你无需手动操作 Qt/Tk 控件或 CSS 样式，即可获得专业、一致、符合用户直觉的工具栏交互体验——这才是 Matplotlib 官方推荐的扩展方式。