Changes between Version 2 and Version 3 of HemlockProgrammer/Miscellaneous

Timestamp:

01/15/08 19:51:22 (5 years ago)

Author:

gz

Comment:

--

HemlockProgrammer/Miscellaneous

@@ -7 +7 @@
 don't fit well anywhere else.
 
-== 17.1. ==
-
-This section intentionally left blank to maintain numbering.
-
-== 17.2. ==
-
-This section intentionally left blank to maintain numbering.
+== 18.1. Key-events ==#KeyEvents
+
+=== 18.1.1. Introduction ===
+
+The canonical representation of editor input is a key-event
+structure. Users can bind commands to keys (see section 1.3.1), which
+are non-empty sequences of key-events. A key-event consists of
+an identifying token known as a keysym and a field of bits
+representing modifiers. Users define keysyms by supplying names
+that reflect the legends on their keyboard's keys.
+Users define modifier names similarly, but the system chooses the
+bit and mask for recognizing the modifier. You can
+use keysym and modifier names to textually specify key-events and
+Hemlock keys in a #k syntax. The following are some examples:
+{{{
+#k"C-u"
+#k"Control-u"
+#k"c-m-z"
+#k"control-x meta-d"
+#k"a"
+#k"A"
+#k"Linefeed"
+}}}
+
+This is convenient for use within code and in init files containing
+bind-key calls.
+
+The #k syntax is delimited by double quotes, but the system parses the
+contents rather than reading it as a Common Lisp string. Within the
+double quotes, spaces separate multiple key-events. A single key-event
+optionally starts with modifier names terminated by hyphens. Modifier
+names are alphabetic sequences of characters which the system uses
+case-insensitively. Following modifiers is a keysym name, which is
+case-insensitive if it consists of multiple characters, but if the
+name consists of only a single character, then it is case-sensitive.
+
+You can escape special characters --- hyphen, double quote, open angle
+bracket, close angle bracket, and space --- with a backslash, and you
+can specify a backslash by using two contiguously. You can use angle
+brackets to enclose a keysym name with many special characters in
+it. Between angle brackets appearing in a keysym name position, there
+are only two special characters, the closing angle bracket and
+backslash.
+
+=== 18.1.2. Interface ===
+
+`define-keysym`         keysym preferred-name &rest other-names  [Function]
+
+This function establishes a mapping from preferred-name to keysym for
+purposes of #k syntax. Other-names also map to keysym, but the system
+uses preferred-name when printing key-events. The names are
+case-insensitive simple-strings; however, if the string contains a
+single character, then it is used case-sensitively. Redefining a
+keysym or re-using names has undefined effects.
+
+Keysym can be any object, but generally it is either an integer
+representing the window-system code for the event, or a keyword
+which allows the mapping of the keysym to its code to be defined
+separately.
+
+`define-keysym-code` keysym code [Function]
+
+Defines the window-system code for the key event which in Hemlock is
+represented by keysym.
+
+`define-mouse-keysym`   button keysym name shifted-bit event-key         [Function]
+
+This function defines keysym named name for key-events representing
+mouse click events. Shifted-bit is a defined modifier name that
+translate-mouse-key-event sets in the key-event it returns whenever
+the shift bit is set in an incoming event.
+
+`name-keysym`   name     [Function]
+
+This function returns the keysym named name. If name is unknown, this
+returns nil.
+
+
+
+`keysym-names`          keysym   [Function]
+
+This function returns the list of all names for keysym. If keysym is
+undefined, this returns nil.
+
+
+
+`keysym-preferred-name`         keysym   [Function]
+
+This returns the preferred name for keysym, how it is typically
+printed. If keysym is undefined, this returns nil.
+
+
+
+`define-key-event-modifier`     long-name short-name     [Function]
+
+This establishes long-name and short-name as modifier names for
+purposes of specifying key-events in #k syntax. The names are
+case-insensitive strings. If either name is already defined,
+this signals an error.
+
+The system defines the following default modifiers (first the long
+name, then the short name):
+
+ * "Hyper", "H"
+ * "Super", "S"
+ * "Meta", "M"
+ * "Control", "C"
+ * "Shift", "Shift"
+ * "Lock", "Lock"
+
+
+`*all-modifier-names*`                   [Variable]
+
+This variable holds all the defined modifier names.
+
+
+
+`make-key-event-bits`   &rest modifier-names     [Function]
+
+This function returns bits suitable for make-key-event from the
+supplied modifier-names. If any name is undefined, this signals an
+error.
+
+
+
+`key-event-modifier-mask`       modifier-name    [Function]
+
+This function returns a mask for modifier-name. This mask is suitable
+for use with key-event-bits. If modifier-name is undefined, this
+signals an error.
+
+
+
+`key-event-bits-modifiers`      bits     [Function]
+
+This returns a list of key-event modifier names, one for each modifier
+set in bits.
+
+
+
+`make-key-event`        object bits      [Function]
+
+This function returns a key-event described by object with
+bits. Object is one of keysym, string, or key-event. When object is a
+key-event, this uses key-event-keysym. You can form bits with
+make-key-event-bits or key-event-modifier-mask.
+
+
+
+`key-event-p`   object   [Function]
+
+This function returns whether object is a key-event.
+
+
+
+`key-event-bits`        key-event        [Function]
+
+This function returns the bits field of a key-event.
+
+
+
+`key-event-keysym`      key-event        [Function]
+
+This function returns the keysym field of a key-event.
+
+
+
+`char-key-event`        character        [Function]
+
+This function returns the key-event associated with character. You can
+associate a key-event with a character by setf-ing this form.
+
+
+
+`key-event-char`        key-event        [Function]
+
+This function returns the character associated with key-event. You can
+associate a character with a key-event by setf'ing this form. The
+system defaultly translates key-events in some implementation
+dependent way for text insertion; for example, under an ASCII system,
+the key-event #k"C-h", as well as #k"backspace" would map to the
+Common Lisp character that causes a backspace.
+
+
+
+`key-event-bit-p`       key-event bit-name       [Function]
+
+This function returns whether key-event has the bit set named by
+bit-name. This signals an error if bit-name is undefined.
+
+
+
+`do-alpha-key-events`   (var kind &optional result) form         [Macro]
+
+This macro evaluates each form with var bound to a key-event
+representing an alphabetic character. Kind is one of :lower, :upper,
+or :both, and this binds var to each key-event in order a-z A-Z.
+When :both is specified, this processes lowercase letters
+first.
+
+`pretty-key-string`     key &optional stream long-names-p        [Function]
+
+This returns a string representing key, a key-event or vector of key-events, in a
+user-expected fashion. Long-names-p indicates whether
+modifiers should be described by their long or short name.
+
 
 [HemlockProgrammer Back to Table of Contents]