matplotlib.widgets

GUI 中性控件

旨在适用于任何 GUI 后端的部件。所有这些部件都要求您预定义一个 Axes 实例并将其作为第一个参数传递。Matplotlib 在布局方面不会过于智能——您需要自行决定 Axes 的宽度和高度以适应您的部件。

类 matplotlib.widgets.AxesWidget(ax)

基类： Widget

连接到单个 Axes 的部件。

为确保部件保持响应并避免被垃圾回收，用户应保留对该对象的引用。

这是必要的，因为回调注册表仅维护对函数的弱引用，这些函数是部件的成员函数。如果对部件对象没有引用，它可能会被垃圾回收，这将导致回调断开。

属性：

axAxes

部件的父 Axes。

canvasFigureCanvasBase

部件的父图形画布。

activebool

部件是否处于激活状态？

属性 canvas

connect_event(event, callback)

将回调函数与事件连接。

这应取代 figure.canvas.mpl_connect 使用，因为此函数存储回调 ID 以便后续清理。

disconnect_events()

断开此部件创建的所有事件。

类 matplotlib.widgets.Button(ax, label, image=None, color='0.85', hovercolor='0.95', *, useblit=True)

基类： AxesWidget

一个 GUI 中性按钮。

为使按钮保持响应，您必须保留对其的引用。调用 on_clicked 以连接到按钮。

属性：

ax

按钮渲染到的 Axes。

label

一个 Text 实例。

color

按钮未悬停时的颜色。

hovercolor

按钮悬停时的颜色。

参数:

axAxes

按钮将被放置到的 Axes 实例。

labelstr

按钮文本。

imagearray-like or PIL Image

要在按钮中放置的图像，如果不是 None。该参数直接转发到 imshow。

color颜色

按钮未激活时的颜色。

hovercolor颜色

鼠标悬停在按钮上时的颜色。

useblitbool, 默认值: True

如果后端支持，使用 blitting 以加快绘图速度。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

版本 3.7 新增。

disconnect(cid)

移除连接 ID 为 cid 的回调函数。

on_clicked(func)

将回调函数 func 连接到按钮点击事件。

返回一个连接 ID，可用于断开回调。

类 matplotlib.widgets.CheckButtons(ax, labels, actives=None, *, useblit=True, label_props=None, frame_props=None, check_props=None)

基类： AxesWidget

一组 GUI 中性复选框。

为使复选框保持响应，您必须保留对此对象的引用。

使用 on_clicked 方法连接到 CheckButtons。

属性：

axAxes

部件的父 Axes。

labelsText 列表

复选框的文本标签对象。

将复选框添加到 Axes 实例 ax。

参数:

axAxes

部件的父 Axes。

labelsstr 列表

复选框的标签。

activesbool 列表，可选

按钮的初始选中状态。列表长度必须与 labels 相同。如果未提供，所有按钮均未选中。

useblitbool, 默认值: True

如果后端支持，使用 blitting 以加快绘图速度。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

版本 3.7 新增。

label_propsdict，可选

用于标签的 Text 属性字典。

版本 3.7 新增。

frame_propsdict，可选

用于复选框框架的散点 Collection 属性字典。默认为 (标签字体大小 / 2)**2 大小，黑色边缘颜色，无填充颜色，以及 1.0 线宽。

版本 3.7 新增。

check_propsdict，可选

用于复选框勾选的散点 Collection 属性字典。默认为 (标签字体大小 / 2)**2 大小，黑色，以及 1.0 线宽。

版本 3.7 新增。

clear()

取消选中所有复选框。

disconnect(cid)

移除连接 ID 为 cid 的观察者。

get_checked_labels()

返回用户当前选中的标签列表。

get_status()

返回所有复选框的状态（True/False）列表。

on_clicked(func)

将回调函数 func 连接到按钮点击事件。

参数:

func可调用对象

点击按钮时，调用 func 并传入按钮标签。当所有按钮都被清除时，调用 func 并传入 None。回调函数 func 必须具有以下签名

def func(label: str | None) -> Any

返回值可能存在，但会被忽略。

返回:

一个连接 ID，可用于断开回调。

set_active(index, state=None)

按索引修改复选框的状态。

如果 eventson 为 True，将触发回调。

参数:

index整数

要切换的复选框的索引。

statebool，可选

如果是一个布尔值，则显式设置状态。如果未提供值，则切换状态。

引发:

ValueError

如果 index 无效。

TypeError

