wiki:HemlockProgrammer/Modes

Back to Table of Contents

8. Modes

A mode is a collection of Hemlock values which may be present in the current environment (page 21) depending on the editing task at hand. An example of a typical mode is Lisp, for editing Lisp code.

8.1. Mode Hooks

When a mode is added to or removed from a buffer, its mode hook is invoked. The hook functions take two arguments, the buffer involved and t if the mode is being added or nil if it is being removed. Mode hooks are typically used to make a mode do something additional to what it usually does. One might, for example, make a Text mode hook that turned on auto-fill mode when you entered.

8.2. Major and Minor Modes

There are two kinds of modes, major modes and minor modes. A buffer always has exactly one major mode, but it may have any number of minor modes. Major modes may have mode character attributes while minor modes may not.

A major mode is usually used to change the environment in some major way, such as to install special commands for editing some language. Minor modes generally change some small attribute of the environment, such as whether lines are automatically broken when they get too long. A minor mode should work regardless of what major mode and minor modes are in effect.

Default Modes (initial value '("Fundamental" "Save")) [Hemlock Variable]

This variable contains a list of mode names which are instantiated in a buffer when no other information is available.

*mode-names* [Variable]

Holds a string-table of the names of all the modes.

Illegal [Command]

This is a useful command to bind in modes that wish to shadow global bindings by making them effectively illegal. Also, although less likely, minor modes may shadow major mode bindings with this. This command calls editor-error.

8.3. Mode Functions

defmode name &key :setup-function :cleanup-function :major-p :precedence :transparent-p :documentation [Function]

This function defines a new mode named name, and enters it in *mode-names* (page 35). If major-p is supplied and is not nil then the mode is a major mode; otherwise it is a minor mode.

Setup-function and cleanup-function are functions which are invoked with the buffer affected, after the mode is turned on, and before it is turned off, respectively. These functions typically are used to make buffer-local key or variable bindings and to remove them when the mode is turned off.

Precedence is only meaningful for a minor mode. The precedence of a minor mode determines the order in which it in a buffer's list of modes. When searching for values in the current environment, minor modes are searched in order, so the precedence of a minor mode determines which value is found when there are several definitions.

Transparent-p determines whether key bindings local to the defined mode are transparent. Transparent key bindings are invoked in addition to the first normal key binding found rather than shadowing less local key bindings.

Documentation is some introductory text about the mode. Commands such as Describe Mode use this.

mode-documentation name [Function]

This function returns the documentation for the mode named name.

buffer-major-mode buffer [Function]
Buffer Major Mode Hook [Hemlock Variable]

buffer-major-mode returns the name of buffer's major mode. The major mode may be changed with setf; then Buffer Major Mode Hook is invoked with buffer and the new mode.

buffer-minor-mode buffer name [Function]
Buffer Minor Mode Hook [Hemlock Variable]

buffer-minor-mode returns t if the minor mode name is active in buffer, nil otherwise. A minor mode may be turned on or off by using setf; then Buffer Minor Mode Hook is invoked with buffer, name and the new value.

mode-variables name [Function]

Returns the string-table of mode local variables.

mode-major-p name [Function]

Returns t if name is the name of a major mode, or nil if it is the name of a minor mode. It is an error for name not to be the name of a mode.

Back to Table of Contents