wiki:HemlockProgrammer/LogicalKeyEvents

Version 1 (modified by rme, 7 years ago) (diff)

--

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

*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, a simple-string. 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]

logical-key-event-documentation keyword [Function]

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

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.

  • :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.
  • :exit Indicates the prompter should terminate its activity in a normal fashion.
  • :abort Indicates the prompter should terminate its activity without performing any closing actions of convenience, for example.
  • :keep Indicates the prompter should preserve something.
  • :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.
  • :recursive-edit Indicates the prompter should enter a recursive edit in the current context.
  • :cancel Indicates the prompter should cancel the effect of a previous key-event input.
  • :forward-search Indicates the prompter should search forward in the current context.
  • :backward-search Indicates the prompter should search backward in the current context.

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.
  1. 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.
  1. 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.