如果 state 不是布尔值。

set_check_props(props)

设置复选框勾选的属性。

版本 3.7 新增。

参数:

propsdict

用于复选框勾选的 Collection 属性字典。

set_frame_props(props)

设置复选框框架的属性。

版本 3.7 新增。

参数:

propsdict

用于复选框框架的 Collection 属性字典。

set_label_props(props)

设置 Text 标签的属性。

版本 3.7 新增。

参数:

propsdict

用于标签的 Text 属性字典。

类 matplotlib.widgets.Cursor(ax, *, horizOn=True, vertOn=True, useblit=False, **lineprops)

基类： AxesWidget

一个跨越 `Axes` 并随鼠标光标移动的十字光标。

为使光标保持响应，您必须保留对其的引用。

参数:

axAxes

光标要附着到的 Axes。

horizOnbool, 默认值: True

是否绘制水平线。

vertOnbool, 默认值: True

是否绘制垂直线。

useblitbool, 默认值: False

如果后端支持，使用 blitting 以加快绘图速度。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

其他参数:

**lineprops

控制线条外观的 Line2D 属性。另请参阅 axhline。

示例

参阅 Cursor。

clear(event)

清除光标的内部事件处理器。

onmove(event)

鼠标移动时绘制光标的内部事件处理器。

类 matplotlib.widgets.EllipseSelector(ax, onselect=None, *, minspanx=0, minspany=0, useblit=False, props=None, spancoords='data', button=None, grab_range=10, handle_props=None, interactive=False, state_modifier_keys=None, drag_from_anywhere=False, ignore_event_outside=False, use_data_coordinates=False)

基类： RectangleSelector

选择 `Axes` 的椭圆形区域。

为使光标保持响应，您必须保留对其的引用。

在选择区域外相同坐标处触发的按下和释放事件将清除选择器，除非 ignore_event_outside=True。

参数:

axAxes

部件的父 Axes。

onselect函数，可选

一个回调函数，在释放事件之后以及选择被创建、更改或移除时调用。它必须具有以下签名

def onselect(eclick: MouseEvent, erelease: MouseEvent)

其中 eclick 和 erelease 是开始和完成选择的鼠标点击和释放 MouseEvent。

minspanxfloat, 默认值: 0

x 跨度小于或等于 minspanx 的选择将被移除（如果已存在）或取消。

minspanyfloat, 默认值: 0

y 跨度小于或等于 minspanx 的选择将被移除（如果已存在）或取消。

useblitbool, 默认值: False

是否使用 blitting 以加快绘图速度（如果后端支持）。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

propsdict，可选

绘制椭圆时使用的属性。有关有效属性，请参阅 Patch。默认值

dict(facecolor='red', edgecolor='black', alpha=0.2, fill=True)

spancoords{"data", "pixels"}, 默认值: "data"

是按数据坐标还是按像素坐标解释 minspanx 和 minspany。

buttonMouseButton, MouseButton 列表, 默认值: 所有按钮

触发矩形选择的按钮。

grab_rangefloat, 默认值: 10

交互式工具句柄可在其内激活的像素距离。

handle_propsdict，可选

绘制交互式手柄（标记艺术家）所用的属性。有效属性请参见 Line2D 中的标记参数。默认值在 mpl.rcParams 中定义，但 markeredgecolor 的默认值将与 props 中的 edgecolor 属性相同。

interactive布尔值, 默认值: False

是否绘制一组手柄，以允许在控件绘制后进行交互。

state_modifier_keys字典, 可选

影响控件行为的键盘修饰键。值将修改默认设置，默认设置如下：

• "move": 移动现有形状, 默认值: 无修饰键。

• "clear": 清除当前形状, 默认值: "escape" (ESC)。

• "square": 使形状为正方形, 默认值: "shift" (Shift键)。

• "center": 围绕其中心改变形状, 默认值: "ctrl" (Ctrl键)。

• "rotate": 围绕其中心旋转形状，范围在 -45° 到 45° 之间, 默认值: "r"。

"square" 和 "center" 可以组合使用。正方形形状可以由创建选择器时指定的 use_data_coordinates 参数决定，是在数据坐标还是显示坐标中定义。

drag_from_anywhere布尔值, 默认值: False

如果为 True，可以通过在其边界内任意点击来移动控件。

ignore_event_outside布尔值, 默认值: False

如果为 True，则将忽略在范围选择器外部触发的事件。

use_data_coordinates布尔值, 默认值: False

