gdb/tui: add 'set tui mouse-events off' to restore mouse selection

Rationale:
I use the mouse with my terminal to select and copy text. In gdb, I use
the mouse to select a function name to set a breakpoint, or a variable
name to print, for example.

When gdb is compiled with ncurses mouse support, gdb's TUI mode
intercepts mouse events. Left-clicking and dragging, which would
normally select text, seems to do nothing. This means I cannot select
text using my mouse anymore. This makes it harder to set breakpoints,
print variables, etc.

Solution:
I tried to fix this issue by editing the 'mousemask' call to only enable
buttons 4 and 5. However, this still caused my terminal (gnome-terminal)
to not allow text to be selected. The only way I could make it work is
by calling 'mousemask (0, NULL);'. But doing so disables the mouse code
entirely, which other people might want.

I therefore decided to make a setting in gdb called 'tui mouse-events'.
If enabled (the default), the behavior is as it is now: terminal mouse
events are given to gdb, disabling the terminal's default behavior.
If disabled (opt-in), the behavior is as it was before the year 2020:
terminal mouse events are not given to gdb, therefore the mouse can be
used to select and copy text.

Notes:
I am not attached to the setting name or its description. Feel free to
suggest better wording.

Testing:
I tested this change in gnome-terminal by performing the following steps
manually:

1. Run: gdb --args ./myprogram
2. Enable TUI: press ctrl-x ctrl-a
3. Click and drag text with the mouse. Observe no selection.
4. Input: set tui mouse-events off
5. Click and drag text with the mouse. Observe that selection works now.
6. Input: set tui mouse-events on.
7. Click and drag text with the mouse. Observe no selection.

2 files changed, 19 insertions, 1 deletions

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 5db30bf..f9c2f95 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -30219,7 +30219,13 @@ the @key{SHIFT} key on your keyboard to temporarily bypass
 @value{GDBN}'s TUI and access the terminal's native mouse copy/paste
 functionality (commonly, click-drag-release or double-click to select
 text, middle-click to paste).  This copy/paste works with the
-terminal's selection buffer, as opposed to the TUI's buffer.
+terminal's selection buffer, as opposed to the TUI's buffer.  Alternatively, to
+disable mouse support in the TUI entirely and give the terminal control over
+mouse clicks, turn off the @code{tui mouse-events} setting
+(@pxref{tui-mouse-events,,set tui mouse-events}).
+
+Python extensions can react to mouse clicks
+(@pxref{python-window-click,,Window.click}).
 
 @node TUI Commands
 @section TUI-specific Commands
@@ -30500,6 +30506,13 @@ The default display uses more space for line numbers; the compact
 display uses only as much space as is needed for the line numbers in
 the current file.
 
+@anchor{tui-mouse-events}
+@item set tui mouse-events @r{[}on@r{|}off@r{]}
+@kindex set tui mouse-events
+When on (default), mouse clicks control the TUI (@pxref{TUI Mouse Support}).
+When off, mouse clicks are handled by the terminal, enabling terminal-native
+text selection.
+
 @kindex set debug tui
 @item set debug tui @r{[}on|off@r{]}
 Turn on or off display of @value{GDBN} internal debug messages relating
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 5b13958..82fa0e3 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -6974,11 +6974,16 @@ contents.  A positive argument should cause the viewport to move down,
 and so the content should appear to move up.
 @end defun
 
+@anchor{python-window-click}
 @defun Window.click (x, y, button)
 This is called on a mouse click in this window.  @var{x} and @var{y} are
 the mouse coordinates inside the window (0-based, from the top left
 corner), and @var{button} specifies which mouse button was used, whose
 values can be 1 (left), 2 (middle), or 3 (right).
+
+When TUI mouse events are disabled by turning off the @code{tui mouse-events}
+setting (@pxref{tui-mouse-events,,set tui mouse-events}), then @code{click} will
+not be called.
 @end defun
 
 @node Disassembly In Python