diff options
Diffstat (limited to 'doc/lispref/commands.texi')
| -rw-r--r-- | doc/lispref/commands.texi | 254 |
1 files changed, 200 insertions, 54 deletions
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 35ef61700c2..0a324a642fe 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -451,11 +451,11 @@ reads and discards the following up-event. You can get access to that up-event with the @samp{U} code character. This kind of input is used by commands such as @code{describe-key} and -@code{global-set-key}. +@code{keymap-global-set}. @item K A key sequence on a form that can be used as input to functions like -@code{define-key}. This works like @samp{k}, except that it +@code{keymap-set}. This works like @samp{k}, except that it suppresses, for the last input event in the key sequence, the conversions that are normally used (when necessary) to convert an undefined key into a defined one (@pxref{Key Sequence Input}), so this @@ -1175,7 +1175,9 @@ intended by Lisp code to be used as an event. * Button-Down Events:: A button was pushed and not yet released. * Repeat Events:: Double and triple click (or drag, or down). * Motion Events:: Just moving the mouse, not pushing a button. +* Touchscreen Events:: Tapping and moving fingers on a touchscreen. * Focus Events:: Moving the mouse between frames. +* Xwidget Events:: Events generated by xwidgets. * Misc Events:: Other events the system can generate. * Event Examples:: Examples of the lists for mouse events. * Classifying Events:: Finding the modifier keys in an event symbol. @@ -1314,12 +1316,9 @@ actually treated as the meta key, not this.) It is best to avoid mentioning specific bit numbers in your program. To test the modifier bits of a character, use the function @code{event-modifiers} (@pxref{Classifying Events}). When making key -bindings, you can use the read syntax for characters with modifier bits -(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with -@code{define-key}, you can use lists such as @code{(control hyper ?x)} to -specify the characters (@pxref{Changing Key Bindings}). The function -@code{event-convert-list} converts such a list into an event type -(@pxref{Classifying Events}). +bindings with @code{keymap-set}, you specify these events using +strings like @samp{C-H-x} instead (for ``control hyper x'') +(@pxref{Changing Key Bindings}). @node Function Keys @subsection Function Keys @@ -1837,6 +1836,59 @@ small movements. Otherwise, motion events are not generated as long as the mouse cursor remains pointing to the same glyph in the text. @end defvar +@node Touchscreen Events +@subsection Touchscreen Events +@cindex touchscreen events +@cindex support for touchscreens + +Some window systems provide support for input devices that react to +the user's touching the screen and moving fingers while touching the +screen. These input devices are known as touchscreens, and Emacs +reports the events they generate as @dfn{touchscreen events}. + +Most individual events generated by a touchscreen only have meaning as +part of a larger sequence of other events: for instance, the simple +operation of tapping the touchscreen involves the user placing and +raising a finger on the touchscreen, and swiping the display to +scroll it involves placing a finger, moving it many times upwards or +downwards, and then raising the finger. + +@cindex touch point, in touchscreen events +While a simplistic model consisting of one finger is adequate for taps +and scrolling, more complicated gestures require support for keeping +track of multiple fingers, where the position of each finger is +represented by a @dfn{touch point}. For example, a ``pinch to zoom'' +gesture might consist of the user placing two fingers and moving them +individually in opposite directions, where the distance between the +positions of their individual points determine the amount by which to +zoom the display, and the center of an imaginary line between those +positions determines where to pan the display after zooming. + +The low-level touchscreen events described below can be used to +implement all the touch sequences described above. In those events, +each point is represented by a cons of an arbitrary number identifying +the point and a mouse position list (@pxref{Click Events}) specifying +the position of the finger when the event occurred. + +@table @code +@cindex @code{touchscreen-begin} event +@item (touchscreen-begin @var{point}) +This event is sent when @var{point} is created by the user pressing a +finger against the touchscreen. + +@cindex @code{touchscreen-update} event +@item (touchscreen-update @var{points}) +This event is sent when a point on the touchscreen has changed +position. @var{points} is a list of touch points containing the +up-to-date positions of each touch point currently on the touchscreen. + +@cindex @code{touchscreen-end} event +@item (touchscreen-end @var{point}) +This event is sent when @var{point} is no longer present on the +display, because another program took the grab, or because the user +raised the finger from the touchscreen. +@end table + @node Focus Events @subsection Focus Events @cindex focus event @@ -1873,6 +1925,100 @@ sequence---that is, after a prefix key---then Emacs reorders the events so that the focus event comes either before or after the multi-event key sequence, and not within it. +@node Xwidget Events +@subsection Xwidget events + +Xwidgets (@pxref{Xwidgets}) can send events to update Lisp programs on +their status. These events are dubbed @code{xwidget-events}, and +contain various data describing the nature of the change. + +@table @code +@cindex @code{xwidget-event} event +@item (xwidget-event @var{kind} @var{xwidget} @var{arg}) +This event is sent whenever some kind of update occurs in +@var{xwidget}. There are several types of updates, identified by +their @var{kind}. + +@cindex xwidget callbacks +It is a special event (@pxref{Special Events}), which should be +handled by adding a callback to an xwidget that is called whenever an +xwidget event for @var{xwidget} is received. + +You can add a callback by setting the @code{callback} of an xwidget's +property list, which should be a function that accepts @var{xwidget} +and @var{kind} as arguments. + +@table @code +@cindex @code{load-changed} xwidget event +@item load-changed +This xwidget event indicates that the @var{xwidget} has reached a +particular point of the page-loading process. When these events are +sent, @var{arg} will contain a string that futher describes the status +of the widget: + +@table @samp +@cindex @samp{load-started} in xwidgets +@item load-started +This means the widget has begun a page-loading operation. + +@cindex @samp{load-finished} in xwidgets +@item load-finished +This means the @var{xwidget} has finished processing whatever +page-loading operation that it was previously performing. + +@cindex @samp{load-redirected} in xwidgets +@item load-redirected +This means the @var{xwidget} has encountered and followed a redirect +during the page-loading operation. + +@cindex @samp{load-committed} in xwidgets +@item load-committed +This means the @var{xwidget} has committed to a given URL during the +page-loading operation, i.e.@: the URL is the final URL that will be +rendered by @var{xwidget} during the current page-loading operation. +@end table + +@cindex @code{download-callback} xwidget events +@item download-callback +This event indicates that a download of some kind has been completed. +@end table + +In the above events, there can be arguments after @var{arg}, which +itself indicates the URL from which the download file was retrieved: +the first argument after @var{arg} indicates the MIME type of the +download, as a string, while the second argument contains the full +file name of the downloaded file. + +@table @code +@cindex @code{download-started} xwidget events +@item download-started +This event indicates that a download has been started. In these +events, @var{arg} contains the URL of the file that is currently being +downloaded. + +@cindex @code{javascript-callback} xwidget events +@item javascript-callback +This event contains JavaScript callback data. These events are used +internally by @code{xwidget-webkit-execute-script}. +@end table + +@cindex @code{xwidget-display-event} event +@item (xwidget-display-event @var{xwidget} @var{source}) +This event is sent whenever an xwidget requests that another xwidget +be displayed. @var{xwidget} is the xwidget that should be displayed, +and @var{source} is the xwidget that asked to display @var{xwidget}. + +It is also a special event which should be handled through callbacks. +You can add such a callback by setting the @code{display-callback} of +@var{source}'s property list, which should be a function that accepts +@var{xwidget} and @var{source} as arguments. + +@var{xwidget}'s buffer will be set to a temporary buffer. When +displaying the widget, care should be taken to replace the buffer with +the buffer in which the xwidget will be displayed, using +@code{set-xwidget-buffer} (@pxref{Xwidgets}). +@end table + @node Misc Events @subsection Miscellaneous System Events @@ -1900,15 +2046,37 @@ This kind of event indicates that the user deiconified @var{frame} using the window manager. Its standard definition is @code{ignore}; since the frame has already been made visible, Emacs has no work to do. +@cindex @code{touch-end} event +@item (touch-end (@var{position})) +This kind of event indicates that the user's finger moved off the +mouse wheel or the touchpad. The @var{position} element is a mouse +position list (@pxref{Click Events}), specifying the position of the +mouse cursor when the finger moved off the mouse wheel. + @cindex @code{wheel-up} event @cindex @code{wheel-down} event -@item (wheel-up @var{position}) -@itemx (wheel-down @var{position}) +@item (wheel-up @var{position} @var{clicks} @var{lines} @var{pixel-delta}) +@itemx (wheel-down @var{position} @var{clicks} @var{lines} @var{pixel-delta}) These kinds of event are generated by moving a mouse wheel. The @var{position} element is a mouse position list (@pxref{Click Events}), specifying the position of the mouse cursor when the event occurred. +@var{clicks}, if present, is the number of times that the wheel was +moved in quick succession. @xref{Repeat Events}. @var{lines}, if +present and not @code{nil}, is the number of screen lines that should +be scrolled. @var{pixel-delta}, if present, is a cons cell of the +form @w{@code{(@var{x} . @var{y})}}, where @var{x} and @var{y} are the +numbers of pixels by which to scroll in each axis, a.k.a.@: +@dfn{pixelwise deltas}. + +@cindex pixel-resolution wheel events +You can use these @var{x} and @var{y} pixelwise deltas to determine +how much the mouse wheel has actually moved at pixel resolution. For +example, the pixelwise deltas could be used to scroll the display at +pixel resolution, exactly according to the user's turning the mouse +wheel. + @vindex mouse-wheel-up-event @vindex mouse-wheel-down-event This kind of event is generated only on some kinds of systems. On some @@ -1968,7 +2136,7 @@ example: (interactive) (message "Caught signal %S" last-input-event)) -(define-key special-event-map [sigusr1] 'sigusr-handler) +(keymap-set special-event-map "<sigusr1>" 'sigusr-handler) @end smallexample To test the signal handler, you can make Emacs send a signal to itself: @@ -2069,7 +2237,7 @@ bind it to the @code{signal usr1} event sequence: (defun usr1-handler () (interactive) (message "Got USR1 signal")) -(global-set-key [signal usr1] 'usr1-handler) +(keymap-global-set "<signal> <usr1>" 'usr1-handler) @end smallexample @node Classifying Events @@ -2174,21 +2342,6 @@ This function returns non-@code{nil} if @var{object} is a mouse movement event. @xref{Motion Events}. @end defun -@defun event-convert-list list -This function converts a list of modifier names and a basic event type -to an event type which specifies all of them. The basic event type -must be the last element of the list. For example, - -@example -(event-convert-list '(control ?a)) - @result{} 1 -(event-convert-list '(control meta ?a)) - @result{} -134217727 -(event-convert-list '(control super f1)) - @result{} C-s-f1 -@end example -@end defun - @node Accessing Mouse @subsection Accessing Mouse Events @cindex mouse events, data in @@ -2408,25 +2561,14 @@ characters in a string is a complex matter, for reasons of historical compatibility, and it is not always possible. We recommend that new programs avoid dealing with these complexities -by not storing keyboard events in strings. Here is how to do that: - -@itemize @bullet -@item -Use vectors instead of strings for key sequences, when you plan to use -them for anything other than as arguments to @code{lookup-key} and -@code{define-key}. For example, you can use -@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and -@code{this-command-keys-vector} instead of @code{this-command-keys}. +by not storing keyboard events in strings containing control +characters or the like, but instead store them in the common Emacs +format as understood by @code{key-valid-p}. -@item -Use vectors to write key sequence constants containing meta characters, -even when passing them directly to @code{define-key}. - -@item -When you have to look at the contents of a key sequence that might be a -string, use @code{listify-key-sequence} (@pxref{Event Input Misc}) -first, to convert it to a list. -@end itemize + If you read a key sequence with @code{read-key-sequence-vector} (or +@code{read-key-sequence}), or access a key sequence with +@code{this-command-keys-vector} (or @code{this-command-keys}), you can +transform this to the recommended format by using @code{key-description}. The complexities stem from the modifier bits that keyboard input characters can include. Aside from the Meta modifier, none of these @@ -2618,10 +2760,14 @@ returns the key sequence as a vector, never as a string. @cindex upper case key sequence @cindex downcasing in @code{lookup-key} @cindex shift-translation +@vindex translate-upper-case-key-bindings If an input character is upper-case (or has the shift modifier) and has no key binding, but its lower-case equivalent has one, then -@code{read-key-sequence} converts the character to lower case. Note -that @code{lookup-key} does not perform case conversion in this way. +@code{read-key-sequence} converts the character to lower case. (This +behaviour can be disabled by setting the +@code{translate-upper-case-key-bindings} user option to @code{nil}.) +Note that @code{lookup-key} does not perform case conversion in this +way. @vindex this-command-keys-shift-translated When reading input results in such a @dfn{shift-translation}, Emacs @@ -2934,7 +3080,7 @@ supplied to input methods (@pxref{Input Methods}). Use if you want to translate characters after input methods operate. @end defvar -@defun keyboard-translate from to +@defun key-translate from to This function modifies @code{keyboard-translate-table} to translate character code @var{from} into character code @var{to}. It creates the keyboard translate table if necessary. @@ -2945,12 +3091,12 @@ make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste operations: @example -(keyboard-translate ?\C-x 'control-x) -(keyboard-translate ?\C-c 'control-c) -(keyboard-translate ?\C-v 'control-v) -(global-set-key [control-x] 'kill-region) -(global-set-key [control-c] 'kill-ring-save) -(global-set-key [control-v] 'yank) +(key-translate "C-x" "<control-x>") +(key-translate "C-c" "<control-c>") +(key-translate "C-v" "<control-v>") +(keymap-global-set "<control-x>" 'kill-region) +(keymap-global-set "<control-c>" 'kill-ring-save) +(keymap-global-set "<control-v>" 'yank) @end example @noindent |