如果为 True，则选择器的“正方形”形状在数据坐标中定义，而不是显示坐标。

示例

矩形和椭圆选择器

class matplotlib.widgets.Lasso(ax, xy, callback, *, useblit=True, props=None)

基类： AxesWidget

任意形状的选择曲线。

所选路径可与 contains_point 结合使用，从图像中选择数据点。

与 LassoSelector 不同，此控件必须使用起点 xy 进行初始化，并且 Lasso 事件在释放时销毁。

参数:

axAxes

部件的父 Axes。

xy(浮点数, 浮点数)

套索起点的坐标。

callback可调用对象

每当套索被释放时，将调用 callback 函数并传递所选路径的顶点。

useblitbool, 默认值: True

是否使用 blitting 以加快绘图速度（如果后端支持）。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

props: 字典, 可选

套索线的属性。有效属性请参见 Line2D。默认 props 为

{'linestyle' : '-', 'color' : 'black', 'lw' : 2}

自 3.9 版本新增。

onmove(event)

onrelease(event)

class matplotlib.widgets.LassoSelector(ax, onselect=None, *, useblit=True, props=None, button=None)

基类: _SelectorWidget

任意形状的选择曲线。

为了使选择器保持响应，您必须保留对其的引用。

所选路径可与 contains_point 结合使用，从图像中选择数据点。

与 Lasso 不同，LassoSelector 的接口类似于 RectangleSelector 和 SpanSelector，并且将继续与坐标轴交互直到断开连接。

示例用法

ax = plt.subplot()
ax.plot(x, y)

def onselect(verts):
    print(verts)
lasso = LassoSelector(ax, onselect)

参数:

axAxes

部件的父 Axes。

onselect函数，可选

每当套索被释放时，将调用 onselect 函数并传递所选路径的顶点。

useblitbool, 默认值: True

是否使用 blitting 以加快绘图速度（如果后端支持）。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

propsdict，可选

绘制线条所用的属性，有效属性请参见 Line2D。默认值在 mpl.rcParams 中定义。

buttonMouseButton 或 MouseButton 列表, 可选

用于矩形选择的鼠标按钮。默认值为 None，表示所有按钮。

class matplotlib.widgets.LockDraw

基类: object

某些控件，如光标，会在画布上绘制，这并非在所有情况下都可取，例如当工具栏处于矩形缩放模式并绘制矩形时。为避免这种情况，控件可以在画布上绘制之前使用 canvas.widgetlock(widget) 获取画布的锁定；这将阻止其他控件同时进行（如果它们也尝试先获取锁定）。

available(o)

返回 `o` 是否可以进行绘制。

isowner(o)

返回 `o` 是否拥有此锁。

locked()

返回锁定当前是否被所有者持有。

release(o)

从 `o` 释放锁定。

class matplotlib.widgets.MultiCursor(canvas, axes, *, useblit=True, horizOn=False, vertOn=True, **lineprops)

基类： Widget

提供多个坐标轴之间共享的垂直（默认）和/或水平线光标。

为使光标保持响应，您必须保留对其的引用。

参数:

canvas对象

此参数完全未使用，仅为向后兼容保留。

axesAxes 列表

光标要附着到的 Axes。

useblitbool, 默认值: True

如果后端支持，使用 blitting 以加快绘图速度。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

horizOn布尔值, 默认值: False

是否绘制水平线。

vertOnbool, 默认值: True

是否绘制垂直线。

其他参数:

**lineprops

控制线条外观的 Line2D 属性。另请参阅 axhline。

示例

参见 多光标。

clear(event)

清除光标。

connect()

连接事件。

disconnect()

断开事件。

onmove(event)

class matplotlib.widgets.PolygonSelector(ax, onselect=None, *, useblit=False, props=None, handle_props=None, grab_range=10, draw_bounding_box=False, box_handle_props=None, box_props=None)

基类: _SelectorWidget

选择坐标轴的多边形区域。

每次鼠标点击放置顶点，并通过完成多边形（点击第一个顶点）进行选择。绘制完成后，可以通过点击并拖动鼠标左键移动单个顶点，或通过点击鼠标右键移除。

此外，可以使用以下修饰键：

• 按住 ctrl 键并点击拖动一个顶点，以在多边形完成之前重新定位它。

• 按住 shift 键并点击拖动坐标轴内的任意位置以移动所有顶点。

• 按 esc 键开始一个新的多边形。

