/[emacs]/emacs/lispref/commands.texi
ViewVC logotype

Diff of /emacs/lispref/commands.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.39.2.2 by miles, Tue Jun 29 16:45:27 2004 UTC revision 1.39.2.3 by miles, Tue Aug 10 07:46:39 2004 UTC
# Line 1  Line 1 
1  @c -*-texinfo-*-  @c -*-texinfo-*-
2  @c This is part of the GNU Emacs Lisp Reference Manual.  @c This is part of the GNU Emacs Lisp Reference Manual.
3  @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999  @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
4  @c   Free Software Foundation, Inc.  @c   Free Software Foundation, Inc.
5  @c See the file elisp.texi for copying conditions.  @c See the file elisp.texi for copying conditions.
6  @setfilename ../info/commands  @setfilename ../info/commands
# Line 119  controls the reading of arguments for an Line 119  controls the reading of arguments for an
119    
120    This section describes how to write the @code{interactive} form that    This section describes how to write the @code{interactive} form that
121  makes a Lisp function an interactively-callable command, and how to  makes a Lisp function an interactively-callable command, and how to
122  examine a commands's @code{interactive} form.  examine a command's @code{interactive} form.
123    
124  @defspec interactive arg-descriptor  @defspec interactive arg-descriptor
125  @cindex argument descriptors  @cindex argument descriptors
# Line 235  string (starting with the first characte Line 235  string (starting with the first characte
235    
236  @cindex examining the @code{interactive} form  @cindex examining the @code{interactive} form
237  @defun interactive-form function  @defun interactive-form function
238  This function returns the @code{interactive} form of @var{function}.  If  This function returns the @code{interactive} form of @var{function}.
239  @var{function} is a command (@pxref{Interactive Call}), the value is a  If @var{function} is an interactively callable function
240  list of the form @code{(interactive @var{spec})}, where @var{spec} is  (@pxref{Interactive Call}), the value is the command's
241  the descriptor specification used by the command's @code{interactive}  @code{interactive} form @code{(interactive @var{spec})}, which
242  form to compute the function's arguments.  If @var{function} is not a  specifies how to compute its arguments.  Otherwise, the value is
243  command, @code{interactive-form} returns @code{nil}.  @code{nil}.  If @var{function} is a symbol, its function definition is
244    used.
245  @end defun  @end defun
246    
247  @node Interactive Codes  @node Interactive Codes
# Line 416  the string.)  Other characters that norm Line 417  the string.)  Other characters that norm
417  parentheses and brackets) do not do so here.  Prompt.  parentheses and brackets) do not do so here.  Prompt.
418    
419  @item v  @item v
420  A variable declared to be a user option (i.e., satisfying the predicate  A variable declared to be a user option (i.e., satisfying the
421  @code{user-variable-p}).  @xref{High-Level Completion}.  Existing,  predicate @code{user-variable-p}).  This reads the variable using
422    @code{read-variable}.  @xref{Definition of read-variable}.  Existing,
423  Completion, Prompt.  Completion, Prompt.
424    
425  @item x  @item x
# Line 528  realistic example of using @code{command Line 530  realistic example of using @code{command
530  @defun call-interactively command &optional record-flag keys  @defun call-interactively command &optional record-flag keys
531  This function calls the interactively callable function @var{command},  This function calls the interactively callable function @var{command},
532  reading arguments according to its interactive calling specifications.  reading arguments according to its interactive calling specifications.
533  An error is signaled if @var{command} is not a function or if it cannot  It returns whatever @var{command} returns.  An error is signaled if
534  be called interactively (i.e., is not a command).  Note that keyboard  @var{command} is not a function or if it cannot be called
535  macros (strings and vectors) are not accepted, even though they are  interactively (i.e., is not a command).  Note that keyboard macros
536  considered commands, because they are not functions.  (strings and vectors) are not accepted, even though they are
537    considered commands, because they are not functions.  If @var{command}
538    is a symbol, then @code{call-interactively} uses its function definition.
539    
540  @cindex record command history  @cindex record command history
541  If @var{record-flag} is non-@code{nil}, then this command and its  If @var{record-flag} is non-@code{nil}, then this command and its
# Line 541  an argument.  @xref{Command History}. Line 545  an argument.  @xref{Command History}.
545    
546  The argument @var{keys}, if given, specifies the sequence of events to  The argument @var{keys}, if given, specifies the sequence of events to
547  supply if the command inquires which events were used to invoke it.  supply if the command inquires which events were used to invoke it.
548    If @var{keys} is omitted or @code{nil}, the return value of
549    @code{this-command-keys} is used.  @xref{Definition of this-command-keys}.
550  @end defun  @end defun
551    
552  @defun command-execute command &optional record-flag keys special  @defun command-execute command &optional record-flag keys special
# Line 551  callable function or a keyboard macro. Line 557  callable function or a keyboard macro.
557    
558  A string or vector as @var{command} is executed with  A string or vector as @var{command} is executed with
559  @code{execute-kbd-macro}.  A function is passed to  @code{execute-kbd-macro}.  A function is passed to
560  @code{call-interactively}, along with the optional @var{record-flag}.  @code{call-interactively}, along with the optional @var{record-flag}
561    and @var{keys}.
562    
563  A symbol is handled by using its function definition in its place.  A  A symbol is handled by using its function definition in its place.  A
564  symbol with an @code{autoload} definition counts as a command if it was  symbol with an @code{autoload} definition counts as a command if it was
# Line 559  declared to stand for an interactively c Line 566  declared to stand for an interactively c
566  definition is handled by loading the specified library and then  definition is handled by loading the specified library and then
567  rechecking the definition of the symbol.  rechecking the definition of the symbol.
568    
 The argument @var{keys}, if given, specifies the sequence of events to  
 supply if the command inquires which events were used to invoke it.  
   
