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 (v3.3.2). 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 a number of user interface toolkits (wxpython,
tkinter, qt4, gtk, 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"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">matplotlib.axes.Axes</span></code></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"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">FigureCanvasBase</span></code></a>. Here is a simple
example that prints the location of the mouse click and which button
<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"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">matplotlib.backend_bases.Event</span></code></a>, which store the attributes:</p>
<spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">set_title</span><spanclass="p">(</span><spanclass="s1">'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"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">MouseEvent</span></code></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"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">LocationEvent</span></code></a>, so we have access to
the data and pixel coordinates in event.x and event.xdata. In
addition to the <codeclass="docutils literal notranslate"><spanclass="pre">LocationEvent</span></code> attributes, it has</p>
<blockquote>
<div><dlclass="docutils">
<dt><codeclass="docutils literal notranslate"><spanclass="pre">button</span></code></dt><dd>button pressed None, 1, 2, 3, 'up', 'down' (up and down are used for scroll events)</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code></dt><dd>the key pressed: None, any character, 'shift', 'win', or 'control'</dd>
<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/_as_gen/matplotlib.patches.Rectangle.html#matplotlib.patches.Rectangle" title="matplotlib.patches.Rectangle"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Rectangle</span></code></a> instance but will move its x,y
location when dragged. Hint: you will need to store the original
<codeclass="docutils literal notranslate"><spanclass="pre">xy</span></code> 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
<codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">matplotlib.patches.Rectangle.contains()</span></code>) 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="s1">'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="s1">'mouse hover over figure or axes to trigger events'</span><spanclass="p">)</span>
<p>There are a variety of meanings of the <codeclass="docutils literal notranslate"><spanclass="pre">picker</span></code> property:</p>
<blockquote>
<div><dlclass="docutils">
<dt><codeclass="docutils literal notranslate"><spanclass="pre">None</span></code></dt><dd>picking is disabled for this artist (default)</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">boolean</span></code></dt><dd>if True then picking will be enabled and the artist will fire a
pick event if the mouse event is over the artist</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">float</span></code></dt><dd>if picker is a number it is interpreted as an epsilon tolerance in
points and the artist will fire off an event if its data is
within epsilon of the mouse event. For some artists like lines
and patch collections, the artist may provide additional data to
the pick event that is generated, e.g., the indices of the data
within epsilon of the pick event.</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">function</span></code></dt><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 <codeclass="docutils literal notranslate"><spanclass="pre">hit,</span><spanclass="pre">props</span><spanclass="pre">=</span><spanclass="pre">picker(artist,</span><spanclass="pre">mouseevent)</span></code> to
determine the hit test. If the mouse event is over the artist,
return <codeclass="docutils literal notranslate"><spanclass="pre">hit=True</span></code> 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"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">PickEvent</span></code></a>
attributes</dd>
</dl>
</div></blockquote>
<p>After you have enabled an artist for picking by setting the <codeclass="docutils literal notranslate"><spanclass="pre">picker</span></code>
property, you need to connect to the figure canvas pick_event to get
<spanclass="c1"># 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"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">PickEvent</span></code></a> which is passed to
your callback is always fired with two attributes:</p>
<blockquote>
<div><dlclass="docutils">
<dt><codeclass="docutils literal notranslate"><spanclass="pre">mouseevent</span></code> the mouse event that generate the pick event. The</dt><dd>mouse event in turn has attributes like <codeclass="docutils literal notranslate"><spanclass="pre">x</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">y</span></code> (the
coords in display space, e.g., 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"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Axes</span></code></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"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">matplotlib.backend_bases.MouseEvent</span></code></a> for
details.</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">artist</span></code></dt><dd>the <aclass="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Artist</span></code></a> that generated the pick
event.</dd>
</dl>
</div></blockquote>
<p>Additionally, certain artists like <aclass="reference internal" href="../api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Line2D</span></code></a>
and <aclass="reference internal" href="../api/collections_api.html#matplotlib.collections.PatchCollection" title="matplotlib.collections.PatchCollection"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">PatchCollection</span></code></a> may attach
additional meta data like the indices into the data that meet the
picker criteria (e.g., 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, <codeclass="docutils literal notranslate"><spanclass="pre">Line2D</span></code> attaches the ind property,
which are the indices into the line data under the pick point. See
<codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">pick()</span></code> for details on the <codeclass="docutils literal notranslate"><spanclass="pre">PickEvent</span></code>
<spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">set_title</span><spanclass="p">(</span><spanclass="s1">'click on points'</span><spanclass="p">)</span>
<spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">set_title</span><spanclass="p">(</span><spanclass="s1">'click on point to plot time series'</span><spanclass="p">)</span>