为了使选择器保持响应，您必须保留对其的引用。

参数:

axAxes

部件的父 Axes。

onselect函数，可选

当多边形完成或完成修改后，将调用 onselect 函数并传递一个包含 (xdata, ydata) 元组形式顶点的列表。

useblitbool, 默认值: False

是否使用 blitting 以加快绘图速度（如果后端支持）。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

propsdict，可选

绘制线条所用的属性，有效属性请参见 Line2D。默认

dict(color='k', linestyle='-', linewidth=2, alpha=0.5)

handle_propsdict，可选

在多边形顶点处绘制的标记的 Artist 属性。有效属性请参见 Line2D 中的标记参数。默认值在 mpl.rcParams 中定义，但 markeredgecolor 的默认值将与 props 中的 color 属性相同。

grab_rangefloat, 默认值: 10

如果鼠标点击位于顶点 grab_range 像素范围内，则选中一个顶点（以完成多边形或移动顶点）。

draw_bounding_box布尔值, 可选

如果为 True，一旦多边形选择器完成，将围绕其绘制一个边界框。此框可用于移动和调整选择器的大小。

box_handle_props字典, 可选

为框手柄设置的属性。更多信息请参阅 RectangleSelector 的 handle_props 参数文档。

box_props字典, 可选

为框设置的属性。更多信息请参阅 RectangleSelector 的 props 参数文档。

备注

如果移除点后只剩一个点，选择器将恢复到不完整状态，您可以从现有顶点开始绘制新的多边形。

示例

多边形选择器 使用多边形选择器从集合中选择索引

onmove(event)

光标移动事件处理程序和验证器。

property verts

多边形顶点，以 (x, y) 对列表的形式。

class matplotlib.widgets.RadioButtons(ax, labels, active=0, activecolor=None, *, useblit=True, label_props=None, radio_props=None)

基类： AxesWidget

一个 GUI 中立的单选按钮。

为了使按钮保持响应，您必须保留对此对象的引用。

使用 on_clicked 方法连接到 RadioButtons。

属性：

axAxes

部件的父 Axes。

activecolor颜色

选中按钮的颜色。

labelsText 列表

按钮标签。

value_selected字符串

当前选中按钮的标签文本。

index_selected整型

选中按钮的索引。

将单选按钮添加到 Axes。

参数:

axAxes

要添加按钮的坐标轴。

labelsstr 列表

按钮标签。

active整型

初始选中按钮的索引。

activecolor颜色

选中按钮的颜色。如果此处或 radio_props 中未指定，默认值为 'blue'。

useblitbool, 默认值: True

如果后端支持，使用 blitting 以加快绘图速度。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

版本 3.7 新增。

label_props字典或字典列表, 可选

用于标签的 Text 属性字典。

版本 3.7 新增。

radio_props字典, 可选

用于单选按钮的散点图 Collection 属性字典。默认值为（标签字体大小 / 2）**2 大小，黑色边缘颜色，以及 activecolor 填充颜色（激活时）。

注意

如果在 radio_props 中提供了填充颜色，它将覆盖 activecolor。这可以用于为每个按钮提供一个活动颜色。

版本 3.7 新增。

property activecolor

clear()

将活动按钮重置为最初活动的按钮。

disconnect(cid)

移除连接 ID 为 cid 的观察者。

on_clicked(func)

将回调函数 func 连接到按钮点击事件。

参数:

func可调用对象

点击按钮时，调用 func 并传入按钮标签。当所有按钮都被清除时，调用 func 并传入 None。回调函数 func 必须具有以下签名

def func(label: str | None) -> Any

返回值可能存在，但会被忽略。

返回:

一个连接 ID，可用于断开回调。

set_active(index)

选中编号为 index 的按钮。

如果 eventson 为 True，将触发回调。

参数:

index整数

要激活的按钮的索引。

引发:

ValueError

如果索引无效。

set_label_props(props)

设置 Text 标签的属性。

版本 3.7 新增。

参数:

propsdict

用于标签的 Text 属性字典。

set_radio_props(props)

设置 Text 标签的属性。

版本 3.7 新增。

参数:

propsdict

用于单选按钮的 Collection 属性字典。

class matplotlib.widgets.RangeSlider(ax, label, valmin, valmax, *, valinit=None, valfmt=None, closedmin=True, closedmax=True, dragging=True, valstep=None, orientation='horizontal', track_color='lightgrey', handle_style=None, **kwargs)

基类: SliderBase

