comparison lispref/commands.texi @ 90043:e24e2e78deda

Revision: [e-mail]--gnu-2004/emacs--unicode--0--patch-69 Merge from emacs--cvs-trunk--0 Patches applied: * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-643 - [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-649 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-650 Merge from gnus--rel--5.10 * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-651 - [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-655 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-656 Update from CVS: lisp/man.el (Man-xref-normal-file): Fix help-echo. * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-657 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-658 Merge from gnus--rel--5.10 * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-659 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-660 Merge from gnus--rel--5.10 * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-661 - [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-667 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-668 Merge from gnus--rel--5.10 * [e-mail]--gnu-2004/gnus--rel--5.10--patch-61 - [e-mail]--gnu-2004/gnus--rel--5.10--patch-68 Update from CVS

90042:003d95404d71

Arbitrary text, read in the minibuffer using the current buffer's input
method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
Emacs Manual}).  Prompt.

@item n
A number read with the minibuffer.  If the input is not a number, the
user is asked to try again.  The prefix argument, if any, is not used.
Prompt.

@item N
@cindex raw prefix argument usage
The numeric prefix argument; but if there is no prefix argument, read a
number as with @kbd{n}.  Requires a number.  @xref{Prefix Command
Arguments}.  Prompt.

@item p
@cindex numeric prefix argument usage
The numeric prefix argument.  (Note that this @samp{p} is lower case.)
No I/O.

@item P
The raw prefix argument.  (Note that this @samp{P} is upper case.)  No
I/O.

@item r
@cindex region argument

@end group
@end example
@end deffn

@defun interactive-p
This function returns @code{t} if the containing function (the one whose
code includes the call to @code{interactive-p}) was called
interactively, with the function @code{call-interactively}.  (It makes
no difference whether @code{call-interactively} was called from Lisp or
directly from the editor command loop.)  If the containing function was
called by Lisp evaluation (or with @code{apply} or @code{funcall}), then
it was not called interactively.
@end defun

  The most common use of @code{interactive-p} is for deciding whether to
print an informative message.  As a special exception,
@code{interactive-p} returns @code{nil} whenever a keyboard macro is
being run.  This is to suppress the informative messages and speed
execution of the macro.

  For example:

@example
@group
(defun foo ()
  (interactive)
  (when (interactive-p)
    (message "foo")))
     @result{} foo
@end group

@group
(defun bar ()
  (interactive)
  (setq foobar (list (foo) (interactive-p))))
     @result{} bar
@end group

     @print{} foo
@end group

@group
;; @r{Type @kbd{M-x bar}.}
;; @r{This does not print anything.}
@end group

@group
foobar
     @result{} (nil t)
@end group
@end example

  The other way to do this sort of job is to make the command take an
argument @code{print-message} which should be non-@code{nil} in an
interactive call, and use the @code{interactive} spec to make sure it is
non-@code{nil}.  Here's how:

@example
(defun foo (&optional print-message)
  (interactive "p")
  (when print-message
    (message "foo")))
@end example

@noindent
Defined in this way, the function does display the message when
called from a keyboard macro.

  The numeric prefix argument, provided by @samp{p}, is never @code{nil}.

@node Command Loop Info
@comment  node-name,  next,  previous,  up
@section Information from the Command Loop

@cindex @code{wheel-up} event
@cindex @code{wheel-down} event
@item (wheel-up @var{position})
@item (wheel-down @var{position})
This kind of event is generated by moving a wheel on a mouse.  Its
effect is typically 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.

This kind of event is generated only on some kinds of systems. On
other systems, mouse-4 and mouse-5 may be used instead.  For portable
code, the variables @code{mouse-wheel-up-event} and
@code{mouse-wheel-down-event} defined in @file{mwheel.el} can be used.

@cindex @code{drag-n-drop} event
@item (drag-n-drop @var{position} @var{files})
This kind of event is generated when a group of files is
selected in an application outside of Emacs, and then dragged and

90043:e24e2e78deda

Arbitrary text, read in the minibuffer using the current buffer's input
method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
Emacs Manual}).  Prompt.

@item n
A number, read with the minibuffer.  If the input is not a number, the
user has to try again.  @samp{n} never uses the prefix argument.
Prompt.

@item N
The numeric prefix argument; but if there is no prefix argument, read
a number as with @kbd{n}.  The value is always a number.  @xref{Prefix
Command Arguments}.  Prompt.

@item p
@cindex numeric prefix argument usage
The numeric prefix argument.  (Note that this @samp{p} is lower case.)
No I/O.

@item P
@cindex raw prefix argument usage
The raw prefix argument.  (Note that this @samp{P} is upper case.)  No
I/O.

@item r
@cindex region argument

@end group
@end example
@end deffn

@defun interactive-p
This function returns @code{t} if the containing function (the one
whose code includes the call to @code{interactive-p}) was called in
direct response to user input.  This means that it was called with the
function @code{call-interactively}, and that a keyboard macro is
not running, and that Emacs is not running in batch mode.

If the containing function was called by Lisp evaluation (or with
@code{apply} or @code{funcall}), then it was not called interactively.
@end defun

  The most common use of @code{interactive-p} is for deciding whether
to give the user additional visual feedback (such as by printing an
informative message).  For example:

@example
@group
;; @r{Here's the usual way to use @code{interactive-p}.}
(defun foo ()
  (interactive)
  (when (interactive-p)
    (message "foo")))
     @result{} foo
@end group

@group
;; @r{This function is just to illustrate the behavior.}
(defun bar ()
  (interactive)
  (setq foobar (list (foo) (interactive-p))))
     @result{} bar
@end group

     @print{} foo
@end group

@group
;; @r{Type @kbd{M-x bar}.}
;; @r{This does not display a message.}
@end group

@group
foobar
     @result{} (nil t)
@end group
@end example

  If you want to test @emph{only} whether the function was called
using @code{call-interactively}, add an optional argument
@code{print-message} which should be non-@code{nil} in an interactive
call, and use the @code{interactive} spec to make sure it is
non-@code{nil}.  Here's an example:

@example
(defun foo (&optional print-message)
  (interactive "p")
  (when print-message
    (message "foo")))
@end example

@noindent
Defined in this way, the function does display the message when called
from a keyboard macro.  We use @code{"p"} because the numeric prefix
argument is never @code{nil}.

@defun called-interactively-p
This function returns @code{t} when the calling function was called
using @code{call-interactively}.

When possible, instead of using this function, you should use the
method in the example above; that method makes it possible for a
caller to ``pretend'' that the function was called interactively.
@end defun

@node Command Loop Info
@comment  node-name,  next,  previous,  up
@section Information from the Command Loop

@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.

This kind of event is generated only on some kinds of systems. On some
systems, @code{mouse-4} and @code{mouse-5} are used instead.  For
portable code, use the variables @code{mouse-wheel-up-event} and
@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
what event types to expect for the mouse wheel.

@cindex @code{drag-n-drop} event
@item (drag-n-drop @var{position} @var{files})
This kind of event is generated when a group of files is
selected in an application outside of Emacs, and then dragged and