Changes between Version 2 and Version 3 of HemlockProgrammer/Miscellaneous

01/16/08 01:51:22 (9 years ago)



  • HemlockProgrammer/Miscellaneous

    v2 v3  
    77don't fit well anywhere else. 
    9 == 17.1. == 
    11 This section intentionally left blank to maintain numbering. 
    13 == 17.2. == 
    15 This section intentionally left blank to maintain numbering. 
     9== 18.1. Key-events ==#KeyEvents 
     11=== 18.1.1. Introduction === 
     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: 
     27#k"control-x meta-d" 
     33This is convenient for use within code and in init files containing 
     34bind-key calls. 
     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. 
     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 
     53=== 18.1.2. Interface === 
     55`define-keysym`         keysym preferred-name &rest other-names  [Function] 
     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. 
     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 
     69`define-keysym-code` keysym code [Function] 
     71Defines the window-system code for the key event which in Hemlock is 
     72represented by keysym. 
     74`define-mouse-keysym`   button keysym name shifted-bit event-key         [Function] 
     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. 
     81`name-keysym`   name     [Function] 
     83This function returns the keysym named name. If name is unknown, this 
     84returns nil. 
     88`keysym-names`          keysym   [Function] 
     90This function returns the list of all names for keysym. If keysym is 
     91undefined, this returns nil. 
     95`keysym-preferred-name`         keysym   [Function] 
     97This returns the preferred name for keysym, how it is typically 
     98printed. If keysym is undefined, this returns nil. 
     102`define-key-event-modifier`     long-name short-name     [Function] 
     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. 
     109The system defines the following default modifiers (first the long 
     110name, then the short name): 
     112 * "Hyper", "H" 
     113 * "Super", "S" 
     114 * "Meta", "M" 
     115 * "Control", "C" 
     116 * "Shift", "Shift" 
     117 * "Lock", "Lock" 
     120`*all-modifier-names*`                   [Variable] 
     122This variable holds all the defined modifier names. 
     126`make-key-event-bits`   &rest modifier-names     [Function] 
     128This function returns bits suitable for make-key-event from the 
     129supplied modifier-names. If any name is undefined, this signals an 
     134`key-event-modifier-mask`       modifier-name    [Function] 
     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. 
     142`key-event-bits-modifiers`      bits     [Function] 
     144This returns a list of key-event modifier names, one for each modifier 
     145set in bits. 
     149`make-key-event`        object bits      [Function] 
     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. 
     158`key-event-p`   object   [Function] 
     160This function returns whether object is a key-event. 
     164`key-event-bits`        key-event        [Function] 
     166This function returns the bits field of a key-event. 
     170`key-event-keysym`      key-event        [Function] 
     172This function returns the keysym field of a key-event. 
     176`char-key-event`        character        [Function] 
     178This function returns the key-event associated with character. You can 
     179associate a key-event with a character by setf-ing this form. 
     183`key-event-char`        key-event        [Function] 
     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. 
     194`key-event-bit-p`       key-event bit-name       [Function] 
     196This function returns whether key-event has the bit set named by 
     197bit-name. This signals an error if bit-name is undefined. 
     201`do-alpha-key-events`   (var kind &optional result) form         [Macro] 
     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 
     209`pretty-key-string`     key &optional stream long-names-p        [Function] 
     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. 
    17216[HemlockProgrammer Back to Table of Contents]