annotate man/lispref/commands.texi @ 5940:c608d4b0b75e cygwin64 tip

rescue lost branch from 64bit.backup
author Henry Thompson <ht@markup.co.uk>
date Thu, 16 Dec 2021 18:48:58 +0000
parents 9fae6227ede5
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1 @c -*-texinfo-*-
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2 @c This is part of the XEmacs Lisp Reference Manual.
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4 @c See the file lispref.texi for copying conditions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5 @setfilename ../../info/commands.info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6 @node Command Loop, Keymaps, Minibuffers, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7 @chapter Command Loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8 @cindex editor command loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9 @cindex command loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
10
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
11 When you run XEmacs, it enters the @dfn{editor command loop} almost
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
12 immediately. This loop reads events, executes their definitions,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
13 and displays the results. In this chapter, we describe how these things
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
14 are done, and the subroutines that allow Lisp programs to do them.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
15
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
16 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
17 * Command Overview:: How the command loop reads commands.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
18 * Defining Commands:: Specifying how a function should read arguments.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
19 * Interactive Call:: Calling a command, so that it will read arguments.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
20 * Command Loop Info:: Variables set by the command loop for you to examine.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
21 * Events:: What input looks like when you read it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
22 * Reading Input:: How to read input events from the keyboard or mouse.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
23 * Waiting:: Waiting for user input or elapsed time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
24 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
25 * Prefix Command Arguments:: How the commands to set prefix args work.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
26 * Recursive Editing:: Entering a recursive edit,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
27 and why you usually shouldn't.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
28 * Disabling Commands:: How the command loop handles disabled commands.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
29 * Command History:: How the command history is set up, and how accessed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
30 * Keyboard Macros:: How keyboard macros are implemented.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
31 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
32
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
33 @node Command Overview, Defining Commands, Command Loop, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
34 @section Command Loop Overview
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
35
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
36 The command loop in XEmacs is a standard event loop, reading events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
37 one at a time with @code{next-event} and handling them with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
38 @code{dispatch-event}. An event is typically a single user action, such
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
39 as a keypress, mouse movement, or menu selection; but they can also be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
40 notifications from the window system, informing XEmacs that (for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
41 example) part of its window was just uncovered and needs to be redrawn.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
42 @xref{Events}. Pending events are held in a first-in, first-out list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
43 called the @dfn{event queue}: events are read from the head of the list,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
44 and newly arriving events are added to the tail. In this way, events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
45 are always processed in the order in which they arrive.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
46
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
47 @code{dispatch-event} does most of the work of handling user actions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
48 The first thing it must do is put the events together into a key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
49 sequence, which is a sequence of events that translates into a command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
50 It does this by consulting the active keymaps, which specify what the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
51 valid key sequences are and how to translate them into commands.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
52 @xref{Key Lookup}, for information on how this is done. The result of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
53 the translation should be a keyboard macro or an interactively callable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
54 function. If the key is @kbd{M-x}, then it reads the name of another
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
55 command, which it then calls. This is done by the command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
56 @code{execute-extended-command} (@pxref{Interactive Call}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
57
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
58 To execute a command requires first reading the arguments for it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
59 This is done by calling @code{command-execute} (@pxref{Interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
60 Call}). For commands written in Lisp, the @code{interactive}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
61 specification says how to read the arguments. This may use the prefix
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
62 argument (@pxref{Prefix Command Arguments}) or may read with prompting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
63 in the minibuffer (@pxref{Minibuffers}). For example, the command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
64 @code{find-file} has an @code{interactive} specification which says to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
65 read a file name using the minibuffer. The command's function body does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
66 not use the minibuffer; if you call this command from Lisp code as a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
67 function, you must supply the file name string as an ordinary Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
68 function argument.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
69
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
70 If the command is a string or vector (i.e., a keyboard macro) then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
71 @code{execute-kbd-macro} is used to execute it. You can call this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
72 function yourself (@pxref{Keyboard Macros}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
73
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
74 To terminate the execution of a running command, type @kbd{C-g}. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
75 character causes @dfn{quitting} (@pxref{Quitting}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
76
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
77 @defvar pre-command-hook
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
78 The editor command loop runs this normal hook before each command. At
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
79 that time, @code{this-command} contains the command that is about to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
80 run, and @code{last-command} describes the previous command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
81 @xref{Hooks}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
82 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
83
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
84 @defvar post-command-hook
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
85 The editor command loop runs this normal hook after each command. (In
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
86 FSF Emacs, it is also run when the command loop is entered, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
87 reentered after an error or quit.) At that time,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
88 @code{this-command} describes the command that just ran, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
89 @code{last-command} describes the command before that. @xref{Hooks}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
90 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
91
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
92 Quitting is suppressed while running @code{pre-command-hook} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
93 @code{post-command-hook}. If an error happens while executing one of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
94 these hooks, it terminates execution of the hook, but that is all it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
95 does.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
96
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
97 @node Defining Commands, Interactive Call, Command Overview, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
98 @section Defining Commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
99 @cindex defining commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
100 @cindex commands, defining
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
101 @cindex functions, making them interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
102 @cindex interactive function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
103
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
104 A Lisp function becomes a command when its body contains, at top
4905
755ae5b97edb Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents: 4885
diff changeset
105 level, a form that calls the special operator @code{interactive}. This
755ae5b97edb Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents: 4885
diff changeset
106 operator does nothing when actually executed, but its presence serves as a
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
107 flag to indicate that interactive calling is permitted. Its argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
108 controls the reading of arguments for an interactive call.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
109
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
110 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
111 * Using Interactive:: General rules for @code{interactive}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
112 * Interactive Codes:: The standard letter-codes for reading arguments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
113 in various ways.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
114 * Interactive Examples:: Examples of how to read interactive arguments.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
115 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
116
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
117 @node Using Interactive, Interactive Codes, Defining Commands, Defining Commands
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
118 @subsection Using @code{interactive}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
119
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
120 This section describes how to write the @code{interactive} form that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
121 makes a Lisp function an interactively-callable command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
122
5361
62b9ef1ed4ac Change "special form" to "special operator" in the manuals, too
Aidan Kehoe <kehoea@parhasard.net>
parents: 4905
diff changeset
123 @deffn {Special Operator} interactive arg-descriptor
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
124 @cindex argument descriptors
4905
755ae5b97edb Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents: 4885
diff changeset
125 This special operator declares that the function in which it appears is a
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
126 command, and that it may therefore be called interactively (via
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
127 @kbd{M-x} or by entering a key sequence bound to it). The argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
128 @var{arg-descriptor} declares how to compute the arguments to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
129 command when the command is called interactively.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
130
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
131 A command may be called from Lisp programs like any other function, but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
132 then the caller supplies the arguments and @var{arg-descriptor} has no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
133 effect.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
134
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
135 The @code{interactive} form has its effect because the command loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
136 (actually, its subroutine @code{call-interactively}) scans through the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
137 function definition looking for it, before calling the function. Once
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
138 the function is called, all its body forms including the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
139 @code{interactive} form are executed, but at this time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
140 @code{interactive} simply returns @code{nil} without even evaluating its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
141 argument.
5361
62b9ef1ed4ac Change "special form" to "special operator" in the manuals, too
Aidan Kehoe <kehoea@parhasard.net>
parents: 4905
diff changeset
142 @end deffn
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
143
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
144 There are three possibilities for the argument @var{arg-descriptor}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
145
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
146 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
147 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
148 It may be omitted or @code{nil}; then the command is called with no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
149 arguments. This leads quickly to an error if the command requires one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
150 or more arguments.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
151
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
152 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
153 It may be a Lisp expression that is not a string; then it should be a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
154 form that is evaluated to get a list of arguments to pass to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
155 command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
156 @cindex argument evaluation form
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
157
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
158 If this expression reads keyboard input (this includes using the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
159 minibuffer), keep in mind that the integer value of point or the mark
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
160 before reading input may be incorrect after reading input. This is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
161 because the current buffer may be receiving subprocess output;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
162 if subprocess output arrives while the command is waiting for input,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
163 it could relocate point and the mark.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
164
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
165 Here's an example of what @emph{not} to do:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
166
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
167 @smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
168 (interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
169 (list (region-beginning) (region-end)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
170 (read-string "Foo: " nil 'my-history)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
171 @end smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
172
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
173 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
174 Here's how to avoid the problem, by examining point and the mark only
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
175 after reading the keyboard input:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
176
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
177 @smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
178 (interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
179 (let ((string (read-string "Foo: " nil 'my-history)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
180 (list (region-beginning) (region-end) string)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
181 @end smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
182
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
183 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
184 @cindex argument prompt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
185 It may be a string; then its contents should consist of a code character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
186 followed by a prompt (which some code characters use and some ignore).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
187 The prompt ends either with the end of the string or with a newline.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
188 Here is a simple example:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
189
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
190 @smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
191 (interactive "bFrobnicate buffer: ")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
192 @end smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
193
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
194 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
195 The code letter @samp{b} says to read the name of an existing buffer,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
196 with completion. The buffer name is the sole argument passed to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
197 command. The rest of the string is a prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
198
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
199 If there is a newline character in the string, it terminates the prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
200 If the string does not end there, then the rest of the string should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
201 contain another code character and prompt, specifying another argument.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
202 You can specify any number of arguments in this way.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
203
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
204 @c Emacs 19 feature
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
205 The prompt string can use @samp{%} to include previous argument values
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
206 (starting with the first argument) in the prompt. This is done using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
207 @code{format} (@pxref{Formatting Strings}). For example, here is how
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
208 you could read the name of an existing buffer followed by a new name to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
209 give to that buffer:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
210
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
211 @smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
212 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
213 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
214 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
215 @end smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
216
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
217 @cindex @samp{*} in interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
218 @cindex read-only buffers in interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
219 If the first character in the string is @samp{*}, then an error is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
220 signaled if the buffer is read-only.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
221
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
222 @cindex @samp{@@} in interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
223 @c Emacs 19 feature
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
224 If the first character in the string is @samp{@@}, and if the key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
225 sequence used to invoke the command includes any mouse events, then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
226 the window associated with the first of those events is selected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
227 before the command is run.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
228
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
229 @cindex @samp{_} in interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
230 @c XEmacs feature
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
231 If the first character in the string is @samp{_}, then this command will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
232 not cause the region to be deactivated when it completes; that is,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
233 @code{zmacs-region-stays} will be set to @code{t} when the command exits
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
234 successfully.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
235
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
236 You can use @samp{*}, @samp{@@}, and @samp{_} together; the order does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
237 not matter. Actual reading of arguments is controlled by the rest of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
238 the prompt string (starting with the first character that is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
239 @samp{*}, @samp{@@}, or @samp{_}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
240 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
241
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
242 @defun function-interactive function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
243 This function retrieves the interactive specification of @var{function},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
244 which may be any funcallable object. The specification will be returned
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
245 as the list of the symbol @code{interactive} and the specs. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
246 @var{function} is not interactive, @code{nil} will be returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
247 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
248
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
249 @node Interactive Codes, Interactive Examples, Using Interactive, Defining Commands
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
250 @subsection Code Characters for @code{interactive}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
251 @cindex interactive code description
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
252 @cindex description for interactive codes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
253 @cindex codes, interactive, description of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
254 @cindex characters for interactive codes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
255
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
256 The code character descriptions below contain a number of key words,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
257 defined here as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
258
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
259 @table @b
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
260 @item Completion
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
261 @cindex interactive completion
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
262 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
263 completion because the argument is read using @code{completing-read}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
264 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
265
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
266 @item Existing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
267 Require the name of an existing object. An invalid name is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
268 accepted; the commands to exit the minibuffer do not exit if the current
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
269 input is not valid.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
270
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
271 @item Default
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
272 @cindex default argument string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
273 A default value of some sort is used if the user enters no text in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
274 minibuffer. The default depends on the code character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
275
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
276 @item No I/O
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
277 This code letter computes an argument without reading any input.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
278 Therefore, it does not use a prompt string, and any prompt string you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
279 supply is ignored.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
280
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
281 Even though the code letter doesn't use a prompt string, you must follow
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
282 it with a newline if it is not the last code character in the string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
283
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
284 @item Prompt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
285 A prompt immediately follows the code character. The prompt ends either
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
286 with the end of the string or with a newline.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
287
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
288 @item Special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
289 This code character is meaningful only at the beginning of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
290 interactive string, and it does not look for a prompt or a newline.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
291 It is a single, isolated character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
292 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
293
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
294 @cindex reading interactive arguments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
295 Here are the code character descriptions for use with @code{interactive}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
296
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
297 @table @samp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
298 @item *
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
299 Signal an error if the current buffer is read-only. Special.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
300
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
301 @item @@
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
302 Select the window mentioned in the first mouse event in the key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
303 sequence that invoked this command. Special.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
304
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
305 @item _
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
306 Do not cause the region to be deactivated when this command completes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
307 Special.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
308
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
309 @item a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
310 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
311 Completion, Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
312
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
313 @item b
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
314 The name of an existing buffer. By default, uses the name of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
315 current buffer (@pxref{Buffers}). Existing, Completion, Default,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
316 Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
317
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
318 @item B
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
319 A buffer name. The buffer need not exist. By default, uses the name of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
320 a recently used buffer other than the current buffer. Completion,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
321 Default, Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
322
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
323 @item c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
324 A character. The cursor does not move into the echo area. Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
325
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
326 @item C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
327 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
328 Completion, Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
329
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
330 @item d
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
331 @cindex position argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
332 The position of point, as an integer (@pxref{Point}). No I/O.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
333
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
334 @item D
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
335 A directory name. The default is the current default directory of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
336 current buffer, @code{default-directory} (@pxref{System Environment}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
337 Existing, Completion, Default, Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
338
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
339 @item e
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
340 The last mouse-button or misc-user event in the key sequence that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
341 invoked the command. No I/O.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
342
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
343 You can use @samp{e} more than once in a single command's interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
344 specification. If the key sequence that invoked the command has @var{n}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
345 mouse-button or misc-user events, the @var{n}th @samp{e} provides the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
346 @var{n}th such event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
347
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
348 @item f
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
349 A file name of an existing file (@pxref{File Names}). The default
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
350 directory is @code{default-directory}. Existing, Completion, Default,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
351 Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
352
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
353 @item F
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
354 A file name. The file need not exist. Completion, Default, Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
355
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
356 @item k
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
357 A key sequence (@pxref{Keymap Terminology}). This keeps reading events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
358 until a command (or undefined command) is found in the current key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
359 maps. The key sequence argument is represented as a vector of events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
360 The cursor does not move into the echo area. Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
361
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
362 This kind of input is used by commands such as @code{describe-key} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
363 @code{global-set-key}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
364
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
365 @item K
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
366 A key sequence, whose definition you intend to change. This works like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
367 @samp{k}, except that it suppresses, for the last input event in the key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
368 sequence, the conversions that are normally used (when necessary) to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
369 convert an undefined key into a defined one.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
370
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
371 @item m
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
372 @cindex marker argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
373 The position of the mark, as an integer. No I/O.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
374
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
375 @item n
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
376 A number read with the minibuffer. If the input is not a number, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
377 user is asked to try again. The prefix argument, if any, is not used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
378 Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
379
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
380 @item N
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
381 @cindex raw prefix argument usage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
382 The raw prefix argument. If the prefix argument is @code{nil}, then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
383 read a number as with @kbd{n}. Requires a number. @xref{Prefix Command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
384 Arguments}. Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
385
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
386 @item p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
387 @cindex numeric prefix argument usage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
388 The numeric prefix argument. (Note that this @samp{p} is lower case.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
389 No I/O.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
390
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
391 @item P
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
392 The raw prefix argument. (Note that this @samp{P} is upper case.) No
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
393 I/O.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
394
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
395 @item r
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
396 @cindex region argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
397 Point and the mark, as two numeric arguments, smallest first. This is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
398 the only code letter that specifies two successive arguments rather than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
399 one. No I/O.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
400
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
401 @item s
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
402 Arbitrary text, read in the minibuffer and returned as a string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
403 (@pxref{Text from Minibuffer}). Terminate the input with either
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
404 @key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
405 these characters in the input.) Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
406
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
407 @item S
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
408 An interned symbol whose name is read in the minibuffer. Any whitespace
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
409 character terminates the input. (Use @kbd{C-q} to include whitespace in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
410 the string.) Other characters that normally terminate a symbol (e.g.,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
411 parentheses and brackets) do not do so here. Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
412
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
413 @item v
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
414 A variable declared to be a user option (i.e., satisfying the predicate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
415 @code{user-variable-p}). @xref{High-Level Completion}. Existing,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
416 Completion, Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
417
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
418 @item x
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
419 A Lisp object, specified with its read syntax, terminated with a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
420 @key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
421 Minibuffer}. Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
422
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
423 @item X
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
424 @cindex evaluated expression argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
425 A Lisp form is read as with @kbd{x}, but then evaluated so that its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
426 value becomes the argument for the command. Prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
427 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
428
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
429 @node Interactive Examples, , Interactive Codes, Defining Commands
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
430 @subsection Examples of Using @code{interactive}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
431 @cindex examples of using @code{interactive}
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
432 @cindex @code{interactive}, examples of using
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
433
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
434 Here are some examples of @code{interactive}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
435
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
436 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
437 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
438 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
439 (interactive) ; @r{just moves forward two words.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
440 (forward-word 2))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
441 @result{} foo1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
442 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
443
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
444 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
445 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
446 (interactive "p") ; @r{which is the numeric prefix.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
447 (forward-word (* 2 n)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
448 @result{} foo2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
449 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
450
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
451 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
452 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
453 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
454 (forward-word (* 2 n)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
455 @result{} foo3
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
456 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
457
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
458 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
459 (defun three-b (b1 b2 b3)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
460 "Select three existing buffers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
461 Put them into three windows, selecting the last one."
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
462 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
463 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
464 (delete-other-windows)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
465 (split-window (selected-window) 8)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
466 (switch-to-buffer b1)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
467 (other-window 1)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
468 (split-window (selected-window) 8)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
469 (switch-to-buffer b2)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
470 (other-window 1)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
471 (switch-to-buffer b3))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
472 @result{} three-b
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
473 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
474 (three-b "*scratch*" "declarations.texi" "*mail*")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
475 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
476 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
477 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
478
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
479 @node Interactive Call, Command Loop Info, Defining Commands, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
480 @section Interactive Call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
481 @cindex interactive call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
482
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
483 After the command loop has translated a key sequence into a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
484 definition, it invokes that definition using the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
485 @code{command-execute}. If the definition is a function that is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
486 command, @code{command-execute} calls @code{call-interactively}, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
487 reads the arguments and calls the command. You can also call these
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
488 functions yourself.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
489
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
490 @defun commandp function
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
491 Returns @code{t} if @var{function} is suitable for calling interactively;
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
492 that is, if @var{function} is a command. Otherwise, returns @code{nil}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
493
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
494 The interactively callable objects include strings and vectors (treated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
495 as keyboard macros), lambda expressions that contain a top-level call to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
496 @code{interactive}, compiled-function objects made from such lambda
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
497 expressions, autoload objects that are declared as interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
498 (non-@code{nil} fourth argument to @code{autoload}), and some of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
499 primitive functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
500
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
501 A symbol is @code{commandp} if its function definition is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
502 @code{commandp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
503
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
504 Keys and keymaps are not commands. Rather, they are used to look up
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
505 commands (@pxref{Keymaps}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
506
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
507 See @code{documentation} in @ref{Accessing Documentation}, for a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
508 realistic example of using @code{commandp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
509 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
510
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
511 @defun call-interactively command &optional record-flag keys
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
512 This function calls the interactively callable function @var{command},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
513 reading arguments according to its interactive calling specifications.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
514 An error is signaled if @var{command} is not a function or if it cannot
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
515 be called interactively (i.e., is not a command). Note that keyboard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
516 macros (strings and vectors) are not accepted, even though they are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
517 considered commands, because they are not functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
518
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
519 @c XEmacs feature?
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
520 If @var{record-flag} is the symbol @code{lambda}, the interactive
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
521 calling arguments for @var{command} are read and returned as a list,
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
522 but the function is not called on them.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
523
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
524 @cindex record command history
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
525 If @var{record-flag} is @code{t}, then this command and its arguments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
526 are unconditionally added to the list @code{command-history}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
527 Otherwise, the command is added only if it uses the minibuffer to read
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
528 an argument. @xref{Command History}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
529 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
530
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
531 @defun command-execute command &optional record-flag keys
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
532 @cindex keyboard macro execution
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
533 This function executes @var{command} as an editing command. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
534 argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
535 it must be an interactively callable function or a keyboard macro.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
536
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
537 A string or vector as @var{command} is executed with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
538 @code{execute-kbd-macro}. A function is passed to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
539 @code{call-interactively}, along with the optional @var{record-flag}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
540
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
541 A symbol is handled by using its function definition in its place. A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
542 symbol with an @code{autoload} definition counts as a command if it was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
543 declared to stand for an interactively callable function. Such a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
544 definition is handled by loading the specified library and then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
545 rechecking the definition of the symbol.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
546 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
547
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
548 @deffn Command execute-extended-command prefix-argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
549 @cindex read command name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
550 This function reads a command name from the minibuffer using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
551 @code{completing-read} (@pxref{Completion}). Then it uses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
552 @code{command-execute} to call the specified command. Whatever that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
553 command returns becomes the value of @code{execute-extended-command}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
554
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
555 @cindex execute with prefix argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
556 If the command asks for a prefix argument, it receives the value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
557 @var{prefix-argument}. If @code{execute-extended-command} is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
558 interactively, the current raw prefix argument is used for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
559 @var{prefix-argument}, and thus passed on to whatever command is run.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
560
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
561 @c !!! Should this be @kindex?
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
562 @cindex @kbd{M-x}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
563 @code{execute-extended-command} is the normal definition of @kbd{M-x},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
564 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
565 to take the prompt from the events used to invoke
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
566 @code{execute-extended-command}, but that is painful to implement.) A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
567 description of the value of the prefix argument, if any, also becomes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
568 part of the prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
569
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
570 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
571 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
572 (execute-extended-command 1)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
573 ---------- Buffer: Minibuffer ----------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
574 1 M-x forward-word RET
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
575 ---------- Buffer: Minibuffer ----------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
576 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
577 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
578 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
579 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
580
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
581 @defun interactive-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
582 This function returns @code{t} if the containing function (the one that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
583 called @code{interactive-p}) was called interactively, with the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
584 @code{call-interactively}. (It makes no difference whether
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
585 @code{call-interactively} was called from Lisp or directly from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
586 editor command loop.) If the containing function was called by Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
587 evaluation (or with @code{apply} or @code{funcall}), then it was not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
588 called interactively.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
589
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
590 The most common use of @code{interactive-p} is for deciding whether to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
591 print an informative message. As a special exception,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
592 @code{interactive-p} returns @code{nil} whenever a keyboard macro is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
593 being run. This is to suppress the informative messages and speed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
594 execution of the macro.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
595
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
596 For example:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
597
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
598 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
599 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
600 (defun foo ()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
601 (interactive)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
602 (and (interactive-p)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
603 (message "foo")))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
604 @result{} foo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
605 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
606
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
607 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
608 (defun bar ()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
609 (interactive)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
610 (setq foobar (list (foo) (interactive-p))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
611 @result{} bar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
612 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
613
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
614 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
615 ;; @r{Type @kbd{M-x foo}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
616 @print{} foo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
617 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
618
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
619 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
620 ;; @r{Type @kbd{M-x bar}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
621 ;; @r{This does not print anything.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
622 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
623
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
624 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
625 foobar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
626 @result{} (nil t)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
627 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
628 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
629 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
630
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
631 @node Command Loop Info, Events, Interactive Call, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
632 @section Information from the Command Loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
633
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
634 The editor command loop sets several Lisp variables to keep status
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
635 records for itself and for commands that are run.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
636
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
637 @defvar last-command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
638 This variable records the name of the previous command executed by the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
639 command loop (the one before the current command). Normally the value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
640 is a symbol with a function definition, but this is not guaranteed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
641
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
642 The value is copied from @code{this-command} when a command returns to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
643 the command loop, except when the command specifies a prefix argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
644 for the following command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
645 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
646
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
647 @defvar this-command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
648 @cindex current command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
649 This variable records the name of the command now being executed by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
650 the editor command loop. Like @code{last-command}, it is normally a symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
651 with a function definition.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
652
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
653 The command loop sets this variable just before running a command, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
654 copies its value into @code{last-command} when the command finishes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
655 (unless the command specifies a prefix argument for the following
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
656 command).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
657
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
658 @cindex kill command repetition
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
659 Some commands set this variable during their execution, as a flag for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
660 whatever command runs next. In particular, the functions for killing text
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
661 set @code{this-command} to @code{kill-region} so that any kill commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
662 immediately following will know to append the killed text to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
663 previous kill.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
664 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
665
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
666 If you do not want a particular command to be recognized as the previous
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
667 command in the case where it got an error, you must code that command to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
668 prevent this. One way is to set @code{this-command} to @code{t} at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
669 beginning of the command, and set @code{this-command} back to its proper
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
670 value at the end, like this:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
671
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
672 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
673 (defun foo (args@dots{})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
674 (interactive @dots{})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
675 (let ((old-this-command this-command))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
676 (setq this-command t)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
677 @r{@dots{}do the work@dots{}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
678 (setq this-command old-this-command)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
679 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
680
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
681 @defun this-command-keys
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
682 This function returns a vector containing the key and mouse events that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
683 invoked the present command, plus any previous commands that generated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
684 the prefix argument for this command. (Note: this is not the same as in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
685 FSF Emacs, which can return a string.) @xref{Events}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
686
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
687 This function copies the vector and the events; it is safe to keep and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
688 modify them.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
689
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
690 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
691 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
692 (this-command-keys)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
693 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
694 @result{} [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
695 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
696 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
697 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
698
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
699 @ignore Not in XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
700 @defvar last-nonmenu-event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
701 This variable holds the last input event read as part of a key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
702 sequence, not counting events resulting from mouse menus.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
703
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
704 One use of this variable is to figure out a good default location to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
705 pop up another menu.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
706 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
707 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
708
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
709 @defvar last-command-event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
710 This variable is set to the last input event that was read by the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
711 command loop as part of a command. The principal use of this variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
712 is in @code{self-insert-command}, which uses it to decide which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
713 character to insert.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
714
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
715 This variable is off limits: you may not set its value or modify the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
716 event that is its value, as it is destructively modified by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
717 @code{read-key-sequence}. If you want to keep a pointer to this value,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
718 you must use @code{copy-event}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
719
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
720 Note that this variable is an alias for @code{last-command-char} in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
721 FSF Emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
722
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
723 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
724 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
725 last-command-event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
726 ;; @r{Now type @kbd{C-u C-x C-e}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
727 @result{} #<keypress-event control-E>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
728 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
729 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
730 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
731
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
732 @defvar last-command-char
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
733
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
734 If the value of @code{last-command-event} is a keyboard event, then this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
735 is the nearest character equivalent to it (or @code{nil} if there is no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
736 character equivalent). @code{last-command-char} is the character that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
737 @code{self-insert-command} will insert in the buffer. Remember that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
738 there is @emph{not} a one-to-one mapping between keyboard events and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
739 XEmacs characters: many keyboard events have no corresponding character,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
740 and when the Mule feature is available, most characters can not be input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
741 on standard keyboards, except possibly with help from an input method.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
742 So writing code that examines this variable to determine what key has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
743 been typed is bad practice, unless you are certain that it will be one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
744 of a small set of characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
745
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
746 This variable exists for compatibility with Emacs version 18.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
747
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
748 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
749 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
750 last-command-char
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
751 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
752 @result{} ?\^E
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
753 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
754 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
755
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
756 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
757
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
758 @defvar current-mouse-event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
759 This variable holds the mouse-button event which invoked this command,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
760 or @code{nil}. This is what @code{(interactive "e")} returns.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
761 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
762
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
763 @defvar echo-keystrokes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
764 This variable determines how much time should elapse before command
4885
6772ce4d982b Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents: 2862
diff changeset
765 characters echo. Its value must be a float or a fixnum, which specifies the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
766 number of seconds to wait before echoing. If the user types a prefix
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
767 key (say @kbd{C-x}) and then delays this many seconds before continuing,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
768 the key @kbd{C-x} is echoed in the echo area. Any subsequent characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
769 in the same command will be echoed as well.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
770
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
771 If the value is zero, then command input is not echoed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
772 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
773
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
774 @node Events, Reading Input, Command Loop Info, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
775 @section Events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
776 @cindex events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
777 @cindex input events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
778
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
779 The XEmacs command loop reads a sequence of @dfn{events} that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
780 represent keyboard or mouse activity. Unlike in Emacs 18 and in FSF
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
781 Emacs, events are a primitive Lisp type that must be manipulated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
782 using their own accessor and settor primitives. This section describes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
783 the representation and meaning of input events in detail.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
784
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
785 A key sequence that starts with a mouse event is read using the keymaps
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
786 of the buffer in the window that the mouse was in, not the current
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
787 buffer. This does not imply that clicking in a window selects that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
788 window or its buffer---that is entirely under the control of the command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
789 binding of the key sequence.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
790
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
791 For information about how exactly the XEmacs command loop works,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
792 @xref{Reading Input}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
793
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
794 @defun eventp object
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
795 This function returns non-@code{nil} if @var{object} is an input event.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
796 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
797
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
798 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
799 * Event Types:: Events come in different types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
800 * Event Contents:: What the contents of each event type are.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
801 * Event Predicates:: Querying whether an event is of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
802 particular type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
803 * Accessing Mouse Event Positions::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
804 Determining where a mouse event occurred,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
805 and over what.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
806 * Accessing Other Event Info:: Accessing non-positional event info.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
807 * Working With Events:: Creating, copying, and destroying events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
808 * Converting Events:: Converting between events, keys, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
809 characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
810 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
811
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
812 @node Event Types, Event Contents, Events, Events
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
813 @subsection Event Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
814
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
815 Events represent keyboard or mouse activity or status changes of various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
816 sorts, such as process input being available or a timeout being triggered.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
817 The different event types are as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
818
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
819 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
820 @item key-press event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
821 A key was pressed. Note that modifier keys such as ``control'', ``shift'',
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
822 and ``alt'' do not generate events; instead, they are tracked internally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
823 by XEmacs, and non-modifier key presses generate events that specify both
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
824 the key pressed and the modifiers that were held down at the time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
825
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
826 @item button-press event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
827 @itemx button-release event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
828 A button was pressed or released. Along with the button that was pressed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
829 or released, button events specify the modifier keys that were held down
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
830 at the time and the position of the pointer at the time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
831
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
832 @item motion event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
833 The pointer was moved. Along with the position of the pointer, these events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
834 also specify the modifier keys that were held down at the time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
835
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
836 @item misc-user event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
837 A menu item was selected, the scrollbar was used, or a drag or a drop occurred.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
838
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
839 @item process event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
840 Input is available on a process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
841
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
842 @item timeout event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
843 A timeout has triggered.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
844
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
845 @item magic event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
846 Some window-system-specific action (such as a frame being resized or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
847 a portion of a frame needing to be redrawn) has occurred. The contents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
848 of this event are not accessible at the E-Lisp level, but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
849 @code{dispatch-event} knows what to do with an event of this type.
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
850
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
851 @item eval event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
852 This is a special kind of event specifying that a particular function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
853 needs to be called when this event is dispatched. An event of this type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
854 is sometimes placed in the event queue when a magic event is processed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
855 This kind of event should generally just be passed off to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
856 @code{dispatch-event}. @xref{Dispatching an Event}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
857 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
858
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
859 @node Event Contents, Event Predicates, Event Types, Events
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
860 @subsection Contents of the Different Types of Events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
861
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
862 Every event, no matter what type it is, contains a timestamp (which is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
863 typically an offset in milliseconds from when the X server was started)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
864 indicating when the event occurred. In addition, many events contain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
865 a @dfn{channel}, which specifies which frame the event occurred on,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
866 and/or a value indicating which modifier keys (shift, control, etc.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
867 were held down at the time of the event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
868
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
869 The contents of each event are as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
870
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
871 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
872 @item key-press event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
873 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
874 @item channel
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
875 @item timestamp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
876 @item key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
877 Which key was pressed. This is an integer (in the printing @sc{ascii}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
878 range: >32 and <127) or a symbol such as @code{left} or @code{right}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
879 Note that many physical keys are actually treated as two separate keys,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
880 depending on whether the shift key is pressed; for example, the ``a''
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
881 key is treated as either ``a'' or ``A'' depending on the state of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
882 shift key, and the ``1'' key is similarly treated as either ``1'' or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
883 ``!'' on most keyboards. In such cases, the shift key does not show up
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
884 in the modifier list. For other keys, such as @code{backspace}, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
885 shift key shows up as a regular modifier.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
886 @item modifiers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
887 Which modifier keys were pressed. As mentioned above, the shift key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
888 is not treated as a modifier for many keys and will not show up in this list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
889 in such cases.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
890 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
891
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
892 @item button-press event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
893 @itemx button-release event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
894 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
895 @item channel
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
896 @item timestamp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
897 @item button
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
898 What button went down or up. Buttons are numbered starting at 1.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
899 @item modifiers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
900 Which modifier keys were pressed. The special business mentioned above
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
901 for the shift key does @emph{not} apply to mouse events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
902 @item x
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
903 @itemx y
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
904 The position of the pointer (in pixels) at the time of the event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
905 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
906
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
907 @item pointer-motion event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
908 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
909 @item channel
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
910 @item timestamp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
911 @item x
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
912 @itemx y
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
913 The position of the pointer (in pixels) after it moved.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
914 @item modifiers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
915 Which modifier keys were pressed. The special business mentioned above
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
916 for the shift key does @emph{not} apply to mouse events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
917 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
918
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
919 @item misc-user event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
920 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
921 @item timestamp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
922 @item function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
923 The E-Lisp function to call for this event. This is normally either
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
924 @code{eval} or @code{call-interactively}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
925 @item object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
926 The object to pass to the function. This is normally the callback that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
927 was specified in the menu description.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
928 @item button
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
929 What button went down or up. Buttons are numbered starting at 1.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
930 @item modifiers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
931 Which modifier keys were pressed. The special business mentioned above
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
932 for the shift key does @emph{not} apply to mouse events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
933 @item x
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
934 @itemx y
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
935 The position of the pointer (in pixels) at the time of the event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
936 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
937
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
938 @item process_event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
939 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
940 @item timestamp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
941 @item process
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
942 The Emacs ``process'' object in question.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
943 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
944
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
945 @item timeout event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
946 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
947 @item timestamp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
948 @item function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
949 The E-Lisp function to call for this timeout. It is called with one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
950 argument, the event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
951 @item object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
952 Some Lisp object associated with this timeout, to make it easier to tell
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
953 them apart. The function and object for this event were specified when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
954 the timeout was set.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
955 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
956
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
957 @item magic event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
958 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
959 @item timestamp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
960 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
961 (The rest of the information in this event is not user-accessible.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
962
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
963 @item eval event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
964 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
965 @item timestamp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
966 @item function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
967 An E-Lisp function to call when this event is dispatched.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
968 @item object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
969 The object to pass to the function. The function and object are set
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
970 when the event is created.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
971 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
972 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
973
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
974 @defun event-type event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
975 Return the type of @var{event}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
976
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
977 This will be a symbol; one of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
978
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
979 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
980 @item key-press
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
981 A key was pressed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
982 @item button-press
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
983 A mouse button was pressed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
984 @item button-release
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
985 A mouse button was released.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
986 @item motion
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
987 The mouse moved.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
988 @item misc-user
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
989 Some other user action happened; typically, this is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
990 a menu selection, scrollbar action, or drag and drop action.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
991 @item process
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
992 Input is available from a subprocess.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
993 @item timeout
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
994 A timeout has expired.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
995 @item eval
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
996 This causes a specified action to occur when dispatched.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
997 @item magic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
998 Some window-system-specific event has occurred.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
999 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1000 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1001
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1002 @node Event Predicates, Accessing Mouse Event Positions, Event Contents, Events
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1003 @subsection Event Predicates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1004
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1005 The following predicates return whether an object is an event of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1006 particular type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1007
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1008 @defun key-press-event-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1009 This is true if @var{object} is a key-press event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1010 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1011
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1012 @defun button-event-p object
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1013 This is true if @var{object} is a mouse button-press or button-release
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1014 event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1015 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1016
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1017 @defun button-press-event-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1018 This is true if @var{object} is a mouse button-press event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1019 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1020
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1021 @defun button-release-event-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1022 This is true if @var{object} is a mouse button-release event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1023 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1024
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1025 @defun motion-event-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1026 This is true if @var{object} is a mouse motion event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1027 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1028
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1029 @defun mouse-event-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1030 This is true if @var{object} is a mouse button-press, button-release
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1031 or motion event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1032 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1033
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1034 @defun eval-event-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1035 This is true if @var{object} is an eval event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1036 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1037
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1038 @defun misc-user-event-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1039 This is true if @var{object} is a misc-user event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1040 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1041
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1042 @defun process-event-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1043 This is true if @var{object} is a process event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1044 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1045
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1046 @defun timeout-event-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1047 This is true if @var{object} is a timeout event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1048 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1049
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1050 @defun event-live-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1051 This is true if @var{object} is any event that has not been deallocated.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1052 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1053
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1054 @node Accessing Mouse Event Positions, Accessing Other Event Info, Event Predicates, Events
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1055 @subsection Accessing the Position of a Mouse Event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1056
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1057 Unlike other events, mouse events (i.e. motion, button-press,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1058 button-release, and drag or drop type misc-user events) occur in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1059 particular location on the screen. Many primitives are provided for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1060 determining exactly where the event occurred and what is under that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1061 location.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1062
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1063 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1064 * Frame-Level Event Position Info::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1065 * Window-Level Event Position Info::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1066 * Event Text Position Info::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1067 * Event Glyph Position Info::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1068 * Event Toolbar Position Info::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1069 * Other Event Position Info::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1070 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1071
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1072 @node Frame-Level Event Position Info, Window-Level Event Position Info, Accessing Mouse Event Positions, Accessing Mouse Event Positions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1073 @subsubsection Frame-Level Event Position Info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1074
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1075 The following functions return frame-level information about where
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1076 a mouse event occurred.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1077
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1078 @defun event-frame event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1079 This function returns the ``channel'' or frame that the given mouse
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1080 motion, button press, button release, or misc-user event occurred in.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1081 This will be @code{nil} for non-mouse events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1082 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1083
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1084 @defun event-x-pixel event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1085 This function returns the X position in pixels of the given mouse event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1086 The value returned is relative to the frame the event occurred in.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1087 This will signal an error if the event is not a mouse event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1088 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1089
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1090 @defun event-y-pixel event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1091 This function returns the Y position in pixels of the given mouse event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1092 The value returned is relative to the frame the event occurred in.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1093 This will signal an error if the event is not a mouse event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1094 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1095
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1096 @node Window-Level Event Position Info, Event Text Position Info, Frame-Level Event Position Info, Accessing Mouse Event Positions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1097 @subsubsection Window-Level Event Position Info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1098
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1099 The following functions return window-level information about where
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1100 a mouse event occurred.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1101
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1102 @defun event-window event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1103 Given a mouse motion, button press, button release, or misc-user event, compute and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1104 return the window on which that event occurred. This may be @code{nil}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1105 if the event occurred in the border or over a toolbar. The modeline is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1106 considered to be within the window it describes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1107 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1108
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1109 @defun event-buffer event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1110 Given a mouse motion, button press, button release, or misc-user event, compute and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1111 return the buffer of the window on which that event occurred. This may
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1112 be @code{nil} if the event occurred in the border or over a toolbar.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1113 The modeline is considered to be within the window it describes. This is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1114 equivalent to calling @code{event-window} and then calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1115 @code{window-buffer} on the result if it is a window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1116 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1117
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1118 @defun event-window-x-pixel event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1119 This function returns the X position in pixels of the given mouse event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1120 The value returned is relative to the window the event occurred in.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1121 This will signal an error if the event is not a mouse-motion, button-press,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1122 button-release, or misc-user event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1123 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1124
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1125 @defun event-window-y-pixel event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1126 This function returns the Y position in pixels of the given mouse event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1127 The value returned is relative to the window the event occurred in.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1128 This will signal an error if the event is not a mouse-motion, button-press,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1129 button-release, or misc-user event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1130 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1131
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1132 @node Event Text Position Info, Event Glyph Position Info, Window-Level Event Position Info, Accessing Mouse Event Positions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1133 @subsubsection Event Text Position Info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1134
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1135 The following functions return information about the text (including the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1136 modeline) that a mouse event occurred over or near.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1137
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1138 @defun event-over-text-area-p event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1139 Given a mouse-motion, button-press, button-release, or misc-user event, this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1140 function returns @code{t} if the event is over the text area of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1141 window. Otherwise, @code{nil} is returned. The modeline is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1142 considered to be part of the text area.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1143 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1144
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1145 @defun event-over-modeline-p event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1146 Given a mouse-motion, button-press, button-release, or misc-user event, this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1147 function returns @code{t} if the event is over the modeline of a window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1148 Otherwise, @code{nil} is returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1149 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1150
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1151 @defun event-x event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1152 This function returns the X position of the given mouse-motion,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1153 button-press, button-release, or misc-user event in characters. This is relative
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1154 to the window the event occurred over.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1155 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1156
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1157 @defun event-y event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1158 This function returns the Y position of the given mouse-motion,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1159 button-press, button-release, or misc-user event in characters. This is relative
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1160 to the window the event occurred over.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1161 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1162
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1163 @defun event-point event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1164 This function returns the character position of the given mouse-motion,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1165 button-press, button-release, or misc-user event. If the event did not occur over
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1166 a window, or did not occur over text, then this returns @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1167 Otherwise, it returns an index into the buffer visible in the event's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1168 window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1169 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1170
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1171 @defun event-closest-point event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1172 This function returns the character position of the given mouse-motion,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1173 button-press, button-release, or misc-user event. If the event did not occur over
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1174 a window or over text, it returns the closest point to the location of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1175 the event. If the Y pixel position overlaps a window and the X pixel
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1176 position is to the left of that window, the closest point is the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1177 beginning of the line containing the Y position. If the Y pixel
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1178 position overlaps a window and the X pixel position is to the right of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1179 that window, the closest point is the end of the line containing the Y
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1180 position. If the Y pixel position is above a window, 0 is returned. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1181 it is below a window, the value of @code{(window-end)} is returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1182 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1183
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1184 @node Event Glyph Position Info, Event Toolbar Position Info, Event Text Position Info, Accessing Mouse Event Positions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1185 @subsubsection Event Glyph Position Info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1186
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1187 The following functions return information about the glyph (if any) that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1188 a mouse event occurred over.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1189
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1190 @defun event-over-glyph-p event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1191 Given a mouse-motion, button-press, button-release, or misc-user event, this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1192 function returns @code{t} if the event is over a glyph. Otherwise,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1193 @code{nil} is returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1194 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1195
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1196 @defun event-glyph-extent event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1197 If the given mouse-motion, button-press, button-release, or misc-user event happened
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1198 on top of a glyph, this returns its extent; else @code{nil} is returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1199 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1200
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1201 @defun event-glyph-x-pixel event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1202 Given a mouse-motion, button-press, button-release, or misc-user event over a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1203 glyph, this function returns the X position of the pointer relative to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1204 the upper left of the glyph. If the event is not over a glyph, it returns
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1205 @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1206 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1207
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1208 @defun event-glyph-y-pixel event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1209 Given a mouse-motion, button-press, button-release, or misc-user event over a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1210 glyph, this function returns the Y position of the pointer relative to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1211 the upper left of the glyph. If the event is not over a glyph, it returns
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1212 @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1213 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1214
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1215 @node Event Toolbar Position Info, Other Event Position Info, Event Glyph Position Info, Accessing Mouse Event Positions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1216 @subsubsection Event Toolbar Position Info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1217
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1218 @defun event-over-toolbar-p event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1219 Given a mouse-motion, button-press, button-release, or misc-user event, this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1220 function returns @code{t} if the event is over a toolbar. Otherwise,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1221 @code{nil} is returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1222 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1223
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1224 @defun event-toolbar-button event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1225 If the given mouse-motion, button-press, button-release, or misc-user event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1226 happened on top of a toolbar button, this function returns the button.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1227 Otherwise, @code{nil} is returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1228 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1229
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1230 @node Other Event Position Info, , Event Toolbar Position Info, Accessing Mouse Event Positions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1231 @subsubsection Other Event Position Info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1232
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1233 @defun event-over-border-p event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1234 Given a mouse-motion, button-press, button-release, or misc-user event, this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1235 function returns @code{t} if the event is over an internal toolbar.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1236 Otherwise, @code{nil} is returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1237 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1238
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1239 @node Accessing Other Event Info, Working With Events, Accessing Mouse Event Positions, Events
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1240 @subsection Accessing the Other Contents of Events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1241
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1242 The following functions allow access to the contents of events other than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1243 the position info described in the previous section.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1244
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1245 @defun event-timestamp event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1246 This function returns the timestamp of the given event object.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1247 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1248
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1249 @defun event-device event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1250 This function returns the device that the given event occurred on.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1251 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1252
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1253 @defun event-key event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1254 This function returns the Keysym of the given key-press event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1255 This will be the @sc{ascii} code of a printing character, or a symbol.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1256 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1257
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1258 @defun event-button event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1259 This function returns the button-number of the given button-press or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1260 button-release event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1261 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1262
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1263 @defun event-modifiers event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1264 This function returns a list of symbols, the names of the modifier keys
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1265 which were down when the given mouse or keyboard event was produced.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1266 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1267
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1268 @defun event-modifier-bits event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1269 This function returns a number representing the modifier keys which were down
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1270 when the given mouse or keyboard event was produced.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1271 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1272
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1273 @defun event-function event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1274 This function returns the callback function of the given timeout, misc-user,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1275 or eval event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1276 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1277
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1278 @defun event-object event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1279 This function returns the callback function argument of the given timeout,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1280 misc-user, or eval event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1281 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1282
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1283 @defun event-process event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1284 This function returns the process of the given process event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1285 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1286
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1287 @node Working With Events, Converting Events, Accessing Other Event Info, Events
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1288 @subsection Working With Events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1289
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1290 XEmacs provides primitives for creating, copying, and destroying event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1291 objects. Many functions that return events take an event object as an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1292 argument and fill in the fields of this event; or they make accept
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1293 either an event object or @code{nil}, creating the event object first in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1294 the latter case.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1295
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1296 @defun make-event &optional type plist
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1297 This function creates a new event structure. If no arguments are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1298 specified, the created event will be empty. To specify the event type,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1299 use the @var{type} argument. The allowed types are @code{empty},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1300 @code{key-press}, @code{button-press}, @code{button-release},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1301 @code{motion}, or @code{misc-user}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1302
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1303 @var{plist} is a property list, the properties being compatible to those
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1304 returned by @code{event-properties}. For events other than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1305 @code{empty}, it is mandatory to specify certain properties. For
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1306 @code{empty} events, @var{plist} must be @code{nil}. The list is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1307 @dfn{canonicalized}, which means that if a property keyword is present
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1308 more than once, only the first instance is taken into account.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1309 Specifying an unknown or illegal property signals an error.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1310
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1311 The following properties are allowed:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1312
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1313 @table @b
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1314 @item @code{channel}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1315 The event channel. This is a frame or a console. For mouse events (of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1316 type @code{button-press}, @code{button-release} and @code{motion}), this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1317 must be a frame. For key-press events, it must be a console. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1318 channel is unspecified by @var{plist}, it will be set to the selected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1319 frame or selected console, as appropriate.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1320
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1321 @item @code{key}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1322 The event key. This is either a symbol or a character. It is allowed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1323 (and required) only for key-press events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1324
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1325 @item @code{button}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1326 The event button. This an integer, either 1, 2 or 3. It is allowed
4885
6772ce4d982b Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents: 2862
diff changeset
1327 for button-press, button-release and misc-user events.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1328
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1329 @item @code{modifiers}
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1330 The event modifiers. This is a list of modifier symbols. It is allowed
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1331 for key-press, button-press, button-release and motion events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1332
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1333 @item @code{x}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1334 The event X coordinate. This is an integer. It is relative to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1335 channel's root window, and is allowed for button-press, button-release
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1336 and motion events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1337
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1338 @item @code{y}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1339 The event Y coordinate. This is an integer. It is relative to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1340 channel's root window, and is allowed for button-press, button-release
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1341 and motion events. This means that, for instance, to access the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1342 toolbar, the @code{y} property will have to be negative.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1343
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1344 @item @code{timestamp}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1345 The event timestamp, a non-negative integer. Allowed for all types of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1346 events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1347 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1348
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1349 @emph{WARNING}: the event object returned by this function may be a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1350 reused one; see the function @code{deallocate-event}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1351
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1352 The events created by @code{make-event} can be used as non-interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1353 arguments to the functions with an @code{(interactive "e")}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1354 specification.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1355
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1356 Here are some basic examples of usage:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1357
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1358 @lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1359 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1360 ;; @r{Create an empty event.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1361 (make-event)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1362 @result{} #<empty-event>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1363 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1364
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1365 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1366 ;; @r{Try creating a key-press event.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1367 (make-event 'key-press)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1368 @error{} Undefined key for keypress event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1369 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1370
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1371 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1372 ;; @r{Creating a key-press event, try 2}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1373 (make-event 'key-press '(key home))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1374 @result{} #<keypress-event home>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1375 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1376
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1377 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1378 ;; @r{Create a key-press event of dubious fame.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1379 (make-event 'key-press '(key escape modifiers (meta alt control shift)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1380 @result{} #<keypress-event control-meta-alt-shift-escape>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1381 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1382
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1383 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1384 ;; @r{Create a M-button1 event at coordinates defined by variables}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1385 ;; @r{@var{x} and @var{y}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1386 (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1387 @result{} #<buttondown-event meta-button1>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1388 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1389
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1390 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1391 ;; @r{Create a similar button-release event.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1392 (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1393 @result{} #<buttonup-event meta-button1up>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1394 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1395
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1396 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1397 ;; @r{Create a mouse-motion event.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1398 (make-event 'motion '(x 20 y 30))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1399 @result{} #<motion-event 20, 30>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1400
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1401 (event-properties (make-event 'motion '(x 20 y 30)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1402 @result{} (channel #<x-frame "emacs" 0x8e2> x 20 y 30
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1403 modifiers nil timestamp 0)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1404 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1405 @end lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1406
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1407 In conjunction with @code{event-properties}, you can use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1408 @code{make-event} to create modified copies of existing events. For
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1409 instance, the following code will return an @code{equal} copy of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1410 @var{event}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1411
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1412 @lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1413 (make-event (event-type @var{event})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1414 (event-properties @var{event}))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1415 @end lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1416
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1417 Note, however, that you cannot use @code{make-event} as the generic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1418 replacement for @code{copy-event}, because it does not allow creating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1419 all of the event types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1420
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1421 To create a modified copy of an event, you can use the canonicalization
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1422 feature of @var{plist}. The following example creates a copy of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1423 @var{event}, but with @code{modifiers} reset to @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1424
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1425 @lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1426 (make-event (event-type @var{event})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1427 (append '(modifiers nil)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1428 (event-properties @var{event})))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1429 @end lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1430 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1431
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1432 @defun copy-event event1 &optional event2
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1433 This function makes a copy of the event object @var{event1}. If a
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1434 second event argument @var{event2} is given, @var{event1} is copied into
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1435 @var{event2} and @var{event2} is returned. If @var{event2} is not
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1436 supplied (or is @code{nil}) then a new event will be made, as with
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1437 @code{make-event}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1438 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1439
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1440 @defun deallocate-event event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1441 This function allows the given event structure to be reused. You
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1442 @strong{MUST NOT} use this event object after calling this function with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1443 it. You will lose. It is not necessary to call this function, as event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1444 objects are garbage-collected like all other objects; however, it may be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1445 more efficient to explicitly deallocate events when you are sure that
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1446 it is safe to do so.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1447 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1448
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1449 @node Converting Events, , Working With Events, Events
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1450 @subsection Converting Events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1451
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1452 XEmacs provides some auxiliary functions for converting between events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1453 and other ways of representing keys. These are useful when working with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1454 @sc{ascii} strings and with keymaps.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1455
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1456 @defun character-to-event key-description &optional event console use-console-meta-flag
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1457 This function converts a keystroke description to an event structure.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1458 @var{key-description} is the specification of a key stroke, and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1459 @var{event} is the event object to fill in. This function contains
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
1460 knowledge about what the codes ``mean''---for example, the number 9 is
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1461 converted to the character @key{Tab}, not the distinct character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1462 @key{Control-I}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1463
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1464 Note that @var{key-description} can be an integer, a character, a symbol
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1465 such as @code{clear} or a list such as @code{(control backspace)}.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1466
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1467 If optional arg @var{event} is non-@code{nil}, it is modified;
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1468 otherwise, a new event object is created. In both cases, the event is
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1469 returned.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1470
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1471 Optional third arg @var{console} is the console to store in the event,
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1472 and defaults to the selected console.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1473
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1474 If @var{key-description} is an integer or character, the high bit may be
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1475 interpreted as the meta key. (This is done for backward compatibility in
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1476 lots of places.) If @var{use-console-meta-flag} is @code{nil}, this
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1477 will always be the case. If @var{use-console-meta-flag} is
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1478 non-@code{nil}, the @code{meta} flag for @var{console} affects whether
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1479 the high bit is interpreted as a meta key. (See @code{set-input-mode}.)
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1480 If you don't want this silly meta interpretation done, you should pass
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1481 in a list containing the character.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1482
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1483 Beware that @code{character-to-event} and @code{event-to-character} are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1484 not strictly inverse functions, since events contain much more
2828
a25c824ed558 [xemacs-hg @ 2005-06-26 18:04:49 by aidan]
aidan
parents: 904
diff changeset
1485 information than the XEmacs internal character encoding can store.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1486 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1487
2862
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1488 @defun event-to-character event &optional allow-extra-modifiers allow-meta allow-no-ascii
2828
a25c824ed558 [xemacs-hg @ 2005-06-26 18:04:49 by aidan]
aidan
parents: 904
diff changeset
1489 This function returns the closest character approximation to
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1490 @var{event}. If the event isn't a keypress, this returns @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1491
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1492 If @var{allow-extra-modifiers} is non-@code{nil}, then this is lenient
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1493 in its translation; it will ignore modifier keys other than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1494 @key{control} and @key{meta}, and will ignore the @key{shift} modifier
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1495 on those characters which have no shifted @sc{ascii} equivalent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1496 (@key{Control-Shift-A} for example, will be mapped to the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1497 @sc{ascii} code as @key{Control-A}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1498
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1499 If @var{allow-meta} is non-@code{nil}, then the @key{Meta} modifier will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1500 be represented by turning on the high bit of the byte returned;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1501 otherwise, @code{nil} will be returned for events containing the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1502 @key{Meta} modifier.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1503
2828
a25c824ed558 [xemacs-hg @ 2005-06-26 18:04:49 by aidan]
aidan
parents: 904
diff changeset
1504 Specifying @var{allow-meta} will give ambiguous results---@key{M-x} and
a25c824ed558 [xemacs-hg @ 2005-06-26 18:04:49 by aidan]
aidan
parents: 904
diff changeset
1505 @key{oslash} will return the same thing, for example---so you should
a25c824ed558 [xemacs-hg @ 2005-06-26 18:04:49 by aidan]
aidan
parents: 904
diff changeset
1506 probably not use it.
2862
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1507
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1508 @var{allow-non-ascii} is ignored; in previous versions of XEmacs, it
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1509 controlled whether one particular type of mapping between X11 keysyms
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1510 and characters would take place. The intention was that this flag could
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1511 be clear and you could be sure that if you got a Latin-1 character with
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1512 the high bit set back, you could assume that the lower seven bits of the
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1513 character were the ASCII code of the character in question, and that the
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1514 Meta key was pressed at the same time. This didn't work in the general
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1515 case, however, because it left the other type of X11 keysym-to-character
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1516 mapping in place, ready to give you a Latin-1 character for a Latin-1
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1517 key. If you feel the need to use such a flag, sit back and think about
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1518 abstracting your code, and if you still feel the need, bear in mind that
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1519 it will be buggy in earlier versions of XEmacs.
b95fe16005fd [xemacs-hg @ 2005-07-17 20:08:40 by aidan]
aidan
parents: 2828
diff changeset
1520
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1521 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1522
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1523 @defun events-to-keys events &optional no-mice
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1524 Given a vector of event objects, this function returns a vector of key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1525 descriptors, or a string (if they all fit in the @sc{ascii} range).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1526 Optional arg @var{no-mice} means that button events are not allowed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1527 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1528
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1529 @node Reading Input, Waiting, Events, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1530 @section Reading Input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1531
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1532 The editor command loop reads keyboard input using the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1533 @code{next-event} and constructs key sequences out of the events using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1534 @code{dispatch-event}. Lisp programs can also use the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1535 @code{read-key-sequence}, which reads input a key sequence at a time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1536 See also @code{momentary-string-display} in @ref{Temporary Displays},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1537 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1538 functions and variables for controlling terminal input modes and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1539 debugging terminal input.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1540
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1541 For higher-level input facilities, see @ref{Minibuffers}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1542
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1543 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1544 * Key Sequence Input:: How to read one key sequence.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1545 * Reading One Event:: How to read just one event.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1546 * Dispatching an Event:: What to do with an event once it has been read.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1547 * Quoted Character Input:: Asking the user to specify a character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1548 * Peeking and Discarding:: How to reread or throw away input events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1549 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1550
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1551 @node Key Sequence Input, Reading One Event, Reading Input, Reading Input
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1552 @subsection Key Sequence Input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1553 @cindex key sequence input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1554
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1555 Lisp programs can read input a key sequence at a time by calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1556 @code{read-key-sequence}; for example, @code{describe-key} uses it to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1557 read the key to describe.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1558
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1559 @defun read-key-sequence prompt &optional continue-echo dont-downcase-last
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1560 @cindex key sequence
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1561 This function reads a sequence of keystrokes or mouse clicks and returns
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1562 it as a vector of event objects read. It keeps reading events until it
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1563 has accumulated a full key sequence; that is, enough to specify a
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1564 non-prefix command using the currently active keymaps.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1565
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1566 The vector and the event objects it contains are freshly created (and
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1567 so will not be side-effected by subsequent calls to this function).
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1568
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1569 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1570 typed while reading with this function works like any other character,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1571 and does not set @code{quit-flag}. @xref{Quitting}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1572
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1573 The argument @var{prompt} is either a string to be displayed in the echo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1574 area as a prompt, or @code{nil}, meaning not to display a prompt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1575
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1576 Second optional arg @var{continue-echo} non-@code{nil} means this key
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1577 echoes as a continuation of the previous key.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1578
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1579 Third optional arg @var{dont-downcase-last} non-@code{nil} means do not
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1580 convert the last event to lower case. (Normally any upper case event is
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1581 converted to lower case if the original event is undefined and the lower
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1582 case equivalent is defined.) This argument is provided mostly for
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1583 @var{fsf} compatibility; the equivalent effect can be achieved more
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1584 generally by binding @code{retry-undefined-key-binding-unshifted} to
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1585 @code{nil} around the call to @code{read-key-sequence}.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1586
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1587 @c XEmacs feature
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1588 If the user selects a menu item while we are prompting for a key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1589 sequence, the returned value will be a vector of a single menu-selection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1590 event (a misc-user event). An error will be signalled if you pass this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1591 value to @code{lookup-key} or a related function.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1592
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1593 In the example below, the prompt @samp{?} is displayed in the echo area,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1594 and the user types @kbd{C-x C-f}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1595
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1596 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1597 (read-key-sequence "?")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1598
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1599 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1600 ---------- Echo Area ----------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1601 ?@kbd{C-x C-f}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1602 ---------- Echo Area ----------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1603
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1604 @result{} [#<keypress-event control-X> #<keypress-event control-F>]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1605 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1606 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1607 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1608
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1609 @ignore @c Not in XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1610 @defvar num-input-keys
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1611 @c Emacs 19 feature
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1612 This variable's value is the number of key sequences processed so far in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1613 this XEmacs session. This includes key sequences read from the terminal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1614 and key sequences read from keyboard macros being executed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1615 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1616 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1617
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1618 @cindex upper case key sequence
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1619 @cindex downcasing in @code{lookup-key}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1620 If an input character is an upper-case letter and has no key binding,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1621 but its lower-case equivalent has one, then @code{read-key-sequence}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1622 converts the character to lower case. Note that @code{lookup-key} does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1623 not perform case conversion in this way.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1624
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1625 @node Reading One Event, Dispatching an Event, Key Sequence Input, Reading Input
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1626 @subsection Reading One Event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1627
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1628 The lowest level functions for command input are those which read a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1629 single event. These functions often make a distinction between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1630 @dfn{command events}, which are user actions (keystrokes and mouse
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1631 actions), and other events, which serve as communication between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1632 XEmacs and the window system.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1633
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1634 @defun next-event &optional event prompt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1635 This function reads and returns the next available event from the window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1636 system or terminal driver, waiting if necessary until an event is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1637 available. Pass this object to @code{dispatch-event} to handle it. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1638 an event object is supplied, it is filled in and returned; otherwise a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1639 new event object will be created.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1640
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1641 Events can come directly from the user, from a keyboard macro, or from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1642 @code{unread-command-events}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1643
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1644 In most cases, the function @code{next-command-event} is more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1645 appropriate.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1646 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1647
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1648 @defun next-command-event &optional event prompt
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1649 This function returns the next available ``user'' event from the window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1650 system or terminal driver. Pass this object to @code{dispatch-event} to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1651 handle it. If an event object is supplied, it is filled in and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1652 returned, otherwise a new event object will be created.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1653
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1654 The event returned will be a keyboard, mouse press, or mouse release
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1655 event. If there are non-command events available (mouse motion,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1656 sub-process output, etc) then these will be executed (with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1657 @code{dispatch-event}) and discarded. This function is provided as a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1658 convenience; it is equivalent to the Lisp code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1659
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1660 @lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1661 @group
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
1662 (while (progn
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
1663 (next-event event)
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
1664 (not (or (key-press-event-p event)
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
1665 (button-press-event-p event)
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
1666 (button-release-event-p event)
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
1667 (menu-event-p event))))
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
1668 (dispatch-event event))
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1669 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1670 @end lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1671
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1672 Here is what happens if you call @code{next-command-event} and then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1673 press the right-arrow function key:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1674
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1675 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1676 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1677 (next-command-event)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1678 @result{} #<keypress-event right>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1679 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1680 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1681 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1682
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1683 @defun read-char
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1684 This function reads and returns a character of command input. If a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1685 mouse click is detected, an error is signalled. The character typed is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1686 returned as an @sc{ascii} value. This function is retained for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1687 compatibility with Emacs 18, and is most likely the wrong thing for you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1688 to be using: consider using @code{next-command-event} instead.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1689 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1690
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1691 @defun enqueue-eval-event function object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1692 This function adds an eval event to the back of the queue. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1693 eval event will be the next event read after all pending events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1694 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1695
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1696 @node Dispatching an Event, Quoted Character Input, Reading One Event, Reading Input
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1697 @subsection Dispatching an Event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1698 @cindex dispatching an event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1699
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1700 @defun dispatch-event event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1701 Given an event object returned by @code{next-event}, this function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1702 executes it. This is the basic function that makes XEmacs respond to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1703 user input; it also deals with notifications from the window system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1704 (such as Expose events).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1705 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1706
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1707 @node Quoted Character Input, Peeking and Discarding, Dispatching an Event, Reading Input
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1708 @subsection Quoted Character Input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1709 @cindex quoted character input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1710
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1711 You can use the function @code{read-quoted-char} to ask the user to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1712 specify a character, and allow the user to specify a control or meta
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1713 character conveniently, either literally or as an octal character code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1714 The command @code{quoted-insert} uses this function.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1715
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1716 @defun read-quoted-char &optional prompt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1717 @cindex octal character input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1718 @cindex control characters, reading
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1719 @cindex nonprinting characters, reading
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1720 This function is like @code{read-char}, except that if the first
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1721 character read is an octal digit (0-7), it reads up to two more octal digits
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1722 (but stopping if a non-octal digit is found) and returns the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1723 character represented by those digits in octal.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1724
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1725 Quitting is suppressed when the first character is read, so that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1726 user can enter a @kbd{C-g}. @xref{Quitting}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1727
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1728 If @var{prompt} is supplied, it specifies a string for prompting the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1729 user. The prompt string is always displayed in the echo area, followed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1730 by a single @samp{-}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1731
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1732 In the following example, the user types in the octal number 177 (which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1733 is 127 in decimal).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1734
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1735 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1736 (read-quoted-char "What character")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1737
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1738 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1739 ---------- Echo Area ----------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1740 What character-@kbd{177}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1741 ---------- Echo Area ----------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1742
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1743 @result{} 127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1744 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1745 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1746 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1747
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1748 @need 2000
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1749 @node Peeking and Discarding, , Quoted Character Input, Reading Input
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1750 @subsection Miscellaneous Event Input Features
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1751
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1752 This section describes how to ``peek ahead'' at events without using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1753 them up, how to check for pending input, and how to discard pending
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1754 input.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1755
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1756 See also the variables @code{last-command-event} and @code{last-command-char}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1757 (@ref{Command Loop Info}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1758
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1759 @defvar unread-command-events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1760 @cindex next input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1761 @cindex peeking at input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1762 This variable holds a list of events waiting to be read as command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1763 input. The events are used in the order they appear in the list, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1764 removed one by one as they are used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1765
904
47c30044fc4e [xemacs-hg @ 2002-07-06 18:56:24 by adrian]
adrian
parents: 444
diff changeset
1766 The variable is needed because in some cases a function reads an event
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1767 and then decides not to use it. Storing the event in this variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1768 causes it to be processed normally, by the command loop or by the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1769 functions to read command input.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1770
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1771 @cindex prefix argument unreading
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1772 For example, the function that implements numeric prefix arguments reads
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1773 any number of digits. When it finds a non-digit event, it must unread
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1774 the event so that it can be read normally by the command loop.
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1775 Likewise, incremental search uses this feature to unread events with no
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1776 special meaning in a search, because these events should exit the search
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1777 and then execute normally.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1778
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1779 @ignore FSF Emacs stuff
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1780 The reliable and easy way to extract events from a key sequence so as to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1781 put them in @code{unread-command-events} is to use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1782 @code{listify-key-sequence} (@pxref{Strings of Events}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1783 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1784 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1785
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1786 @defvar unread-command-event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1787 This variable holds a single event to be read as command input.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1788
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1789 This variable is mostly obsolete now that you can use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1790 @code{unread-command-events} instead; it exists only to support programs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1791 written for versions of XEmacs prior to 19.12.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1792 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1793
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1794 @defun input-pending-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1795 @cindex waiting for command key input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1796 This function determines whether any command input is currently
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1797 available to be read. It returns immediately, with value @code{t} if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1798 there is available input, @code{nil} otherwise. On rare occasions it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1799 may return @code{t} when no input is available.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1800 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1801
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1802 @defvar last-input-event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1803 This variable is set to the last keyboard or mouse button event received.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1804
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1805 This variable is off limits: you may not set its value or modify the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1806 event that is its value, as it is destructively modified by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1807 @code{read-key-sequence}. If you want to keep a pointer to this value,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1808 you must use @code{copy-event}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1809
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1810 Note that this variable is an alias for @code{last-input-char} in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1811 FSF Emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1812
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1813 In the example below, a character is read (the character @kbd{1}). It
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1814 becomes the value of @code{last-input-event}, while @kbd{C-e} (from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1815 @kbd{C-x C-e} command used to evaluate this expression) remains the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1816 value of @code{last-command-event}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1817
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1818 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1819 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1820 (progn (print (next-command-event))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1821 (print last-command-event)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1822 last-input-event)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1823 @print{} #<keypress-event 1>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1824 @print{} #<keypress-event control-E>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1825 @result{} #<keypress-event 1>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1826
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1827 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1828 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1829 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1830
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1831 @defvar last-input-char
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1832 If the value of @code{last-input-event} is a keyboard event, then this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1833 is the nearest @sc{ascii} equivalent to it. Remember that there is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1834 @emph{not} a 1:1 mapping between keyboard events and @sc{ascii}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1835 characters: the set of keyboard events is much larger, so writing code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1836 that examines this variable to determine what key has been typed is bad
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1837 practice, unless you are certain that it will be one of a small set of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1838 characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1839
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1840 This function exists for compatibility with Emacs version 18.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1841 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1842
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1843 @defun discard-input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1844 @cindex flush input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1845 @cindex discard input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1846 @cindex terminate keyboard macro
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1847 This function discards the contents of the terminal input buffer and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1848 cancels any keyboard macro that might be in the process of definition.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1849 It returns @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1850
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1851 In the following example, the user may type a number of characters right
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1852 after starting the evaluation of the form. After the @code{sleep-for}
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1853 finishes sleeping, @code{discard-input} discards any characters typed
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1854 during the sleep.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1855
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1856 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1857 (progn (sleep-for 2)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1858 (discard-input))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1859 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1860 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1861 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1862
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1863 @node Waiting, Quitting, Reading Input, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1864 @section Waiting for Elapsed Time or Input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1865 @cindex pausing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1866 @cindex waiting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1867
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1868 The wait functions are designed to wait for a certain amount of time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1869 to pass or until there is input. For example, you may wish to pause in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1870 the middle of a computation to allow the user time to view the display.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1871 @code{sit-for} pauses and updates the screen, and returns immediately if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1872 input comes in, while @code{sleep-for} pauses without updating the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1873 screen.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1874
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1875 Note that in FSF Emacs, the commands @code{sit-for} and @code{sleep-for}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1876 take two arguments to specify the time (one integer and one float
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1877 value), instead of a single argument that can be either an integer or a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1878 float.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1879
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1880 @defun sit-for seconds &optional nodisplay
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1881 This function performs redisplay (provided there is no pending input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1882 from the user), then waits @var{seconds} seconds, or until input is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1883 available. The result is @code{t} if @code{sit-for} waited the full
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1884 time with no input arriving (see @code{input-pending-p} in @ref{Peeking
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1885 and Discarding}). Otherwise, the value is @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1886
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1887 The argument @var{seconds} need not be an integer. If it is a floating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1888 point number, @code{sit-for} waits for a fractional number of seconds.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1889
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1890 @cindex forcing redisplay
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1891 Redisplay is normally preempted if input arrives, and does not happen at
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1892 all if input is available before it starts. (You can force screen
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1893 updating in such a case by using @code{force-redisplay}. @xref{Refresh
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1894 Screen}.) If there is no input pending, you can force an update with no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1895 delay by using @code{(sit-for 0)}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1896
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1897 If @var{nodisplay} is non-@code{nil}, then @code{sit-for} does not
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1898 redisplay, but it still returns as soon as input is available (or when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1899 the timeout elapses).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1900
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1901 @ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1902 Iconifying or deiconifying a frame makes @code{sit-for} return, because
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1903 that generates an event. @xref{Misc Events}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1904 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1905
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1906 The usual purpose of @code{sit-for} is to give the user time to read
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1907 text that you display.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1908 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1909
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1910 @defun sleep-for seconds
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1911 This function simply pauses for @var{seconds} seconds without updating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1912 the display. This function pays no attention to available input. It
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1913 returns @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1914
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1915 The argument @var{seconds} need not be an integer. If it is a floating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1916 point number, @code{sleep-for} waits for a fractional number of seconds.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1917 @ignore FSF Emacs stuff
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1918 Some systems support only a whole number of seconds; on these systems,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1919 @var{seconds} is rounded down.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1920
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1921 The optional argument @var{millisec} specifies an additional waiting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1922 period measured in milliseconds. This adds to the period specified by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1923 @var{seconds}. If the system doesn't support waiting fractions of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1924 second, you get an error if you specify nonzero @var{millisec}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1925 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1926
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1927 Use @code{sleep-for} when you wish to guarantee a delay.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1928 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1929
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1930 @xref{Time of Day}, for functions to get the current time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1931
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
1932 @node Quitting, Prefix Command Arguments, Waiting, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1933 @section Quitting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1934 @cindex @kbd{C-g}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1935 @cindex quitting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1936
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1937 Typing @kbd{C-g} while a Lisp function is running causes XEmacs to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1938 @dfn{quit} whatever it is doing. This means that control returns to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1939 innermost active command loop.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1940
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1941 Typing @kbd{C-g} while the command loop is waiting for keyboard input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1942 does not cause a quit; it acts as an ordinary input character. In the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1943 simplest case, you cannot tell the difference, because @kbd{C-g}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1944 normally runs the command @code{keyboard-quit}, whose effect is to quit.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1945 However, when @kbd{C-g} follows a prefix key, the result is an undefined
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1946 key. The effect is to cancel the prefix key as well as any prefix
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1947 argument.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1948
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1949 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1950 of the minibuffer. This means, in effect, that it exits the minibuffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1951 and then quits. (Simply quitting would return to the command loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1952 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1953 directly when the command reader is reading input is so that its meaning
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1954 can be redefined in the minibuffer in this way. @kbd{C-g} following a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1955 prefix key is not redefined in the minibuffer, and it has its normal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1956 effect of canceling the prefix key and prefix argument. This too
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1957 would not be possible if @kbd{C-g} always quit directly.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1958
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1959 When @kbd{C-g} does directly quit, it does so by setting the variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1960 @code{quit-flag} to @code{t}. XEmacs checks this variable at appropriate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1961 times and quits if it is not @code{nil}. Setting @code{quit-flag}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1962 non-@code{nil} in any way thus causes a quit.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1963
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1964 At the level of C code, quitting cannot happen just anywhere; only at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1965 special places that check @code{quit-flag}. The reason for this is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1966 that quitting at other places might leave an inconsistency in XEmacs's
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1967 internal state. Because quitting is delayed until a safe place, quitting
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1968 cannot make XEmacs crash.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1969
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1970 Certain functions such as @code{read-key-sequence} or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1971 @code{read-quoted-char} prevent quitting entirely even though they wait
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1972 for input. Instead of quitting, @kbd{C-g} serves as the requested
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1973 input. In the case of @code{read-key-sequence}, this serves to bring
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1974 about the special behavior of @kbd{C-g} in the command loop. In the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1975 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1976 to quote a @kbd{C-g}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1977
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1978 You can prevent quitting for a portion of a Lisp function by binding
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1979 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1980 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1981 usual result of this---a quit---is prevented. Eventually,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1982 @code{inhibit-quit} will become @code{nil} again, such as when its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1983 binding is unwound at the end of a @code{let} form. At that time, if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1984 @code{quit-flag} is still non-@code{nil}, the requested quit happens
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1985 immediately. This behavior is ideal when you wish to make sure that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1986 quitting does not happen within a ``critical section'' of the program.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1987
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1988 @cindex @code{read-quoted-char} quitting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1989 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1990 handled in a special way that does not involve quitting. This is done
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1991 by reading the input with @code{inhibit-quit} bound to @code{t}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1992 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1993 becomes @code{nil} again. This excerpt from the definition of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1994 @code{read-quoted-char} shows how this is done; it also shows that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1995 normal quitting is permitted after the first character of input.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1996
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1997 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1998 (defun read-quoted-char (&optional prompt)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1999 "@dots{}@var{documentation}@dots{}"
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2000 (let ((count 0) (code 0) char)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2001 (while (< count 3)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2002 (let ((inhibit-quit (zerop count))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2003 (help-form nil))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2004 (and prompt (message "%s-" prompt))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2005 (setq char (read-char))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2006 (if inhibit-quit (setq quit-flag nil)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2007 @dots{})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2008 (logand 255 code)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2009 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2010
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2011 @defvar quit-flag
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2012 If this variable is non-@code{nil}, then XEmacs quits immediately, unless
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2013 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2014 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2015 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2016
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2017 @defvar inhibit-quit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2018 This variable determines whether XEmacs should quit when @code{quit-flag}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2019 is set to a value other than @code{nil}. If @code{inhibit-quit} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2020 non-@code{nil}, then @code{quit-flag} has no special effect.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2021 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2022
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2023 @deffn Command keyboard-quit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2024 This function signals the @code{quit} condition with @code{(signal 'quit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2025 nil)}. This is the same thing that quitting does. (See @code{signal}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2026 in @ref{Errors}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2027 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2028
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2029 You can specify a character other than @kbd{C-g} to use for quitting.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2030 See the function @code{set-input-mode} in @ref{Terminal Input}.
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2031
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
2032 @node Prefix Command Arguments, Recursive Editing, Quitting, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2033 @section Prefix Command Arguments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2034 @cindex prefix argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2035 @cindex raw prefix argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2036 @cindex numeric prefix argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2037
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2038 Most XEmacs commands can use a @dfn{prefix argument}, a number
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2039 specified before the command itself. (Don't confuse prefix arguments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2040 with prefix keys.) The prefix argument is at all times represented by a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2041 value, which may be @code{nil}, meaning there is currently no prefix
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2042 argument. Each command may use the prefix argument or ignore it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2043
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2044 There are two representations of the prefix argument: @dfn{raw} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2045 @dfn{numeric}. The editor command loop uses the raw representation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2046 internally, and so do the Lisp variables that store the information, but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2047 commands can request either representation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2048
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2049 Here are the possible values of a raw prefix argument:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2050
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2051 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2052 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2053 @code{nil}, meaning there is no prefix argument. Its numeric value is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2054 1, but numerous commands make a distinction between @code{nil} and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2055 integer 1.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2056
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2057 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2058 An integer, which stands for itself.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2059
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2060 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2061 A list of one element, which is an integer. This form of prefix
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2062 argument results from one or a succession of @kbd{C-u}'s with no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2063 digits. The numeric value is the integer in the list, but some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2064 commands make a distinction between such a list and an integer alone.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2065
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2066 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2067 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2068 typed, without following digits. The equivalent numeric value is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2069 @minus{}1, but some commands make a distinction between the integer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2070 @minus{}1 and the symbol @code{-}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2071 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2072
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2073 We illustrate these possibilities by calling the following function with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2074 various prefixes:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2075
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2076 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2077 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2078 (defun display-prefix (arg)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2079 "Display the value of the raw prefix arg."
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2080 (interactive "P")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2081 (message "%s" arg))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2082 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2083 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2084
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2085 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2086 Here are the results of calling @code{display-prefix} with various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2087 raw prefix arguments:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2088
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2089 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2090 M-x display-prefix @print{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2091
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2092 C-u M-x display-prefix @print{} (4)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2093
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2094 C-u C-u M-x display-prefix @print{} (16)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2095
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2096 C-u 3 M-x display-prefix @print{} 3
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2097
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2098 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2099
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2100 C-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2101
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2102 C-u - M-x display-prefix @print{} -
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2103
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2104 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2105
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2106 C-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2107
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2108 C-u - 7 M-x display-prefix @print{} -7
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2109
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2110 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2111
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2112 C-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2113 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2114
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2115 XEmacs uses two variables to store the prefix argument:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2116 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2117 @code{universal-argument} that set up prefix arguments for other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2118 commands store them in @code{prefix-arg}. In contrast,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2119 @code{current-prefix-arg} conveys the prefix argument to the current
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2120 command, so setting it has no effect on the prefix arguments for future
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2121 commands.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2122
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2123 Normally, commands specify which representation to use for the prefix
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2124 argument, either numeric or raw, in the @code{interactive} declaration.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2125 (@xref{Using Interactive}.) Alternatively, functions may look at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2126 value of the prefix argument directly in the variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2127 @code{current-prefix-arg}, but this is less clean.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2128
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2129 @defun prefix-numeric-value raw
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2130 This function returns the numeric meaning of a valid raw prefix argument
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2131 value, @var{raw}. The argument may be a symbol, a number, or a list.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2132 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2133 value @minus{}1 is returned; if it is a number, that number is returned;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2134 if it is a list, the @sc{car} of that list (which should be a number) is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2135 returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2136 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2137
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2138 @defvar current-prefix-arg
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2139 This variable holds the raw prefix argument for the @emph{current}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2140 command. Commands may examine it directly, but the usual way to access
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2141 it is with @code{(interactive "P")}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2142 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2143
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2144 @defvar prefix-arg
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2145 The value of this variable is the raw prefix argument for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2146 @emph{next} editing command. Commands that specify prefix arguments for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2147 the following command work by setting this variable.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2148 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2149
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2150 Do not call the functions @code{universal-argument},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2151 @code{digit-argument}, or @code{negative-argument} unless you intend to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2152 let the user enter the prefix argument for the @emph{next} command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2153
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2154 @deffn Command universal-argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2155 This command reads input and specifies a prefix argument for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2156 following command. Don't call this command yourself unless you know
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2157 what you are doing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2158 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2159
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2160 @deffn Command digit-argument arg
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2161 This command adds to the prefix argument for the following command. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2162 argument @var{arg} is the raw prefix argument as it was before this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2163 command; it is used to compute the updated prefix argument. Don't call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2164 this command yourself unless you know what you are doing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2165 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2166
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2167 @deffn Command negative-argument arg
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2168 This command adds to the numeric argument for the next command. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2169 argument @var{arg} is the raw prefix argument as it was before this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2170 command; its value is negated to form the new prefix argument. Don't
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2171 call this command yourself unless you know what you are doing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2172 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2173
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
2174 @node Recursive Editing, Disabling Commands, Prefix Command Arguments, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2175 @section Recursive Editing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2176 @cindex recursive command loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2177 @cindex recursive editing level
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2178 @cindex command loop, recursive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2179
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2180 The XEmacs command loop is entered automatically when XEmacs starts up.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2181 This top-level invocation of the command loop never exits; it keeps
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2182 running as long as XEmacs does. Lisp programs can also invoke the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2183 command loop. Since this makes more than one activation of the command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2184 loop, we call it @dfn{recursive editing}. A recursive editing level has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2185 the effect of suspending whatever command invoked it and permitting the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2186 user to do arbitrary editing before resuming that command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2187
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2188 The commands available during recursive editing are the same ones
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2189 available in the top-level editing loop and defined in the keymaps.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2190 Only a few special commands exit the recursive editing level; the others
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2191 return to the recursive editing level when they finish. (The special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2192 commands for exiting are always available, but they do nothing when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2193 recursive editing is not in progress.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2194
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2195 All command loops, including recursive ones, set up all-purpose error
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2196 handlers so that an error in a command run from the command loop will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2197 not exit the loop.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2198
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2199 @cindex minibuffer input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2200 Minibuffer input is a special kind of recursive editing. It has a few
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2201 special wrinkles, such as enabling display of the minibuffer and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2202 minibuffer window, but fewer than you might suppose. Certain keys
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2203 behave differently in the minibuffer, but that is only because of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2204 minibuffer's local map; if you switch windows, you get the usual XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2205 commands.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2206
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2207 @cindex @code{throw} example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2208 @kindex exit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2209 @cindex exit recursive editing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2210 @cindex aborting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2211 To invoke a recursive editing level, call the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2212 @code{recursive-edit}. This function contains the command loop; it also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2213 contains a call to @code{catch} with tag @code{exit}, which makes it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2214 possible to exit the recursive editing level by throwing to @code{exit}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2215 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2216 then @code{recursive-edit} returns normally to the function that called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2217 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2218 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2219 control returns to the command loop one level up. This is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2220 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2221
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2222 Most applications should not use recursive editing, except as part of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2223 using the minibuffer. Usually it is more convenient for the user if you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2224 change the major mode of the current buffer temporarily to a special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2225 major mode, which should have a command to go back to the previous mode.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2226 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2227 give the user different text to edit ``recursively'', create and select
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2228 a new buffer in a special mode. In this mode, define a command to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2229 complete the processing and go back to the previous buffer. (The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2230 @kbd{m} command in Rmail does this.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2231
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2232 Recursive edits are useful in debugging. You can insert a call to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2233 @code{debug} into a function definition as a sort of breakpoint, so that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2234 you can look around when the function gets there. @code{debug} invokes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2235 a recursive edit but also provides the other features of the debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2236
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2237 Recursive editing levels are also used when you type @kbd{C-r} in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2238 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2239
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2240 @deffn Command recursive-edit
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2241 @cindex suspend evaluation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2242 This function invokes the editor command loop. It is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2243 automatically by the initialization of XEmacs, to let the user begin
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2244 editing. When called from a Lisp program, it enters a recursive editing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2245 level.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2246
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2247 In the following example, the function @code{simple-rec} first
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2248 advances point one word, then enters a recursive edit, printing out a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2249 message in the echo area. The user can then do any editing desired, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2250 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2251
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2252 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2253 (defun simple-rec ()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2254 (forward-word 1)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2255 (message "Recursive edit in progress")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2256 (recursive-edit)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2257 (forward-word 1))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2258 @result{} simple-rec
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2259 (simple-rec)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2260 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2261 @end example
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2262 @end deffn
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2263
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2264 @deffn Command exit-recursive-edit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2265 This function exits from the innermost recursive edit (including
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2266 minibuffer input). Its definition is effectively @code{(throw 'exit
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2267 nil)}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2268 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2269
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2270 @deffn Command abort-recursive-edit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2271 This function aborts the command that requested the innermost recursive
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2272 edit (including minibuffer input), by signaling @code{quit}
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2273 after exiting the recursive edit. Its definition is effectively
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2274 @code{(throw 'exit t)}. @xref{Quitting}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2275 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2276
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2277 @deffn Command top-level
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2278 This function exits all recursive editing levels; it does not return a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2279 value, as it jumps completely out of any computation directly back to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2280 the main command loop.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2281 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2282
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2283 @defun recursion-depth
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2284 This function returns the current depth of recursive edits. When no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2285 recursive edit is active, it returns 0.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2286 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2287
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
2288 @node Disabling Commands, Command History, Recursive Editing, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2289 @section Disabling Commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2290 @cindex disabled command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2291
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2292 @dfn{Disabling a command} marks the command as requiring user
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2293 confirmation before it can be executed. Disabling is used for commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2294 which might be confusing to beginning users, to prevent them from using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2295 the commands by accident.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2296
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2297 @kindex disabled
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2298 The low-level mechanism for disabling a command is to put a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2299 non-@code{nil} @code{disabled} property on the Lisp symbol for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2300 command. These properties are normally set up by the user's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2301 @file{.emacs} file with Lisp expressions such as this:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2302
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2303 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2304 (put 'upcase-region 'disabled t)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2305 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2306
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2307 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2308 For a few commands, these properties are present by default and may be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2309 removed by the @file{.emacs} file.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2310
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2311 If the value of the @code{disabled} property is a string, the message
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2312 saying the command is disabled includes that string. For example:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2313
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2314 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2315 (put 'delete-region 'disabled
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2316 "Text deleted this way cannot be yanked back!\n")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2317 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2318
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2319 @xref{Disabling,,, xemacs, The XEmacs User's Manual}, for the details on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2320 what happens when a disabled command is invoked interactively.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2321 Disabling a command has no effect on calling it as a function from Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2322 programs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2323
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2324 @deffn Command enable-command command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2325 Allow @var{command} to be executed without special confirmation from now
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2326 on, and (if the user confirms) alter the user's @file{.emacs} file so
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2327 that this will apply to future sessions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2328 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2329
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2330 @deffn Command disable-command command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2331 Require special confirmation to execute @var{command} from now on, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2332 (if the user confirms) alter the user's @file{.emacs} file so that this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2333 will apply to future sessions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2334 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2335
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2336 @defvar disabled-command-hook
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2337 This normal hook is run instead of a disabled command, when the user
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2338 invokes the disabled command interactively. The hook functions can use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2339 @code{this-command-keys} to determine what the user typed to run the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2340 command, and thus find the command itself. @xref{Hooks}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2341
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2342 By default, @code{disabled-command-hook} contains a function that asks
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2343 the user whether to proceed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2344 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2345
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
2346 @node Command History, Keyboard Macros, Disabling Commands, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2347 @section Command History
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2348 @cindex command history
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2349 @cindex complex command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2350 @cindex history of commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2351
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2352 The command loop keeps a history of the complex commands that have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2353 been executed, to make it convenient to repeat these commands. A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2354 @dfn{complex command} is one for which the interactive argument reading
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2355 uses the minibuffer. This includes any @kbd{M-x} command, any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2356 @kbd{M-:} command, and any command whose @code{interactive}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2357 specification reads an argument from the minibuffer. Explicit use of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2358 the minibuffer during the execution of the command itself does not cause
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2359 the command to be considered complex.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2360
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2361 @defvar command-history
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2362 This variable's value is a list of recent complex commands, each
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2363 represented as a form to evaluate. It continues to accumulate all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2364 complex commands for the duration of the editing session, but all but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2365 the first (most recent) thirty elements are deleted when a garbage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2366 collection takes place (@pxref{Garbage Collection}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2367
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2368 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2369 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2370 command-history
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2371 @result{} ((switch-to-buffer "chistory.texi")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2372 (describe-key "^X^[")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2373 (visit-tags-table "~/emacs/src/")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2374 (find-tag "repeat-complex-command"))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2375 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2376 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2377 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2378
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2379 This history list is actually a special case of minibuffer history
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2380 (@pxref{Minibuffer History}), with one special twist: the elements are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2381 expressions rather than strings.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2382
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2383 There are a number of commands devoted to the editing and recall of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2384 previous commands. The commands @code{repeat-complex-command}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2385 @code{list-command-history} are described in the user manual
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2386 (@pxref{Repetition,,, xemacs, The XEmacs User's Manual}). Within the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2387 minibuffer, the history commands used are the same ones available in any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2388 minibuffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2389
5791
9fae6227ede5 Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents: 5361
diff changeset
2390 @node Keyboard Macros, , Command History, Command Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2391 @section Keyboard Macros
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2392 @cindex keyboard macros
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2393
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2394 A @dfn{keyboard macro} is a canned sequence of input events that can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2395 be considered a command and made the definition of a key. The Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2396 representation of a keyboard macro is a string or vector containing the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2397 events. Don't confuse keyboard macros with Lisp macros
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2398 (@pxref{Macros}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2399
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2400 @defun execute-kbd-macro macro &optional count
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2401 This function executes @var{macro} as a sequence of events. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2402 @var{macro} is a string or vector, then the events in it are executed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2403 exactly as if they had been input by the user. The sequence is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2404 @emph{not} expected to be a single key sequence; normally a keyboard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2405 macro definition consists of several key sequences concatenated.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2406
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2407 If @var{macro} is a symbol, then its function definition is used in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2408 place of @var{macro}. If that is another symbol, this process repeats.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2409 Eventually the result should be a string or vector. If the result is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2410 not a symbol, string, or vector, an error is signaled.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2411
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2412 The argument @var{count} is a repeat count; @var{macro} is executed that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2413 many times. If @var{count} is omitted or @code{nil}, @var{macro} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2414 executed once. If it is 0, @var{macro} is executed over and over until it
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2415 encounters an error or a failing search.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2416 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2417
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2418 @defvar executing-macro
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2419 This variable contains the string or vector that defines the keyboard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2420 macro that is currently executing. It is @code{nil} if no macro is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2421 currently executing. A command can test this variable to behave
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2422 differently when run from an executing macro. Do not set this variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2423 yourself.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2424 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2425
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2426 @defvar defining-kbd-macro
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2427 This variable indicates whether a keyboard macro is being defined. A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2428 command can test this variable to behave differently while a macro is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2429 being defined. The commands @code{start-kbd-macro} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2430 @code{end-kbd-macro} set this variable---do not set it yourself.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2431 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2432
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2433 @defvar last-kbd-macro
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2434 This variable is the definition of the most recently defined keyboard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2435 macro. Its value is a string or vector, or @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2436 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2437
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2438 @c Broke paragraph to prevent overfull hbox. --rjc 15mar92
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2439 The commands are described in the user's manual (@pxref{Keyboard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2440 Macros,,, xemacs, The XEmacs User's Manual}).