[Enhancement] Improve User Interaction Clarity for Polygon Drawing Tool in Bokeh 3.4.x

[angelsen]

Software versions

Python version : 3.11.8 (main, Feb 12 2024, 14:50:05) [GCC 13.2.1 20230801]
IPython version : (not installed)
Tornado version : 6.4
Bokeh version : 3.4.1
BokehJS static path : /home/fredrik/Documents/git/bokeh/bokeh_server/myapp_one/.venv/lib/python3.11/site-packages/bokeh/server/static
node.js version : v21.7.3
npm version : 10.5.2
jupyter_bokeh version : (not installed)
Operating system : Linux-6.8.7-arch1-1-x86_64-with-glibc2.39

Browser name and version

Google Chrome 124.0.6367.78

Jupyter notebook / Jupyter Lab version

No response

Expected behavior

Steps to Reproduce

1. Navigate to the poly_draw example in the Bokeh 3.4.x documentation.
2. Attempt to use the tool by double-clicking to set an initial vertex.
3. Try adding additional vertices by clicking.
4. Press ESC to complete the shape.

Expected Behavior

The tool should allow setting an initial vertex with a double-click, adding vertices with further clicks, and completing the drawing with the ESC key, as it works in version 3.3.4.

Observed behavior

Actual Behavior

• Description of what actually happens when following the steps above, with details on how the tool fails to perform as expected.

Example code

from bokeh.models import PolyDrawTool
from bokeh.plotting import figure, show

p = figure(x_range=(0, 10), y_range=(0, 10), width=400, height=400,
           title='Poly Draw Tool')

r1 = p.patches([[2, 5, 8]], [[2, 8, 2]], line_width=0, alpha=0.4)

r2 = p.multi_line([[1, 9]], [[5, 5]], line_width=5, alpha=0.4, color='red')

draw_tool_r1 = PolyDrawTool(renderers=[r1])
p.toolbar.active_drag = draw_tool_r1

draw_tool_r2 = PolyDrawTool(renderers=[r2])
p.add_tools(draw_tool_r1, draw_tool_r2)

show(p)

Stack traceback or browser console output

Additional Context

This issue was initially pointed out in a forum discussion here.

Screenshots

No response

[mattpap]

Attempt to use the tool by double-clicking to set an initial vertex.

In bokeh 3.4 we had to replace double tap gesture with press gesture in edit tools and others, due to changes in UI gesture recognition. Press on the canvas to add the first vertex, then tap to added subsequent vertices and press again to finalize drawing.

[angelsen]

When i try the latest example poly_draw.html i'm not able to add new patches or multi-lines by press(single tap?). I get the same unexpected behaviour if i run the example locally.

$ bokeh info
Python version        :  3.11.8 (main, Feb 12 2024, 14:50:05) [GCC 13.2.1 20230801]
IPython version       :  (not installed)
Tornado version       :  6.4
Bokeh version         :  3.4.1
BokehJS static path   :  /home/fredrik/Documents/git/bokeh/bokeh_server/myapp_one/.venv/lib/python3.11/site-packages/bokeh/server/static
node.js version       :  v21.7.3
npm version           :  10.5.2
jupyter_bokeh version :  (not installed)
Operating system      :  Linux-6.8.7-arch1-1-x86_64-with-glibc2.39

[bryevdv]

@angelsen the first tap has to be a "long" press, I don't think this docs are clear on this point.

The UX is also presently lacking significantly in that there is no indication that the tool has been activated after the long press, or even after the second tap. Nothing shows up at all until a third vertex is dropped, which makes it very hard to judge what the tool is doing. cc @philippjfr

[philippjfr]

I'd have to look at this again in more detail and am away from my computer at least until Tuesday but iirc @mattpap made some significant changes to the UX of the draw/edit tools that may not have been documented.

[bryevdv]

Regardless of the documentation, the current UX is fairly impossible to navigate out of the box. There are no visual cues that anything at all is happening at all, until after a long press and two taps happen. It's very easy to imagine why users thinks it is just not working.

[philippjfr]

Yes, it's pretty clear this needs another in-depth look. I'm out of office until tomorrow, in the meantime @mattpap could you summarize what was changed here an why.

[mattpap]

The only recent and intentional change to edit/draw tools was replacement of double tap gesture with press tap. It was documented, but perhaps it wasn't advertised sufficiently. However, I myself have a problem with understanding whether the relevant tools actually work or not, at least without consulting documentation and source code. We previously discussed the possibility of redesigning those tools, but nothing came to fruition yet.

[angelsen]

I believe it would be beneficial for users if the documentation included a dedicated section explaining the different gesture interactions required for tools in Bokeh. If such documentation already exists, it would be helpful to have it linked directly within the sections where these tools are described or discussed.

[bryevdv]

@angelsen can you be more specific with your suggestion, e.g. what exact pages you have in mind? Currently there is an entire user guide chapter dedicated to tools:

https://docs.bokeh.org/en/latest/docs/user_guide/interaction/tools.html

with a subsection for edit tools, where all the individual edit tools have their own subsections such as

https://docs.bokeh.org/en/latest/docs/user_guide/interaction/tools.html#boxedittool

each with descriptions like this for their use:

Add box
Hold shift, then click and drag anywhere on the plot or press tap once to start drawing. Move the mouse and press tap again to finish drawing.

Move box
Click and drag an existing box. The box will be dropped once you let go of the mouse button.

Delete box
Tap a box to select it, then press the BACKSPACE key while the mouse is within the plot area.
To Move or Delete multiple boxes at once:

Move selection
Select box(es) with SHIFT+tap (or another selection tool) then drag anywhere on the plot. Selecting and then dragging on a specific box will move both.

Delete selection
Select box(es) with SHIFT+tap (or another selection tool) then press BACKSPACE while the mouse is within the plot area.

[angelsen]

Press tap differs from tap, press involves a long hold tap. This behavior is perhaps more intuitive on touch devices. However, I believe the documentation would benefit from clearly differentiating Press tap and tap, especially for those using a mouse.

PolySelectTool#

• name: 'poly_select'

• icon:

The polygon selection tool allows you to define an arbitrary polygonal region for selection by left-clicking a mouse, or tapping a finger at different locations.

After a selection is made, the indices of the selected points are available from properties on the Selection object for a glyph data source. For example:

source.selected.indices

will hold the selected indices in the common case of a “scatter” type glyph.

Note

Complete the selection by making press tap on the canvas. To make a multiple selection, press the SHIFT key. To clear the selection, press the ESC key.

E.g., when i read the documentation for PolySelectTool i wouldn't know, now i do, that press tap = long press/click.

Ideally this should be intuniv and a user shouldn't be required to read the documentation, but developers do and could guide a user via tooltips etc.