Mercurial > hg > xemacs-beta

comparison src/keymap.c @ 3086:c6ef6267f65c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2005-11-22 10:36:34 by stephent] Improve define-key docstring. <87oe4dhvvq.fsf@tleepslib.sk.tsukuba.ac.jp>
author stephent
date Tue, 22 Nov 2005 10:36:39 +0000
parents facf3239ba30
children 5694c986bd92
comparison
equal deleted inserted replaced
3085:d9ca850d40de 3086:c6ef6267f65c
1329 !qxestrcmp_ascii (name, "SPC") || 1329 !qxestrcmp_ascii (name, "SPC") ||
1330 !qxestrcmp_ascii (name, "BS"))) 1330 !qxestrcmp_ascii (name, "BS")))
1331 #endif /* unused */ 1331 #endif /* unused */
1332 ) 1332 )
1333 invalid_argument 1333 invalid_argument
1334 ("Invalid (FSF Emacs) key format (see doc of define-key)", 1334 ("Invalid (GNU Emacs) key format (see doc of define-key)",
1335 *keysym); 1335 *keysym);
1336 1336
1337 /* #### Ok, this is a bit more dubious - make people not lose if they 1337 /* #### Ok, this is a bit more dubious - make people not lose if they
1338 do things like (global-set-key 'RET 'something) because that would 1338 do things like (global-set-key 'RET 'something) because that would
1339 otherwise have the same problem as above. (Gag!) We silently 1339 otherwise have the same problem as above. (Gag!) We silently
1778 } 1778 }
1779 1779
1780 DEFUN ("define-key", Fdefine_key, 3, 3, 0, /* 1780 DEFUN ("define-key", Fdefine_key, 3, 3, 0, /*
1781 Define key sequence KEYS, in KEYMAP, as DEF. 1781 Define key sequence KEYS, in KEYMAP, as DEF.
1782 KEYMAP is a keymap object. 1782 KEYMAP is a keymap object.
1783 KEYS is the sequence of keystrokes to bind, described below. 1783 KEYS is the key sequence to bind, described below.
1784 DEF is anything that can be a key's definition: 1784 DEF is anything that can be a key's definition:
1785 nil (means key is undefined in this keymap); 1785 nil (means key is undefined in this keymap);
1786 a command (a Lisp function suitable for interactive calling); 1786 a command (a Lisp function suitable for interactive calling);
1787 a string or key sequence vector (treated as a keyboard macro); 1787 a string or key sequence vector (treated as a keyboard macro);
1788 a keymap (to define a prefix key); 1788 a keymap (to define a prefix key);
1791 or another symbol whose function definition is used, and so on. 1791 or another symbol whose function definition is used, and so on.
1792 a cons (STRING . DEFN), meaning that DEFN is the definition 1792 a cons (STRING . DEFN), meaning that DEFN is the definition
1793 (DEFN should be a valid definition in its own right); 1793 (DEFN should be a valid definition in its own right);
1794 or a cons (KEYMAP . CHAR), meaning use definition of CHAR in map KEYMAP. 1794 or a cons (KEYMAP . CHAR), meaning use definition of CHAR in map KEYMAP.
1795 1795
1796 Contrary to popular belief, the world is not ASCII. When running under a 1796 A `key sequence' is a vector of one or more keystrokes.
1797 window system, XEmacs can tell the difference between, for example, the 1797 A `keystroke' is a list containing a key and zero or more modifiers. The
1798 keystrokes control-h, control-shift-h, and backspace. You can, in fact, 1798 key must be the last element of the list.
1799 bind different commands to each of these. 1799 A `key' is a symbol corresponding to a key on the keyboard, or to a mouse
1800 1800 gesture. Mouse clicks are denoted by symbols prefixed with "button",
1801 A `key sequence' is a set of keystrokes. A `keystroke' is a keysym and some 1801 followed by a digit for which button, and optionally "up". Thus `button1'
1802 set of modifiers (such as control and meta). A `keysym' is what is printed 1802 means the down-stroke and `button1up' means the up-stroke when clicking
1803 on the keys on your keyboard. 1803 mouse button 1.
1804 1804 A `modifier' is a symbol naming a physical key which is only "noticed" by
1805 A keysym may be represented by a symbol, or (if and only if it is equivalent 1805 XEmacs when chorded with another key. The `shift' modifier is a special
1806 to a character with a code in the range 32 - 255) by a character or its 1806 case. You cannot use `(meta shift a)' to mean `(meta A)', since for
1807 equivalent code. The `A' key may be represented by the symbol `A', the 1807 characters that have ASCII equivalents, the state of the shift key is
1808 character `?A', or by the number 65. The `break' key may be represented 1808 implicit in the keysym (a vs. A). You also cannot say `(shift =)' to mean
1809 only by the symbol `break'. 1809 `+', as that correspondence varies from keyboard to keyboard. The shift
1810 1810 modifier can only be applied to keys that do not have a second keysym on the
1811 A keystroke may be represented by a list: the last element of the list 1811 same key, such as `backspace' and `tab'. A mouse click may be combined with
1812 is the key (a symbol, character, or number, as above) and the 1812 modifiers to create a compound "keystroke".
1813 preceding elements are the symbolic names of modifier keys (control, 1813
1814 meta, super, hyper, alt, and shift). Thus, the sequence control-b is 1814 The keys, mouse gestures, and modifiers that are available depend on your
1815 represented by the forms `(control b)', `(control ?b)', and `(control 1815 console and its driver. At a minimum the ASCII graphic characters will be
1816 98)'. A keystroke may also be represented by an event object, as 1816 available as keys, and shift, control, and meta as modifiers.
1817 returned by the `next-command-event' and `read-key-sequence' 1817
1818 functions. 1818 To find out programmatically what a key is bound to, use `key-binding' to
1819 1819 check all applicable keymaps, or `lookup-key' to check a specific keymap.
1820 Note that in this context, the keystroke `control-b' is *not* represented 1820 The documentation for `key-binding' also contains a description of which
1821 by the number 2 (the ASCII code for ^B) or the character `?\^B'. See below. 1821 keymaps are applicable in various situations. `where-is-internal' does
1822 1822 the opposite of `key-binding', i.e. searches keymaps for the keys that
1823 The `shift' modifier is somewhat of a special case. You should not (and 1823 map to a particular binding.
1824 cannot) use `(meta shift a)' to mean `(meta A)', since for characters that 1824
1825 have ASCII equivalents, the state of the shift key is implicit in the 1825 If you are confused about why a particular key sequence is generating a
1826 keysym (a vs. A). You also cannot say `(shift =)' to mean `+', as that 1826 particular binding, and looking through the keymaps doesn't help, setting
1827 sort of thing varies from keyboard to keyboard. The shift modifier is for 1827 the variable `debug-emacs-events' may help. If not, try checking
1828 use only with characters that do not have a second keysym on the same key, 1828 what's in `function-key-map' and `key-translation-map'.
1829 such as `backspace' and `tab'. 1829
1830 1830 When running under a window system, typically the repertoire of keys is
1831 A key sequence is a vector of keystrokes. As a degenerate case, elements 1831 vastly expanded. XEmacs does its best to use the names defined on each
1832 of this vector may also be keysyms if they have no modifiers. That is, 1832 platform. Also, when running under a window system, XEmacs can tell the
1833 the `A' keystroke is represented by all of these forms: 1833 difference between the keystrokes control-h, control-shift-h, and backspace.
1834 If the symbols differ, you can bind different actions to each. For mouse
1835 clicks, different commands may be bound to the up and down strokes, though
1836 that is probably not what you want, so be careful.
1837
1838 Variant representations:
1839
1840 Besides the canonical representation as a vector of lists of symbols,
1841 `define-key' also accepts a number of abbreviations, aliases, and variants
1842 for convenience, compatibility, and internal use.
1843
1844 A keystroke may be represented by a key; this is treated as though it were a
1845 list containing that key as the only element. A keystroke may also be
1846 represented by an event object, as returned by the `next-command-event' and
1847 `read-key-sequence' functions. A key sequence may be represented by a
1848 single keystroke; this is treated as a vector containing that keystroke as
1849 its only element.
1850
1851 A key may be represented by a character or its equivalent integer code,
1852 if and only if it is equivalent to a character with a code in the range
1853 32 - 255.
1854
1855 For backward compatibility, a key sequence may also be represented by a
1856 string. In this case, it represents the key sequence(s) that would
1857 produce that sequence of ASCII characters in a purely ASCII world. An
1858 alternative string representation is keyboard macro notation, which can
1859 be translated to the canonical representation with `kbd'.
1860
1861 Examples:
1862
1863 The key sequence `A' (which invokes `self-insert-command') is represented
1864 by all of these forms:
1834 A ?A 65 (A) (?A) (65) 1865 A ?A 65 (A) (?A) (65)
1835 [A] [?A] [65] [(A)] [(?A)] [(65)] 1866 [A] [?A] [65] [(A)] [(?A)] [(65)]
1836 1867
1837 the `control-a' keystroke is represented by these forms: 1868 The key sequence `control-a' is represented by these forms:
1838 (control A) (control ?A) (control 65) 1869 (control A) (control ?A) (control 65)
1839 [(control A)] [(control ?A)] [(control 65)] 1870 [(control A)] [(control ?A)] [(control 65)]
1840 the key sequence `control-c control-a' is represented by these forms: 1871
1872 The key sequence `control-c control-a' is represented by these forms:
1841 [(control c) (control a)] [(control ?c) (control ?a)] 1873 [(control c) (control a)] [(control ?c) (control ?a)]
1842 [(control 99) (control 65)] etc. 1874 [(control 99) (control 65)] etc.
1843 1875
1876 The keystroke `control-b' *may not* be represented by the number 2 (the
1877 ASCII code for ^B) or the character `?\^B'.
1878
1879 The `break' key may be represented only by the symbol `break'.
1880
1844 Mouse button clicks work just like keypresses: (control button1) means 1881 Mouse button clicks work just like keypresses: (control button1) means
1845 pressing the left mouse button while holding down the control key. 1882 pressing the left mouse button while holding down the control key.
1846 \[(control c) (shift button3)] means control-c, hold shift, click right. 1883
1847 1884 A string containing the ASCII backspace character, "\\^H", would represent
1848 Commands may be bound to the mouse-button up-stroke rather than the down- 1885 two key sequences: `(control h)' and `backspace'. Binding a
1849 stroke as well. `button1' means the down-stroke, and `button1up' means the
1850 up-stroke. Different commands may be bound to the up and down strokes,
1851 though that is probably not what you want, so be careful.
1852
1853 For backward compatibility, a key sequence may also be represented by a
1854 string. In this case, it represents the key sequence(s) that would
1855 produce that sequence of ASCII characters in a purely ASCII world. For
1856 example, a string containing the ASCII backspace character, "\\^H", would
1857 represent two key sequences: `(control h)' and `backspace'. Binding a
1858 command to this will actually bind both of those key sequences. Likewise 1886 command to this will actually bind both of those key sequences. Likewise
1859 for the following pairs: 1887 for the following pairs:
1860 1888
1861 control h backspace 1889 control h backspace
1862 control i tab 1890 control i tab
1871 1899
1872 it is possible to redefine only one of those sequences like so: 1900 it is possible to redefine only one of those sequences like so:
1873 1901
1874 (define-key global-map [(control x) (control i)] \'command-2) 1902 (define-key global-map [(control x) (control i)] \'command-2)
1875 (define-key global-map [(control x) tab] \'command-3) 1903 (define-key global-map [(control x) tab] \'command-3)
1876
1877 Of course, all of this applies only when running under a window system. If
1878 you're talking to XEmacs through a TTY connection, you don't get any of
1879 these features.
1880
1881 To find out programmatically what a key is bound to, use `key-binding' to
1882 check all applicable keymaps, or `lookup-key' to check a specific keymap.
1883 The documentation for `key-binding' also contains a description of which
1884 keymaps are applicable in various situations. `where-is-internal' does
1885 the opposite of `key-binding', i.e. searches keymaps for the keys that
1886 map to a particular binding.
1887
1888 If you are confused about why a particular key sequence is generating a
1889 particular binding, and looking through the keymaps doesn't help, setting
1890 the variable `debug-emacs-events' may help. If not, try checking
1891 what's in `function-key-map' and `key-translation-map'.
1892 */ 1904 */
1893 (keymap, keys, def)) 1905 (keymap, keys, def))
1894 { 1906 {
1895 /* This function can GC */ 1907 /* This function can GC */
1896 int idx; 1908 int idx;
1923 When the user defines a key which, in a strictly ASCII world, would be 1935 When the user defines a key which, in a strictly ASCII world, would be
1924 produced by two different keys (^J and linefeed, or ^H and backspace, 1936 produced by two different keys (^J and linefeed, or ^H and backspace,
1925 for example) then the binding will be made for both keysyms. 1937 for example) then the binding will be made for both keysyms.
1926 1938
1927 This is done if the user binds a command to a string, as in 1939 This is done if the user binds a command to a string, as in
1928 (define-key map "\^H" 'something), but not when using one of the new 1940 (define-key map "\^H" 'something), but not when using the canonical
1929 syntaxes, like (define-key map '(control h) 'something). 1941 syntax (define-key map '(control h) 'something).
1930 */ 1942 */
1931 ascii_hack = (STRINGP (keys)); 1943 ascii_hack = (STRINGP (keys));
1932 1944
1933 keymap = get_keymap (keymap, 1, 1); 1945 keymap = get_keymap (keymap, 1, 1);
1934 1946