You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
<divid="unreleased-message"> You are reading an old version of the documentation (v1.2.1). For the latest version see <ahref="https://matplotlib.org/stable/users/event_handling.html">https://matplotlib.org/stable/users/event_handling.html</a></div>
<spanid="event-handling-tutorial"></span><h1>Event handling and picking<aclass="headerlink" href="#event-handling-and-picking" title="Permalink to this headline">¶</a></h1>
<p>matplotlib works with 6 user interface toolkits (wxpython, tkinter,
qt, gtk, fltk and macosx) and in order to support features like interactive
panning and zooming of figures, it is helpful to the developers to
have an API for interacting with the figure via key presses and mouse
movements that is “GUI neutral” so we don’t have to repeat a lot of
code across the different user interfaces. Although the event
handling API is GUI neutral, it is based on the GTK model, which was
the first user interface matplotlib supported. The events that are
triggered are also a bit richer vis-a-vis matplotlib than standard GUI
events, including information like which <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><ttclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.axes.Axes</span></tt></a>
the event occurred in. The events also understand the matplotlib
coordinate system, and report event locations in both pixel and data
coordinates.</p>
<divclass="section" id="event-connections">
<spanid="id1"></span><h2>Event connections<aclass="headerlink" href="#event-connections" title="Permalink to this headline">¶</a></h2>
<p>To receive events, you need to write a callback function and then
connect your function to the event manager, which is part of the
<aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase" title="matplotlib.backend_bases.FigureCanvasBase"><ttclass="xref py py-class docutils literal"><spanclass="pre">FigureCanvasBase</span></tt></a>. Here is a simple
example that prints the location of the mouse click and which button
<td><aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.PickEvent" title="matplotlib.backend_bases.PickEvent"><ttclass="xref py py-class docutils literal"><spanclass="pre">PickEvent</span></tt></a> - an object in the canvas is selected</td>
<spanid="id2"></span><h2>Event attributes<aclass="headerlink" href="#event-attributes" title="Permalink to this headline">¶</a></h2>
<p>All matplotlib events inherit from the base class
<aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.Event" title="matplotlib.backend_bases.Event"><ttclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.backend_bases.Event</span></tt></a>, which store the attributes:</p>
<dd>the <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><ttclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></tt></a> instance if mouse is over axes</dd>
<spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">set_title</span><spanclass="p">(</span><spanclass="s">'click to build line segments'</span><spanclass="p">)</span>
<p>The <aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.MouseEvent" title="matplotlib.backend_bases.MouseEvent"><ttclass="xref py py-class docutils literal"><spanclass="pre">MouseEvent</span></tt></a> that we just used is a
<aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.LocationEvent" title="matplotlib.backend_bases.LocationEvent"><ttclass="xref py py-class docutils literal"><spanclass="pre">LocationEvent</span></tt></a>, so we have access to
the data and pixel coordinates in event.x and event.xdata. In
addition to the <ttclass="docutils literal"><spanclass="pre">LocationEvent</span></tt> attributes, it has</p>
<h3>Draggable rectangle exercise<aclass="headerlink" href="#draggable-rectangle-exercise" title="Permalink to this headline">¶</a></h3>
<p>Write draggable rectangle class that is initialized with a
<aclass="reference internal" href="../api/artist_api.html#matplotlib.patches.Rectangle" title="matplotlib.patches.Rectangle"><ttclass="xref py py-class docutils literal"><spanclass="pre">Rectangle</span></tt></a> instance but will move its x,y
location when dragged. Hint: you will need to store the original
<ttclass="docutils literal"><spanclass="pre">xy</span></tt> location of the rectangle which is stored as rect.xy and
connect to the press, motion and release mouse events. When the mouse
is pressed, check to see if the click occurs over your rectangle (see
<aclass="reference internal" href="../api/artist_api.html#matplotlib.patches.Rectangle.contains" title="matplotlib.patches.Rectangle.contains"><ttclass="xref py py-meth docutils literal"><spanclass="pre">matplotlib.patches.Rectangle.contains()</span></tt></a>) and if it does, store
the rectangle xy and the location of the mouse click in data coords.
In the motion event callback, compute the deltax and deltay of the
mouse movement, and add those deltas to the origin of the rectangle
you stored. The redraw the figure. On the button release event, just
reset all the button press data you stored as None.</p>
<spanid="enter-leave-events"></span><h2>Mouse enter and leave<aclass="headerlink" href="#mouse-enter-and-leave" title="Permalink to this headline">¶</a></h2>
<p>If you want to be notified when the mouse enters or leaves a figure or
axes, you can connect to the figure/axes enter/leave events. Here is
a simple example that changes the colors of the axes and figure
<spanclass="n">fig1</span><spanclass="o">.</span><spanclass="n">suptitle</span><spanclass="p">(</span><spanclass="s">'mouse hover over figure or axes to trigger events'</span><spanclass="p">)</span>
<spanclass="n">fig2</span><spanclass="o">.</span><spanclass="n">suptitle</span><spanclass="p">(</span><spanclass="s">'mouse hover over figure or axes to trigger events'</span><spanclass="p">)</span>
<dd>if picker is callable, it is a user supplied function which
determines whether the artist is hit by the mouse event. The
signature is <ttclass="docutils literal"><spanclass="pre">hit,</span><spanclass="pre">props</span><spanclass="pre">=</span><spanclass="pre">picker(artist,</span><spanclass="pre">mouseevent)</span></tt> to
determine the hit test. If the mouse event is over the artist,
return <ttclass="docutils literal"><spanclass="pre">hit=True</span></tt> and props is a dictionary of properties you
want added to the <aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.PickEvent" title="matplotlib.backend_bases.PickEvent"><ttclass="xref py py-class docutils literal"><spanclass="pre">PickEvent</span></tt></a>
attributes</dd>
</dl>
</div></blockquote>
<p>After you have enabled an artist for picking by setting the <ttclass="docutils literal"><spanclass="pre">picker</span></tt>
property, you need to connect to the figure canvas pick_event to get
<spanclass="c"># now do something with this...</span>
</pre></div>
</div>
<p>The <aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.PickEvent" title="matplotlib.backend_bases.PickEvent"><ttclass="xref py py-class docutils literal"><spanclass="pre">PickEvent</span></tt></a> which is passed to
your callback is always fired with two attributes:</p>
<blockquote>
<div><dlclass="docutils">
<dt><ttclass="docutils literal"><spanclass="pre">mouseevent</span></tt> the mouse event that generate the pick event. The</dt>
<dd>mouse event in turn has attributes like <ttclass="docutils literal"><spanclass="pre">x</span></tt> and <ttclass="docutils literal"><spanclass="pre">y</span></tt> (the
coords in display space, eg pixels from left, bottom) and xdata,
ydata (the coords in data space). Additionally, you can get
information about which buttons were pressed, which keys were
pressed, which <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><ttclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></tt></a> the mouse is over,
etc. See <aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.MouseEvent" title="matplotlib.backend_bases.MouseEvent"><ttclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.backend_bases.MouseEvent</span></tt></a> for
<dd>the <aclass="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><ttclass="xref py py-class docutils literal"><spanclass="pre">Artist</span></tt></a> that generated the pick
event.</dd>
</dl>
</div></blockquote>
<p>Additionally, certain artists like <aclass="reference internal" href="../api/artist_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><ttclass="xref py py-class docutils literal"><spanclass="pre">Line2D</span></tt></a>
and <aclass="reference internal" href="../api/collections_api.html#matplotlib.collections.PatchCollection" title="matplotlib.collections.PatchCollection"><ttclass="xref py py-class docutils literal"><spanclass="pre">PatchCollection</span></tt></a> may attach
additional meta data like the indices into the data that meet the
picker criteria (eg all the points in the line that are within the
specified epsilon tolerance)</p>
<divclass="section" id="simple-picking-example">
<h3>Simple picking example<aclass="headerlink" href="#simple-picking-example" title="Permalink to this headline">¶</a></h3>
<p>In the example below, we set the line picker property to a scalar, so
it represents a tolerance in points (72 points per inch). The onpick
callback function will be called when the pick event it within the
tolerance distance from the line, and has the indices of the data
vertices that are within the pick distance tolerance. Our onpick
callback function simply prints the data that are under the pick
location. Different matplotlib Artists can attach different data to
the PickEvent. For example, <ttclass="docutils literal"><spanclass="pre">Line2D</span></tt> attaches the ind property,
which are the indices into the line data under the pick point. See
<ttclass="xref py py-meth docutils literal"><spanclass="pre">pick()</span></tt> for details on the <ttclass="docutils literal"><spanclass="pre">PickEvent</span></tt>
<spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">set_title</span><spanclass="p">(</span><spanclass="s">'click on points'</span><spanclass="p">)</span>
<spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">set_title</span><spanclass="p">(</span><spanclass="s">'click on point to plot time series'</span><spanclass="p">)</span>