Changes between Version 2 and Version 3 of HemlockProgrammer/Miscellaneous


Ignore:
Timestamp:
01/16/08 01:51:22 (7 years ago)
Author:
gz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/Miscellaneous

    v2 v3  
    77don't fit well anywhere else. 
    88 
    9 == 17.1. == 
    10  
    11 This section intentionally left blank to maintain numbering. 
    12  
    13 == 17.2. == 
    14  
    15 This section intentionally left blank to maintain numbering. 
     9== 18.1. Key-events ==#KeyEvents 
     10 
     11=== 18.1.1. Introduction === 
     12 
     13The canonical representation of editor input is a key-event 
     14structure. Users can bind commands to keys (see section 1.3.1), which 
     15are non-empty sequences of key-events. A key-event consists of 
     16an identifying token known as a keysym and a field of bits 
     17representing modifiers. Users define keysyms by supplying names 
     18that reflect the legends on their keyboard's keys. 
     19Users define modifier names similarly, but the system chooses the 
     20bit and mask for recognizing the modifier. You can 
     21use keysym and modifier names to textually specify key-events and 
     22Hemlock keys in a #k syntax. The following are some examples: 
     23{{{ 
     24#k"C-u" 
     25#k"Control-u" 
     26#k"c-m-z" 
     27#k"control-x meta-d" 
     28#k"a" 
     29#k"A" 
     30#k"Linefeed" 
     31}}} 
     32 
     33This is convenient for use within code and in init files containing 
     34bind-key calls. 
     35 
     36The #k syntax is delimited by double quotes, but the system parses the 
     37contents rather than reading it as a Common Lisp string. Within the 
     38double quotes, spaces separate multiple key-events. A single key-event 
     39optionally starts with modifier names terminated by hyphens. Modifier 
     40names are alphabetic sequences of characters which the system uses 
     41case-insensitively. Following modifiers is a keysym name, which is 
     42case-insensitive if it consists of multiple characters, but if the 
     43name consists of only a single character, then it is case-sensitive. 
     44 
     45You can escape special characters --- hyphen, double quote, open angle 
     46bracket, close angle bracket, and space --- with a backslash, and you 
     47can specify a backslash by using two contiguously. You can use angle 
     48brackets to enclose a keysym name with many special characters in 
     49it. Between angle brackets appearing in a keysym name position, there 
     50are only two special characters, the closing angle bracket and 
     51backslash. 
     52 
     53=== 18.1.2. Interface === 
     54 
     55`define-keysym`         keysym preferred-name &rest other-names  [Function] 
     56 
     57This function establishes a mapping from preferred-name to keysym for 
     58purposes of #k syntax. Other-names also map to keysym, but the system 
     59uses preferred-name when printing key-events. The names are 
     60case-insensitive simple-strings; however, if the string contains a 
     61single character, then it is used case-sensitively. Redefining a 
     62keysym or re-using names has undefined effects. 
     63 
     64Keysym can be any object, but generally it is either an integer 
     65representing the window-system code for the event, or a keyword 
     66which allows the mapping of the keysym to its code to be defined 
     67separately. 
     68 
     69`define-keysym-code` keysym code [Function] 
     70 
     71Defines the window-system code for the key event which in Hemlock is 
     72represented by keysym. 
     73 
     74`define-mouse-keysym`   button keysym name shifted-bit event-key         [Function] 
     75 
     76This function defines keysym named name for key-events representing 
     77mouse click events. Shifted-bit is a defined modifier name that 
     78translate-mouse-key-event sets in the key-event it returns whenever 
     79the shift bit is set in an incoming event. 
     80 
     81`name-keysym`   name     [Function] 
     82 
     83This function returns the keysym named name. If name is unknown, this 
     84returns nil. 
     85 
     86 
     87 
     88`keysym-names`          keysym   [Function] 
     89 
     90This function returns the list of all names for keysym. If keysym is 
     91undefined, this returns nil. 
     92 
     93 
     94 
     95`keysym-preferred-name`         keysym   [Function] 
     96 
     97This returns the preferred name for keysym, how it is typically 
     98printed. If keysym is undefined, this returns nil. 
     99 
     100 
     101 
     102`define-key-event-modifier`     long-name short-name     [Function] 
     103 
     104This establishes long-name and short-name as modifier names for 
     105purposes of specifying key-events in #k syntax. The names are 
     106case-insensitive strings. If either name is already defined, 
     107this signals an error. 
     108 
     109The system defines the following default modifiers (first the long 
     110name, then the short name): 
     111 
     112 * "Hyper", "H" 
     113 * "Super", "S" 
     114 * "Meta", "M" 
     115 * "Control", "C" 
     116 * "Shift", "Shift" 
     117 * "Lock", "Lock" 
     118 
     119 
     120`*all-modifier-names*`                   [Variable] 
     121 
     122This variable holds all the defined modifier names. 
     123 
     124 
     125 
     126`make-key-event-bits`   &rest modifier-names     [Function] 
     127 
     128This function returns bits suitable for make-key-event from the 
     129supplied modifier-names. If any name is undefined, this signals an 
     130error. 
     131 
     132 
     133 
     134`key-event-modifier-mask`       modifier-name    [Function] 
     135 
     136This function returns a mask for modifier-name. This mask is suitable 
     137for use with key-event-bits. If modifier-name is undefined, this 
     138signals an error. 
     139 
     140 
     141 
     142`key-event-bits-modifiers`      bits     [Function] 
     143 
     144This returns a list of key-event modifier names, one for each modifier 
     145set in bits. 
     146 
     147 
     148 
     149`make-key-event`        object bits      [Function] 
     150 
     151This function returns a key-event described by object with 
     152bits. Object is one of keysym, string, or key-event. When object is a 
     153key-event, this uses key-event-keysym. You can form bits with 
     154make-key-event-bits or key-event-modifier-mask. 
     155 
     156 
     157 
     158`key-event-p`   object   [Function] 
     159 
     160This function returns whether object is a key-event. 
     161 
     162 
     163 
     164`key-event-bits`        key-event        [Function] 
     165 
     166This function returns the bits field of a key-event. 
     167 
     168 
     169 
     170`key-event-keysym`      key-event        [Function] 
     171 
     172This function returns the keysym field of a key-event. 
     173 
     174 
     175 
     176`char-key-event`        character        [Function] 
     177 
     178This function returns the key-event associated with character. You can 
     179associate a key-event with a character by setf-ing this form. 
     180 
     181 
     182 
     183`key-event-char`        key-event        [Function] 
     184 
     185This function returns the character associated with key-event. You can 
     186associate a character with a key-event by setf'ing this form. The 
     187system defaultly translates key-events in some implementation 
     188dependent way for text insertion; for example, under an ASCII system, 
     189the key-event #k"C-h", as well as #k"backspace" would map to the 
     190Common Lisp character that causes a backspace. 
     191 
     192 
     193 
     194`key-event-bit-p`       key-event bit-name       [Function] 
     195 
     196This function returns whether key-event has the bit set named by 
     197bit-name. This signals an error if bit-name is undefined. 
     198 
     199 
     200 
     201`do-alpha-key-events`   (var kind &optional result) form         [Macro] 
     202 
     203This macro evaluates each form with var bound to a key-event 
     204representing an alphabetic character. Kind is one of :lower, :upper, 
     205or :both, and this binds var to each key-event in order a-z A-Z. 
     206When :both is specified, this processes lowercase letters 
     207first. 
     208 
     209`pretty-key-string`     key &optional stream long-names-p        [Function] 
     210 
     211This returns a string representing key, a key-event or vector of key-events, in a 
     212user-expected fashion. Long-names-p indicates whether 
     213modifiers should be described by their long or short name. 
     214 
    16215 
    17216[HemlockProgrammer Back to Table of Contents]