表示浮点值范围的滑块。通过 val 属性将范围的最小值和最大值定义为 (min, max) 元组。

在坐标轴 ax 中创建一个定义在 [valmin, valmax] 范围内的滑块。为了使滑块保持响应，您必须保留对其的引用。调用 on_changed() 连接到滑块事件。

属性：

val浮点数元组

滑块值。

参数:

ax坐标轴

放置滑块的坐标轴。

labelstr

滑块标签。

valmin浮点数

滑块的最小值。

valmax浮点数

滑块的最大值。

valinit浮点数元组或 None, 默认值: None

滑块的初始位置。如果为 None，初始位置将在范围的第 25 和 75 百分位。

valfmt字符串, 默认值: None

用于格式化滑块值的百分比格式字符串。如果为 None，则使用 ScalarFormatter。

closedmin布尔值, 默认值: True

滑块区间底部是否闭合。

closedmax布尔值, 默认值: True

滑块区间顶部是否闭合。

dragging布尔值, 默认值: True

如果为 True，滑块可以通过鼠标拖动。

valstep浮点数, 默认值: None

如果给定，滑块将吸附到 valstep 的倍数。

orientation{'horizontal', 'vertical'}，默认值: 'horizontal'

滑块的方向。

track_color颜色, 默认值: 'lightgrey'

背景轨道的颜色。轨道可以通过 track 属性进行进一步样式设置。

handle_style字典

滑块手柄的属性。默认值为

键	值	默认	描述
填充色	color	'白色'	滑块手柄的填充色。
边缘颜色	color	'.75'	滑块手柄的边缘颜色。
大小	整型	10	滑块手柄的点大小。

其他值将转换为 marker{foo} 并传递给 Line2D 构造函数。例如，handle_style = {'style'='x'} 将导致 markerstyle = 'x'。

备注

额外的关键字参数将传递给 self.poly，它是绘制滑块旋钮的 Polygon。有效属性名称（facecolor、edgecolor、alpha 等）请参阅 Polygon 文档。

on_changed(func)

将 func 作为回调函数连接到滑块值的变化。

参数:

func可调用对象

当滑块改变时调用的函数。函数必须接受一个浮点数组成的 2 元组作为其参数。

返回:

整型

连接 ID（可用于断开 func）。

set_max(max)

将滑块的上限值设置为 max。

参数:

max浮点数

set_min(min)

将滑块的下限值设置为 min。

参数:

min浮点数

set_val(val)

将滑块值设置为 val。

参数:

val浮点数元组或类数组对象

class matplotlib.widgets.RectangleSelector(ax, onselect=None, *, minspanx=0, minspany=0, useblit=False, props=None, spancoords='data', button=None, grab_range=10, handle_props=None, interactive=False, state_modifier_keys=None, drag_from_anywhere=False, ignore_event_outside=False, use_data_coordinates=False)

基类: _SelectorWidget

选择坐标轴的矩形区域。

为使光标保持响应，您必须保留对其的引用。

在选择区域外相同坐标处触发的按下和释放事件将清除选择器，除非 ignore_event_outside=True。

参数:

axAxes

部件的父 Axes。

onselect函数，可选

一个回调函数，在释放事件之后以及选择被创建、更改或移除时调用。它必须具有以下签名

def onselect(eclick: MouseEvent, erelease: MouseEvent)

其中 eclick 和 erelease 是开始和完成选择的鼠标点击和释放 MouseEvent。

minspanxfloat, 默认值: 0

x 跨度小于或等于 minspanx 的选择将被移除（如果已存在）或取消。

minspanyfloat, 默认值: 0

y 跨度小于或等于 minspanx 的选择将被移除（如果已存在）或取消。

useblitbool, 默认值: False

是否使用 blitting 以加快绘图速度（如果后端支持）。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

propsdict，可选

绘制矩形所用的属性。有效属性请参见 Patch。默认

dict(facecolor='red', edgecolor='black', alpha=0.2, fill=True)

spancoords{"data", "pixels"}, 默认值: "data"

是按数据坐标还是按像素坐标解释 minspanx 和 minspany。

buttonMouseButton, MouseButton 列表, 默认值: 所有按钮

触发矩形选择的按钮。

grab_rangefloat, 默认值: 10

交互式工具句柄可在其内激活的像素距离。

handle_propsdict，可选

绘制交互式手柄（标记艺术家）所用的属性。有效属性请参见 Line2D 中的标记参数。默认值在 mpl.rcParams 中定义，但 markeredgecolor 的默认值将与 props 中的 edgecolor 属性相同。

