mpl-gui 文档#

动机#

这个项目是用于彻底改革 Matplotlib 在 pyplot 中提供的 GUI 事件循环管理工具的原型空间。

pyplot 模块目前服务于两个关键但不相关的功能

提供一个受 MATLAB 启发/受其影响的、有状态的隐式 API
提供 Matplotlib 和 GUI 事件循环之间的交互管理，包括保持图形的活动状态

虽然在提示符下工作时可能非常方便，但有状态的 API 可能会导致脆弱的代码，这些代码以令人困惑的方式依赖于全局状态，尤其是在库代码中使用时。另一方面，matplotlib.pyplot 在向用户隐藏他们正在开发 GUI 应用程序这一事实方面做得非常好，并且与 IPython 一起处理了与并行运行 GUI 应用程序相关的许多细节。

示例#

如果您想确保此代码不会秘密依赖于 pyplot 运行

import sys
sys.modules['matplotlib.pyplot'] = None

这将阻止导入 pyplot！

显示#

API 的核心是 show

import mpl_gui as mg
from matplotlib.figure import Figure

fig1 = Figure(label='A Label!')

fig2 = Figure()

mg.show([fig1, fig2])

它将显示图形并阻塞直到它们关闭。作为“显示”过程的一部分，将创建正确的 GUI 对象，将其放置在屏幕上，并运行宿主 GUI 框架的事件循环。

阻塞（或不阻塞）#

类似于 plt.ion 和 plt.ioff，我们提供了 mg.ion() 和 mg.ioff()，它们具有相同的语义。因此

import mpl_gui as mg
from matplotlib.figure import Figure

mg.ion()
print(mg.is_interactive())
fig = Figure()

mg.show([fig])  # will not block

mg.ioff()
print(mg.is_interactive())
mg.show([fig])  # will block!

与 plt.show 一样，您可以通过 block 关键字参数显式控制 mg.show 的阻塞行为

import mpl_gui as mg
from matplotlib.figure import Figure

fig = Figure(label='control blocking')

mg.show([fig], block=False)  # will never block
mg.show([fig], block=True)   # will always block

交互状态是 Matplotlib 共享的，也可以使用 matplotlib.interactive 进行控制，并通过 matplotlib.is_interactive 进行查询。

图形和轴的创建#

与 matplotlib.pyplot 类似，我们还提供了 figure、subplots 和 subplot_mosaic

import mpl_gui as mg
fig1 = mg.figure()
fig2, axs = mg.subplots(2, 2)
fig3, axd = mg.subplot_mosaic('AA\nBC')

mg.show([fig1, fig2, fig3])

如果 mpl_gui 处于“交互模式”，则 mpl_gui.figure、mpl_gui.subplots 和 mpl_gui.subplot_mosaic 将自动将新图形放置在屏幕上的窗口中（但不运行事件循环）。

FigureRegistry#

在上面的示例中，用户有责任跟踪创建的 Figure 实例。如果用户没有保持对 fig 对象的硬引用，无论是直接还是通过其子对象间接引用，那么它将像任何其他 Python 对象一样被垃圾回收。虽然这在某些情况下可能是有利的（例如，创建许多瞬态图形的脚本或函数）。它失去了 matplotlib.pyplot 为您跟踪实例的便利性。为此，我们还提供了 FigureRegistry

import mpl_gui as mg

fr = mg.FigureRegistry()

fr.figure()
fr.subplots(2, 2)
fr.subplot_mosaic('AA\nBC')

fr.show_all()     # will show all three figures
fr.show()         # alias for pyplot compatibility

fr.close_all()    # will close all three figures
fr.close('all')   # alias for pyplot compatibility

因此，如果您仅使用 pyplot API 的这个受限集，则可以更改

import matplotlib.pyplot as plt

到

import mpl_gui as mg
plt = mg.FigureRegistry()

并拥有（几乎）即插即用的替代品。

此外，还有一个 FigureRegistry.by_label 辅助工具，它返回一个将图形标签映射到每个图形的字典

import mpl_gui as mg

fr = mg.FigureRegistry()

figA = fr.figure(label='A')
figB = fr.subplots(2, 2, label='B')

fr.by_label['A'] is figA
fr.by_label['B'] is figB

FigureContext#

一个非常常见的用例是制作几个图形，然后在最后一起显示它们。为了方便这一点，我们提供了 FigureRegistry 的子类，它可以作为上下文管理器使用，该管理器（局部地）跟踪创建的图形并在退出时显示它们

import mpl_gui as mg

with mg.FigureContext() as fc:
    fc.subplot_mosaic('AA\nBC')
    fc.figure()
    fc.subplots(2, 2)

这将创建 3 个图形并阻塞 __exit__。阻塞行为取决于 mg.is_interacitve()（并遵循 mg.show 的行为，或者可以通过 block 关键字参数显式控制）。

选择 GUI 工具包#

mpl_gui 利用 Matplotlib 后端来实际提供 GUI 绑定。类似于 matplotlib.use 和 matplotlib.pyplot.switch_backend mpl_gui 提供 mpl_gui.select_gui_toolkit 来选择使用哪个 GUI 工具包。select_gui_toolkit 具有与 pyplot 相同的回退行为，并将其状态存储在 rcParams["backend"] 中。mpl_gui 将始终与同一进程中的 matplotlib.pyplot 管理的图形共存。

下一个主题