emacs/doc/emacs/input.texi

@c This is part of the Emacs manual.
@c Copyright (C) 2023--2024 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Other Input
@section Touchscreen Input and Virtual Keyboards
@cindex other input devices

  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}).

  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::                Interacting with Emacs from touchscreens.
* On-Screen Keyboards::         Text input with virtual keyboards.
@end menu

@node Touchscreens
@subsection Using Emacs on Touchscreens
@cindex touchscreen input

  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 it is
displayed.

  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
@cindex tapping, touchscreens
  @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
@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
  @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 analogously.
@xref{Mouse Commands}.

@vindex touch-screen-word-select
@cindex word selection mode, touchscreens
  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
  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
subsequent movement.

@vindex touch-screen-preview-select
@cindex previewing the region during selection, touchscreens
  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
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
(@pxref{Text Scale}) in proportion to the change in that distance.
@end itemize

@vindex 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
@subsection Using Emacs with Virtual Keyboards
@cindex virtual keyboards
@cindex on-screen keyboards

  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.

  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 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.

  The default value of @code{touch-screen-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.

@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 several 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 virtual
keyboard while it is executing a command, Emacs implements a feature
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
  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 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 ongoing character composition on
screen, and send key events reflecting its contents to Emacs after it
is confirmed by the user.

  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}, 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
@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 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.