interactive布尔值, 默认值: False

是否绘制一组手柄，以允许在控件绘制后进行交互。

state_modifier_keys字典, 可选

影响控件行为的键盘修饰键。值将修改默认设置，默认设置如下：

• "move": 移动现有形状, 默认值: 无修饰键。

• "clear": 清除当前形状, 默认值: "escape" (ESC)。

• "square": 使形状为正方形, 默认值: "shift" (Shift键)。

• "center": 围绕其中心改变形状, 默认值: "ctrl" (Ctrl键)。

• "rotate": 围绕其中心旋转形状，范围在 -45° 到 45° 之间, 默认值: "r"。

"square" 和 "center" 可以组合使用。正方形形状可以由创建选择器时指定的 use_data_coordinates 参数决定，是在数据坐标还是显示坐标中定义。

drag_from_anywhere布尔值, 默认值: False

如果为 True，可以通过在其边界内任意点击来移动控件。

ignore_event_outside布尔值, 默认值: False

如果为 True，则将忽略在范围选择器外部触发的事件。

use_data_coordinates布尔值, 默认值: False

如果为 True，则选择器的“正方形”形状在数据坐标中定义，而不是显示坐标。

示例

>>> import matplotlib.pyplot as plt
>>> import matplotlib.widgets as mwidgets
>>> fig, ax = plt.subplots()
>>> ax.plot([1, 2, 3], [10, 50, 100])
>>> def onselect(eclick, erelease):
...     print(eclick.xdata, eclick.ydata)
...     print(erelease.xdata, erelease.ydata)
>>> props = dict(facecolor='blue', alpha=0.5)
>>> rect = mwidgets.RectangleSelector(ax, onselect, interactive=True,
...                                   props=props)
>>> fig.show()
>>> rect.add_state('square')

另请参见: 矩形和椭圆选择器

property center

矩形在数据坐标中的中心。

property corners

矩形在数据坐标中的角点，从左下角开始顺时针移动。

property edge_centers

矩形边缘在中点数据坐标中从左开始逆时针移动。

property extents

返回旋转前由边界框定义的数据坐标中的 (xmin, xmax, ymin, ymax)。

property geometry

返回一个形状为 (2, 5) 的数组，其中包含矩形四个角（从左上角开始并结束）的 x (RectangleSelector.geometry[1, :]) 和 y (RectangleSelector.geometry[0, :]) 数据坐标。

property rotation

旋转角度，范围在 [-45°, 45°] 之间。旋转范围受限以保持实现简单。

class matplotlib.widgets.Slider(ax, label, valmin, valmax, *, valinit=0.5, valfmt=None, closedmin=True, closedmax=True, slidermin=None, slidermax=None, dragging=True, valstep=None, orientation='horizontal', initcolor='r', track_color='lightgrey', handle_style=None, **kwargs)

基类: SliderBase

表示浮点范围的滑块。

在坐标轴 ax 中创建从 valmin 到 valmax 的滑块。为了使滑块保持响应，您必须保留对其的引用。调用 on_changed() 连接到滑块事件。

属性：

val浮点数

滑块值。

参数:

ax坐标轴

放置滑块的坐标轴。

labelstr

滑块标签。

valmin浮点数

滑块的最小值。

valmax浮点数

滑块的最大值。

valinit浮点数, 默认值: 0.5

滑块初始位置。

valfmt字符串, 默认值: None

用于格式化滑块值的百分比格式字符串。如果为 None，则使用 ScalarFormatter。

closedmin布尔值, 默认值: True

滑块区间底部是否闭合。

closedmax布尔值, 默认值: True

滑块区间顶部是否闭合。

slidermin滑块, 默认值: None

不允许当前滑块的值小于滑块 slidermin 的值。

slidermax滑块, 默认值: None

不允许当前滑块的值大于滑块 slidermax 的值。

dragging布尔值, 默认值: True

如果为 True，滑块可以通过鼠标拖动。

valstep浮点数或类数组对象, 默认值: None

如果是浮点数，滑块将吸附到 valstep 的倍数。如果是数组，滑块将吸附到数组中的值。

orientation{'horizontal', 'vertical'}，默认值: 'horizontal'

滑块的方向。

initcolor颜色, 默认值: 'r'

位于 valinit 位置线的颜色。设置为 'none' 则无此线。

