\#perminv, 2 of 2: implementation

Add new '|' command, aka #perminv, which allows the player to
send menu scrolling keystrokes to the persistent inventory window.

Implemented for X11, where its usefulness is limited, and for
curses, where it is more needed and also more fully functional.
The interface can either prompt for one keystroke, act upon it,
and return to normal play, or it can loop for multiple keystrokes
until player types <return> or <escape>.  X11 does the former if
the 'slow' application resource is False so that prompting uses
popups, and the latter when 'slow' is True where prompting is in
a fixed spot and doesn't end up causing the persistent inventory
window to be stacked behind the map window.  curses always does
the loop-until-done approach.  It also accepts up and down arrow
keys to scroll one line at a time.

Also adds two new menu scrolling commands, menu_shift_right (key
'}' by default) and menu_shift_left ('{') if wincap2 flags contain
WC2_MENU_SHIFT.  Shifting allows different substrings of too-long
lines to be seen.

For X11, neither works because their handling requires a horizontal
scrollbar and for some reason that escapes me our menus don't have
one of those.  If they did, shifts could work for all menus but a
shifted window would hide the selection letters.  So shifting would
be most usefully done as:  pan right, read more of any long lines,
immediately pan back to the left.

For curses, they only apply to the persistent inventory window.
Shift right redraws it with class headers and inventory letters
shown normally but the item descriptions omit their leftmost
portion, showing more text towards the end.  Shift left reverses
that and does nothing if the beginning is already in view.  Forward
and backward scrolling while shifted leave the shift in place.

doc/Guidebook.mn

@@ -35,7 +35,7 @@
 .ds vr "NetHack 3.7
 .ds f0 "\*(vr
 .ds f1
-.ds f2 "February 11, 2021
+.ds f2 "March 12, 2021
 .
 .\" A note on some special characters:
 .\" \(lq = left double quote
