<commit_before>.. _userguide_tools:

Configuring Plot Tools
======================

Bokeh comes with a number of interactive tools that can be used to report
information, to change plot parameters such as zoom level or range extents,
or to add, edit, or delete glyphs. Tools can be grouped into four basic
categories:

Gestures
    These are tools that respond to single gestures, such as a pan movement.
    The types of gesture tools are:

    - :ref:`userguide_tools_pandrag`
    - :ref:`userguide_tools_clicktap`
    - :ref:`userguide_tools_scrollpinch`

    For each type of gesture, one tool can be active at any given time, and
    the active tool is indicated on the toolbar by a highlight next to to the
    tool icon.

:ref:`userguide_tools_actions`
    These  are immediate or modal operations that are only activated when their
    button in the toolbar is pressed, such as the ``ResetTool``.

:ref:`userguide_tools_inspectors`
    These are passive tools that report information or annotate plots in some
    way, such as the ``HoverTool`` or ``CrosshairTool``.

:ref:`userguide_tools_edit`
    These are sophisticated multi-gesture tools that can add, delete, or modify
    glyphs on a plot. Since they may respond to several gestures at once, an
    edit tool will potentially deactivate multiple single-gesture tools at once
    when it is activated.

In addition to information about all the individual tools, this chapter
describes how the toolbar may be configured.

.. _userguide_tools_toolbar:

Positioning the Toolbar
-----------------------

By default, Bokeh plots come with a toolbar above the plot. In this section
you will learn how to specify a different location for the toolbar, or to
remove it entirely.

The toolbar location can be specified by passing the ``toolbar_location``
parameter to the |figure| function. Valid values are:

* ``"above"``
* ``"below"``
* ``"left"``
* ``"right"``

If you would like to hide the toolbar entirely, pass ``None``.

Below is some code that positions the toolbar below the plot. Try
running the code and changing the ``toolbar_location`` value.

.. bokeh-plot:: docs/user_guide/examples/tools_position_toolbar_clash.py
    :source-position: above

Note that the toolbar position clashes with the default axes, in this case
setting the ``toolbar_sticky`` option to ``False`` will move the toolbar
to outside of the region where the axis is drawn.

.. bokeh-plot:: docs/user_guide/examples/tools_position_toolbar.py
    :source-position: above

.. _userguide_tools_specifying_tools:

Specifying Tools
----------------

At the lowest ``bokeh.models`` level, tools are added to a ``Plot`` by
passing instances of ``Tool`` objects to the ``add_tools`` method:

.. code-block:: python

    plot = Plot()
    plot.add_tools(LassoSelectTool())
    plot.add_tools(WheelZoomTool())

This explicit way of adding tools works with any Bokeh ``Plot`` or
``Plot`` subclass, such as ``Figure``.

Tools can be specified by passing the ``tools`` parameter to the |figure|
function. The tools parameter accepts a list of tool objects, for instance:

.. code-block:: python

    tools = [BoxZoomTool(), ResetTool()]

Tools can also be supplied conveniently with a comma-separate string
containing tool shortcut names:

.. code-block:: python

    tools = "pan,wheel_zoom,box_zoom,reset"

However, this method does not allow setting properties of the tools.

Finally, it is also always possible to add new tools to a plot by passing
a tool object to the ``add_tools`` method of a plot. This can also be done
in conjunction with the ``tools`` keyword described above:

.. code-block:: python

    from bokeh.models import BoxSelectTool

    plot = figure(tools="pan,wheel_zoom,box_zoom,reset")
    plot.add_tools(BoxSelectTool(dimensions=["width"]))

.. _userguide_tools_setting_active_tools:

Setting the Active Tools
------------------------

Bokeh toolbars can have (at most) one active tool from each kind of gesture
(drag, scroll, tap). By default, Bokeh will use a default pre-defined
order of preference to choose one of each kind from the set of configured
tools, to be active.

However it is possible to exert control over which tool is active. At the
lowest ``bokeh.models`` level, this is accomplished by using the ``active_drag``,
``active_inspect``, ``active_scroll``, and ``active_tap`` properties of
``Toolbar``. These properties can take the following values:

