Mercurial > emacs
comparison doc/lispref/commands.texi @ 98751:a0e705c1e7f7
(Using Interactive, Interactive Codes): Document `^'.
(Interactive Examples): Show an example of `^'.
(Key Sequence Input): Document this-command-keys-shift-translated.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Wed, 15 Oct 2008 16:47:35 +0000 |
parents | 6d85304f4f12 |
children | fa98223dc5ff |
comparison
equal
deleted
inserted
replaced
98750:3d5bcaefd8cf | 98751:a0e705c1e7f7 |
---|---|
184 @end group | 184 @end group |
185 @end smallexample | 185 @end smallexample |
186 | 186 |
187 @cindex @samp{*} in @code{interactive} | 187 @cindex @samp{*} in @code{interactive} |
188 @cindex read-only buffers in interactive | 188 @cindex read-only buffers in interactive |
189 If the first character in the string is @samp{*}, then an error is | 189 If @samp{*} appears at the beginning of the string, then an error is |
190 signaled if the buffer is read-only. | 190 signaled if the buffer is read-only. |
191 | 191 |
192 @cindex @samp{@@} in @code{interactive} | 192 @cindex @samp{@@} in @code{interactive} |
193 @c Emacs 19 feature | 193 @c Emacs 19 feature |
194 If the first character in the string is @samp{@@}, and if the key | 194 If @samp{@@} appears at the beginning of the string, and if the key |
195 sequence used to invoke the command includes any mouse events, then | 195 sequence used to invoke the command includes any mouse events, then |
196 the window associated with the first of those events is selected | 196 the window associated with the first of those events is selected |
197 before the command is run. | 197 before the command is run. |
198 | 198 |
199 You can use @samp{*} and @samp{@@} together; the order does not matter. | 199 @cindex @samp{^} in @code{interactive} |
200 Actual reading of arguments is controlled by the rest of the prompt | 200 @cindex shift-selection, and @code{interactive} spec |
201 string (starting with the first character that is not @samp{*} or | 201 If @samp{^} appears at the beginning of the string, and if the command |
202 @samp{@@}). | 202 was invoked through @dfn{shift-translation}, set the mark and activate |
203 the region temporarily, or extend an already active region, before the | |
204 command is run. If the command was invoked without shift-translation, | |
205 and the region is temporarily active, deactivate the region before the | |
206 command is run. Shift-translation is controlled on the user level by | |
207 @code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU | |
208 Emacs Manual}. | |
209 | |
210 You can use @samp{*}, @samp{@@}, and @code{^} together; the order does | |
211 not matter. Actual reading of arguments is controlled by the rest of | |
212 the prompt string (starting with the first character that is not | |
213 @samp{*}, @samp{@@}, or @samp{^}). | |
203 | 214 |
204 @item | 215 @item |
205 It may be a Lisp expression that is not a string; then it should be a | 216 It may be a Lisp expression that is not a string; then it should be a |
206 form that is evaluated to get a list of arguments to pass to the | 217 form that is evaluated to get a list of arguments to pass to the |
207 command. Usually this form will call various functions to read input | 218 command. Usually this form will call various functions to read input |
314 | 325 |
315 @item @@ | 326 @item @@ |
316 Select the window mentioned in the first mouse event in the key | 327 Select the window mentioned in the first mouse event in the key |
317 sequence that invoked this command. Special. | 328 sequence that invoked this command. Special. |
318 | 329 |
330 @item ^ | |
331 If the command was invoked through shift-translation, set the mark and | |
332 activate the region temporarily, or extend an already active region, | |
333 before the command is run. If the command was invoked without | |
334 shift-translation, and the region is temporarily active, deactivate | |
335 the region before the command is run. Special. | |
336 | |
319 @item a | 337 @item a |
320 A function name (i.e., a symbol satisfying @code{fboundp}). Existing, | 338 A function name (i.e., a symbol satisfying @code{fboundp}). Existing, |
321 Completion, Prompt. | 339 Completion, Prompt. |
322 | 340 |
323 @item b | 341 @item b |
490 @result{} foo1 | 508 @result{} foo1 |
491 @end group | 509 @end group |
492 | 510 |
493 @group | 511 @group |
494 (defun foo2 (n) ; @r{@code{foo2} takes one argument,} | 512 (defun foo2 (n) ; @r{@code{foo2} takes one argument,} |
495 (interactive "p") ; @r{which is the numeric prefix.} | 513 (interactive "^p") ; @r{which is the numeric prefix.} |
514 ; @r{under @code{shift-select-mode},} | |
515 ; @r{will activate or extend region.} | |
496 (forward-word (* 2 n))) | 516 (forward-word (* 2 n))) |
497 @result{} foo2 | 517 @result{} foo2 |
498 @end group | 518 @end group |
499 | 519 |
500 @group | 520 @group |
2212 @xref{Strings of Events}. | 2232 @xref{Strings of Events}. |
2213 @end defun | 2233 @end defun |
2214 | 2234 |
2215 @cindex upper case key sequence | 2235 @cindex upper case key sequence |
2216 @cindex downcasing in @code{lookup-key} | 2236 @cindex downcasing in @code{lookup-key} |
2237 @cindex shift-translation | |
2217 If an input character is upper-case (or has the shift modifier) and | 2238 If an input character is upper-case (or has the shift modifier) and |
2218 has no key binding, but its lower-case equivalent has one, then | 2239 has no key binding, but its lower-case equivalent has one, then |
2219 @code{read-key-sequence} converts the character to lower case. Note | 2240 @code{read-key-sequence} converts the character to lower case. Note |
2220 that @code{lookup-key} does not perform case conversion in this way. | 2241 that @code{lookup-key} does not perform case conversion in this way. |
2242 | |
2243 @vindex this-command-keys-shift-translated | |
2244 When reading input results in such a @dfn{shift-translation}, Emacs | |
2245 sets the variable @code{this-command-keys-shift-translated} to a | |
2246 non-nil value. Lisp programs can examine this variable if they need | |
2247 to modify their behavior when invoked by shift-translated keys. For | |
2248 example, the function @code{handle-shift-selection} examines the value | |
2249 of this variable to determine how to activate or deactivate the region | |
2250 (@pxref{The Mark, handle-shift-selection}). | |
2221 | 2251 |
2222 The function @code{read-key-sequence} also transforms some mouse events. | 2252 The function @code{read-key-sequence} also transforms some mouse events. |
2223 It converts unbound drag events into click events, and discards unbound | 2253 It converts unbound drag events into click events, and discards unbound |
2224 button-down events entirely. It also reshuffles focus events and | 2254 button-down events entirely. It also reshuffles focus events and |
2225 miscellaneous window events so that they never appear in a key sequence | 2255 miscellaneous window events so that they never appear in a key sequence |