Changes between Version 2 and Version 3 of HemlockProgrammer/Miscellaneous

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