[PATCH] Document TUI mouse support in the manual & NEWS

[PATCH] Document TUI mouse support in the manual & NEWS

[Pedro Alves]

gdb/ChangeLog:
yyyy-mm-dd  Pedro Alves  <pedro@palves.net>
	    Hannes Domani  <ssbssa@yahoo.de>

	* NEWS: Add new "TUI Improvements" section and mention mouse
	support and that unrecognized special keys are now passed to
	GDB.  Mention Python Window.click in the Python improvements
	section.

gdb/doc/ChangeLog:
yyyy-mm-dd  Pedro Alves  <pedro@palves.net>

	* gdb.texinfo (TUI): <TUI Mouse Support>: New node/section.

Co-​authored-by: Hannes Domani <ssbssa@yahoo.de>

Change-Id: I0d79a795d8ac561fd28cdc5184bff029ba28bc64
---
 gdb/doc/gdb.texinfo | 14 ++++++++++++++
 gdb/NEWS            | 16 ++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7cdc83b9537..c1b63b63f6c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -28371,6 +28371,7 @@ enable} or @kbd{C-x C-a}.  @xref{TUI Commands, ,TUI Commands}, and
 * TUI Overview::                TUI overview
 * TUI Keys::                    TUI key bindings
 * TUI Single Key Mode::         TUI single key mode
+* TUI Mouse Support::           TUI mouse support
 * TUI Commands::                TUI-specific commands
 * TUI Configuration::           TUI configuration variables
 @end menu
@@ -28660,6 +28661,19 @@ If @value{GDBN} was built with Readline 8.0 or later, the TUI
 SingleKey keymap will be named @samp{SingleKey}.  This can be used in
 @file{.inputrc} to add additional bindings to this keymap.
 
+@node TUI Mouse Support
+@section TUI Mouse Support
+@cindex TUI mouse support
+
+If the curses library supports the mouse, the TUI supports mouse
+actions.
+
+The mouse wheel scrolls the appropriate window under the mouse cursor.
+
+On most terminals, pressing and holding the @key{SHIFT} key on your
+keyboard temporarily disables the terminal's mouse protocol, and let's
+you select/paste text with the mouse.
+
 @node TUI Commands
 @section TUI-specific Commands
 @cindex TUI commands
diff --git a/gdb/NEWS b/gdb/NEWS
index 56743fc9aea..bf7041996b9 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -78,6 +78,18 @@
   and "-eiex" that allow options (that would normally appear in a
   gdbearlyinit file) to be passed on the command line.
 
+* TUI improvements
+
+  ** TUI windows now support mouse actions.  The mouse wheel scrolls
+     the appropriate window.
+
+  ** Key combinations that do not have a specific action on the
+     focused window are passed to GDB.  For example, you now can use
+     Ctrl-Left/Ctrl-Right to move between words in the command window
+     regardless of which window is in focus.  Previously you would
+     need to focus on the command window for such key combinations to
+     work.
+
 * New commands
 
 set debug event-loop
@@ -220,6 +232,10 @@ QMemTags
      gives the connection number as seen in 'info connections' and
      'info inferiors'.
 
+  ** Python TUI windows can now receive mouse click events.  If the
+     Window object implements the click method, it is called for each
+     mouse click event in this window.
+
 *** Changes in GDB 10
 
 * There are new feature names for ARC targets: "org.gnu.gdb.arc.core"

base-commit: 82a5082ed3f00b8d7bd1e3810c6eeb4351e35286
-- 
2.26.2

Re: [PATCH] Document TUI mouse support in the manual & NEWS

[Eli Zaretskii]

> From: Pedro Alves <pedro@palves.net>
> Date: Thu, 17 Jun 2021 13:23:00 +0100
> 
> +On most terminals, pressing and holding the @key{SHIFT} key on your
> +keyboard temporarily disables the terminal's mouse protocol, and let's
> +you select/paste text with the mouse.                            ^^^^^