@@ -1068,6 +1068,20 @@ May be preceded by \(oq\f(CRm\fP\(cq to select preferred display order.
 Show discovered types for one class of objects.
 .lp ""
 May be preceded by \(oq\f(CRm\fP\(cq to select preferred display order.
+.lp |
+If persistent inventory display is supported and enabled (with the
+.op perm_invent
+option), interact with it instead of with the map.
+.lp ""
+Allows scrolling with the
+menu_first_page, menu_previous_page,
+menu_next_page, and menu_last_page
+keys (\(oq\f(CR\(ha\fP\(cq, \(oq\f(CR<\fP\(cq,
+\(oq\f(CR>\fP\(cq, \(oq\f(CR|\fP\(cq by default).
+Some interfaces also support menu_shift_left and menu_shift_right
+keys (\(oq\f(CR{\fP\(cq and \(oq\f(CR}\fP\(cq by default).
+Use the \fIReturn\fP (aka \fIEnter\fP) or \fIEscape\fP key to
+resume play.
 .lp !
 Escape to a shell.
 See \(lq#shell\(rq below for more details.
@@ -3828,6 +3842,20 @@ Default \(oq.\(cq.
 Menu character accelerator to select all items on this page of a menu.
 Implemented by the Amiga, Gem and tty ports.
 Default \(oq,\(cq.
+.lp menu_shift_left
+Menu character accelerator to scroll a menu\(emone which has been
+scrolled right\(emback to the left.
+Implemented by curses for
+.op perm_invent
+only and by X11.
+Default \(oq{\(cq.
+.lp menu_shift_right
+Menu character accelerator to scroll a menu which has text beyond the
+right edge to the right.
+Implemented by curses for
+.op perm_invent
+only and by X11.
+Default \(oq}\(cq.
 ." .lp menu_tab_sep
 ." Format menu entries using TAB to separate columns (default off).
 ." Only applicable to some menus, and only useful to some interfaces.

doc/Guidebook.tex

@@ -45,7 +45,7 @@
 %.au
 \author{Original version - Eric S. Raymond\\
 (Edited and expanded for 3.7 by Mike Stephenson and others)}
-\date{February 11, 2021}
+\date{March 12, 2021}
 
 \maketitle
 
@@ -1174,6 +1174,23 @@ Show discovered types for one class of objects.
 \\
 .lp ""
 May be preceded by `{\tt m}' to select preferred display order.
+
+%.lp
+\item[\tb{|}]
+If persistent inventory display is supported and enabled (with the
+{\it perm_invent\/}
+option), interact with it instead of with the map.
+\\
+%.lp ""
+Allows scrolling with the
+menu\verb+_+first\verb+_+page, menu\verb+_+previous\verb+_+page,
+menu\verb+_+next\verb+_+page, and menu\verb+_+last\verb+_+page
+keys (`{\tt \^{}}', `{\tt <}', `{\tt >}', `{\tt |}' by default).
+Some interfaces also support menu_shift_left and menu_shift_right
+keys (`{\tt \verb+{+}' and `{\tt \verb+}+}' by default).
+Use the {\it Return\/} (aka {\it Enter\/}) or {\it Escape\/} key to
+resume play.
+
 %.lp
 \item[\tb{!}]
 Escape to a shell.
@@ -4137,6 +4154,21 @@ Default `.'.
 Menu character accelerator to select all items on this page of a menu.
 Implemented by the Amiga, Gem and tty ports.
 Default `,'.
+
+%.lp
+\item[\ib{menu\verb+_+shift\verb+_+left}]
+Menu character accelerator to scroll a menu---one which has been
+scrolled right---back to the left.
+Implemented by curses for {\it perm\verb+_+invent\/} only and by X11.
+Default `{\tt \verb+{+}'.
+
+%.lp
+\item[\ib{menu\verb+_+shift\verb+_+right}]
+Menu character accelerator to scroll a menu which has text beyond the
+right edge to the right.
+Implemented by curses for {\it perm\verb+_+invent\/} only and by X11.
+Default `{\tt \verb+}+}'.
+Default \(oq}\(cq.
 % %.lp
 % \item[\ib{menu\verb+_+tab\verb+_+sep}]
 % Format menu entries using TAB to separate columns (default off).

doc/fixes37.0

@@ -823,6 +823,11 @@ show bones levels information in enlightenment at end of game or in explore
 	and wizmode
 for #wizintrinsic, use any counts entered during menu selection
 give feedback when boolean options are toggled interactively ('O' command)
+'|' command (#perminv) for interacting with persistent inventory display
+	(curses and X11 only)
+menu_shift_left, menu_shift_right menu command keys; default '{' and '}'
+	(curses for perm_invent only; implemented for X11 too but menus for
+	it lack horizontal scroll bars so the shifts don't work there)
 
 
 Platform- and/or Interface-Specific New Features

doc/window.doc

@@ -259,11 +259,16 @@ display_file(str, boolean complain)
 		-- Display the file named str.  Complain about missing files
 		   iff complain is TRUE.
 update_inventory(arg)
-		-- Indicate to the window port that the inventory has been
-		   changed.
-		-- Merely calls display_inventory() for window-ports that
-		   leave the window up, otherwise empty.
-		-- 'arg' is not used yet
+		-- For an argument of 0:
+		   -- Indicate to the window port that the inventory has
+		      been changed.
+		   -- Merely calls display_inventory() for window-ports
+		      that leave the window up, otherwise empty.
+		-- or for a non-zero argument:
+		   -- Prompts the user for a menu scrolling action and
+		      executes that.
+		   -- May repeat until user finishes (typically by using
+		      <return> or <esc> but interface may use other means).
 doprev_message()
 		-- Display previous messages.  Used by the ^P command.
 		-- On the tty-port this scrolls WIN_MESSAGE back one line.
@@ -810,6 +815,8 @@ to support:
   |  guicolor          | WC2_GUICOLOR       | wc2_guicolor       |boolean |
   |  hilite_status     | WC2_HILITE_STATUS  | wc2_hilite_status  |strings |
   |  hitpointbar       | WC2_HITPOINTBAR    | wc2_hitpointbar    |boolean |
+  |  menu_shift_left   | WC2_MENU_SHIFT     |  n/a               |char    |
+  |  menu_shift_right  | WC2_MENU_SHIFT     |  n/a               |char    |
   |  petattr           | WC2_PETATTR        | wc2_petattr        |int     |
   |  selectsaved       | WC2_SELECTSAVED    | wc2_selectsaved    |boolean |
   |  softkeyboard      | WC2_SOFTKEYBOARD   | wc2_softkeyboard   |boolean |