From: Po Lu Date: Tue, 18 Jul 2023 01:29:16 +0000 (+0800) Subject: Merge remote-tracking branch 'origin/master' into feature/android X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=46fd03a49617066fca87000378771caedfd150f3;p=emacs.git Merge remote-tracking branch 'origin/master' into feature/android --- 46fd03a49617066fca87000378771caedfd150f3 diff --cc doc/lispref/commands.texi index bcba3fe4026,037f42124cc..ffb01254fc9 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@@ -2027,140 -2023,12 +2027,145 @@@ This event is sent when @var{point} is display, because another program took the grab, or because the user raised the finger from the touchscreen. + @var{canceled} is non-@code{nil} if the touch sequence has been + intercepted by another program (such as the window manager), and Emacs + should undo or avoid any editing commands that would otherwise result + from the touch sequence. ++ +These events also have imaginary prefixes keys added by +@code{read-key-sequence} when they originate on top of a special part +of a frame or window. @end table +If a touchpoint is pressed against the menu bar, then Emacs will not +generate any corresponding @code{touchscreen-begin} or +@code{touchscreen-end} events; instead, the menu bar may be displayed +after @code{touchscreen-end} would have been delivered under other +circumstances. + +@cindex mouse emulation from touch screen events +When no command is bound to @code{touchscreen-begin}, +@code{touchscreen-end} or @code{touchscreen-update}, Emacs calls a +``key translation function'' (@pxref{Translation Keymaps}) to +translate key sequences containing touch screen events into ordinary +mouse events (@pxref{Mouse Events}.) Since Emacs doesn't support +distinguishing events originating from separate mouse devices, it +assumes that only one touchpoint is active while translation takes +place; breaking this assumption may lead to unexpected behavior. + +Emacs applies two different strategies for translating touch events +into mouse events, contingent on factors such as the commands bound to +keymaps that are active at the location of the +@code{touchscreen-begin} event. If a command is bound to +@code{down-mouse-1} at that location, the initial translation consists +of a single @code{down-mouse-1} event, with subsequent +@code{touchscreen-update} events translated to mouse motion events +(@pxref{Motion Events}), and a final @code{touchscreen-end} event +translated to a @code{mouse-1} or @code{drag-mouse-1} event. This is +referred to ``simple translation'', and produces a simple +correspondence between touchpoint motion and mouse motion. + +@cindex @code{ignored-mouse-command}, a symbol property +However, some commands bound to +@code{down-mouse-1}--@code{mouse-drag-region}, for example--either +conflict with defined touch screen gestures (such as ``long-press to +drag''), or with user expectations for touch input, and shouldn't +subject the touch sequence to simple translation. If a command whose +name contains the property (@pxref{Symbol Properties}) +@code{ignored-mouse-command} is encountered or there is no command +bound to @code{down-mouse-1}, a more irregular form of translation +takes place: here, Emacs processes touch screen gestures +(@pxref{Touchscreens,,, emacs, The GNU Emacs Manual}) first, and +finally attempts to translate touch screen events into mouse events if +no gesture was detected prior to a closing @code{touchscreen-end} +event and a command is bound to @code{mouse-1} at the location of that +event. Before generating the @code{mouse-1} event, point is also set +to the location of the @code{touchscreen-end} event, and the window +containing the position of that event is selected, as a compromise for +packages which assume @code{mouse-drag-region} has already set point +to the location of any mouse click and selected the window where it +took place. + +To prevent unwanted @code{mouse-1} events arriving after a mouse menu +is dismissed (@pxref{Mouse Menus}), Emacs also avoids simple +translation if @code{down-mouse-1} is bound to a keymap, making it a +prefix key. In lieu of simple translation, it translates the closing +@code{touchscreen-end} to a @code{down-mouse-1} event with the +starting position of the touch sequence, consequentially displaying +the mouse menu. + +@cindex @code{mouse-1-menu-command}, a symbol property +Since certain commands are also bound to @code{down-mouse-1} for the +purpose of displaying pop-up menus, Emacs additionally behaves as +illustrated in the last paragraph if @code{down-mouse-1} is bound to a +command whose name has the property @code{mouse-1-menu-command}. + +@cindex touchscreen gesture events +If touch gestures are detected during translation, one of the +following input events may be generated: + +@table @code +@cindex @code{touchscreen-scroll} event +@item (touchscreen-scroll @var{window} @var{dx} @var{dy}) +If a ``scrolling'' gesture is detected during the translation process, +each subsequent @code{touchscreen-update} event is translated to a +@code{touchscreen-scroll} event, where @var{dx} and @var{dy} specify, +in pixels, the relative motion of the touchpoint from the position of +the @code{touchscreen-begin} event that started the sequence or the +last @code{touchscreen-scroll} event, whichever came later. + +@cindex @code{touchscreen-hold} event +@item (touchscreen-hold @var{posn}) +If the single active touchpoint remains stationary for more than +@code{touch-screen-delay} seconds after a @code{touchscreen-begin} is +generated, a ``long-press'' gesture is detected during the translation +process, and a @code{touchscreen-hold} event is sent, with @var{posn} +set to a mouse position list containing the position of the +@code{touchscreen-begin} event. + +@cindex @code{touchscreen-drag} event +@item (touchscreen-drag @var{posn}) +If a ``long-press'' gesture is detected while translating the current +touch sequence, a @code{touchscreen-drag} event is sent upon each +subsequent @code{touchscreen-update} event, with @var{posn} set to the +new position of the touchpoint. +@end table + +@cindex handling touch screen events +@cindex tap and drag, touch screen gestures +Emacs provides two functions to handle touch screen events independent +of gesture recognition or mouse event translation. They are intended +to be used by commands bound to @code{touchscreen-begin}, to recognize +and handle common gestures. + +@defun touch-screen-track-tap event &optional update data +This function is used to track a single ``tap'' gesture originating +from the @code{touchscreen-begin} event @var{event}, often used to +set the point or to activate a button. It waits for a +@code{touchscreen-end} event with the same touch identifier to arrive, +at which point it returns @code{t}, signifying the end of the gesture. + +If a @code{touchscreen-update} event arrives in the mean time and +contains at least one touchpoint with the same identifier as in +@var{event}, the function @var{update} is called with two arguments, +the list of touchpoints in that @code{touchscreen-update} event, and +@var{data}. + +If any other event arrives in the mean time, @code{nil} is returned. +The caller should not perform any action in that case. +@end defun + +@defun touch-screen-track-drag event update &optional data +This function is used to track a single ``drag'' gesture originating +from the @code{touchscreen-begin} event @code{event}. + +It behaves like @code{touch-screen-track-tap}, except that it returns +@code{no-drag} and refrains from calling @var{update} if the +touchpoint in @code{event} did not move far enough (by default, 5 +pixels from its position in @code{event}) to qualify as an actual +drag. +@end defun + @node Focus Events @subsection Focus Events @cindex focus event diff --cc etc/NEWS index d4d9fd37210,c50f560282a..76b1cda9e26 --- a/etc/NEWS +++ b/etc/NEWS @@@ -661,13 -615,14 +661,19 @@@ from within a command This user option names directories in which Emacs will treat all directory-local variables as safe. + +++ + ** New parameter to 'touchscreen-end' events. + CANCEL non-nil establishes that the touch sequence has been + intercepted by programs such as window managers and should be ignored + with Emacs. + ** New variable 'inhibit-auto-fill' to temporarily prevent auto-fill. ++++ +** New variable 'secondary-tool-bar-map'. +If non-nil, this variable contains a keymap of menu items that are +displayed along tool bar items inside 'tool-bar-map'. + ** Functions and variables to transpose sexps +++ diff --cc src/keyboard.c index 78105fa9e05,41cda2e65de..bd7433e584a --- a/src/keyboard.c +++ b/src/keyboard.c @@@ -6557,17 -6404,10 +6557,16 @@@ make_lispy_event (struct input_event *e } case TOUCHSCREEN_BEGIN_EVENT: - case TOUCHSCREEN_END_EVENT: { Lisp_Object x, y, id, position; - struct frame *f = XFRAME (event->frame_or_window); + struct frame *f; + int tab_bar_item; + bool close; +#if defined HAVE_WINDOW_SYSTEM && !defined HAVE_EXT_MENU_BAR + int column, row, dummy; +#endif /* defined HAVE_WINDOW_SYSTEM && !defined HAVE_EXT_MENU_BAR */ + f = XFRAME (event->frame_or_window); id = event->arg; x = event->x; y = event->y;