Typo: should be "lets".

And I admit I'm confused by the above text: if one can select with the
mouse, why are we saying that "mouse protocol is disabled"?

> +  ** Key combinations that do not have a specific action on the
> +     focused window are passed to GDB.  For example, you now can use
> +     Ctrl-Left/Ctrl-Right to move between words in the command window
> +     regardless of which window is in focus.  Previously you would
> +     need to focus on the command window for such key combinations to
> +     work.

This part doesn't fit the header line of the patch.

OK with the above fixed.

Thanks.

Re: [PATCH] Document TUI mouse support in the manual & NEWS

[Pedro Alves]

On 2021-06-17 2:17 p.m., Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>
>> Date: Thu, 17 Jun 2021 13:23:00 +0100
>>
>> +On most terminals, pressing and holding the @key{SHIFT} key on your
>> +keyboard temporarily disables the terminal's mouse protocol, and let's
>> +you select/paste text with the mouse.                            ^^^^^
> 
> Typo: should be "lets".
> 
> And I admit I'm confused by the above text: if one can select with the
> mouse, why are we saying that "mouse protocol is disabled"?

How about this then:

"During normal operation, the TUI uses the terminal's mouse protocol
and all mouse input is consumed by the TUI, which means that you
cannot use the mouse to select/paste text, which is a terminal
function, not a TUI function.  On most terminals however, pressing and
holding the @key{SHIFT} key on your keyboard temporarily disables the
terminal's mouse protocol, which then let's you select/paste text with
the mouse."


I did notice that emacs in text mode lets you select text with the
mouse without doing anything special.  How does that work?  How does
selecting text in emacs make the text end up in the terminals selection
buffer?  I'd like it if we could do that same, but I have no idea whether
it's possible with curses.

> 
>> +  ** Key combinations that do not have a specific action on the
>> +     focused window are passed to GDB.  For example, you now can use
>> +     Ctrl-Left/Ctrl-Right to move between words in the command window
>> +     regardless of which window is in focus.  Previously you would
>> +     need to focus on the command window for such key combinations to
>> +     work.
> 
> This part doesn't fit the header line of the patch.

Ah, right.  I'll switch it to "Document TUI improvements".

> 
> OK with the above fixed.
> 
> Thanks.
> 

Re: [PATCH] Document TUI mouse support in the manual & NEWS

[Pedro Alves]

On 2021-06-17 9:50 p.m., Pedro Alves wrote:
> 
> 
> I did notice that emacs in text mode lets you select text with the
> mouse without doing anything special.  How does that work?  How does
> selecting text in emacs make the text end up in the terminals selection
> buffer?  I'd like it if we could do that same, but I have no idea whether
> it's possible with curses.

Oh, it doesn't really.  I did not have the mouse mode active at all.
If I enable xterm-mouse-mode, then in order to access the terminal's
mouse select/paste functionality (*), I have to press&hold the shift key, same as
the TUI.

* - click & drag to select, middle click to paste.

Re: [PATCH] Document TUI mouse support in the manual & NEWS

[Eli Zaretskii]

> From: Pedro Alves <pedro@palves.net>
> Cc: gdb-patches@sourceware.org
> Date: Thu, 17 Jun 2021 21:50:02 +0100
> 
> On 2021-06-17 2:17 p.m., Eli Zaretskii wrote:
> >> From: Pedro Alves <pedro@palves.net>
> >> Date: Thu, 17 Jun 2021 13:23:00 +0100
> >>
> >> +On most terminals, pressing and holding the @key{SHIFT} key on your
> >> +keyboard temporarily disables the terminal's mouse protocol, and let's
> >> +you select/paste text with the mouse.                            ^^^^^
> > 
> > Typo: should be "lets".
> > 
> > And I admit I'm confused by the above text: if one can select with the
> > mouse, why are we saying that "mouse protocol is disabled"?
> 
> How about this then:
> 
> "During normal operation, the TUI uses the terminal's mouse protocol
> and all mouse input is consumed by the TUI, which means that you
> cannot use the mouse to select/paste text, which is a terminal
> function, not a TUI function.  On most terminals however, pressing and
> holding the @key{SHIFT} key on your keyboard temporarily disables the
> terminal's mouse protocol, which then let's you select/paste text with
> the mouse."

