master 4bf6f8d9976: Introduce an option which controls touch screen hscroll

[Po Lu]

branch: master
commit 4bf6f8d99765851e46f58488bae75c19bcc6c797
Author: Po Lu <luangruo@yahoo.com>
Commit: Po Lu <luangruo@yahoo.com>

    Introduce an option which controls touch screen hscroll
    
    * doc/emacs/input.texi (Touchscreens): Document this new
    function and revise this node for clarity and pithiness.
    
    * lisp/touch-screen.el (touch-screen): New custom group.
    (touch-screen-display-keyboard, touch-screen-delay)
    (touch-screen-precision-scroll, touch-screen-word-select)
    (touch-screen-extend-selection, touch-screen-preview-select):
    Move such options to that group.
    (touch-screen-enable-hscroll): New user option.
    (touch-screen-handle-scroll): If it is disabled, maintain the
    hscroll accumulators but refrain from scrolling the window.
---
 doc/emacs/input.texi | 84 +++++++++++++++++++++++++---------------------------
 lisp/touch-screen.el | 35 +++++++++++++++++-----
 2 files changed, 68 insertions(+), 51 deletions(-)

diff --git a/doc/emacs/input.texi b/doc/emacs/input.texi
index db0e88a1c9c..5b559652896 100644
--- a/doc/emacs/input.texi
+++ b/doc/emacs/input.texi
@@ -23,56 +23,56 @@ which is detailed here.
 @section Using Emacs on Touchscreens
 @cindex touchscreen input
 
-  Touchscreen input works by pressing and moving tools (which include
-fingers and some pointing devices--styluses, for example) onto a frame
-in order to manipulate its contents.
+  Touchscreen input is the manipulation of a frame's contents by the
+placement and motion of tools (instanced by fingers and such pointing
+devices as styluses) on a monitor or computer terminal where a frame
+is displayed.
 
-  When running under the X Window System or Android, Emacs
-automatically detects and maps the following sequences of movements
-(``gestures'') to common actions:
+  Under the X Window System or Android, Emacs detects and maps the
+following sequences of movements (``gestures'') to common actions:
 
 @itemize @bullet
 @item
 @cindex tapping, touchscreens
-  ``Tapping'', briefly placing and lifting a tool from the display,
-will result in Emacs selecting the window that was tapped, and
-executing any command bound to @code{mouse-1} at that location in the
-window.  If the tap happened on top of a link (@pxref{Mouse
-References}), then Emacs will follow the link instead.
-
-  If a command bound to @code{down-mouse-1} is bound to the location
-where the tap took place, Emacs will execute that command as well.
+  @dfn{Tapping}, briefly placing and lifting a tool from the display,
+will select the window that was tapped, and execute any command bound
+to @code{mouse-1} at that location in the window.  If a link
+(@pxref{Mouse References}) exists there, then Emacs will follow that
+link instead (insofar as such action differs from that taken upon the
+simulation of a @code{mouse-1} event).
 
 @item
 @cindex scrolling, touchscreens
-  ``Scrolling'', meaning to place a tool on the display and move it up
-or down, will result in Emacs scrolling the window contents in the
-direction where the tool moves.
-
-  If the tool is moved left or right, Emacs additionally scrolls the
-window horizontally to follow (@pxref{Horizontal Scrolling}.)
+@vindex touch-screen-enable-hscroll
+  @dfn{Scrolling}, which is continuous vertical or horizontal motion
+on the screen, will scroll the contents of the window beneath the
+tool's initial location in the direction of movement.  The user option
+@code{touch-screen-enable-hscroll} governs whether horizontal
+scrolling (@pxref{Horizontal Scrolling}) is performed in reaction to
+this gesture.
 
 @item
 @cindex dragging, touchscreens
 @cindex long-press, touchscreens
-  ``Dragging'', which is performing a @dfn{long-press} by placing a
-tool on the display and leaving it there for a while prior to moving
-the tool around will make Emacs set the point to where the tool was
-and begin selecting text under the tool as it moves around, as if
-@code{mouse-1} were to be held down.  @xref{Mouse Commands}.
+  @dfn{Dragging}, which is performing a @dfn{long-press} by placing a
+tool on the display and leaving it there awhile before moving it to
+another position, will move point to the tool's initial position, and
+commence selecting text under the tool as it continues its motion, as
+if @code{mouse-1} were to be held down and a mouse moved anologously.
+@xref{Mouse Commands}.
 
 @vindex touch-screen-word-select
 @cindex word selection mode, touchscreens
-  Some people find it difficult to position a tool accurately on a
-touch screen display, to the detriment of text selection.  The user
-option @code{touch-screen-word-select} enables ``word selection
-mode'', causing dragging to select the complete word, not only the
-character containing the position of the tool.
+  To the detriment of text selection, it can prove challenging to
+position a tool accurately on a touch screen display.  The user option
+@code{touch-screen-word-select}, which when enabled, prompts dragging
+to select the complete word under the tool.  (Normally, the selection
+is only extended to encompass the character beneath the tool.)
 
 @vindex touch-screen-extend-selection
 @cindex extending the selection, touchscreens
-  Similarly, it may be difficult to select all of the text intended
-within a single gesture.  If the user option
+  In the same vein, it may be difficult to select all of the text
+intended within a single gesture.  If the user option
 @code{touch-screen-extend-selection} is enabled, taps on the locations
 of the point or the mark within a window will begin a new ``drag''
 gesture, where the region will be extended in the direction of any