track_color颜色, 默认值: 'lightgrey'

背景轨道的颜色。轨道可以通过 track 属性进行进一步样式设置。

handle_style字典

滑块手柄的属性。默认值为

键	值	默认	描述
填充色	color	'白色'	滑块手柄的填充色。
边缘颜色	color	'.75'	滑块手柄的边缘颜色。
大小	整型	10	滑块手柄的点大小。

其他值将转换为 marker{foo} 并传递给 Line2D 构造函数。例如，handle_style = {'style'='x'} 将导致 markerstyle = 'x'。

备注

额外的关键字参数将传递给 self.poly，它是绘制滑块旋钮的 Rectangle。有效属性名称（facecolor、edgecolor、alpha 等）请参阅 Rectangle 文档。

on_changed(func)

将 func 作为回调函数连接到滑块值的变化。

参数:

func可调用对象

当滑块改变时调用的函数。函数必须接受一个浮点数作为其参数。

返回:

整型

连接 ID（可用于断开 func）。

set_val(val)

将滑块值设置为 val。

参数:

val浮点数

class matplotlib.widgets.SliderBase(ax, orientation, closedmin, closedmax, valmin, valmax, valfmt, dragging, valstep)

基类： AxesWidget

构建滑块控件的基类。不建议直接使用。

为了使滑块保持响应，您必须保留对其的引用。

disconnect(cid)

移除连接 ID 为 cid 的观察者。

参数:

cid整型

要移除的观察者的连接 ID。

reset()

将滑块重置为初始值。

class matplotlib.widgets.SpanSelector(ax, onselect, direction, *, minspan=0, useblit=False, props=None, onmove_callback=None, interactive=False, button=None, handle_props=None, grab_range=10, state_modifier_keys=None, drag_from_anywhere=False, ignore_event_outside=False, snap_values=None)

基类: _SelectorWidget

在单个坐标轴上可视化选择一个最小/最大范围，并使用这些值调用函数。

为确保选择器保持响应，请保留对其的引用。

要关闭 SpanSelector，请将 span_selector.active 设置为 False。要重新打开，请将其设置为 True。

在选择区域外相同坐标处触发的按下和释放事件将清除选择器，除非 ignore_event_outside=True。

参数:

axAxes

onselect可调用对象，签名为 func(min: float, max: float)

在释放事件后以及选择创建、更改或移除时调用的回调函数。

direction{"horizontal", "vertical"}

绘制范围选择器的方向。

minspan浮点数, 默认值: 0

如果选择小于或等于 minspan，则选择将被移除（如果已存在）或取消。

useblitbool, 默认值: False

如果为 True，则使用后端相关的 blitting 功能以加快画布更新。详情请参阅教程 使用 blitting 加快渲染。

props字典, 默认值: {'facecolor': 'red', 'alpha': 0.5}

Patch 属性字典。

onmove_callback可调用对象，签名为 func(min: float, max: float), 可选

在选择范围时鼠标移动时调用。

interactive布尔值, 默认值: False

是否绘制一组手柄，以允许在控件绘制后进行交互。

buttonMouseButton 或 MouseButton 列表, 默认值: 所有按钮

激活范围选择器的鼠标按钮。

handle_props字典, 默认值: None

范围边缘手柄线的属性。仅当 interactive 为 True 时使用。有效属性请参见 Line2D。

grab_rangefloat, 默认值: 10

交互式工具句柄可在其内激活的像素距离。

state_modifier_keys字典, 可选

影响控件行为的键盘修饰键。值将修改默认设置，默认设置如下：

• "clear": 清除当前形状, 默认值: "escape" (ESC)。

drag_from_anywhere布尔值, 默认值: False

如果为 True，可以通过在其边界内任意点击来移动控件。

ignore_event_outside布尔值, 默认值: False

如果为 True，则将忽略在范围选择器外部触发的事件。

snap_values一维类数组对象, 可选

将选择器边缘吸附到给定值。

示例

>>> import matplotlib.pyplot as plt
>>> import matplotlib.widgets as mwidgets
>>> fig, ax = plt.subplots()
>>> ax.plot([1, 2, 3], [10, 50, 100])
>>> def onselect(vmin, vmax):
...     print(vmin, vmax)
>>> span = mwidgets.SpanSelector(ax, onselect, 'horizontal',
...                              props=dict(facecolor='blue', alpha=0.5))
>>> fig.show()

另请参见: 范围选择器

connect_default_events()

将主要的画布事件连接到方法。