* ``None`` --- there is no active tool of this kind
* ``"auto"`` --- Bokeh chooses a tool of this kind to be active (possibly none)
* a ``Tool`` instance --- Bokeh sets the given tool to be the active tool

Additionally, the ``active_inspect`` tool may accept:
* A sequence of ``Tool`` instances to be set as the active tools

As an example:

.. code-block:: python

    # configure so that no drag tools are active
    plot.toolbar.active_drag = None

    # configure so that Bokeh chooses what (if any) scroll tool is active
    plot.toolbar.active_scroll = "auto"

    # configure so that a specific PolySelect tap tool is active
    plot.toolbar.active_tap = poly_select

    # configure so that a sequence of specific inspect tools are active
    # note: this only works for inspect tools
    plot.toolbar.active_inspect = [hover_tool, crosshair_tool]

The default value for all of these properties is ``"auto"``.

Active tools can be specified by passing the these properties as keyword
arguments to the |figure| function. It is also possible to pass any one of
the string names for, ease of configuration:

.. code-block:: python

    # configures the lasso tool to be active
    plot = figure(tools="pan,lasso_select,box_select", active_drag="lasso_select")

.. _userguide_tools_pandrag:

Pan/Drag Tools
--------------

These tools are employed by panning (on touch devices) or left-dragging (on
mouse devices). Only one pan/drag tool may be active at a time. Where
applicable, Pan/Drag tools will respect any max and min values set on ranges.

BoxSelectTool
~~~~~~~~~~~~~

* name: ``'box_select'``
* icon: |box_select_icon|

