diff options
Diffstat (limited to 'doc/lispref/commands.texi')
| -rw-r--r-- | doc/lispref/commands.texi | 176 |
1 files changed, 139 insertions, 37 deletions
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index b4a8b733a0b..6ed46fa6a27 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -601,6 +601,9 @@ Put them into three windows, selecting the last one." @node Command Modes @subsection Specifying Modes For Commands +@cindex commands, mode-specific +@cindex commands, specify as mode-specific +@cindex mode-specific commands Many commands in Emacs are general, and not tied to any specific mode. For instance, @kbd{M-x kill-region} can be used in pretty much any @@ -1173,6 +1176,7 @@ intended by Lisp code to be used as an event. * Repeat Events:: Double and triple click (or drag, or down). * Motion Events:: Just moving the mouse, not pushing a button. * 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. @@ -1421,9 +1425,12 @@ binding of the key sequence. @subsection Click Events @cindex click event @cindex mouse click event +@cindex mouse wheel event When the user presses a mouse button and releases it at the same -location, that generates a @dfn{click} event. All mouse click event +location, that generates a @dfn{click} event. Depending on how your +window-system reports mouse-wheel events, turning the mouse wheel can +generate either a mouse click or a mouse-wheel event. All mouse event share the same format: @example @@ -1434,7 +1441,8 @@ share the same format: @item @var{event-type} This is a symbol that indicates which mouse button was used. It is one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the -buttons are numbered left to right. +buttons are numbered left to right. For mouse-wheel event, it can be +@code{wheel-up} or @code{wheel-down}. You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift @@ -1447,19 +1455,20 @@ describe events by their types; thus, if there is a key binding for @item @var{position} @cindex mouse position list -This is a @dfn{mouse position list} specifying where the mouse click +This is a @dfn{mouse position list} specifying where the mouse event occurred; see below for details. @item @var{click-count} This is the number of rapid repeated presses so far of the same mouse -button. @xref{Repeat Events}. +button or the number of repeated turns of the wheel. @xref{Repeat +Events}. @end table To access the contents of a mouse position list in the -@var{position} slot of a click event, you should typically use the +@var{position} slot of a mouse event, you should typically use the functions documented in @ref{Accessing Mouse}. -The explicit format of the list depends on where the click occurred. +The explicit format of the list depends on where the event occurred. For clicks in the text area, mode line, header line, tab line, or in the fringe or marginal areas, the mouse position list has the form @@ -1474,11 +1483,11 @@ The meanings of these list elements are as follows: @table @asis @item @var{window} -The window in which the click occurred. +The window in which the mouse event occurred. @item @var{pos-or-area} The buffer position of the character clicked on in the text area; or, -if the click was outside the text area, the window area where it +if the event was outside the text area, the window area where it occurred. It is one of the symbols @code{mode-line}, @code{header-line}, @code{tab-line}, @code{vertical-line}, @code{left-margin}, @code{right-margin}, @code{left-fringe}, or @@ -1490,10 +1499,10 @@ happens after the imaginary prefix keys for the event are registered by Emacs. @xref{Key Sequence Input}. @item @var{x}, @var{y} -The relative pixel coordinates of the click. For clicks in the text +The relative pixel coordinates of the event. For events in the text area of a window, the coordinate origin @code{(0 . 0)} is taken to be the top left corner of the text area. @xref{Window Sizes}. For -clicks in a mode line, header line or tab line, the coordinate origin +events in a mode line, header line or tab line, the coordinate origin is the top left corner of the window itself. For fringes, margins, and the vertical border, @var{x} does not have meaningful data. For fringes and margins, @var{y} is relative to the bottom edge of the @@ -1505,9 +1514,9 @@ The time at which the event occurred, as an integer number of milliseconds since a system-dependent initial time. @item @var{object} -Either @code{nil}, which means the click occurred on buffer text, or a +Either @code{nil}, which means the event occurred on buffer text, or a cons cell of the form @w{(@var{string} . @var{string-pos})} if there -is a string from a text property or an overlay at the click position. +is a string from a text property or an overlay at the event position. @table @asis @item @var{string} @@ -1592,7 +1601,8 @@ handle), @code{up} (the up arrow at one end of the scroll bar), or @end table For clicks on the frame's internal border (@pxref{Frame Layout}), -@var{position} has this form: +the frame's tool bar (@pxref{Tool Bar}) or tab bar, @var{position} +has this form: @example (@var{frame} @var{part} (@var{X} . @var{Y}) @var{timestamp}) @@ -1600,19 +1610,20 @@ For clicks on the frame's internal border (@pxref{Frame Layout}), @table @asis @item @var{frame} -The frame whose internal border was clicked on. +The frame whose internal border or tool bar or tab bar was clicked on. @item @var{part} -The part of the internal border which was clicked on. This can be one +The part of the frame which was clicked on. This can be one of the following: @table @code -@item nil -The frame does not have an internal border. This usually happens on -text-mode frames. This can also happen on GUI frames with internal -border if the frame doesn't have its @code{drag-internal-border} -parameter (@pxref{Mouse Dragging Parameters}) set to a non-@code{nil} -value. +@cindex tool-bar mouse events +@item tool-bar +The frame has a tool bar, and the event was in the tool-bar area. + +@cindex tab-bar mouse events +@item tab-bar +The frame has a tab bar, and the event was in the tab-bar area. @item left-edge @itemx top-edge @@ -1626,6 +1637,13 @@ canonical character from the border's nearest corner. @itemx bottom-right-corner @itemx bottom-left-corner The click was on the corresponding corner of the internal border. + +@item nil +The frame does not have an internal border, and the event was not on +the tab bar or the tool bar. This usually happens on text-mode +frames. This can also happen on GUI frames with internal border if +the frame doesn't have its @code{drag-internal-border} parameter +(@pxref{Mouse Dragging Parameters}) set to a non-@code{nil} value. @end table @end table @@ -1854,6 +1872,85 @@ 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}. + +@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}) +This event is sent whenever an xwidget requests that another xwidget +be displayed. @var{xwidget} is the xwidget that should be displayed. + +@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 @@ -2337,10 +2434,9 @@ This function returns position information corresponding to pixel coordinates @var{x} and @var{y} in a specified frame or window, @var{frame-or-window}, which defaults to the selected window. The coordinates @var{x} and @var{y} are relative to the -frame or window used. -If @var{whole} is @code{nil}, the coordinates are relative -to the window text area, otherwise they are relative to -the entire window area including scroll bars, margins and fringes. +text area of the selected window. +If @var{whole} is @code{non-nil}, the @var{x} coordinate is relative +to the entire window area including scroll bars, margins and fringes. @end defun @node Accessing Scroll @@ -2600,10 +2696,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 @@ -3568,17 +3668,19 @@ commands. @cindex exit recursive editing @cindex aborting To invoke a recursive editing level, call the function -@code{recursive-edit}. This function contains the command loop; it also -contains a call to @code{catch} with tag @code{exit}, which makes it -possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a @code{nil} value, then -@code{recursive-edit} returns normally to the function that called it. -The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. -Throwing a @code{t} value causes @code{recursive-edit} to quit, so that -control returns to the command loop one level up. This is called -@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). -You can also throw a function value. In that case, +@code{recursive-edit}. This function contains the command loop; it +also contains a call to @code{catch} with tag @code{exit}, which makes +it possible to exit the recursive editing level by throwing to +@code{exit} (@pxref{Catch and Throw}). Throwing a @code{t} value +causes @code{recursive-edit} to quit, so that control returns to the +command loop one level up. This is called @dfn{aborting}, and is done +by @kbd{C-]} (@code{abort-recursive-edit}). Similarly, you can throw +a string value to make @code{recursive-edit} signal an error, printing +this string as the message. If you throw a function, @code{recursive-edit} will call it without arguments before returning. +Throwing any other value, will make @code{recursive-edit} return +normally to the function that called it. The command @kbd{C-M-c} +(@code{exit-recursive-edit}) does this. Most applications should not use recursive editing, except as part of using the minibuffer. Usually it is more convenient for the user if you |