AFAIU, what is missing here is the fact that "select/paste text with
the mouse" copies/pastes text to/from the _terminal_'s selection
buffer (as opposed to the GDB's TUI buffer).  I think your original
text will be fine if you mention this explicitly.  IOW, we need to say
that this copy/paste bypasses GDB and goes into the terminal's
text-selection functionality.

Thanks.

[PATCH] Document TUI improvements in the manual & NEWS (was: Re: [PATCH] Document TUI mouse support in the manual & NEWS)

[Pedro Alves]

Hi,

On 2021-06-18 8:15 a.m., Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>
>> Cc: gdb-patches@sourceware.org
>> Date: Thu, 17 Jun 2021 21:50:02 +0100
>>
>> On 2021-06-17 2:17 p.m., Eli Zaretskii wrote:
>>>> From: Pedro Alves <pedro@palves.net>
>>>> Date: Thu, 17 Jun 2021 13:23:00 +0100
>>>>
>>>> +On most terminals, pressing and holding the @key{SHIFT} key on your
>>>> +keyboard temporarily disables the terminal's mouse protocol, and let's
>>>> +you select/paste text with the mouse.                            ^^^^^
>>>
>>> Typo: should be "lets".
>>>
>>> And I admit I'm confused by the above text: if one can select with the
>>> mouse, why are we saying that "mouse protocol is disabled"?
>>
>> How about this then:
>>
>> "During normal operation, the TUI uses the terminal's mouse protocol
>> and all mouse input is consumed by the TUI, which means that you
>> cannot use the mouse to select/paste text, which is a terminal
>> function, not a TUI function.  On most terminals however, pressing and
>> holding the @key{SHIFT} key on your keyboard temporarily disables the
>> terminal's mouse protocol, which then let's you select/paste text with
>> the mouse."
> 
> AFAIU, what is missing here is the fact that "select/paste text with
> the mouse" copies/pastes text to/from the _terminal_'s selection
> buffer (as opposed to the GDB's TUI buffer).  I think your original
> text will be fine if you mention this explicitly.  IOW, we need to say
> that this copy/paste bypasses GDB and goes into the terminal's
> text-selection functionality.

How about this then?

From db9ff15e9b69bb46332a6b492886d5c95f727daf Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Fri, 4 Jun 2021 17:12:41 +0100
Subject: [PATCH] Document TUI improvements in the manual & NEWS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

gdb/ChangeLog:
yyyy-mm-dd  Pedro Alves  <pedro@palves.net>
	    Hannes Domani  <ssbssa@yahoo.de>

	* NEWS: Add new "TUI Improvements" section and mention mouse
	support and that unrecognized special keys are now passed to
	GDB.  Mention Python Window.click in the Python improvements
	section.

gdb/doc/ChangeLog:
yyyy-mm-dd  Pedro Alves  <pedro@palves.net>

	* gdb.texinfo (TUI): <TUI Mouse Support>: New node/section.

Co-​authored-by: Hannes Domani <ssbssa@yahoo.de>

Change-Id: I0d79a795d8ac561fd28cdc5184bff029ba28bc64
---
 gdb/doc/gdb.texinfo | 18 ++++++++++++++++++
 gdb/NEWS            | 16 ++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f1c3e7ba847..a16a3825ebb 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -28387,6 +28387,7 @@ enable} or @kbd{C-x C-a}.  @xref{TUI Commands, ,TUI Commands}, and
 * TUI Overview::                TUI overview
 * TUI Keys::                    TUI key bindings
 * TUI Single Key Mode::         TUI single key mode
+* TUI Mouse Support::           TUI mouse support
 * TUI Commands::                TUI-specific commands
 * TUI Configuration::           TUI configuration variables
 @end menu
@@ -28676,6 +28677,23 @@ If @value{GDBN} was built with Readline 8.0 or later, the TUI
 SingleKey keymap will be named @samp{SingleKey}.  This can be used in
 @file{.inputrc} to add additional bindings to this keymap.
 
+@node TUI Mouse Support
+@section TUI Mouse Support
+@cindex TUI mouse support
+
+If the curses library supports the mouse, the TUI supports mouse
+actions.
+
+The mouse wheel scrolls the appropriate window under the mouse cursor.
+
+The TUI itself does not directly support copying/pasting with the
+mouse.  However, on Unix terminals, you can typically press and hold
+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.
+
 @node TUI Commands
 @section TUI-specific Commands
 @cindex TUI commands
diff --git a/gdb/NEWS b/gdb/NEWS
index 7f3ed4f02f0..1e474eca90a 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -108,6 +108,18 @@
   registers of a target.  The precise requirements of this register
   feature are documented in the GDB manual.
 
+* TUI improvements
+
+  ** TUI windows now support mouse actions.  The mouse wheel scrolls
+     the appropriate window.
+
+  ** Key combinations that do not have a specific action on the
+     focused window are passed to GDB.  For example, you now can use
+     Ctrl-Left/Ctrl-Right to move between words in the command window
+     regardless of which window is in focus.  Previously you would
+     need to focus on the command window for such key combinations to
+     work.
+
 * New commands
 
 set debug event-loop
@@ -266,6 +278,10 @@ QMemTags
      gdb.BreakpointEvent rather than a gdb.StopEvent.  The
      gdb.Breakpoint attached to the event will have type BP_CATCHPOINT.
 
+  ** Python TUI windows can now receive mouse click events.  If the
+     Window object implements the click method, it is called for each
+     mouse click event in this window.
+
 *** Changes in GDB 10
 
 * There are new feature names for ARC targets: "org.gnu.gdb.arc.core"

base-commit: e0fd25e4859e1610395b93ff6f05d67c13220cf6
-- 
2.26.2

Re: [PATCH] Document TUI improvements in the manual & NEWS (was: Re: [PATCH] Document TUI mouse support in the manual & NEWS)

[Eli Zaretskii]

> From: Pedro Alves <pedro@palves.net>
> Cc: gdb-patches@sourceware.org
> Date: Sun, 27 Jun 2021 18:44:04 +0100
> 
> > AFAIU, what is missing here is the fact that "select/paste text with
> > the mouse" copies/pastes text to/from the _terminal_'s selection
> > buffer (as opposed to the GDB's TUI buffer).  I think your original
> > text will be fine if you mention this explicitly.  IOW, we need to say
> > that this copy/paste bypasses GDB and goes into the terminal's
> > text-selection functionality.
> 
> How about this then?

Fine by me, thanks.

Re: [PATCH] Document TUI improvements in the manual & NEWS (was: Re: [PATCH] Document TUI mouse support in the manual & NEWS)

[Pedro Alves]

On 2021-06-27 8:14 p.m., Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>
>> Cc: gdb-patches@sourceware.org
>> Date: Sun, 27 Jun 2021 18:44:04 +0100
>>
>>> AFAIU, what is missing here is the fact that "select/paste text with
>>> the mouse" copies/pastes text to/from the _terminal_'s selection
>>> buffer (as opposed to the GDB's TUI buffer).  I think your original
>>> text will be fine if you mention this explicitly.  IOW, we need to say
>>> that this copy/paste bypasses GDB and goes into the terminal's
>>> text-selection functionality.
>>
>> How about this then?
> 
> Fine by me, thanks.
> 

Thanks, I've merged it now.