@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
@node Command Overview
@section Command Loop Overview
- The first thing the command loop must do is read a key sequence, which
-is a sequence of events that translates into a command. It does this by
-calling the function @code{read-key-sequence}. Your Lisp code can also
-call this function (@pxref{Key Sequence Input}). Lisp programs can also
-do input at a lower level with @code{read-event} (@pxref{Reading One
-Event}) or discard pending input with @code{discard-input}
-(@pxref{Event Input Misc}).
+ The first thing the command loop must do is read a key sequence,
+which is a sequence of input events that translates into a command.
+It does this by calling the function @code{read-key-sequence}. Lisp
+programs can also call this function (@pxref{Key Sequence Input}).
+They can also read input at a lower level with @code{read-key} or
+@code{read-event} (@pxref{Reading One Event}), or discard pending
+input with @code{discard-input} (@pxref{Event Input Misc}).
The key sequence is translated into a command through the currently
active keymaps. @xref{Key Lookup}, for information on how this is done.
Lisp code, you must supply the file name string as an ordinary Lisp
function argument.
- If the command is a string or vector (i.e., a keyboard macro) then
-@code{execute-kbd-macro} is used to execute it. You can call this
-function yourself (@pxref{Keyboard Macros}).
-
- To terminate the execution of a running command, type @kbd{C-g}. This
-character causes @dfn{quitting} (@pxref{Quitting}).
+ If the command is a keyboard macro (i.e.@: a string or vector),
+Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard
+Macros}).
@defvar pre-command-hook
-The editor command loop runs this normal hook before each command. At
-that time, @code{this-command} contains the command that is about to
-run, and @code{last-command} describes the previous command.
-@xref{Command Loop Info}.
+This normal hook is run by the editor command loop before it executes
+each command. At that time, @code{this-command} contains the command
+that is about to run, and @code{last-command} describes the previous
+command. @xref{Command Loop Info}.
@end defvar
@defvar post-command-hook
-The editor command loop runs this normal hook after each command
-(including commands terminated prematurely by quitting or by errors),
-and also when the command loop is first entered. At that time,
-@code{this-command} refers to the command that just ran, and
-@code{last-command} refers to the command before that.
+This normal hook is run by the editor command loop after it executes
+each command (including commands terminated prematurely by quitting or
+by errors). At that time, @code{this-command} refers to the command
+that just ran, and @code{last-command} refers to the command before
+that.
+
+This hook is also run when Emacs first enters the command loop (at
+which point @code{this-command} and @code{last-command} are both
+@code{nil}).
@end defvar
Quitting is suppressed while running @code{pre-command-hook} and
@code{post-command-hook}. If an error happens while executing one of
-these hooks, it terminates execution of the hook, and clears the hook
-variable to @code{nil} so as to prevent an infinite loop of errors.
+these hooks, it does not terminate execution of the hook; instead
+the error is silenced and the function in which the error occurred
+is removed from the hook.
A request coming into the Emacs server (@pxref{Emacs Server,,,
emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
@item
It may be a string; its contents are a sequence of elements separated
-by newlines, one for each parameter@footnote{Some elements actually
-supply two parameters.}. Each element consists of a code character
+by newlines, one for each argument@footnote{Some elements actually
+supply two arguments.}. Each element consists of a code character
(@pxref{Interactive Codes}) optionally followed by a prompt (which
some code characters use and some ignore). Here is an example:
@code{call-interactively}, which reads the arguments and calls the
command. You can also call these functions yourself.
-@defun commandp object &optional for-call-interactively
-Returns @code{t} if @var{object} is suitable for calling interactively;
-that is, if @var{object} is a command. Otherwise, returns @code{nil}.
-
-Interactively-callable objects include strings and vectors (which are
-treated as keyboard macros), lambda expressions that contain a
-top-level @code{interactive} form (@pxref{Using Interactive}),
-byte-code function objects made from such lambda expressions, autoload
-objects that are declared as interactive (non-@code{nil} fourth
-argument to @code{autoload}), and some primitive functions.
+ Note that the term ``command'', in this context, refers to an
+interactively callable function (or function-like object), or a
+keyboard macro. It does not refer to the key sequence used to invoke
+a command (@pxref{Keymaps}).
-A symbol satisfies @code{commandp} if it has a non-@code{nil}
+@defun commandp object &optional for-call-interactively
+This function returns @code{t} if @var{object} is a command.
+Otherwise, it returns @code{nil}.
+
+Commands include strings and vectors (which are treated as keyboard
+macros), lambda expressions that contain a top-level
+@code{interactive} form (@pxref{Using Interactive}), byte-code
+function objects made from such lambda expressions, autoload objects
+that are declared as interactive (non-@code{nil} fourth argument to
+@code{autoload}), and some primitive functions. Also, a symbol is
+considered a command if it has a non-@code{nil}
@code{interactive-form} property, or if its function definition
-satisfies @code{commandp}. Keys and keymaps are not commands.
-Rather, they are used to look up commands (@pxref{Keymaps}).
+satisfies @code{commandp}.
If @var{for-call-interactively} is non-@code{nil}, then
@code{commandp} returns @code{t} only for objects that
@defun call-interactively command &optional record-flag keys
This function calls the interactively callable function @var{command},
-reading arguments according to its interactive calling specifications.
-It returns whatever @var{command} returns. An error is signaled if
-@var{command} is not a function or if it cannot be called
-interactively (i.e., is not a command). Note that keyboard macros
-(strings and vectors) are not accepted, even though they are
-considered commands, because they are not functions. If @var{command}
-is a symbol, then @code{call-interactively} uses its function definition.
+providing arguments according to its interactive calling specifications.
+It returns whatever @var{command} returns.
+
+If, for instance, you have a function with the following signature:
+
+@example
+(defun foo (begin end)
+ (interactive "r")
+ ...)
+@end example
+
+then saying
+
+@example
+(call-interactively 'foo)
+@end example
+
+will call @code{foo} with the region (@code{point} and @code{mark}) as
+the arguments.
+
+An error is signaled if @var{command} is not a function or if it
+cannot be called interactively (i.e., is not a command). Note that
+keyboard macros (strings and vectors) are not accepted, even though
+they are considered commands, because they are not functions. If
+@var{command} is a symbol, then @code{call-interactively} uses its
+function definition.
@cindex record command history
If @var{record-flag} is non-@code{nil}, then this command and its
A string or vector as @var{command} is executed with
@code{execute-kbd-macro}. A function is passed to
-@code{call-interactively}, along with the optional @var{record-flag}
-and @var{keys}.
+@code{call-interactively} (see above), along with the
+@var{record-flag} and @var{keys} arguments.
-A symbol is handled by using its function definition in its place. A
-symbol with an @code{autoload} definition counts as a command if it was
-declared to stand for an interactively callable function. Such a
-definition is handled by loading the specified library and then
-rechecking the definition of the symbol.
+If @var{command} is a symbol, its function definition is used in its
+place. A symbol with an @code{autoload} definition counts as a
+command if it was declared to stand for an interactively callable
+function. Such a definition is handled by loading the specified
+library and then rechecking the definition of the symbol.
The argument @var{special}, if given, means to ignore the prefix
argument and not clear it. This is used for executing special events
It is not easy to display a value of point in the middle of a
sequence of text that has the @code{display}, @code{composition} or
-@code{intangible} property, or is invisible. Therefore, after a
-command finishes and returns to the command loop, if point is within
-such a sequence, the command loop normally moves point to the edge of
-the sequence.
+is invisible. Therefore, after a command finishes and returns to the
+command loop, if point is within such a sequence, the command loop
+normally moves point to the edge of the sequence.
A command can inhibit this feature by setting the variable
@code{disable-point-adjustment}:
@ifnottex
2**22
@end ifnottex
-bit in the character code indicates a character typed with
-the alt key held down. (On some terminals, the key labeled @key{ALT}
-is actually the meta key.)
+bit in the character code indicates a character typed with the alt key
+held down. (The key labeled @key{Alt} on most keyboards is actually
+treated as the meta key, not this.)
@end table
It is best to avoid mentioning specific bit numbers in your program.
@cindex function keys
Most keyboards also have @dfn{function keys}---keys that have names or
-symbols that are not characters. Function keys are represented in Emacs
-Lisp as symbols; the symbol's name is the function key's label, in lower
-case. For example, pressing a key labeled @key{F1} places the symbol
-@code{f1} in the input stream.
+symbols that are not characters. Function keys are represented in
+Emacs Lisp as symbols; the symbol's name is the function key's label,
+in lower case. For example, pressing a key labeled @key{F1} generates
+an input event represented by the symbol @code{f1}.
The event type of a function key event is the event symbol itself.
@xref{Classifying Events}.
@var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
@end example
+@noindent
+The meanings of these list elements are documented below.
+@xref{Accessing Mouse}, for functions that let you easily access these
+elements.
+
@table @asis
@item @var{window}
This is the window in which the click occurred.
@code{header-line}, @code{vertical-line}, @code{left-margin},
@code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
-In one special case, @var{pos-or-area} is a list containing a symbol (one
-of the symbols listed above) instead of just the symbol. This happens
-after the imaginary prefix keys for the event are inserted into the
-input stream. @xref{Key Sequence Input}.
-
+In one special case, @var{pos-or-area} is a list containing a symbol
+(one of the symbols listed above) instead of just the symbol. This
+happens after the imaginary prefix keys for the event are registered
+by Emacs. @xref{Key Sequence Input}.
@item @var{x}, @var{y}
-These are the pixel coordinates of the click, relative to
-the top left corner of @var{window}, which is @code{(0 . 0)}.
-For the mode or header line, @var{y} does not have meaningful data.
-For the vertical line, @var{x} does not have meaningful data.
+These are the relative pixel coordinates of the click. For clicks 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 or header 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 header line. In all cases, the @var{x} and @var{y} coordinates
+increase rightward and downward respectively.
@item @var{timestamp}
This is the time at which the event occurred, in milliseconds.
@item @var{object}
-This is the object on which the click occurred. It is either
-@code{nil} if there is no string property, or it has the form
-(@var{string} . @var{string-pos}) when there is a string-type text
-property at the click position.
+This is either @code{nil} if there is no string-type text property at
+the click position, or a cons cell of the form (@var{string}
+. @var{string-pos}) if there is one:
@table @asis
@item @var{string}
-This is the string on which the click occurred, including any
-properties.
+The string which was clicked on, including any properties.
@item @var{string-pos}
-This is the position in the string on which the click occurred,
-relevant if properties at the click need to be looked up.
+The position in the string where the click occurred.
@end table
@item @var{text-pos}
the window.
@item @var{col}, @var{row}
-These are the actual coordinates of the glyph under the @var{x},
-@var{y} position, possibly padded with default character width
-glyphs if @var{x} is beyond the last glyph on the line.
+These are the actual column and row coordinate numbers of the glyph
+under the @var{x}, @var{y} position. If @var{x} lies beyond the last
+column of actual text on its line, @var{col} is reported by adding
+fictional extra columns that have the default character width. Row 0
+is taken to be the header line if the window has one, or the topmost
+row of the text area otherwise. Column 0 is taken to be the leftmost
+column of the text area for clicks on a window text area, or the
+leftmost mode line or header line column for clicks there. For clicks
+on fringes or vertical borders, these have no meaningful data. For
+clicks on margins, @var{col} is measured from the left edge of the
+margin area and @var{row} is measured from the top of the margin area.
@item @var{image}
This is the image object on which the click occurred. It is either
These are the pixel width and height of @var{object} or, if this is
@code{nil}, those of the character glyph clicked on.
@end table
-
+
@sp 1
For mouse clicks on a scroll-bar, @var{position} has this form:
These events are generated when the Emacs process receives
the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no
additional data because signals do not carry additional information.
+They can be useful for debugging (@pxref{Error Debugging}).
To catch a user signal, bind the corresponding event to an interactive
command in the @code{special-event-map} (@pxref{Active Keymaps}).
a mouse button or motion event.
These two functions return the starting or ending position of a
-mouse-button event, as a list of this form:
+mouse-button event, as a list of this form (@pxref{Click Events}):
@example
(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
cons cell @code{(@var{x} . @var{y})}. These coordinates are relative
to the window given by @code{posn-window}.
-This example shows how to convert these window-relative coordinates
-into frame-relative coordinates:
+This example shows how to convert the window-relative coordinates in
+the text area of a window into frame-relative coordinates:
@example
(defun frame-relative-coordinates (position)
- "Return frame-relative coordinates from POSITION."
+ "Return frame-relative coordinates from POSITION.
+POSITION is assumed to lie in a window text area."
(let* ((x-y (posn-x-y position))
(window (posn-window position))
(edges (window-inside-pixel-edges window)))
@end defun
@defun posn-col-row position
-Return the row and column (in units of the frame's default character
-height and width) of @var{position}, as a cons cell @code{(@var{col} .
-@var{row})}. These are computed from the @var{x} and @var{y} values
-actually found in @var{position}.
+This function returns a cons cell @code{(@var{col} . @var{row})},
+containing the estimated column and row corresponding to buffer
+position @var{position}. The return value is given in units of the
+frame's default character width and height, as computed from the
+@var{x} and @var{y} values corresponding to @var{position}. (So, if
+the actual characters have non-default sizes, the actual row and
+column may differ from these computed values.)
+
+Note that @var{row} is counted from the top of the text area. If the
+window possesses a header line (@pxref{Header Lines}), it is
+@emph{not} counted as the first line.
@end defun
@defun posn-actual-col-row position
Return the actual row and column in @var{position}, as a cons cell
-@code{(@var{col} . @var{row})}. The values are the actual row number
-in the window, and the actual character number in that row. It returns
-@code{nil} if @var{position} does not include actual positions values.
-You can use @code{posn-col-row} to get approximate values.
+@code{(@var{col} . @var{row})}. The values are the actual row and
+column numbers in the window. @xref{Click Events}, for details. It
+returns @code{nil} if @var{position} does not include actual positions
+values.
@end defun
@defun posn-string position
echo area as a prompt, or @code{nil}, meaning not to display a prompt.
@end defun
+@defun read-char-choice prompt chars &optional inhibit-quit
+This function uses @code{read-key} to read and return a single
+character. It ignores any input that is not a member of @var{chars},
+a list of accepted characters. Optionally, it will also ignore
+keyboard-quit events while it is waiting for valid input. If you bind
+@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value
+while calling @code{read-char-choice}, then pressing @code{help-char}
+causes it to evaluate @code{help-form} and display the result. It
+then continues to wait for a valid input character, or keyboard-quit.
+@end defun
+
@node Event Mod
@subsection Modifying and Translating Input Events
special meaning in a search, because these events should exit the search
and then execute normally.
-The reliable and easy way to extract events from a key sequence so as to
-put them in @code{unread-command-events} is to use
-@code{listify-key-sequence} (@pxref{Strings of Events}).
+The reliable and easy way to extract events from a key sequence so as
+to put them in @code{unread-command-events} is to use
+@code{listify-key-sequence} (see below).
Normally you add events to the front of this list, so that the events
most recently unread will be reread first.
@section Special Events
@cindex special events
-Special events are handled at a very low level---as soon as they are
-read. The @code{read-event} function processes these events itself, and
-never returns them. Instead, it keeps waiting for the first event
-that is not special and returns that one.
+Certain @dfn{special events} are handled at a very low level---as soon
+as they are read. The @code{read-event} function processes these
+events itself, and never returns them. Instead, it keeps waiting for
+the first event that is not special and returns that one.
-Events that are handled in this way do not echo, they are never grouped
-into key sequences, and they never appear in the value of
+ Special events do not echo, they are never grouped into key
+sequences, and they never appear in the value of
@code{last-command-event} or @code{(this-command-keys)}. They do not
discard a numeric argument, they cannot be unread with
@code{unread-command-events}, they may not appear in a keyboard macro,
and they are not recorded in a keyboard macro while you are defining
one.
-These events do, however, appear in @code{last-input-event} immediately
-after they are read, and this is the way for the event's definition to
-find the actual event.
+ Special events do, however, appear in @code{last-input-event}
+immediately after they are read, and this is the way for the event's
+definition to find the actual event.
-The events types @code{iconify-frame}, @code{make-frame-visible},
+ The events types @code{iconify-frame}, @code{make-frame-visible},
@code{delete-frame}, @code{drag-n-drop}, and user signals like
@code{sigusr1} are normally handled in this way. The keymap which
-defines how to handle special events---and which events are special---is
-in the variable @code{special-event-map} (@pxref{Active Keymaps}).
+defines how to handle special events---and which events are
+special---is in the variable @code{special-event-map} (@pxref{Active
+Keymaps}).
@node Waiting
@section Waiting for Elapsed Time or Input
@item
A list of one element, which is an integer. This form of prefix
-argument results from one or a succession of @kbd{C-u}'s with no
+argument results from one or a succession of @kbd{C-u}s with no
digits. The numeric value is the integer in the list, but some
commands make a distinction between such a list and an integer alone.
@end defvar
@defvar kbd-macro-termination-hook
-This normal hook (@pxref{Standard Hooks}) is run when a keyboard
-macro terminates, regardless of what caused it to terminate (reaching
-the macro end or an error which ended the macro prematurely).
+This normal hook is run when a keyboard macro terminates, regardless
+of what caused it to terminate (reaching the macro end or an error
+which ended the macro prematurely).
@end defvar
-
-@ignore
- arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1
-@end ignore
HCoop / bpt / emacs.git / blobdiff