Mercurial > hg > xemacs-beta

comparison man/lispref/commands.texi @ 412:697ef44129c6 r21-2-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-14
author cvs
date Mon, 13 Aug 2007 11:20:41 +0200
parents 74fd4e045ea6
children
comparison
equal deleted inserted replaced
411:12e008d41344 412:697ef44129c6
872 @item key-press event 872 @item key-press event
873 @table @asis 873 @table @asis
874 @item channel 874 @item channel
875 @item timestamp 875 @item timestamp
876 @item key 876 @item key
877 Which key was pressed. This is an integer (in the printing @sc{ascii} 877 Which key was pressed. This is an integer (in the printing @sc{ASCII}
878 range: >32 and <127) or a symbol such as @code{left} or @code{right}. 878 range: >32 and <127) or a symbol such as @code{left} or @code{right}.
879 Note that many physical keys are actually treated as two separate keys, 879 Note that many physical keys are actually treated as two separate keys,
880 depending on whether the shift key is pressed; for example, the ``a'' 880 depending on whether the shift key is pressed; for example, the ``a''
881 key is treated as either ``a'' or ``A'' depending on the state of the 881 key is treated as either ``a'' or ``A'' depending on the state of the
882 shift key, and the ``1'' key is similarly treated as either ``1'' or 882 shift key, and the ``1'' key is similarly treated as either ``1'' or
1250 This function returns the device that the given event occurred on. 1250 This function returns the device that the given event occurred on.
1251 @end defun 1251 @end defun
1252 1252
1253 @defun event-key event 1253 @defun event-key event
1254 This function returns the Keysym of the given key-press event. 1254 This function returns the Keysym of the given key-press event.
1255 This will be the @sc{ascii} code of a printing character, or a symbol. 1255 This will be the @sc{ASCII} code of a printing character, or a symbol.
1256 @end defun 1256 @end defun
1257 1257
1258 @defun event-button event 1258 @defun event-button event
1259 This function returns the button-number of the given button-press or 1259 This function returns the button-number of the given button-press or
1260 button-release event. 1260 button-release event.
1448 @node Converting Events 1448 @node Converting Events
1449 @subsection Converting Events 1449 @subsection Converting Events
1450 1450
1451 XEmacs provides some auxiliary functions for converting between events 1451 XEmacs provides some auxiliary functions for converting between events
1452 and other ways of representing keys. These are useful when working with 1452 and other ways of representing keys. These are useful when working with
1453 @sc{ascii} strings and with keymaps. 1453 @sc{ASCII} strings and with keymaps.
1454 1454
1455 @defun character-to-event ch &optional event device 1455 @defun character-to-event ch &optional event device
1456 This function converts a numeric @sc{ascii} value to an event structure, 1456 This function converts a numeric @sc{ASCII} value to an event structure,
1457 replete with modifier bits. @var{ch} is the character to convert, and 1457 replete with modifier bits. @var{ch} is the character to convert, and
1458 @var{event} is the event object to fill in. This function contains 1458 @var{event} is the event object to fill in. This function contains
1459 knowledge about what the codes ``mean''---for example, the number 9 is 1459 knowledge about what the codes ``mean'' -- for example, the number 9 is
1460 converted to the character @key{Tab}, not the distinct character 1460 converted to the character @key{Tab}, not the distinct character
1461 @key{Control-I}. 1461 @key{Control-I}.
1462 1462
1463 Note that @var{ch} does not have to be a numeric value, but can be a 1463 Note that @var{ch} does not have to be a numeric value, but can be a
1464 symbol such as @code{clear} or a list such as @code{(control 1464 symbol such as @code{clear} or a list such as @code{(control
1472 value of @code{nil} means use the selected device but always treat the 1472 value of @code{nil} means use the selected device but always treat the
1473 high bit as meta. 1473 high bit as meta.
1474 1474
1475 Beware that @code{character-to-event} and @code{event-to-character} are 1475 Beware that @code{character-to-event} and @code{event-to-character} are
1476 not strictly inverse functions, since events contain much more 1476 not strictly inverse functions, since events contain much more
1477 information than the @sc{ascii} character set can encode. 1477 information than the @sc{ASCII} character set can encode.
1478 @end defun 1478 @end defun
1479 1479
1480 @defun event-to-character event &optional allow-extra-modifiers allow-meta allow-non-ascii 1480 @defun event-to-character event &optional allow-extra-modifiers allow-meta allow-non-ascii
1481 This function returns the closest @sc{ascii} approximation to 1481 This function returns the closest @sc{ASCII} approximation to
1482 @var{event}. If the event isn't a keypress, this returns @code{nil}. 1482 @var{event}. If the event isn't a keypress, this returns @code{nil}.
1483 1483
1484 If @var{allow-extra-modifiers} is non-@code{nil}, then this is lenient 1484 If @var{allow-extra-modifiers} is non-@code{nil}, then this is lenient
1485 in its translation; it will ignore modifier keys other than 1485 in its translation; it will ignore modifier keys other than
1486 @key{control} and @key{meta}, and will ignore the @key{shift} modifier 1486 @key{control} and @key{meta}, and will ignore the @key{shift} modifier
1487 on those characters which have no shifted @sc{ascii} equivalent 1487 on those characters which have no shifted @sc{ASCII} equivalent
1488 (@key{Control-Shift-A} for example, will be mapped to the same 1488 (@key{Control-Shift-A} for example, will be mapped to the same
1489 @sc{ascii} code as @key{Control-A}). 1489 @sc{ASCII} code as @key{Control-A}).
1490 1490
1491 If @var{allow-meta} is non-@code{nil}, then the @key{Meta} modifier will 1491 If @var{allow-meta} is non-@code{nil}, then the @key{Meta} modifier will
1492 be represented by turning on the high bit of the byte returned; 1492 be represented by turning on the high bit of the byte returned;
1493 otherwise, @code{nil} will be returned for events containing the 1493 otherwise, @code{nil} will be returned for events containing the
1494 @key{Meta} modifier. 1494 @key{Meta} modifier.
1495 1495
1496 If @var{allow-non-ascii} is non-@code{nil}, then characters which are 1496 If @var{allow-non-ascii} is non-@code{nil}, then characters which are
1497 present in the prevailing character set (@pxref{Keymaps, variable 1497 present in the prevailing character set (@pxref{Keymaps, variable
1498 @code{character-set-property}}) will be returned as their code in that 1498 @code{character-set-property}}) will be returned as their code in that
1499 character set, instead of the return value being restricted to 1499 character set, instead of the return value being restricted to
1500 @sc{ascii}. 1500 @sc{ASCII}.
1501 1501
1502 Note that specifying both @var{allow-meta} and @var{allow-non-ascii} is 1502 Note that specifying both @var{allow-meta} and @var{allow-non-ascii} is
1503 ambiguous, as both use the high bit; @key{M-x} and @key{oslash} will be 1503 ambiguous, as both use the high bit; @key{M-x} and @key{oslash} will be
1504 indistinguishable. 1504 indistinguishable.
1505 @end defun 1505 @end defun
1506 1506
1507 @defun events-to-keys events &optional no-mice 1507 @defun events-to-keys events &optional no-mice
1508 Given a vector of event objects, this function returns a vector of key 1508 Given a vector of event objects, this function returns a vector of key
1509 descriptors, or a string (if they all fit in the @sc{ascii} range). 1509 descriptors, or a string (if they all fit in the @sc{ASCII} range).
1510 Optional arg @var{no-mice} means that button events are not allowed. 1510 Optional arg @var{no-mice} means that button events are not allowed.
1511 @end defun 1511 @end defun
1512 1512
1513 @node Reading Input 1513 @node Reading Input
1514 @section Reading Input 1514 @section Reading Input
1630 @code{dispatch-event}) and discarded. This function is provided as a 1630 @code{dispatch-event}) and discarded. This function is provided as a
1631 convenience; it is equivalent to the Lisp code 1631 convenience; it is equivalent to the Lisp code
1632 1632
1633 @lisp 1633 @lisp
1634 @group 1634 @group
1635 (while (progn 1635 (while (progn
1636 (next-event event) 1636 (next-event event)
1637 (not (or (key-press-event-p event) 1637 (not (or (key-press-event-p event)
1638 (button-press-event-p event) 1638 (button-press-event-p event)
1639 (button-release-event-p event) 1639 (button-release-event-p event)
1640 (menu-event-p event)))) 1640 (menu-event-p event))))
1641 (dispatch-event event)) 1641 (dispatch-event event))
1642 @end group 1642 @end group
1643 @end lisp 1643 @end lisp
1644 1644
1645 Here is what happens if you call @code{next-command-event} and then 1645 Here is what happens if you call @code{next-command-event} and then
1646 press the right-arrow function key: 1646 press the right-arrow function key:
1654 @end defun 1654 @end defun
1655 1655
1656 @defun read-char 1656 @defun read-char
1657 This function reads and returns a character of command input. If a 1657 This function reads and returns a character of command input. If a
1658 mouse click is detected, an error is signalled. The character typed is 1658 mouse click is detected, an error is signalled. The character typed is
1659 returned as an @sc{ascii} value. This function is retained for 1659 returned as an @sc{ASCII} value. This function is retained for
1660 compatibility with Emacs 18, and is most likely the wrong thing for you 1660 compatibility with Emacs 18, and is most likely the wrong thing for you
1661 to be using: consider using @code{next-command-event} instead. 1661 to be using: consider using @code{next-command-event} instead.
1662 @end defun 1662 @end defun
1663 1663
1664 @defun enqueue-eval-event function object 1664 @defun enqueue-eval-event function object
1801 @end example 1801 @end example
1802 @end defvar 1802 @end defvar
1803 1803
1804 @defvar last-input-char 1804 @defvar last-input-char
1805 If the value of @code{last-input-event} is a keyboard event, then this 1805 If the value of @code{last-input-event} is a keyboard event, then this
1806 is the nearest @sc{ascii} equivalent to it. Remember that there is 1806 is the nearest @sc{ASCII} equivalent to it. Remember that there is
1807 @emph{not} a 1:1 mapping between keyboard events and @sc{ascii} 1807 @emph{not} a 1:1 mapping between keyboard events and @sc{ASCII}
1808 characters: the set of keyboard events is much larger, so writing code 1808 characters: the set of keyboard events is much larger, so writing code
1809 that examines this variable to determine what key has been typed is bad 1809 that examines this variable to determine what key has been typed is bad
1810 practice, unless you are certain that it will be one of a small set of 1810 practice, unless you are certain that it will be one of a small set of
1811 characters. 1811 characters.
1812 1812