[HemlockProgrammer Back to Table of Contents]
[[PageOutline]]

= 11. Logical Key-Events =

== 11.1. Introduction ==

Some primitives such as prompt-for-key (page 50) and commands such as
Emacs query replace read key-events directly from the keyboard instead
of using the command interpreter.  To encourage consistency between
these commands and to make them portable and easy to customize, there
is a mechanism for defininglogical key-events.  A logical key-event is
a keyword which stands for some set of key-events.  The system
globally interprets these key-events as indicators a particular
action.  For example, the :help logical key-event represents the set of
key-events that request help in a given Hemlock implementation. This
mapping is a many-to-many mapping, not one-to-one, so a given logical
key-event may have multiple corresponding actual key-events.  Also,
any key-event may represent different logical key-events.

== 11.2. Logical Key-Event Functions ==#LogicalKeyEventFunctions

`*logical-key-event-names*` [Variable]

This variable holds a string-table mapping all logical key-event names
to the keyword identifying the logical key-event.

`define-logical-key-event` string-name documentation [Function]

This function defines a new logical key-event with name string-name.
Logical key-event operations take logical key-events
arguments as a keyword whose name is string-name uppercased with
spaces replaced by hyphens.

Documentation describes the action indicated by the logical key-event.

`logical-key-event-key-events` keyword [Function]

This function returns the list of key-events representing the logical
key-event keyword.

`logical-key-event-name` keyword [Function][[BR]]
`logical-key-event-documentation` keyword [Function][[BR]]

These functions return the string name and documentation given
to define-logical-key-event for logical key-event keyword.

`logical-key-event-p` key-event keyword [Function]

This function returns t if key-event is the logical key-event
keyword. This is setf-able establishing or disestablishing key-events
as particular logical key-events. It is a error for keyword to be an
undefined logical key-event.

== 11.3. System Defined Logical Key-Events ==#SystemDefinedLogicalKeyEvents

There are many default logical key-events, some of which are used by
functions documented in this manual.  If a command wants to read a
single key-event command that fits one of these descriptions then the
key-event read should be compared to the corresponding logical
key-event instead of explicitly mentioning the particular key-event in
the code.  In many cases you can use the command-case (page 48) macro.
It makes logical key-events easy to use and takes care of prompting
and displaying help messages.

 * :abort Indicates the prompter should terminate its activity without performing any closing actions of convenience, for example.
 * :yes Indicates the prompter should take the action under consideration.
 * :no Indicates the prompter should NOT take the action under consideration.
 * :do-all Indicates the prompter should repeat the action under consideration as many times as possible.
 * :do-once Indicates the prompter should execute the action under consideration once and then exit.
 * :help Indicates the prompter should display some help information.
 * :confirm Indicates the prompter should take any input provided or use the default if the user entered nothing.
 * :quote Indicates the prompter should take the following key-event as itself without any sort of command interpretation.
 * :keep Indicates the prompter should preserve something.
 * :y Indicates a short positive response
 * :n Indicates a short negative response

Define a new logical key-event whenever:

 1. The key-event concerned represents a general class of actions, and
 several commands may want to take a similar action of this type.

 2. The exact key-event a command implementor chooses may generate
 violent taste disputes among users, and then the users can trivially
 change the command in their init files.

 3. You are using `command-case` which prevents implementors from
 specifying non-standard characters for dispatching in otherwise
 possibly portable code, and you can define and set the logical
 key-event in a site dependent file where you can mention
 implementation dependent characters.


[HemlockProgrammer Back to Table of Contents]