Skip to content

DOC: restore navigation documentation #25926

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 14, 2023
+83 −7
Merged

DOC: restore navigation documentation #25926

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 83 additions & 7 deletions galleries/users_explain/figure/interactive.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,25 +194,101 @@ the GUI main loop in some other way.
interactive mode. This may work (depending on the GUI toolkit) but
will likely result in a non-responsive figure.

.. _navigation-toolbar:

.. _default_ui:

Default UI
==========


The windows created by :mod:`~.pyplot` have an interactive toolbar with navigation
buttons and a readout of the data values the cursor is pointing at. A number of
helpful keybindings are registered by default.
buttons and a readout of the data values the cursor is pointing at.

.. _navigation-toolbar:

Interactive navigation
======================

.. image:: ../../../_static/toolbar.png

All figure windows come with a navigation toolbar, which can be used
to navigate through the data set. Here is a description of each of
the buttons at the bottom of the toolbar

.. image:: ../../../../lib/matplotlib/mpl-data/images/home_large.png

.. image:: ../../../../lib/matplotlib/mpl-data/images/back_large.png

.. image:: ../../../../lib/matplotlib/mpl-data/images/forward_large.png

The ``Home``, ``Forward`` and ``Back`` buttons
These are akin to a web browser's home, forward and back controls.
``Forward`` and ``Back`` are used to navigate back and forth between
previously defined views. They have no meaning unless you have already
navigated somewhere else using the pan and zoom buttons. This is analogous
to trying to click ``Back`` on your web browser before visiting a
new page or ``Forward`` before you have gone back to a page --
nothing happens. ``Home`` always takes you to the
first, default view of your data. Again, all of these buttons should
feel very familiar to any user of a web browser.

.. image:: ../../../../lib/matplotlib/mpl-data/images/move_large.png

The ``Pan/Zoom`` button
This button has two modes: pan and zoom. Click the toolbar button
to activate panning and zooming, then put your mouse somewhere
over an axes. Press the left mouse button and hold it to pan the
figure, dragging it to a new position. When you release it, the
data under the point where you pressed will be moved to the point
where you released. If you press 'x' or 'y' while panning the
motion will be constrained to the x or y axis, respectively. Press
the right mouse button to zoom, dragging it to a new position.
The x axis will be zoomed in proportionately to the rightward
movement and zoomed out proportionately to the leftward movement.
The same is true for the y axis and up/down motions. The point under your
mouse when you begin the zoom remains stationary, allowing you to
zoom in or out around that point as much as you wish. You can use the
modifier keys 'x', 'y' or 'CONTROL' to constrain the zoom to the x
axis, the y axis, or aspect ratio preserve, respectively.

With polar plots, the pan and zoom functionality behaves
differently. The radius axis labels can be dragged using the left
mouse button. The radius scale can be zoomed in and out using the
right mouse button.

.. image:: ../../../../lib/matplotlib/mpl-data/images/zoom_to_rect_large.png

The ``Zoom-to-rectangle`` button
Click this toolbar button to activate this mode. Put your mouse somewhere
over an axes and press a mouse button. Define a rectangular region by
dragging the mouse while holding the button to a new location. When using
the left mouse button, the axes view limits will be zoomed to the defined
region. When using the right mouse button, the axes view limits will be
zoomed out, placing the original axes in the defined region.

.. image:: ../../../../lib/matplotlib/mpl-data/images/subplots_large.png

The ``Subplot-configuration`` button
Use this tool to configure the appearance of the subplot:
you can stretch or compress the left, right, top, or bottom
side of the subplot, or the space between the rows or
space between the columns.

.. image:: ../../../../lib/matplotlib/mpl-data/images/filesave_large.png

The ``Save`` button
Click this button to launch a file save dialog. You can save
files with the following extensions: ``png``, ``ps``, ``eps``,
``svg`` and ``pdf``.


.. _key-event-handling:

Navigation keyboard shortcuts
-----------------------------

The following table holds all the default keys, which can be
overwritten by use of your :ref:`matplotlibrc
<customizing>`.
A number of helpful keybindings are registered by default. The following table
holds all the default keys, which can be overwritten by use of your
:ref:`matplotlibrc <customizing>`.

================================== ===============================
Command Default key binding and rcParam
Expand Down