569  The argument @var{special}, if given, means to ignore the prefix  The argument @var{special}, if given, means to ignore the prefix
570  argument and not clear it.  This is used for executing special events  argument and not clear it.  This is used for executing special events
571  (@pxref{Special Events}).  (@pxref{Special Events}).
# Line 741  was specified to run but remapped into a Line 745  was specified to run but remapped into a
745  @end defvar  @end defvar
746    
747  @defun this-command-keys  @defun this-command-keys
748    @anchor{Definition of this-command-keys}
749  This function returns a string or vector containing the key sequence  This function returns a string or vector containing the key sequence
750  that invoked the present command, plus any previous commands that  that invoked the present command, plus any previous commands that
751  generated the prefix argument for this command.  The value is a string  generated the prefix argument for this command.  However, if the
752  if all those events were characters.  @xref{Input Events}.  command has called @code{read-key-sequence}, it returns the last read
753    key sequence.  @xref{Key Sequence Input}.  The value is a string if
754    all events in the sequence were characters that fit in a string.
755    @xref{Input Events}.
756    
757  @example  @example
758  @group  @group
# Line 762  input events in a string (@pxref{Strings Line 770  input events in a string (@pxref{Strings
770  @end defun  @end defun
771    
772  @tindex clear-this-command-keys  @tindex clear-this-command-keys
773  @defun clear-this-command-keys  @defun clear-this-command-keys &optional keep-record
774  This function empties out the table of events for  This function empties out the table of events for
775  @code{this-command-keys} to return, and also empties the records that  @code{this-command-keys} to return.  Unless @var{keep-record} is
776  the function @code{recent-keys} (@pxref{Recording Input}) will  non-@code{nil}, it also empties the records that the function
777  subsequently return.  This is useful after reading a password, to  @code{recent-keys} (@pxref{Recording Input}) will subsequently return.
778  prevent the password from echoing inadvertently as part of the next  This is useful after reading a password, to prevent the password from
779  command in certain cases.  echoing inadvertently as part of the next command in certain cases.
780  @end defun  @end defun
781    
782  @defvar last-nonmenu-event  @defvar last-nonmenu-event
# Line 809  Usually this is the frame that was selec Line 817  Usually this is the frame that was selec
817  generated, but if that frame has redirected input focus to another  generated, but if that frame has redirected input focus to another
818  frame, the value is the frame to which the event was redirected.  frame, the value is the frame to which the event was redirected.
819  @xref{Input Focus}.  @xref{Input Focus}.
820    
821    If the last event came from a keyboard macro, the value is @code{macro}.
822  @end defvar  @end defvar
823    
824  @node Adjusting Point  @node Adjusting Point
# Line 1155  the marginal areas, @var{position} has t Line 1165  the marginal areas, @var{position} has t
1165    
1166  @example  @example
1167  (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}  (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1168   @var{object} @var{text-pos} (@var{col} . @var{row})   @var{object} @var{text-pos} (@var{col} . @var{row})
1169   @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))   @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1170  @end example  @end example
1171    
# Line 1387  the value is 3 or greater.  If @var{even Line 1397  the value is 3 or greater.  If @var{even
1397  (not a repeat event), the value is 1.  (not a repeat event), the value is 1.
1398  @end defun  @end defun
1399    
1400  @defvar double-click-fuzz  @defopt double-click-fuzz
1401  To generate repeat events, successive mouse button presses must be at  To generate repeat events, successive mouse button presses must be at
1402  approximately the same screen position.  The value of  approximately the same screen position.  The value of
1403  @code{double-click-fuzz} specifies the maximum number of pixels the  @code{double-click-fuzz} specifies the maximum number of pixels the
1404  mouse may be moved between two successive clicks to make a  mouse may be moved (horizontally or vertically) between two successive
1405  double-click.  clicks to make a double-click.
 @end defvar  
