From f2898e24fd125fce0db0ebdad26aa6355eee3ccf Mon Sep 17 00:00:00 2001 From: Po Lu Date: Sun, 19 Nov 2023 11:00:25 +0800 Subject: [PATCH] Reorganize documentation relating to touch screens Chiefly, elevate it from an appendix to a node in the User Input chapter. I have been approached time and again with questions from people who have not searched the appendices for such documentation. * doc/emacs/emacs.texi: Move Other Input below Commands in the menu. * doc/emacs/input.texi (Other Input Devices): Rename to Other Input. All callers changed. (Touchscreens, On-Screen Keyboards): Revise and reword documentation. Homogenize nomenclature for on screen keyboards, preferring "virtual keyboards" after it has been mentioned once by the other name. --- doc/emacs/android.texi | 6 +- doc/emacs/commands.texi | 2 + doc/emacs/emacs.texi | 3 +- doc/emacs/frames.texi | 15 ++-- doc/emacs/input.texi | 152 +++++++++++++++++++++------------------- doc/emacs/windows.texi | 2 +- 6 files changed, 93 insertions(+), 87 deletions(-) diff --git a/doc/emacs/android.texi b/doc/emacs/android.texi index 161712493a6..915ba948b93 100644 --- a/doc/emacs/android.texi +++ b/doc/emacs/android.texi @@ -9,9 +9,9 @@ Alliance. This section describes the peculiarities of using Emacs on an Android device running Android 2.2 or later. - Android devices commonly rely on user input through a touch screen -or digitizer device and on-screen keyboard. For more information -about using such devices with Emacs, @pxref{Other Input Devices}. + Android devices commonly rely a touch screen or digitizer device and +virtual keyboard for user input. For more information about using +such devices with Emacs, @pxref{Other Input}. @menu * What is Android?:: Preamble. diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi index 98f0610ee44..cb924519175 100644 --- a/doc/emacs/commands.texi +++ b/doc/emacs/commands.texi @@ -227,6 +227,8 @@ until you are interested in customizing them. Then read the basic information on variables (@pxref{Variables}) and the information about specific variables will make sense. +@include input.texi + @ifnottex @lowersections @end ifnottex diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index da9696dfa4b..f7d9033c5f4 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -149,6 +149,7 @@ Important General Concepts editing action. * Mouse Input:: Using the mouse and keypads. * Commands:: Named functions run by key sequences to do editing. +* Other Input:: Input besides the mouse, keyboard and keypads. * Entering Emacs:: Starting Emacs from the shell. * Exiting:: Stopping or killing Emacs. @@ -224,7 +225,6 @@ Appendices * Haiku:: Using Emacs on Haiku. * Android:: Using Emacs on Android. * Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS. -* Other Input Devices:: Using Emacs with other input devices. * Manifesto:: What's GNU? Gnu's Not Unix! * Glossary:: Terms used in this manual. @@ -1652,7 +1652,6 @@ Lisp programming. @include android.texi @c Includes msdos-xtra. @include msdos.texi -@include input.texi @include gnu.texi @include glossary.texi @ifnottex diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index e2e30408a65..1862ed2d5d4 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -1586,14 +1586,13 @@ the items that operate on the clicked tab. Dragging the tab with wheel scrolling switches to the next or previous tab. Holding down the @key{SHIFT} key during scrolling moves the tab to the left or right. - Touch screen input (@pxref{Other Input Devices}) can also be used to -operate on tabs. Long-pressing (@pxref{Touchscreens}) a tab will -display a context menu with items that operate on the tab that was -pressed, and long-pressing the tab bar itself will display a context -menu which lets you create and remove tabs; tapping a tab itself will -result in that tab's window configuration being selected, and tapping -a button on the tab bar will behave as if it was clicked with -@kbd{mouse-1}. + Touch screen input (@pxref{Other Input}) can also be used to operate +on tabs. Long-pressing (@pxref{Touchscreens}) a tab will display a +context menu with items that operate on the tab that was pressed, and +long-pressing the tab bar itself will display a context menu which +lets you create and remove tabs; tapping a tab itself will result in +that tab's window configuration being selected, and tapping a button +on the tab bar will behave as if it was clicked with @kbd{mouse-1}. @findex tab-bar-history-mode You can enable @code{tab-bar-history-mode} to remember window diff --git a/doc/emacs/input.texi b/doc/emacs/input.texi index e4d595caf84..ae3dc05364e 100644 --- a/doc/emacs/input.texi +++ b/doc/emacs/input.texi @@ -1,26 +1,27 @@ @c This is part of the Emacs manual. @c Copyright (C) 2023 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. -@node Other Input Devices -@appendix Emacs and Unconventional Input Devices +@node Other Input +@section Touchscreen Input and Virtual Keyboards @cindex other input devices - Emacs was originally developed with the assumption that its users -have access to a desktop computer or computer terminal, with a -keyboard and perhaps a suitable pointing device such as a mouse. + Emacs was first written assuming that its users were to use it from +a desktop computer or computer terminal, equipped with a keyboard and +perhaps a suitable pointing device such as a mouse (@pxref{Mouse +Input}). - However, recent developments in the X Window System and operating -systems such as Android mean that this assumption no longer holds -true. Emacs supports input from various other kinds of input devices, -which is detailed here. + Emacs is also capable of receiving input from alternative sources of +input, enabling users to interact with it even if it is installed on a +computer that substitutes such input sources for the customary +combination of keyboard and mouse. @menu -* Touchscreens:: Using Emacs on touchscreens. -* On-Screen Keyboards:: Using Emacs with virtual keyboards. +* Touchscreens:: Interacting with Emacs from touchscreens. +* On-Screen Keyboards:: Text input with virtual keyboards. @end menu @node Touchscreens -@section Using Emacs on Touchscreens +@subsection Using Emacs on Touchscreens @cindex touchscreen input Touchscreen input is the manipulation of a frame's contents by the @@ -28,9 +29,11 @@ placement and motion of tools (instanced by fingers and such pointing devices as styluses) on a monitor or computer terminal where it is displayed. - Under the X Window System or Android, Emacs detects and translates -the following sequences of movements (@dfn{gestures}) to common -actions: + Two factors, the order and position on which such tools are placed, +are compared against predefined patterns dubbed @dfn{gestures}, after +which any gesture those factors align with designates a series of +actions to be taken on the text beneath the tools; the gestures +presently recognized are: @itemize @bullet @item @@ -62,13 +65,6 @@ 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 analogously. @xref{Mouse Commands}. -@item -@cindex pinching, touchscreens - @dfn{Pinching}, which is placing two tools apart on the screen and -adjusting their position such as to increase or decrease the distance -between them will modify the text scale (@xref{Text Scale}) in -proportion to the change in that distance. - @vindex touch-screen-word-select @cindex word selection mode, touchscreens To the detriment of text selection, it can prove challenging to @@ -95,6 +91,13 @@ indicating the position of the point within the echo area. If 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. + +@item +@cindex pinching, touchscreens + @dfn{Pinching}, the placement of two tools apart on the screen +followed by adjustments to their position such as to increase or +decrease the distance between them will modify the text scale +(@xref{Text Scale}) in proportion to the change in that distance. @end itemize @vindex touch-screen-delay @@ -103,84 +106,87 @@ 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 +@subsection Using Emacs with Virtual Keyboards @cindex virtual keyboards @cindex on-screen keyboards - When there is no physical keyboard attached to a system, the -windowing system typically provides an on-screen keyboard, more often -known as a ``virtual keyboard'', containing rows of clickable buttons -that send keyboard input to the application, much like a real keyboard -would. This virtual keyboard is hidden by default, as it uses up -valuable on-screen real estate, and must be opened once the program -being used is ready to accept keyboard input. - - Under the X Window System, the client that provides the on-screen -keyboard typically detects when the application is ready to accept -keyboard input through a set of complex heuristics, and automatically -displays the keyboard when necessary. + When there is no physical keyboard attached to a system, its +windowing system might provide an on-screen keyboard, widely known as +a ``virtual keyboard'', containing rows of clickable buttons that send +keyboard input to the application, much as a real keyboard would. - On other systems such as Android, Emacs must tell the system when it -is ready to accept keyboard input. Typically, this is done in -response to a touchscreen ``tap'' gesture (@pxref{Touchscreens}), or -once to the minibuffer becomes in use (@pxref{Minibuffer}.) + This virtual keyboard is hidden when the focused program is not +requesting text input as it occupies scarce space on display, and +programs are therefore enjoined to display it once they are ready to +accept keyboard input. Systems running X detect when the presence of +the virtual keyboard is warranted, but on others such as Android Emacs +is responsible for displaying it when need be, generally in reaction +to a touch screen ``tap'' gesture (@pxref{Touchscreens}) or the +minibuffer being brought into use (@pxref{Minibuffer}). @vindex touch-screen-set-point-commands When a ``tap'' gesture results in a command being executed, Emacs -checks to see whether or not the command is supposed to set the point -by looking for it in the list @code{touch-screen-set-point-commands}. -If it is, then Emacs looks up whether or not the text under the point -is read-only; if not, it activates the on-screen keyboard, assuming -that the user is about to enter text in to the current buffer. +checks whether the command is meant to set the point by searching for +it in the list @code{touch-screen-set-point-commands}. If it is and +the text beneath the new point is not read-only, it activates the +virtual keyboard, in anticipation that the user is about to enter text +there. -@vindex touch-screen-display-keyboard - The user option @code{touch-screen-display-keyboard} forces Emacs to -always display the on screen keyboard; it may also be set buffer -locally, which means that Emacs should always display the keyboard -when the buffer is selected. + The default value of @code{touch-point-set-point-commands} holds +only the command @code{mouse-set-point} (@pxref{Mouse Commands}), +which is the default binding of @code{mouse-1}, and thus of +touchscreen tap gestures as well. - Emacs also provides a set of functions to show or hide the on-screen -keyboard. For more details, @pxref{On-Screen Keyboards,,, elisp, The +@vindex touch-screen-display-keyboard + The user option @code{touch-screen-display-keyboard} compels Emacs +to display the virtual keyboard on such taps even if the text is read +only; it may also be set buffer locally, in which case Emacs will +always display the keyboard in response to a tap on a window +displaying the buffer it is set in. + + There are moreover a set of functions to show or hide the on-screen +keyboard. For more details, @xref{On-Screen Keyboards,,, elisp, The Emacs Lisp Reference Manual}. @cindex quitting, without a keyboard - Since it may not be possible for Emacs to display the on screen + Since it may not be possible for Emacs to display the virtual keyboard while it is executing a command, Emacs implements a feature -on devices with only an on-screen keyboard, by which two rapid clicks -of a hardware button that is always present on the device results in -Emacs quitting. @xref{Quitting}. +on window systems frequently equipped with no physical keyboard, by +which two rapid clicks of a hardware button that is always present on +the device induces a quit. @xref{Quitting}. @vindex x-quit-keysym - The button afforded such special treatment varies; under X, no such -button exists by default, but one can be configured through the -variable @code{x-quit-keysym}, whereas under Android it is always the -volume down buttons. + No such button is enabled on X, but one can be configured through +the variable @code{x-quit-keysym}. On Android this button is always +the volume down button. @cindex text conversion, keyboards - Most input methods designed to work with on-screen keyboards perform -buffer edits differently from desktop input methods. + Most input methods designed to work with virtual keyboards edit text +differently from desktop input methods. On a conventional desktop windowing system, an input method will -simply display the contents of any on going character compositions on -screen, and send the appropriate key events to Emacs after completion. +simply display the contents of any ongoing character composition on +screen, and send key events reflecting its contents to Emacs after it +is confirmed by the user. - However, on screen keyboard input methods directly perform edits to -the selected window of each frame; this is known as ``text + By contrast, virtual keyboard input methods directly perform edits +to the selected window of each frame; this is known as ``text conversion'', or ``string conversion'' under the X Window System. -Emacs enables these input methods whenever the buffer local value of -@code{text-conversion-style} is non-@code{nil}, normally inside -derivatives of @code{text-mode} and @code{prog-mode}. + + Emacs enables these input methods whenever the buffer local value of +@code{text-conversion-style} is non-@code{nil}, that is to say, +generally inside derivatives of @code{text-mode} and @code{prog-mode}. Text conversion is performed asynchronously whenever Emacs receives a request to perform the conversion from the input method, and Emacs is not currently reading a key sequence for which one prefix key has -already been read (@pxref{Keys}.) After the conversion completes, a +already been read (@pxref{Keys}). After the conversion completes, a @code{text-conversion} event is sent. @xref{Misc Events,,, elisp, the Emacs Reference Manual}. @vindex text-conversion-face If the input method needs to work on a region of the buffer, then -the region becomes known as the ``composing region'' (or -``preconversion region''.) The variable @code{text-conversion-face} -describes whether or not to display the composing region in a specific -face. +the region is designated the ``composing region'' (or ``preconversion +region''). The variable @code{text-conversion-face} controls whether +to display the composing region in a distinctive face, and if so, +which face to employ. diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index ca5e424d939..a2946bcada9 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -664,7 +664,7 @@ to the window-local tab line of buffers, and clicking on the @kbd{x} icon of a tab deletes it. The mouse wheel on the tab line scrolls the tabs horizontally. - Touch screen input (@pxref{Other Input Devices}) can also be used to + Touch screen input (@pxref{Other Input}) can also be used to interact with the ``tab line''. Long-pressing (@pxref{Touchscreens}) a tab will display a context menu with items that operate on the tab that was pressed; tapping a tab itself will result in switching to -- 2.39.5