Changes between Version 2 and Version 3 of HemlockProgrammer/Miscellaneous


Ignore:
Timestamp:
Jan 16, 2008, 1:51:22 AM (12 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]