The box selection tool allows the user to define a rectangular selection
region by left-dragging a mouse, or dragging a finger across the plot area.
The box select tool may be configured to select across only one dimension by
setting the ``dimensions`` property to a list containing ``width`` or
``height``.<commit_msg>Corrected docs for `dimensions` parameter to BoxZoomTool (#8004)<commit_after>.. _userguide_tools:

Configuring Plot Tools
======================

Bokeh comes with a number of interactive tools that can be used to report
information, to change plot parameters such as zoom level or range extents,
or to add, edit, or delete glyphs. Tools can be grouped into four basic
categories:

Gestures
    These are tools that respond to single gestures, such as a pan movement.
    The types of gesture tools are:

    - :ref:`userguide_tools_pandrag`
    - :ref:`userguide_tools_clicktap`
    - :ref:`userguide_tools_scrollpinch`

    For each type of gesture, one tool can be active at any given time, and
    the active tool is indicated on the toolbar by a highlight next to to the
    tool icon.

:ref:`userguide_tools_actions`
    These  are immediate or modal operations that are only activated when their
    button in the toolbar is pressed, such as the ``ResetTool``.

:ref:`userguide_tools_inspectors`
    These are passive tools that report information or annotate plots in some
    way, such as the ``HoverTool`` or ``CrosshairTool``.

:ref:`userguide_tools_edit`
    These are sophisticated multi-gesture tools that can add, delete, or modify
    glyphs on a plot. Since they may respond to several gestures at once, an
    edit tool will potentially deactivate multiple single-gesture tools at once
    when it is activated.

In addition to information about all the individual tools, this chapter
describes how the toolbar may be configured.

.. _userguide_tools_toolbar:

Positioning the Toolbar
-----------------------

By default, Bokeh plots come with a toolbar above the plot. In this section
you will learn how to specify a different location for the toolbar, or to
remove it entirely.

The toolbar location can be specified by passing the ``toolbar_location``
parameter to the |figure| function. Valid values are:

* ``"above"``
* ``"below"``
* ``"left"``
* ``"right"``

If you would like to hide the toolbar entirely, pass ``None``.

Below is some code that positions the toolbar below the plot. Try
running the code and changing the ``toolbar_location`` value.

.. bokeh-plot:: docs/user_guide/examples/tools_position_toolbar_clash.py
    :source-position: above

Note that the toolbar position clashes with the default axes, in this case
setting the ``toolbar_sticky`` option to ``False`` will move the toolbar
to outside of the region where the axis is drawn.

.. bokeh-plot:: docs/user_guide/examples/tools_position_toolbar.py
    :source-position: above

.. _userguide_tools_specifying_tools:

Specifying Tools
----------------

At the lowest ``bokeh.models`` level, tools are added to a ``Plot`` by
passing instances of ``Tool`` objects to the ``add_tools`` method:

.. code-block:: python

    plot = Plot()
    plot.add_tools(LassoSelectTool())
    plot.add_tools(WheelZoomTool())

This explicit way of adding tools works with any Bokeh ``Plot`` or
``Plot`` subclass, such as ``Figure``.

Tools can be specified by passing the ``tools`` parameter to the |figure|
function. The tools parameter accepts a list of tool objects, for instance:

.. code-block:: python

    tools = [BoxZoomTool(), ResetTool()]

Tools can also be supplied conveniently with a comma-separate string
containing tool shortcut names:

.. code-block:: python

    tools = "pan,wheel_zoom,box_zoom,reset"

However, this method does not allow setting properties of the tools.

Finally, it is also always possible to add new tools to a plot by passing
a tool object to the ``add_tools`` method of a plot. This can also be done
in conjunction with the ``tools`` keyword described above:

.. code-block:: python

    from bokeh.models import BoxSelectTool

    plot = figure(tools="pan,wheel_zoom,box_zoom,reset")
    plot.add_tools(BoxSelectTool(dimensions="width"))

.. _userguide_tools_setting_active_tools:

Setting the Active Tools
------------------------

Bokeh toolbars can have (at most) one active tool from each kind of gesture
(drag, scroll, tap). By default, Bokeh will use a default pre-defined
order of preference to choose one of each kind from the set of configured
tools, to be active.

However it is possible to exert control over which tool is active. At the
lowest ``bokeh.models`` level, this is accomplished by using the ``active_drag``,
``active_inspect``, ``active_scroll``, and ``active_tap`` properties of
``Toolbar``. These properties can take the following values:

* ``None`` --- there is no active tool of this kind
* ``"auto"`` --- Bokeh chooses a tool of this kind to be active (possibly none)
* a ``Tool`` instance --- Bokeh sets the given tool to be the active tool

Additionally, the ``active_inspect`` tool may accept:
* A sequence of ``Tool`` instances to be set as the active tools

As an example:

.. code-block:: python

    # configure so that no drag tools are active
    plot.toolbar.active_drag = None

    # configure so that Bokeh chooses what (if any) scroll tool is active
    plot.toolbar.active_scroll = "auto"

    # configure so that a specific PolySelect tap tool is active
    plot.toolbar.active_tap = poly_select

    # configure so that a sequence of specific inspect tools are active
    # note: this only works for inspect tools
    plot.toolbar.active_inspect = [hover_tool, crosshair_tool]

The default value for all of these properties is ``"auto"``.

Active tools can be specified by passing the these properties as keyword
arguments to the |figure| function. It is also possible to pass any one of
the string names for, ease of configuration:

.. code-block:: python

    # configures the lasso tool to be active
    plot = figure(tools="pan,lasso_select,box_select", active_drag="lasso_select")

.. _userguide_tools_pandrag:

Pan/Drag Tools
--------------

These tools are employed by panning (on touch devices) or left-dragging (on
mouse devices). Only one pan/drag tool may be active at a time. Where
applicable, Pan/Drag tools will respect any max and min values set on ranges.

BoxSelectTool
~~~~~~~~~~~~~

* name: ``'box_select'``
* icon: |box_select_icon|

The box selection tool allows the user to define a rectangular selection
region by left-dragging a mouse, or dragging a finger across the plot area.
The box select tool may be configured to select across only one dimension by
setting the ``dimensions`` property to ``width`` or ``height`` instead of the
default ``both``.
{'fraction_non_alphanumeric': 0.09215762777994538, 'fraction_numerical': 0.00031213421771361687, 'mean_word_length': 4.0023419203747075, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1545956', 'n_tokens_mistral': 3580, 'n_tokens_neox': 3460, 'n_words': 1678}