Document TUI mouse support in the manual & NEWS

Message ID 20210617122300.3471654-1-pedro@palves.net
State New
Headers show
Series
  • Document TUI mouse support in the manual & NEWS
Related show

Commit Message

Pedro Alves June 17, 2021, 12:23 p.m.
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(+)


base-commit: 82a5082ed3f00b8d7bd1e3810c6eeb4351e35286
-- 
2.26.2

Comments

Simon Marchi via Gdb-patches June 17, 2021, 1:17 p.m. | #1
> 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.
Pedro Alves June 17, 2021, 8:50 p.m. | #2
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.

>
Pedro Alves June 17, 2021, 9:05 p.m. | #3
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.
Simon Marchi via Gdb-patches June 18, 2021, 7:15 a.m. | #4
> 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

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"