# 事件处理及拾取
> 原文：[Event handling and picking](http://matplotlib.org/users/event_handling.html)
> 译者：[飞龙](https://github.com/)
> 协议：[CC BY-NC-SA 4.0](http://creativecommons.org/licenses/by-nc-sa/4.0/)
matplotlib 使用了许多用户界面工具包（wxpython，tkinter，qt4，gtk 和 macosx），为了支持交互式平移和缩放图形等功能，拥有一套 API 通过按键和鼠标移动与图形交互，并且『GUI中立』，对开发人员十分有帮助，所以我们不必重复大量的代码来跨不同的用户界面。虽然事件处理 API 是 GUI 中立的，但它是基于 GTK 模型，这是 matplotlib 支持的第一个用户界面。与标准 GUI 事件相比，被触发的事件也比 matplotlib 丰富一些，例如包括发生事件的`matplotlib.axes.Axes`的信息。事件还能够理解 matplotlib 坐标系，并且在事件中以像素和数据坐标为单位报告事件位置。
## 事件连接
要接收事件，你需要编写一个回调函数，然后将你的函数连接到事件管理器，它是`FigureCanvasBase`的一部分。这是一个简单的例子，打印鼠标点击的位置和按下哪个按钮：
```py
fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot(np.random.rand(10))
def onclick(event):
print('button=%d, x=%d, y=%d, xdata=%f, ydata=%f' %
(event.button, event.x, event.y, event.xdata, event.ydata))
cid = fig.canvas.mpl_connect('button_press_event', onclick)
```
`FigureCanvas`的方法`mpl_connect()`返回一个连接`id`，它只是一个整数。 当你要断开回调时，只需调用：
```py
fig.canvas.mpl_disconnect(cid)
```
> 注意
> 画布仅保留回调的弱引用。 因此，如果回调是类实例的方法，你需要保留对该实例的引用。 否则实例将被垃圾回收，回调将消失。
以下是可以连接到的事件，在事件发生时发回给你的类实例以及事件描述：
| 事件名称 | 类和描述 |
| --- | --- | --- |
| `'button_press_event'` | `MouseEvent` - 鼠标按钮被按下 |
| `'button_release_event'` | `MouseEvent` - 鼠标按钮被释放 |
| `'draw_event'` | `DrawEvent` - 画布绘图 |
| `'key_press_event'` | `KeyEvent` - 按键被按下 |
| `'key_release_event'` | `KeyEvent` - 按键被释放 |
| `'motion_notify_event'` | `MouseEvent` - 鼠标移动 |
| `'pick_event'` | `PickEvent` - 画布中的对象被选中 |
| `'resize_event'` | `ResizeEvent` - 图形画布大小改变 |
| `'scroll_event'` | `MouseEvent` - 鼠标滚轮被滚动 |
| `'figure_enter_event'` | `LocationEvent` - 鼠标进入新的图形 |
| `'figure_leave_event'` | `LocationEvent` - 鼠标离开图形 |
| `'axes_enter_event'` | `LocationEvent` - 鼠标进入新的轴域 |
| `'axes_leave_event'` | `LocationEvent` - 鼠标离开轴域 |
## 事件属性
所有 matplotlib 事件继承自基类`matplotlib.backend_bases.Event`，储存以下属性：
`name`
事件名称
`canvas`
生成事件的`FigureCanvas `实例
`guiEvent`
触发 matplotlib 事件的 GUI 事件
最常见的事件是按键按下/释放事件、鼠标按下/释放和移动事件。 处理这些事件的`KeyEvent`和`MouseEvent`类都派生自`LocationEvent`，它具有以下属性：
`x`
x 位置，距离画布左端的像素
`y`
y 位置，距离画布底端的像素
`inaxes`
如果鼠标经过轴域，则为`Axes`实例
`xdata`
鼠标的`x`坐标，以数据坐标为单位
`ydata`
鼠标的`y`坐标，以数据坐标为单位
但我们看一看画布的简单示例，其中每次按下鼠标时都会创建一条线段。
```py
from matplotlib import pyplot as plt
class LineBuilder:
def __init__(self, line):
self.line = line
self.xs = list(line.get_xdata())
self.ys = list(line.get_ydata())
self.cid = line.figure.canvas.mpl_connect('button_press_event', self)
def __call__(self, event):
print('click', event)
if event.inaxes!=self.line.axes: return
self.xs.append(event.xdata)
self.ys.append(event.ydata)
self.line.set_data(self.xs, self.ys)
self.line.figure.canvas.draw()
fig = plt.figure()
ax = fig.add_subplot(111)
ax.set_title('click to build line segments')
line, = ax.plot([0], [0]) # empty line
linebuilder = LineBuilder(line)
plt.show()
```
我们刚刚使用的`MouseEvent`是一个`LocationEvent`，因此我们可以访问`event.x`和`event.xdata`中的数据和像素坐标。 除了`LocationEvent`属性，它拥有：
`button`
按下的按钮，`None`、1、2、3、`'up'`、`'down'`（`'up'`、`'down'`用于滚动事件）
`key`
按下的键，`None`，任何字符，`'shift'`、`'win'`或者`'control'`
### 可拖拽的矩形练习
编写使用`Rectangle`实例初始化的可拖动矩形类，但在拖动时会移动其`x`，`y`位置。 提示：你需要存储矩形的原始`xy`位置，存储为`rect.xy`并连接到按下，移动和释放鼠标事件。 当鼠标按下时，检查点击是否发生在你的矩形上（见`matplotlib.patches.Rectangle.contains()`），如果是，存储矩形`xy`和数据坐标为单位的鼠标点击位置。 在移动事件回调中，计算鼠标移动的`deltax`和`deltay`，并将这些增量添加到存储的原始矩形，并重新绘图。 在按钮释放事件中，只需将所有你存储的按钮按下数据重置为`None`。
这里是解决方案：
```py
import numpy as np
import matplotlib.pyplot as plt
class DraggableRectangle:
def __init__(self, rect):
self.rect = rect
self.press = None
def connect(self):
'connect to all the events we need'
self.cidpress = self.rect.figure.canvas.mpl_connect(
'button_press_event', self.on_press)
self.cidrelease = self.rect.figure.canvas.mpl_connect(
'button_release_event', self.on_release)
self.cidmotion = self.rect.figure.canvas.mpl_connect(
'motion_notify_event', self.on_motion)
def on_press(self, event):
'on button press we will see if the mouse is over us and store some data'
if event.inaxes != self.rect.axes: return
contains, attrd = self.rect.contains(event)
if not contains: return
print('event contains', self.rect.xy)
x0, y0 = self.rect.xy
self.press = x0, y0, event.xdata, event.ydata
def on_motion(self, event):
'on motion we will move the rect if the mouse is over us'
if self.press is None: return
if event.inaxes != self.rect.axes: return
x0, y0, xpress, ypress = self.press
dx = event.xdata - xpress
dy = event.ydata - ypress
#print('x0=%f, xpress=%f, event.xdata=%f, dx=%f, x0+dx=%f' %
# (x0, xpress, event.xdata, dx, x0+dx))
self.rect.set_x(x0+dx)
self.rect.set_y(y0+dy)
self.rect.figure.canvas.draw()
def on_release(self, event):
'on release we reset the press data'
self.press = None
self.rect.figure.canvas.draw()
def disconnect(self):
'disconnect all the stored connection ids'
self.rect.figure.canvas.mpl_disconnect(self.cidpress)
self.rect.figure.canvas.mpl_disconnect(self.cidrelease)
self.rect.figure.canvas.mpl_disconnect(self.cidmotion)
fig = plt.figure()
ax = fig.add_subplot(111)
rects = ax.bar(range(10), 20*np.random.rand(10))
drs = []
for rect in rects:
dr = DraggableRectangle(rect)
dr.connect()
drs.append(dr)
plt.show()
```
附加题：使用动画秘籍中讨论的动画 blit 技术，使动画绘制更快更流畅。
附加题解决方案：
```py
# draggable rectangle with the animation blit techniques; see
# http://www.scipy.org/Cookbook/Matplotlib/Animations
import numpy as np
import matplotlib.pyplot as plt
class DraggableRectangle:
lock = None # only one can be animated at a time
def __init__(self, rect):
self.rect = rect
self.press = None
self.background = None
def connect(self):
'connect to all the events we need'
self.cidpress = self.rect.figure.canvas.mpl_connect(
'button_press_event', self.on_press)
self.cidrelease = self.rect.figure.canvas.mpl_connect(
'button_release_event', self.on_release)
self.cidmotion = self.rect.figure.canvas.mpl_connect(
'motion_notify_event', self.on_motion)
def on_press(self, event):
'on button press we will see if the mouse is over us and store some data'
if event.inaxes != self.rect.axes: return
if DraggableRectangle.lock is not None: return
contains, attrd = self.rect.contains(event)
if not contains: return
print('event contains', self.rect.xy)
x0, y0 = self.rect.xy
self.press = x0, y0, event.xdata, event.ydata
DraggableRectangle.lock = self
# draw everything but the selected rectangle and store the pixel buffer
canvas = self.rect.figure.canvas
axes = self.rect.axes
self.rect.set_animated(True)
canvas.draw()
self.background = canvas.copy_from_bbox(self.rect.axes.bbox)
# now redraw just the rectangle
axes.draw_artist(self.rect)
# and blit just the redrawn area
canvas.blit(axes.bbox)
def on_motion(self, event):
'on motion we will move the rect if the mouse is over us'
if DraggableRectangle.lock is not self:
return
if event.inaxes != self.rect.axes: return
x0, y0, xpress, ypress = self.press
dx = event.xdata - xpress
dy = event.ydata - ypress
self.rect.set_x(x0+dx)
self.rect.set_y(y0+dy)
canvas = self.rect.figure.canvas
axes = self.rect.axes
# restore the background region
canvas.restore_region(self.background)
# redraw just the current rectangle
axes.draw_artist(self.rect)
# blit just the redrawn area
canvas.blit(axes.bbox)
def on_release(self, event):
'on release we reset the press data'
if DraggableRectangle.lock is not self:
return
self.press = None
DraggableRectangle.lock = None
# turn off the rect animation property and reset the background
self.rect.set_animated(False)
self.background = None
# redraw the full figure
self.rect.figure.canvas.draw()
def disconnect(self):
'disconnect all the stored connection ids'
self.rect.figure.canvas.mpl_disconnect(self.cidpress)
self.rect.figure.canvas.mpl_disconnect(self.cidrelease)
self.rect.figure.canvas.mpl_disconnect(self.cidmotion)
fig = plt.figure()
ax = fig.add_subplot(111)
rects = ax.bar(range(10), 20*np.random.rand(10))
drs = []
for rect in rects:
dr = DraggableRectangle(rect)
dr.connect()
drs.append(dr)
plt.show()
```
## 鼠标进入和离开
如果希望在鼠标进入或离开图形时通知你，你可以连接到图形/轴域进入/离开事件。 下面是一个简单的例子，它改变了鼠标所在的轴域和图形的背景颜色：
```py
"""
Illustrate the figure and axes enter and leave events by changing the
frame colors on enter and leave
"""
import matplotlib.pyplot as plt
def enter_axes(event):
print('enter_axes', event.inaxes)
event.inaxes.patch.set_facecolor('yellow')
event.canvas.draw()
def leave_axes(event):
print('leave_axes', event.inaxes)
event.inaxes.patch.set_facecolor('white')
event.canvas.draw()
def enter_figure(event):
print('enter_figure', event.canvas.figure)
event.canvas.figure.patch.set_facecolor('red')
event.canvas.draw()
def leave_figure(event):
print('leave_figure', event.canvas.figure)
event.canvas.figure.patch.set_facecolor('grey')
event.canvas.draw()
fig1 = plt.figure()
fig1.suptitle('mouse hover over figure or axes to trigger events')
ax1 = fig1.add_subplot(211)
ax2 = fig1.add_subplot(212)
fig1.canvas.mpl_connect('figure_enter_event', enter_figure)
fig1.canvas.mpl_connect('figure_leave_event', leave_figure)
fig1.canvas.mpl_connect('axes_enter_event', enter_axes)
fig1.canvas.mpl_connect('axes_leave_event', leave_axes)
fig2 = plt.figure()
fig2.suptitle('mouse hover over figure or axes to trigger events')
ax1 = fig2.add_subplot(211)
ax2 = fig2.add_subplot(212)
fig2.canvas.mpl_connect('figure_enter_event', enter_figure)
fig2.canvas.mpl_connect('figure_leave_event', leave_figure)
fig2.canvas.mpl_connect('axes_enter_event', enter_axes)
fig2.canvas.mpl_connect('axes_leave_event', leave_axes)
plt.show()
```
## 对象拾取
你可以通过设置艺术家的`picker `属性（例如，matplotlib `Line2D`，`Text`，`Patch`，`Polygon`，`AxesImage`等）来启用选择，
`picker `属性有多种含义：
`None`
选择对于该艺术家已禁用（默认）
`boolean`
如果为`True`，则启用选择，当鼠标移动到该艺术家上方时，会触发事件
`float`
如果选择器是数字，则将其解释为点的 ε 公差，并且如果其数据在鼠标事件的 ε 内，则艺术家将触发事件。 对于像线条和补丁集合的一些艺术家，艺术家可以向生成的选择事件提供附加数据，例如，在选择事件的 ε 内的数据的索引。
函数
如果拾取器是可调用的，则它是用户提供的函数，用于确定艺术家是否被鼠标事件击中。 签名为`hit, props = picker(artist, mouseevent)`，用于测试是否命中。 如果鼠标事件在艺术家上，返回`hit = True`，`props`是一个属性字典，它们会添加到`PickEvent`属性。
通过设置`picker`属性启用对艺术家进行拾取后，你需要连接到图画布的`pick_event`，以便在鼠标按下事件中获取拾取回调。 例如：
```py
def pick_handler(event):
mouseevent = event.mouseevent
artist = event.artist
# now do something with this...
```
传给你的回调的`PickEvent`事件永远有两个属性：
`mouseevent `
是生成拾取事件的鼠标事件。鼠标事件具有像`x`和`y`（显示空间中的坐标，例如，距离左，下的像素）和`xdata`，`ydata`（数据空间中的坐标）的属性。 此外，你可以获取有关按下哪些按钮，按下哪些键，鼠标在哪个轴域上面等信息。详细信息请参阅`matplotlib.backend_bases.MouseEvent`。
`artist`
生成拾取事件的`Artist`。
另外，像`Line2D`和`PatchCollection`的某些艺术家可以将附加的元数据（如索引）附加到满足选择器标准的数据中（例如，行中在指定 ε 容差内的所有点）
### 简单拾取示例
在下面的示例中，我们将行选择器属性设置为标量，因此它表示以点为单位的容差（72 点/英寸）。 当拾取事件位于距离线条的容差范围时，将调用`onpick`回调函数，并且带有在拾取距离容差内的数据顶点索引。 我们的`onpick`回调函数只打印在拾取位置上的数据。 不同的 matplotlib 艺术家可以将不同的数据附加到`PickEvent`。 例如，`Line2D`将`ind`属性作为索引附加到拾取点下面的行数据中。 有关`Line`的`PickEvent`属性的详细信息，请参阅`pick()`。 这里是代码：
```py
import numpy as np
import matplotlib.pyplot as plt
fig = plt.figure()
ax = fig.add_subplot(111)
ax.set_title('click on points')
line, = ax.plot(np.random.rand(100), 'o', picker=5) # 5 points tolerance
def onpick(event):
thisline = event.artist
xdata = thisline.get_xdata()
ydata = thisline.get_ydata()
ind = event.ind
points = tuple(zip(xdata[ind], ydata[ind]))
print('onpick points:', points)
fig.canvas.mpl_connect('pick_event', onpick)
plt.show()
```
### 拾取练习
创建含有 100 个数组的数据集，包含 1000 个高斯随机数，并计算每个数组的样本平均值和标准差（提示：`numpy`数组具有`mean`和`std`方法），并制作 100 个均值与 100 个标准的`xy`标记图。 将绘图命令创建的线条连接到拾取事件，并绘制数据的原始时间序列，这些数据生成了被点击的点。 如果在被点击的点的容差范围内存在多于一个点，则可以使用多个子图来绘制多个时间序列。
练习的解决方案：
```py
"""
compute the mean and stddev of 100 data sets and plot mean vs stddev.
When you click on one of the mu, sigma points, plot the raw data from
the dataset that generated the mean and stddev
"""
import numpy as np
import matplotlib.pyplot as plt
X = np.random.rand(100, 1000)
xs = np.mean(X, axis=1)
ys = np.std(X, axis=1)
fig = plt.figure()
ax = fig.add_subplot(111)
ax.set_title('click on point to plot time series')
line, = ax.plot(xs, ys, 'o', picker=5) # 5 points tolerance
def onpick(event):
if event.artist!=line: return True
N = len(event.ind)
if not N: return True
figi = plt.figure()
for subplotnum, dataind in enumerate(event.ind):
ax = figi.add_subplot(N,1,subplotnum+1)
ax.plot(X[dataind])
ax.text(0.05, 0.9, 'mu=%1.3f\nsigma=%1.3f'%(xs[dataind], ys[dataind]),
transform=ax.transAxes, va='top')
ax.set_ylim(-0.5, 1.5)
figi.show()
return True
fig.canvas.mpl_connect('pick_event', onpick)
plt.show()
```