@@ -80,21 +80,19 @@ subsequent movement.
 
 @vindex touch-screen-preview-select
 @cindex previewing the region during selection, touchscreens
-  Difficulties in making accurate adjustments to the region can also
-be alleviated by indicating the position of the point relative to its
-containing line within the echo area, since the window cursor may be
-physically obscured by the tool.  If
+  Difficulties in making accurate adjustments to the region from the
+cursor being physically obscured by the tool can be mitigated by
+indicating the position of the point within the echo area.  If
 @code{touch-screen-preview-select} is non-@code{nil}, the line
-containing point is displayed in the echo area (@pxref{Echo Area})
-during the motion of the tool, followed by another line indicating the
-position of point within the first line.
+surrounding point is displayed in the echo area (@pxref{Echo Area})
+during the motion of the tool, below which is another line indicating
+the position of point relative to the first.
 @end itemize
 
 @vindex touch-screen-delay
-  By default, Emacs considers a tool as having been left on the
-display long enough to trigger a ``long-press'' after 0.7 seconds, but
-this can be changed by customizing the variable
-@code{touch-screen-delay}.
+  Emacs registers a long-press after the time a tool has been placed
+upon the screen exceeds 0.7 seconds.  This delay can be adjusted
+through customizing the variable @code{touch-screen-delay}.
 
 @node On-Screen Keyboards
 @section Using Emacs with Virtual Keyboards
diff --git a/lisp/touch-screen.el b/lisp/touch-screen.el
index 2621aebf037..ea1e27a263b 100644
--- a/lisp/touch-screen.el
+++ b/lisp/touch-screen.el
@@ -58,25 +58,30 @@ This is always cleared upon any significant state change.")
 If non-nil, the touch screen key event translation machinery
 is being called from `read-sequence' or some similar function.")
 
+(defgroup touch-screen nil
+  "Interact with Emacs from touch screen devices."
+  :group 'mouse
+  :version "30.0")
+
 (defcustom touch-screen-display-keyboard nil
   "If non-nil, always display the on screen keyboard.
 A buffer local value means to always display the on screen
 keyboard when the buffer is selected."
   :type 'boolean
-  :group 'mouse
+  :group 'touch-screen
   :version "30.1")
 
 (defcustom touch-screen-delay 0.7
   "Delay in seconds before Emacs considers a touch to be a long-press."
   :type 'number
-  :group 'mouse
+  :group 'touch-screen
   :version "30.1")
 
 (defcustom touch-screen-precision-scroll nil
   "Whether or not to use precision scrolling for touch screens.
 See `pixel-scroll-precision-mode' for more details."
   :type 'boolean
-  :group 'mouse
+  :group 'touch-screen
   :version "30.1")
 
 (defcustom touch-screen-word-select nil
@@ -84,7 +89,7 @@ See `pixel-scroll-precision-mode' for more details."
 If non-nil, long-press events (see `touch-screen-delay') followed
 by dragging will try to select entire words."
   :type 'boolean
-  :group 'mouse
+  :group 'touch-screen
   :version "30.1")
 
 (defcustom touch-screen-extend-selection nil
@@ -93,7 +98,7 @@ When enabled, tapping on the character containing the point or
 mark will resume dragging where it left off while the region is
 active."
   :type 'boolean
-  :group 'mouse
+  :group 'touch-screen
   :version "30.1")
 
 (defcustom touch-screen-preview-select nil
@@ -102,7 +107,15 @@ When enabled, a preview of the visible line within the 
window
 will be displayed in the echo area while dragging combined with
 an indication of the position of point within that line."
   :type 'boolean
-  :group 'mouse
+  :group 'touch-screen
+  :version "30.1")
+
+(defcustom touch-screen-enable-hscroll t
+  "If non-nil, hscroll can be changed from the touch screen.
+When enabled, tapping on a window and dragging your finger left
+or right will scroll that window horizontally."
+  :type 'boolean
+  :group 'touch-screen
   :version "30.1")
 
 (defvar-local touch-screen-word-select-bounds nil
@@ -229,7 +242,12 @@ horizontal scrolling according to the movement in DX."
                             (>= (- accumulator) column-width))
                        (progn
                          (setq accumulator (+ accumulator column-width))
-                         (scroll-right 1)
+                         ;; Maintain both hscroll counters even when
+                         ;; it's disabled to prevent unintentional or
+                         ;; patently horizontal gestures from
+                         ;; scrolling the window vertically.
+                         (when touch-screen-enable-hscroll
+                           (scroll-right 1))
                          (setq lines-hscrolled (1+ lines-hscrolled))
                          (when (not (zerop accumulator))
                            ;; If there is still an outstanding amount
@@ -238,7 +256,8 @@ horizontal scrolling according to the movement in DX."
                      (when (and (> accumulator 0)
                                 (>= accumulator column-width))
                        (setq accumulator (- accumulator column-width))
-                       (scroll-left 1)
+                       (when touch-screen-enable-hscroll
+                         (scroll-left 1))
                        (setq lines-hscrolled (1+ lines-hscrolled))
                        (when (not (zerop accumulator))
                          ;; If there is still an outstanding amount to