1406    
1407  @defvar double-click-time  This variable is also the threshold for motion of the mouse to count
1408    as a drag.
1409    @end defopt
1410    
1411    @defopt double-click-time
1412  To generate repeat events, the number of milliseconds between  To generate repeat events, the number of milliseconds between
1413  successive button presses must be less than the value of  successive button presses must be less than the value of
1414  @code{double-click-time}.  Setting @code{double-click-time} to  @code{double-click-time}.  Setting @code{double-click-time} to
1415  @code{nil} disables multi-click detection entirely.  Setting it to  @code{nil} disables multi-click detection entirely.  Setting it to
1416  @code{t} removes the time limit; Emacs then detects multi-clicks by  @code{t} removes the time limit; Emacs then detects multi-clicks by
1417  position only.  position only.
1418  @end defvar  @end defopt
1419    
1420  @node Motion Events  @node Motion Events
1421  @subsection Motion Events  @subsection Motion Events
# Line 1593  This function returns a list of the modi Line 1606  This function returns a list of the modi
1606  modifiers are symbols; they include @code{shift}, @code{control},  modifiers are symbols; they include @code{shift}, @code{control},
1607  @code{meta}, @code{alt}, @code{hyper} and @code{super}.  In addition,  @code{meta}, @code{alt}, @code{hyper} and @code{super}.  In addition,
1608  the modifiers list of a mouse event symbol always contains one of  the modifiers list of a mouse event symbol always contains one of
1609  @code{click}, @code{drag}, and @code{down}.  @code{click}, @code{drag}, and @code{down}.  For double or triple
1610    events, it also contains @code{double} or @code{triple}.
1611    
1612  The argument @var{event} may be an entire event object, or just an event  The argument @var{event} may be an entire event object, or just an
1613  type.  event type.  If @var{event} is a symbol that has never been used in an
1614    event that has been read as input in the current Emacs session, then
1615    @code{event-modifiers} can return @code{nil}, even when @var{event}
1616    actually has modifiers.
1617    
1618  Here are some examples:  Here are some examples:
1619    
1620  @example  @example
1621  (event-modifiers ?a)  (event-modifiers ?a)
1622       @result{} nil       @result{} nil
1623    (event-modifiers ?A)
1624         @result{} (shift)
1625  (event-modifiers ?\C-a)  (event-modifiers ?\C-a)
1626       @result{} (control)       @result{} (control)
1627  (event-modifiers ?\C-%)  (event-modifiers ?\C-%)
# Line 1627  but the event symbol name itself does no Line 1646  but the event symbol name itself does no
1646    
1647  @defun event-basic-type event  @defun event-basic-type event
1648  This function returns the key or mouse button that @var{event}  This function returns the key or mouse button that @var{event}
1649  describes, with all modifiers removed.  For example:  describes, with all modifiers removed.  The @var{event} argument is as
1650    in @code{event-modifiers}.  For example:
1651    
1652  @example  @example
1653  (event-basic-type ?a)  (event-basic-type ?a)
# Line 1656  event. Line 1676  event.
1676    
1677  @defun event-convert-list list  @defun event-convert-list list
1678  This function converts a list of modifier names and a basic event type  This function converts a list of modifier names and a basic event type
1679  to an event type which specifies all of them.  For example,  to an event type which specifies all of them.  The basic event type
1680    must be the last element of the list.  For example,
1681    
1682  @example  @example
1683  (event-convert-list '(control ?a))  (event-convert-list '(control ?a))
# Line 1788  is a buffer position, return the size of Line 1809  is a buffer position, return the size of
1809    
1810  @cindex mouse event, timestamp  @cindex mouse event, timestamp
1811  @cindex timestamp of a mouse event  @cindex timestamp of a mouse event
1812  @defun posn-timestamp  @defun posn-timestamp position
1813  Return the timestamp in @var{position}.  This is the time at which the  Return the timestamp in @var{position}.  This is the time at which the
1814  event occurred, in milliseconds.  event occurred, in milliseconds.
1815  @end defun  @end defun
# Line 2001  for example, @code{describe-key} uses it Line 2022  for example, @code{describe-key} uses it
2022  This function reads a key sequence and returns it as a string or  This function reads a key sequence and returns it as a string or
2023  vector.  It keeps reading events until it has accumulated a complete key  vector.  It keeps reading events until it has accumulated a complete key
2024  sequence; that is, enough to specify a non-prefix command using the  sequence; that is, enough to specify a non-prefix command using the
2025  currently active keymaps.  currently active keymaps.  (Remember that a key sequence that starts
2026    with a mouse event is read using the keymaps of the buffer in the
2027    window that the mouse was in, not the current buffer.)
2028    
2029  If the events are all characters and all can fit in a string, then  If the events are all characters and all can fit in a string, then
2030  @code{read-key-sequence} returns a string (@pxref{Strings of Events}).  @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
# Line 2101  from the terminal---not counting those g Line 2124  from the terminal---not counting those g
2124    The lowest level functions for command input are those that read a    The lowest level functions for command input are those that read a
2125  single event.  single event.
2126    
2127    None of the three functions below suppresses quitting.
2128    
2129  @defun read-event &optional prompt inherit-input-method  @defun read-event &optional prompt inherit-input-method
2130  This function reads and returns the next event of command input, waiting  This function reads and returns the next event of command input, waiting
2131  if necessary until an event is available.  Events can come directly from  if necessary until an event is available.  Events can come directly from
# Line 2122  If @code{cursor-in-echo-area} is non-@co Line 2147  If @code{cursor-in-echo-area} is non-@co
2147  moves the cursor temporarily to the echo area, to the end of any message  moves the cursor temporarily to the echo area, to the end of any message
2148  displayed there.  Otherwise @code{read-event} does not move the cursor.  displayed there.  Otherwise @code{read-event} does not move the cursor.
2149    
2150  If @code{read-event} gets an event that is defined as a help character, in  If @code{read-event} gets an event that is defined as a help character,
2151  some cases @code{read-event} processes the event directly without  then in some cases @code{read-event} processes the event directly without
2152  returning.  @xref{Help Functions}.  Certain other events, called  returning.  @xref{Help Functions}.  Certain other events, called
2153  @dfn{special events}, are also processed directly within  @dfn{special events}, are also processed directly within
2154  @code{read-event} (@pxref{Special Events}).  @code{read-event} (@pxref{Special Events}).
# Line 2235  The command @code{quoted-insert} uses th Line 2260  The command @code{quoted-insert} uses th
2260  This function is like @code{read-char}, except that if the first  This function is like @code{read-char}, except that if the first
2261  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
2262  digits (but stopping if a non-octal digit is found), and returns the  digits (but stopping if a non-octal digit is found), and returns the
2263  character represented by that numeric character code.  character represented by that numeric character code.  If the
2264    character that terminates the sequence of octal digits is @key{RET},
2265    it is discarded.  Any other terminating character is used as input
2266    after this function returns.
2267    
2268  Quitting is suppressed when the first character is read, so that the  Quitting is suppressed when the first character is read, so that the
2269  user can enter a @kbd{C-g}.  @xref{Quitting}.  user can enter a @kbd{C-g}.  @xref{Quitting}.
# Line 2252  is 127 in decimal). Line 2280  is 127 in decimal).
2280    
2281  @group  @group
2282  ---------- Echo Area ----------  ---------- Echo Area ----------
2283  What character-@kbd{177}  What character @kbd{1 7 7}-
2284  ---------- Echo Area ----------  ---------- Echo Area ----------
2285    
2286       @result{} 127       @result{} 127
# Line 2370  during the sleep. Line 2398  during the sleep.
2398  @cindex special events  @cindex special events
2399  Special events are handled at a very low level---as soon as they are  Special events are handled at a very low level---as soon as they are
2400  read.  The @code{read-event} function processes these events itself, and  read.  The @code{read-event} function processes these events itself, and
2401  never returns them.  never returns them.  Instead, it keeps waiting for the first event
2402    that is not special and returns that one.
2403    
2404  Events that are handled in this way do not echo, they are never grouped  Events that are handled in this way do not echo, they are never grouped
2405  into key sequences, and they never appear in the value of  into key sequences, and they never appear in the value of
# Line 2544  is set to a value other than @code{nil}. Line 2573  is set to a value other than @code{nil}.
2573  non-@code{nil}, then @code{quit-flag} has no special effect.  non-@code{nil}, then @code{quit-flag} has no special effect.
2574  @end defvar  @end defvar
2575    
2576    @defmac with-local-quit forms@dots{}
2577    This macro executes @var{forms} in sequence, but allows quitting, at
2578    least locally, within @var{body} even if @code{inhibit-quit} was
2579    non-@code{nil} outside this construct.  It returns the value of the
2580    last form in @var{forms}.
2581    
2582    If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
2583    it only executes the @var{forms}, and setting @code{quit-flag} causes
2584    a normal quit.  However, if @code{inhibit-quit} is non-@code{nil} so
2585    that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
2586    triggers a special kind of local quit.  This ends the execution of
2587    @var{forms} and exits the @code{with-local-quit} form with
2588    @code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
2589    will happen as soon as that is allowed.  If @code{quit-flag} is
2590    already non-@code{nil} at the beginning of @var{forms}, the local quit
2591    happens immediately and they don't execute at all.
2592    
2593    This macro is mainly useful in functions that can be called from
2594    timers, @code{pre-command-hook}, @code{post-command-hook} and other
2595    places where @code{inhibit-quit} is normally bound to @code{t}.
2596    @end defmac
2597    
2598  @deffn Command keyboard-quit  @deffn Command keyboard-quit
2599  This function signals the @code{quit} condition with @code{(signal 'quit  This function signals the @code{quit} condition with @code{(signal 'quit
2600  nil)}.  This is the same thing that quitting does.  (See @code{signal}  nil)}.  This is the same thing that quitting does.  (See @code{signal}
# Line 2844  Disabling a command has no effect on cal Line 2895  Disabling a command has no effect on cal
2895  programs.  programs.
2896    
2897  @deffn Command enable-command command  @deffn Command enable-command command
2898  Allow @var{command} to be executed without special confirmation from now  Allow @var{command} (a symbol) to be executed without special
2899  on, and (if the user confirms) alter the user's init file (@pxref{Init  confirmation from now on, and alter the user's init file (@pxref{Init
2900  File}) so that this will apply to future sessions.  File}) so that this will apply to future sessions.
2901  @end deffn  @end deffn
2902    
2903  @deffn Command disable-command command  @deffn Command disable-command command
2904  Require special confirmation to execute @var{command} from now on, and  Require special confirmation to execute @var{command} from now on, and
2905  (if the user confirms) alter the user's init file so that this  alter the user's init file so that this will apply to future sessions.
 will apply to future sessions.  