property direction

范围选择器的方向：“vertical” 或 “horizontal”。

property extents

(浮点数, 浮点数)

当前选择的起点和终点的数据坐标值。如果没有选择，则起点和终点值相同。

new_axes(ax, *, _props=None, _init=False)

将 SpanSelector 设置为在新坐标轴上操作。

class matplotlib.widgets.SubplotTool(targetfig, toolfig)

基类： Widget

调整 Figure 子图参数的工具。

参数:

targetfigFigure

要调整的图形实例。

toolfigFigure

要嵌入子图工具的图形实例。

class matplotlib.widgets.TextBox(ax, label, initial='', *, color='.95', hovercolor='1', label_pad=0.01, textalignment='left')

基类： AxesWidget

一个 GUI 中立的文本输入框。

为了使文本框保持响应，您必须保留对其的引用。

每当文本改变时，调用 on_text_change 进行更新。

每当用户按下回车键或离开文本输入字段时，调用 on_submit 进行更新。

属性：

axAxes

部件的父 Axes。

labelText

color颜色

鼠标未悬停时文本框的颜色。

hovercolor颜色

鼠标悬停时文本框的颜色。

参数:

axAxes

按钮将被放置到的 Axes 实例。

labelstr

此文本框的标签。

initial字符串

文本框中的初始值。

color颜色

框的颜色。

hovercolor颜色

鼠标在其上方时框的颜色。

label_pad浮点数

标签与文本框右侧之间的距离。

textalignment{'left', 'center', 'right'}

文本的水平位置。

begin_typing()

disconnect(cid)

移除连接 ID 为 cid 的观察者。

on_submit(func)

当用户按下回车键或离开提交框时，调用此 func 并传入事件。

返回一个连接 ID，可用于断开连接。

on_text_change(func)

当文本更改时，调用此 func 并传入事件。

返回一个连接 ID，可用于断开连接。

set_val(val)

stop_typing()

property text

class matplotlib.widgets.ToolHandles(ax, x, y, *, marker='o', marker_props=None, useblit=True)

基类: object

画布工具的控制句柄。

参数:

axAxes

显示工具句柄的 Matplotlib 坐标轴。

x, y一维数组

控制句柄的坐标。

marker字符串，默认值：'o'

用于显示句柄的标记形状。参见 plot。

marker_props字典，可选

其他标记属性。参见 Line2D。

useblitbool, 默认值: True

是否使用 blitting 以加快绘图速度（如果后端支持）。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

property artists

closest(x, y)

返回最接近索引的索引和像素距离。

set_animated(val)

set_data(pts, y=None)

设置句柄的 x 和 y 位置。

set_visible(val)

property x

property y

class matplotlib.widgets.ToolLineHandles(ax, positions, direction, *, line_props=None, useblit=True)

基类: object

画布工具的控制句柄。

参数:

axAxes

显示工具句柄的 Matplotlib 坐标轴。

positions一维数组

句柄在数据坐标中的位置。

direction{"horizontal", "vertical"}

句柄的方向，'vertical'（垂直）或 'horizontal'（水平）。

line_props字典，可选

其他线条属性。参见 Line2D。

useblitbool, 默认值: True

是否使用 blitting 以加快绘图速度（如果后端支持）。有关详细信息，请参阅教程 使用 blitting 加快渲染速度。

property artists

closest(x, y)

返回最接近句柄的索引和像素距离。

参数:

x, y浮点数

用于确定最近句柄的 x, y 位置，并从中计算距离。

返回:

index, distance句柄的索引及其距离

位置 x, y

property direction

句柄的方向：'vertical'（垂直）或 'horizontal'（水平）。

property positions

句柄在数据坐标中的位置。

remove()

从图中移除句柄艺术家（artist）。

set_animated(value)

设置句柄艺术家（artist）的动画状态。

set_data(positions)

设置句柄的 x 或 y 位置，具体取决于线条是垂直还是水平。

参数:

positions长度为 2 的元组

设置句柄在数据坐标中的位置。

set_visible(value)

设置句柄艺术家（artist）的可见性状态。

class matplotlib.widgets.Widget

基类: object

GUI 中立控件的抽象基类。

property active

部件是否处于激活状态？

drawon = True

eventson = True

get_active()

获取控件是否处于活动状态。

ignore(event)

返回 event 是否应被忽略。

此方法应在任何事件回调的开头调用。

set_active(active)

设置控件是否处于活动状态。