@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@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
@chapter Command Loop
Lisp code, you must supply the file name string as an ordinary Lisp
function argument.
- If the command is a keyboard macro (i.e.@: a string or vector),
+ If the command is a keyboard macro (i.e., a string or vector),
Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard
Macros}).
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}.
then the caller supplies the arguments and @var{arg-descriptor} has no
effect.
-@cindex @code{interactive-form}, function property
+@cindex @code{interactive-form}, symbol property
The @code{interactive} form must be located at top-level in the
function body, or in the function symbol's @code{interactive-form}
-property (@pxref{Symbol Plists}). It has its effect because the
+property (@pxref{Symbol Properties}). It has its effect because the
command loop looks for it before calling the function
(@pxref{Interactive Call}). Once the function is called, all its body
forms are executed; at this time, if the @code{interactive} form
the name of an existing buffer, which becomes the second and final
argument.
-@c Emacs 19 feature
The prompt string can use @samp{%} to include previous argument values
(starting with the first argument) in the prompt. This is done using
@code{format} (@pxref{Formatting Strings}). For example, here is how
signaled if the buffer is read-only.
@cindex @samp{@@} in @code{interactive}
-@c Emacs 19 feature
If @samp{@@} appears at the beginning of the string, and if the key
sequence used to invoke the command includes any mouse events, then
the window associated with the first of those events is selected
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
@end defvar
@defvar last-command-event
-@defvarx last-command-char
This variable is set to the last input event that was read by the
command loop as part of a command. The principal use of this variable
is in @code{self-insert-command}, which uses it to decide which
@noindent
The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
-
-The alias @code{last-command-char} is obsolete.
@end defvar
-@c Emacs 19 feature
@defvar last-event-frame
This variable records which frame the last input event was directed to.
Usually this is the frame that was selected when the event was
@var{event-type} is @code{mouse-1}.
@item @var{position}
-This is the position where the mouse click occurred. The actual
-format of @var{position} depends on what part of a window was clicked
-on.
+@cindex mouse position list
+This is a @dfn{mouse position list} specifying where the mouse click
+occurred; see below for details.
-For mouse click events in the text area, mode line, header line, or in
-the marginal areas, @var{position} has this form:
+@item @var{click-count}
+This is the number of rapid repeated presses so far of the same mouse
+button. @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
+functions documented in @ref{Accessing Mouse}. The explicit format of
+the list depends on where the click occurred. For clicks in the text
+area, mode line, header line, or in the fringe or marginal areas, the
+mouse position list has the form
@example
(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
@end example
@noindent
-The meanings of these list elements are documented below.
-@xref{Accessing Mouse}, for functions that let you easily access these
-elements.
+The meanings of these list elements are as follows:
@table @asis
@item @var{window}
-This is the window in which the click occurred.
+The window in which the click occurred.
@item @var{pos-or-area}
-This is the buffer position of the character clicked on in the text
-area, or if clicked outside the text area, it is the window area in
-which the click occurred. It is one of the symbols @code{mode-line},
+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
+occurred. It is one of the symbols @code{mode-line},
@code{header-line}, @code{vertical-line}, @code{left-margin},
@code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
by Emacs. @xref{Key Sequence Input}.
@item @var{x}, @var{y}
-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.
+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.
+The time at which the event occurred, as an integer number of
+milliseconds since a system-dependent initial time.
@item @var{object}
-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}
+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
@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:
+For clicks on a scroll bar, @var{position} has this form:
@example
(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
@table @asis
@item @var{window}
-This is the window whose scroll-bar was clicked on.
+The window whose scroll bar was clicked on.
@item @var{area}
-This is the scroll bar where the click occurred. It is one of the
-symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
+This is the symbol @code{vertical-scroll-bar}.
@item @var{portion}
-This is the distance of the click from the top or left end of
-the scroll bar.
+The number of pixels from the top of the scroll bar to the click
+position. On some toolkits, including GTK+, Emacs cannot extract this
+data, so the value is always @code{0}.
@item @var{whole}
-This is the length of the entire scroll bar.
+The total length, in pixels, of the scroll bar. On some toolkits,
+including GTK+, Emacs cannot extract this data, so the value is always
+@code{0}.
@item @var{timestamp}
-This is the time at which the event occurred, in milliseconds.
+The time at which the event occurred, in milliseconds. On some
+toolkits, including GTK+, Emacs cannot extract this data, so the value
+is always @code{0}.
@item @var{part}
-This is the part of the scroll-bar which was clicked on. It is one
-of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
-@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
+The part of the scroll bar on which the click occurred. It is one of
+the symbols @code{handle} (the scroll bar handle), @code{above-handle}
+(the area above the handle), @code{below-handle} (the area below the
+handle), @code{up} (the up arrow at one end of the scroll bar), or
+@code{down} (the down arrow at one end of the scroll bar).
+@c The `top', `bottom', and `end-scroll' codes don't seem to be used.
@end table
-@item @var{click-count}
-This is the number of rapid repeated presses so far of the same mouse
-button. @xref{Repeat Events}.
-@end table
@node Drag Events
@subsection Drag Events
prefix @samp{drag-}. For example, dragging the mouse with button 2
held down generates a @code{drag-mouse-2} event. The second and third
elements of the event give the starting and ending position of the
-drag. They have the same form as @var{position} in a click event
-(@pxref{Click Events}) that is not on the scroll bar part of the
-window. You can access the second element of any mouse event in the
-same way, with no need to distinguish drag events from others.
+drag, as mouse position lists (@pxref{Click Events}). You can access
+the second element of any mouse event in the same way, with no need to
+distinguish drag events from others.
The @samp{drag-} prefix follows the modifier key prefixes such as
@samp{C-} and @samp{M-}.
(mouse-movement POSITION)
@end example
-The second element of the list describes the current position of the
-mouse, just as in a click event (@pxref{Click Events}).
+@noindent
+@var{position} is a mouse position list (@pxref{Click Events}),
+specifying the current position of the mouse cursor.
-The special form @code{track-mouse} enables generation of motion events
-within its body. Outside of @code{track-mouse} forms, Emacs does not
-generate events for mere motion of the mouse, and these events do not
-appear. @xref{Mouse Tracking}.
+The special form @code{track-mouse} enables generation of motion
+events within its body. Outside of @code{track-mouse} forms, Emacs
+does not generate events for mere motion of the mouse, and these
+events do not appear. @xref{Mouse Tracking}.
@node Focus Events
@subsection Focus Events
@cindex @code{wheel-up} event
@cindex @code{wheel-down} event
@item (wheel-up @var{position})
-@item (wheel-down @var{position})
-These kinds of event are generated by moving a mouse wheel. Their
-usual meaning is a kind of scroll or zoom.
-
-The element @var{position} is a list describing the position of the
-event, in the same format as used in a mouse-click event (@pxref{Click
-Events}).
+@itemx (wheel-down @var{position})
+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.
@vindex mouse-wheel-up-event
@vindex mouse-wheel-down-event
This section describes convenient functions for accessing the data in
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 (@pxref{Click Events}):
-
-@example
-(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
- @var{object} @var{text-pos} (@var{col} . @var{row})
- @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
-@end example
+ The following two functions return a mouse position list
+(@pxref{Click Events}), specifying the position of a mouse event.
@defun event-start event
This returns the starting position of @var{event}.
position such events have.
@end defun
+@defun posnp object
+This function returns non-@code{nil} if @var{object} is a mouse
+position list, in either of the formats documented in @ref{Click
+Events}); and @code{nil} otherwise.
+@end defun
+
@cindex mouse position list, accessing
- These functions take a position list as described above, and
-return various parts of it.
+ These functions take a mouse position list as argument, and return
+various parts of it:
@defun posn-window position
Return the window that @var{position} is in.
@end example
@defvar num-input-keys
-@c Emacs 19 feature
This variable's value is the number of key sequences processed so far in
this Emacs session. This includes key sequences read from the terminal
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,
@defun read-char &optional prompt inherit-input-method seconds
This function reads and returns a character of command input. If the
-user generates an event which is not a character (i.e. a mouse click or
+user generates an event which is not a character (i.e., a mouse click or
function key event), @code{read-char} signals an error. The arguments
work as in @code{read-event}.
@code{keyboard-translate-table} (if applicable), before returning it
from @code{read-event}.
-@c Emacs 19 feature
@defvar extra-keyboard-modifiers
This variable lets Lisp programs ``press'' the modifier keys on the
keyboard. The value is a character. Only the modifiers of the
@cindex control characters, reading
@cindex nonprinting characters, reading
This function is like @code{read-char}, except that if the first
-character read is an octal digit (0-7), it reads any number of octal
+character read is an octal digit (0--7), it reads any number of octal
digits (but stopping if a non-octal digit is found), and returns the
character represented by that numeric character code. If the
character that terminates the sequence of octal digits is @key{RET},
most recently unread will be reread first.
Events read from this list are not normally added to the current
-command's key sequence (as returned by e.g. @code{this-command-keys}),
+command's key sequence (as returned by, e.g., @code{this-command-keys}),
as the events will already have been added once as they were read for
the first time. An element of the form @code{(@code{t} . @var{event})}
forces @var{event} to be added to the current command's key sequence.
individual events, which you can put in @code{unread-command-events}.
@end defun
-@ignore
-@defvar unread-command-char
-This variable holds a character to be read as command input.
-A value of -1 means ``empty''.
-
-This variable is mostly obsolete now that you can use
-@code{unread-command-events} instead; it exists only to support programs
-written for Emacs versions 18 and earlier.
-@end defvar
-@end ignore
-
-@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
-@defvarx last-input-char
This variable records the last terminal input event read, whether
as part of a command or explicitly by a Lisp program.
@result{} 49
@end group
@end example
-
-The alias @code{last-input-char} is obsolete.
@end defvar
@defmac while-no-input body@dots{}
@var{seconds} is rounded down.
The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)},
-i.e. it requests a redisplay, without any delay, if there is no pending input.
+i.e., it requests a redisplay, without any delay, if there is no pending input.
@xref{Forcing Redisplay}.
If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
HCoop / bpt / emacs.git / blobdiff