2906  @end deffn  @end deffn
2907    
2908  @defvar disabled-command-hook  @defvar disabled-command-function
2909  When the user invokes a disabled command interactively, this normal hook  The value of this variable should be a function.  When the user
2910  is run instead of the disabled command.  The hook functions can use  invokes a disabled command interactively, this function is called
2911  @code{this-command-keys} to determine what the user typed to run the  instead of the disabled command.  It can use @code{this-command-keys}
2912  command, and thus find the command itself.  @xref{Hooks}.  to determine what the user typed to run the command, and thus find the
2913    command itself.
2914    
2915    The value may also be @code{nil}.  Then all commands work normally,
2916    even disabled ones.
2917    
2918  By default, @code{disabled-command-hook} contains a function that asks  By default, the value is a function that asks the user whether to
2919  the user whether to proceed.  proceed.
2920  @end defvar  @end defvar
2921    
2922  @node Command History  @node Command History
# Line 2918  representation of a keyboard macro is a Line 2972  representation of a keyboard macro is a
2972  events.  Don't confuse keyboard macros with Lisp macros  events.  Don't confuse keyboard macros with Lisp macros
2973  (@pxref{Macros}).  (@pxref{Macros}).
2974    
2975  @defun execute-kbd-macro kbdmacro &optional count  @defun execute-kbd-macro kbdmacro &optional count loopfunc
2976  This function executes @var{kbdmacro} as a sequence of events.  If  This function executes @var{kbdmacro} as a sequence of events.  If
2977  @var{kbdmacro} is a string or vector, then the events in it are executed  @var{kbdmacro} is a string or vector, then the events in it are executed
2978  exactly as if they had been input by the user.  The sequence is  exactly as if they had been input by the user.  The sequence is
# Line 2935  many times.  If @var{count} is omitted o Line 2989  many times.  If @var{count} is omitted o
2989  executed once.  If it is 0, @var{kbdmacro} is executed over and over until it  executed once.  If it is 0, @var{kbdmacro} is executed over and over until it
2990  encounters an error or a failing search.  encounters an error or a failing search.
2991    
2992    If @var{loopfunc} is non-@code{nil}, it is a function that is called,
2993    without arguments, prior to each iteration of the macro.  If
2994    @var{loopfunc} returns @code{nil}, then this stops execution of the macro.
2995    
2996  @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.  @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
2997  @end defun  @end defun
2998    
2999  @defvar executing-macro  @defvar executing-kbd-macro
3000  This variable contains the string or vector that defines the keyboard  This variable contains the string or vector that defines the keyboard
3001  macro that is currently executing.  It is @code{nil} if no macro is  macro that is currently executing.  It is @code{nil} if no macro is
3002  currently executing.  A command can test this variable so as to behave  currently executing.  A command can test this variable so as to behave
# Line 2947  yourself. Line 3005  yourself.
3005  @end defvar  @end defvar
3006    
3007  @defvar defining-kbd-macro  @defvar defining-kbd-macro
3008  This variable indicates whether a keyboard macro is being defined.  A  This variable is non-@code{nil} if and only if a keyboard macro is
3009  command can test this variable so as to behave differently while a macro  being defined.  A command can test this variable so as to behave
3010  is being defined.  The commands @code{start-kbd-macro} and  differently while a macro is being defined.  The commands
3011  @code{end-kbd-macro} set this variable---do not set it yourself.  @code{start-kbd-macro} and @code{end-kbd-macro} set this variable---do
3012    not set it yourself.
3013    
3014  The variable is always local to the current terminal and cannot be  The variable is always local to the current terminal and cannot be
3015  buffer-local.  @xref{Multiple Displays}.  buffer-local.  @xref{Multiple Displays}.

Legend:
Removed from v.1.39.2.2  
changed lines
  Added in v.1.39.2.3

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26