X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/ab422c4d6899b1442cb6954c1829c1fb656b006c..09b73f0820fd38194b46aa71e1652c594a25586c:/doc/lispref/commands.texi diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index f3589fc2ed..5c28522158 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Command Loop @@ -108,19 +108,33 @@ command does. The special form @code{interactive} turns a Lisp function into a command. The @code{interactive} form must be located at top-level in -the function body (usually as the first form in the body), or in the -@code{interactive-form} property of the function symbol. When the -@code{interactive} form is located in the function body, it does -nothing when actually executed. Its presence serves as a flag, which -tells the Emacs command loop that the function can be called -interactively. The argument of the @code{interactive} form controls -the reading of arguments for an interactive call. +the function body, usually as the first form in the body; this applies +to both lambda expressions (@pxref{Lambda Expressions}) and +@code{defun} forms (@pxref{Defining Functions}). This form does +nothing during the actual execution of the function; its presence +serves as a flag, telling the Emacs command loop that the function can +be called interactively. The argument of the @code{interactive} form +specifies how the arguments for an interactive call should be read. + +@cindex @code{interactive-form} property + Alternatively, an @code{interactive} form may be specified in a +function symbol's @code{interactive-form} property. A non-@code{nil} +value for this property takes precedence over any @code{interactive} +form in the function body itself. This feature is seldom used. + +@cindex @code{interactive-only} property + Sometimes, a named command is only intended to be called +interactively, never directly from Lisp. In that case, give it a +non-@code{nil} @code{interactive-only} property. In that case, the +byte compiler will print a warning message if the command is called +from Lisp. @menu * Using Interactive:: General rules for @code{interactive}. * Interactive Codes:: The standard letter-codes for reading arguments in various ways. * Interactive Examples:: Examples of how to read interactive arguments. +* Generic Commands:: Select among command alternatives. @end menu @node Using Interactive @@ -471,10 +485,10 @@ Arbitrary text, read in the minibuffer and returned as a string these characters in the input.) Prompt. @item S -An interned symbol whose name is read in the minibuffer. Any whitespace -character terminates the input. (Use @kbd{C-q} to include whitespace in -the string.) Other characters that normally terminate a symbol (e.g., -parentheses and brackets) do not do so here. Prompt. +An interned symbol whose name is read in the minibuffer. Terminate +the input with either @kbd{C-j} or @key{RET}. Other characters that +normally terminate a symbol (e.g., whitespace, parentheses and +brackets) do not do so here. Prompt. @item U A key sequence or @code{nil}. Can be used after a @samp{k} or @@ -562,6 +576,39 @@ Put them into three windows, selecting the last one." @end group @end example +@node Generic Commands +@subsection Select among Command Alternatives +@cindex generic commands +@cindex alternatives, defining + +The macro @code{define-alternatives} can be used to define +@dfn{generic commands}. Generic commands are interactive functions +whose implementation can be selected among several alternatives, as a +matter of user preference. + +@defmac define-alternatives command &rest customizations +Define the new command `COMMAND'. + +The argument `COMMAND' should be a symbol. + +When a user runs @kbd{M-x COMMAND @key{RET}} for the first time, Emacs +will prompt for which alternative to use and record the selected +command as a custom variable. + +Running @kbd{C-u M-x COMMAND @key{RET}} prompts again for an +alternative and overwrites the previous choice. + +The variable @code{COMMAND-alternatives} contains an alist +(@pxref{Association Lists}) with alternative implementations of +`COMMAND'. @code{define-alternatives} does not have any effect until +this variable is set. + +If @var{customizations} is non-@var{nil}, it should be composed of +alternating @code{defcustom} keywords and values to add to the +declaration of @code{COMMAND-alternatives} (typically :group and +:version). +@end defmac + @node Interactive Call @section Interactive Call @cindex interactive call @@ -1921,9 +1968,12 @@ must be the last element of the list. For example, @node Accessing Mouse @subsection Accessing Mouse Events @cindex mouse events, data in +@cindex keyboard events, data in This section describes convenient functions for accessing the data in -a mouse button or motion event. +a mouse button or motion event. Keyboard event data can be accessed +using the same functions, but data elements that aren't applicable to +keyboard events are zero or @code{nil}. The following two functions return a mouse position list (@pxref{Click Events}), specifying the position of a mouse event. @@ -2395,9 +2445,12 @@ and key sequences read from keyboard macros being executed. @code{read-char}, and @code{read-char-exclusive}. @defun read-event &optional prompt inherit-input-method seconds -This function reads and returns the next event of command input, waiting -if necessary until an event is available. Events can come directly from -the user or from a keyboard macro. +This function reads and returns the next event of command input, +waiting if necessary until an event is available. + +The returned event may come directly from the user, or from a keyboard +macro. It is not decoded by the keyboard's input coding system +(@pxref{Terminal I/O Encoding}). If the optional argument @var{prompt} is non-@code{nil}, it should be a string to display in the echo area as a prompt. Otherwise, @@ -2418,7 +2471,7 @@ displayed there. Otherwise @code{read-event} does not move the cursor. If @var{seconds} is non-@code{nil}, it should be a number specifying the maximum time to wait for input, in seconds. If no input arrives within that time, @code{read-event} stops waiting and returns -@code{nil}. A floating-point value for @var{seconds} means to wait +@code{nil}. A floating point @var{seconds} means to wait for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, @var{seconds} is rounded down. If @var{seconds} is @code{nil}, @code{read-event} waits as long as @@ -2739,12 +2792,16 @@ This function converts the string or vector @var{key} to a list of individual events, which you can put in @code{unread-command-events}. @end defun -@defun input-pending-p +@defun input-pending-p &optional check-timers @cindex waiting for command key input This function determines whether any command input is currently available to be read. It returns immediately, with value @code{t} if there is available input, @code{nil} otherwise. On rare occasions it may return @code{t} when no input is available. + +If the optional argument @var{check-timers} is non-@code{nil}, then if +no input is available, Emacs runs any timers which are ready. +@xref{Timers}. @end defun @defvar last-input-event @@ -2858,8 +2915,8 @@ time to read text that you display. The value is @code{t} if @code{sit-for} waited the full time with no input arriving (@pxref{Event Input Misc}). Otherwise, the value is @code{nil}. -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sit-for} waits for a fractional number of seconds. +The argument @var{seconds} need not be an integer. If it is floating +point, @code{sit-for} waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, @var{seconds} is rounded down. @@ -2885,8 +2942,8 @@ This function simply pauses for @var{seconds} seconds without updating the display. It pays no attention to available input. It returns @code{nil}. -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sleep-for} waits for a fractional number of seconds. +The argument @var{seconds} need not be an integer. If it is floating +point, @code{sleep-for} waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, @var{seconds} is rounded down. @@ -3024,7 +3081,7 @@ in @ref{Errors}.) @end deffn You can specify a character other than @kbd{C-g} to use for quitting. -See the function @code{set-input-mode} in @ref{Terminal Input}. +See the function @code{set-input-mode} in @ref{Input Modes}. @node Prefix Command Arguments @section Prefix Command Arguments