19. Writing Customization Definitions

This chapter describes how to declare user options for customization, and also customization groups for classifying them. We use the term customization item to include both kinds of customization definitions--as well as face definitions.

19.1 Common Keywords for All Kinds of Items

All kinds of customization declarations (for variables and groups, and for faces) accept keyword arguments for specifying various information. This section describes some keywords that apply to all kinds.

All of these keywords, except :tag, can be used more than once in a given item. Each use of the keyword has an independent effect. The keyword :tag is an exception because any given item can only display one name.

:tag name

Use name, a string, instead of the item's name, to label the item in customization menus and buffers.

:group group

Put this customization item in group group. When you use :group in a defgroup, it makes the new group a subgroup of group.

If you use this keyword more than once, you can put a single item into more than one group. Displaying any of those groups will show this item. Be careful not to overdo this!

:link link-data

Include an external link after the documentation string for this item. This is a sentence containing an active field which references some other documentation.

There are three alternatives you can use for link-data:

(custom-manual info-node)

Link to an Info node; info-node is a string which specifies the node name, as in "(emacs)Top". The link appears as `[manual]' in the customization buffer.

(info-link info-node)

Like custom-manual except that the link appears in the customization buffer with the Info node name.

(url-link url)

Link to a web page; url is a string which specifies the URL. The link appears in the customization buffer as url.

You can specify the text to use in the customization buffer by adding :tag name after the first element of the link-data; for example, (info-link :tag "foo" "(emacs)Top") makes a link to the Emacs manual which appears in the buffer as `foo'.

An item can have more than one external link; however, most items have none at all.

:load file

Load file file (a string) before displaying this customization item. Loading is done with load-library, and only if the file is not already loaded.

:require feature

Require feature feature (a symbol) when installing a value for this item (an option or a face) that was saved using the customization feature. This is done by calling require.

The most common reason to use :require is when a variable enables a feature such as a minor mode, and just setting the variable won't have any effect unless the code which implements the mode is loaded.

19.2 Defining Custom Groups

Each Emacs Lisp package should have one main customization group which contains all the options, faces and other groups in the package. If the package has a small number of options and faces, use just one group and put everything in it. When there are more than twelve or so options and faces, then you should structure them into subgroups, and put the subgroups under the package's main customization group. It is OK to put some of the options and faces in the package's main group alongside the subgroups.

The package's main or only group should be a member of one or more of the standard customization groups. (To display the full list of them, use M-x customize.) Choose one or more of them (but not too many), and add your group to each of them using the :group keyword.

The way to declare new customization groups is with defgroup.

Macro: defgroup group members doc [keyword value]...

Declare group as a customization group containing members. Do not quote the symbol group. The argument doc specifies the documentation string for the group.

The argument members is a list specifying an initial set of customization items to be members of the group. However, most often members is nil, and you specify the group's members by using the :group keyword when defining those members.

If you want to specify group members through members, each element should have the form (name widget). Here name is a symbol, and widget is a widget type for editing that symbol. Useful widgets are custom-variable for a variable, custom-face for a face, and custom-group for a group.

In addition to the common keywords (see section 19.1 Common Keywords for All Kinds of Items), you can use this keyword in defgroup:

:prefix prefix

If the name of an item in the group starts with prefix, then the tag for that item is constructed (by default) by omitting prefix.

One group can have any number of prefixes.

19.3 Defining Customization Variables

Use defcustom to declare user-editable variables. For face declarations, use defface instead. See section 19.4 Face Definitions.

Macro: defcustom option default doc [keyword value]...

Declare option as a customizable user option variable. Do not quote option. The argument doc specifies the documentation string for the variable.

If option is void, defcustom initializes it to default. default should be an expression to compute the value; be careful in writing it, because it can be evaluated on more than one occasion.

The following additional keywords are defined:

:type type

Use type as the data type for this option. It specifies which values are legitimate, and how to display the value. See section 19.5 Customization Types, for more information.

:options list

Specify list as the list of reasonable values for use in this option.

Currently this is meaningful only when the type is hook. In that case, the elements of list should be functions that are useful as elements of the hook value. The user is not restricted to using only these functions, but they are offered as convenient alternatives.

:version version

This option specifies that the variable was first introduced, or its default value was changed, in Emacs version version. The value version must be a string. For example,

(defcustom foo-max 34 "*Maximum number of foo's allowed." :type 'integer :group 'foo :version "20.3")

:set setfunction

Specify setfunction as the way to change the value of this option. The function setfunction should take two arguments, a symbol and the new value, and should do whatever is necessary to update the value properly for this option (which may not mean simply setting the option as a Lisp variable). The default for setfunction is set-default.

:get getfunction

Specify getfunction as the way to extract the value of this option. The function getfunction should take one argument, a symbol, and should return the "current value" for that symbol (which need not be the symbol's Lisp value). The default is default-value.

:initialize function

function should be a function used to initialize the variable when the defcustom is evaluated. It should take two arguments, the symbol and value. Here are some predefined functions meant for use in this way:

custom-initialize-set

Use the variable's :set function to initialize the variable, but do not reinitialize it if it is already non-void. This is the default :initialize function.

custom-initialize-default

Like custom-initialize-set, but use the function set-default to set the variable, instead of the variable's :set function. This is the usual choice for a variable whose :set function enables or disables a minor mode; with this choice, defining the variable will not call the minor mode function, but customizing the variable will do so.

custom-initialize-reset

Always use the :set function to initialize the variable. If the variable is already non-void, reset it by calling the :set function using the current value (returned by the :get method).

custom-initialize-changed

Use the :set function to initialize the variable, if it is already set or has been customized; otherwise, just use set-default.

The :require option is useful for an option that turns on the operation of a certain feature. Assuming that the package is coded to check the value of the option, you still need to arrange for the package to be loaded. You can do that with :require. See section 19.1 Common Keywords for All Kinds of Items. Here is an example, from the library `paren.el':

(defcustom show-paren-mode nil
  "Toggle Show Paren mode...."
  :set (lambda (symbol value)
         (show-paren-mode (or value 0)))
  :initialize 'custom-initialize-default
  :type 'boolean
  :group 'paren-showing
  :require 'paren)

Internally, defcustom uses the symbol property standard-value to record the expression for the default value, and saved-value to record the value saved by the user with the customization buffer. The saved-value property is actually a list whose car is an expression which evaluates to the value.

19.4 Face Definitions

Use defface to declare a new face. Conventions used in specifying properties are similar to those for general customizable variables. See section 19.3 Defining Customization Variables.

Function: defface face spec doc &rest args

Declare face as a customizable face that defaults to spec. face does not need to be quoted.

Third argument doc is the face documentation.

If face has been set with `custom-set-face', set the face attributes as specified by that function, otherwise set the face attributes according to spec.

The remaining arguments args are a property list, which has the form

keyword value...

The following keywords are defined:

:group

value is a customization group. Add face to that group.

spec is an alist of the form ((display atts)...).

atts is a list of face attributes and their values. The possible attributes are defined in the variable `custom-face-attributes'.

The atts of the first entry in spec where the display matches the frame take effect in that frame. display can either be the symbol t, which will match all frames, or an alist of the form \((req item...)...)

For display to match a frame, the req property of the frame must match one of the item. The following req are defined:

type (the value of window-system)

Should be one of x, mswindows, or tty.

class (the frame's color support) Should be one of color, grayscale, or mono.

min-colors (the minimum number of colors the frame supports) Should be in integer which is compared to display-color-cells

background (what color is used for the background text) Should be one of light or dark.

19.5 Customization Types

When you define a user option with defcustom, you must specify its customization type. That is a Lisp object which describes (1) which values are legitimate and (2) how to display the value in the customization buffer for editing.

You specify the customization type in defcustom with the :type keyword. The argument of :type is evaluated; since types that vary at run time are rarely useful, normally you use a quoted constant. For example:

(defcustom diff-command "diff"
  "*The command to use to run diff."
  :type '(string)
  :group 'diff)

In general, a customization type is a list whose first element is a symbol, one of the customization type names defined in the following sections. After this symbol come a number of arguments, depending on the symbol. Between the type symbol and its arguments, you can optionally write keyword-value pairs (see section 19.5.4 Type Keywords).

Some of the type symbols do not use any arguments; those are called simple types. For a simple type, if you do not use any keyword-value pairs, you can omit the parentheses around the type symbol. For example just string as a customization type is equivalent to (string).

19.5.1 Simple Types

This section describes all the simple customization types.

sexp

The value may be any Lisp object that can be printed and read back. You can use sexp as a fall-back for any option, if you don't want to take the time to work out a more specific type to use.

integer

The value must be an integer, and is represented textually in the customization buffer.

number

The value must be a number, and is represented textually in the customization buffer.

string

The value must be a string, and the customization buffer shows just the contents, with no delimiting `"' characters and no quoting with `\'.

regexp

Like string except that the string must be a valid regular expression.

character

The value must be a character code. A character code is actually an integer, but this type shows the value by inserting the character in the buffer, rather than by showing the number.

file

The value must be a file name, and you can do completion with M-TAB.

(file :must-match t)

The value must be a file name for an existing file, and you can do completion with M-TAB.

directory

The value must be a directory name, and you can do completion with M-TAB.

symbol

The value must be a symbol. It appears in the customization buffer as the name of the symbol.

function

The value must be either a lambda expression or a function name. When it is a function name, you can do completion with M-TAB.

variable

The value must be a variable name, and you can do completion with M-TAB.

face

The value must be a symbol which is a face name.

boolean

The value is boolean--either nil or t. Note that by using choice and const together (see the next section), you can specify that the value must be nil or t, but also specify the text to describe each value in a way that fits the specific meaning of the alternative.

19.5.2 Composite Types

When none of the simple types is appropriate, you can use composite types, which build new types from other types. Here are several ways of doing that:

(restricted-sexp :match-alternatives criteria)

The value may be any Lisp object that satisfies one of criteria. criteria should be a list, and each elements should be one of these possibilities:

• A predicate--that is, a function of one argument that returns non-nil if the argument fits a certain type. This means that objects of that type are acceptable.

• A quoted constant--that is, 'object. This means that object itself is an acceptable value.

For example,

(restricted-sexp :match-alternatives (integerp 't 'nil))

allows integers, t and nil as legitimate values.

The customization buffer shows all legitimate values using their read syntax, and the user edits them textually.

(cons car-type cdr-type)

The value must be a cons cell, its CAR must fit car-type, and its CDR must fit cdr-type. For example, (cons string symbol) is a customization type which matches values such as ("foo" . foo).

In the customization buffer, the CAR and the CDR are displayed and edited separately, each according to the type that you specify for it.

(list element-types...)

The value must be a list with exactly as many elements as the element-types you have specified; and each element must fit the corresponding element-type.

For example, (list integer string function) describes a list of three elements; the first element must be an integer, the second a string, and the third a function.

In the customization buffer, the each element is displayed and edited separately, according to the type specified for it.

(vector element-types...)

Like list except that the value must be a vector instead of a list. The elements work the same as in list.

(choice alternative-types...)

The value must fit at least one of alternative-types. For example, (choice integer string) allows either an integer or a string.

In the customization buffer, the user selects one of the alternatives using a menu, and can then edit the value in the usual way for that alternative.

Normally the strings in this menu are determined automatically from the choices; however, you can specify different strings for the menu by including the :tag keyword in the alternatives. For example, if an integer stands for a number of spaces, while a string is text to use verbatim, you might write the customization type this way,

(choice (integer :tag "Number of spaces") (string :tag "Literal text"))

so that the menu offers `Number of spaces' and `Literal Text'.

In any alternative for which nil is not a valid value, other than a const, you should specify a valid default for that alternative using the :value keyword. See section 19.5.4 Type Keywords.

(const value)

The value must be value---nothing else is allowed.

The main use of const is inside of choice. For example, (choice integer (const nil)) allows either an integer or nil.

:tag is often used with const, inside of choice. For example,

(choice (const :tag "Yes" t) (const :tag "No" nil) (const :tag "Ask" foo))

(function-item function)

Like const, but used for values which are functions. This displays the documentation string as well as the function name. The documentation string is either the one you specify with :doc, or function's own documentation string.

(variable-item variable)

Like const, but used for values which are variable names. This displays the documentation string as well as the variable name. The documentation string is either the one you specify with :doc, or variable's own documentation string.

(set elements...)

The value must be a list and each element of the list must be one of the elements specified. This appears in the customization buffer as a checklist.

(repeat element-type)

The value must be a list and each element of the list must fit the type element-type. This appears in the customization buffer as a list of elements, with `[INS]' and `[DEL]' buttons for adding more elements or removing elements.

19.5.3 Splicing into Lists

The :inline feature lets you splice a variable number of elements into the middle of a list or vector. You use it in a set, choice or repeat type which appears among the element-types of a list or vector.

Normally, each of the element-types in a list or vector describes one and only one element of the list or vector. Thus, if an element-type is a repeat, that specifies a list of unspecified length which appears as one element.

But when the element-type uses :inline, the value it matches is merged directly into the containing sequence. For example, if it matches a list with three elements, those become three elements of the overall sequence. This is analogous to using `,@' in the backquote construct.

For example, to specify a list whose first element must be t and whose remaining arguments should be zero or more of foo and bar, use this customization type:

(list (const t) (set :inline t foo bar))

This matches values such as (t), (t foo), (t bar) and (t foo bar).

When the element-type is a choice, you use :inline not in the choice itself, but in (some of) the alternatives of the choice. For example, to match a list which must start with a file name, followed either by the symbol t or two strings, use this customization type:

(list file
      (choice (const t)
              (list :inline t string string)))

If the user chooses the first alternative in the choice, then the overall list has two elements and the second element is t. If the user chooses the second alternative, then the overall list has three elements and the second and third must be strings.

19.5.4 Type Keywords

You can specify keyword-argument pairs in a customization type after the type name symbol. Here are the keywords you can use, and their meanings:

:value default

This is used for a type that appears as an alternative inside of choice; it specifies the default value to use, at first, if and when the user selects this alternative with the menu in the customization buffer.

Of course, if the actual value of the option fits this alternative, it will appear showing the actual value, not default.

If nil is not a valid value for the alternative, then it is essential to specify a valid default with :value.

:format format-string

This string will be inserted in the buffer to represent the value corresponding to the type. The following `%' escapes are available for use in format-string:

`%[button%]'

Display the text button marked as a button. The :action attribute specifies what the button will do if the user invokes it; its value is a function which takes two arguments--the widget which the button appears in, and the event.

There is no way to specify two different buttons with different actions.

`%{sample%}'

Show sample in a special face specified by :sample-face.

`%v'

Substitute the item's value. How the value is represented depends on the kind of item, and (for variables) on the customization type.

`%d'

Substitute the item's documentation string.

`%h'

Like `%d', but if the documentation string is more than one line, add an active field to control whether to show all of it or just the first line.

`%t'

Substitute the tag here. You specify the tag with the :tag keyword.

`%%'

Display a literal `%'.

:action action

Perform action if the user clicks on a button.

:button-face face

Use the face face (a face name or a list of face names) for button text displayed with `%[...%]'.

:button-prefix prefix

:button-suffix suffix

These specify the text to display before and after a button. Each can be:

nil

No text is inserted.

a string

The string is inserted literally.

a symbol

The symbol's value is used.

:tag tag

Use tag (a string) as the tag for the value (or part of the value) that corresponds to this type.

:doc doc

Use doc as the documentation string for this value (or part of the value) that corresponds to this type. In order for this to work, you must specify a value for :format, and use `%d' or `%h' in that value.

The usual reason to specify a documentation string for a type is to provide more information about the meanings of alternatives inside a :choice type or the parts of some other composite type.

:help-echo motion-doc

When you move to this item with widget-forward or widget-backward, it will display the string motion-doc in the echo area.

:match function

Specify how to decide whether a value matches the type. The corresponding value, function, should be a function that accepts two arguments, a widget and a value; it should return non-nil if the value is acceptable.

19.5.5 Enabling Behavior

Some functionality requires a fair amount of effort to enable globally in a session. For example, someone who discovers filladapt and really likes it must toggle it separately in each buffer. On the other hand, after trying it for a while she might like to disable it everywhere, having decided it doesn't work very well for her. Such a functionality is called a behavior.

define-behavior allows the programmer to register functions to enable or disable a package globally in a session. The user sees a consistent interface through the enable-behavior and disable-behavior functions. These functions were introduced in XEmacs 21.5.6.

Variable: behavior-hash-table

Internal table of registered behaviors.

Variable: behavior-history

History of entered behaviors.

Function: define-behavior name doc-string [cl-keys ...]

Define a behavior named name.

doc-string must be specified. It is a description of what the behavior does when it's enabled and how to further control it (typically through custom variables). Accepted keywords are

:title

A "pretty" version of the name, for use in menus. If omitted a prettified name will be generated.

:require

A single symbol or a list of such symbols, which need to be present at enable time, or will be loaded using require.

:enable

A function of no variables, which turns the behavior on.

:disable

A function of no variables, which turns the behavior off.

Behaviors are assumed to be global, and to take effect immediately; if the underlying package is per-buffer, the enabler may have to scan all existing buffers and frob them. When a behavior is disabled, it should completely go away everywhere, as if it were never invoked at all.

The :disable keyword can be missing. This is bad practice. In such a case, attempting to disable the behavior will signal an error unless you use the force option.

Function: read-behavior prompt [require-match [initial-contents [history [default]]]]

Return a behavior symbol from the minibuffer, prompting with string prompt.

The optional arguments require-match, initial-contents, history, and default are passed to completing-read, and have semantics derived from that function. 24.5.2 Completion and the Minibuffer. The default value of history is behavior-history.

Function: behavior-enabled-p name

Return non-nil if the behavior registered under name is enabled.

Unimplemented in 21.5.6.

Function: enable-behavior behavior [force]

Enable the behavior registered under the symbol behavior.

The optional argument force is unimplemented in 21.5.6.

Called interactively, prompt the user for behavior, and take force from the prefix argument.

Function: disable-behavior (behavior &optional force)

Disable the behavior registered under the symbol behavior.

The optional argument force is unimplemented in 21.5.6.

Called interactively, prompt the user for behavior, and take force from the prefix argument.

19.5.6 Defining New Types

In the previous sections we have described how to construct elaborate type specifications for defcustom. In some cases you may want to give such a type specification a name. The obvious case is when you are using the same type for many user options, rather than repeat the specification for each option, you can give the type specification a name once, and use that name each defcustom. The other case is when a user option accept a recursive datastructure. To make it possible for a datatype to refer to itself, it needs to have a name.

Since custom types are implemented as widgets, the way to define a new customize type is to define a new widget. We are not going to describe the widget interface here in details, see section `Introduction' in The Emacs Widget Library, for that. Instead we are going to demonstrate the minimal functionality needed for defining new customize types by a simple example.

(define-widget 'binary-tree-of-string 'lazy
  "A binary tree made of cons-cells and strings."
  :offset 4
  :tag "Node"
  :type '(choice (string :tag "Leaf" :value "")
                 (cons :tag "Interior"
                       :value ("" . "") 
                       binary-tree-of-string
                       binary-tree-of-string)))

(defcustom foo-bar ""
  "Sample variable holding a binary tree of strings."
  :type 'binary-tree-of-string)

The function to define a new widget is name define-widget. The first argument is the symbol we want to make a new widget type. The second argument is a symbol representing an existing widget, the new widget is going to be defined in terms of difference from the existing widget. For the purpose of defining new customization types, the lazy widget is perfect, because it accept a :type keyword argument with the same syntax as the keyword argument to defcustom with the same name. The third argument is a documentation string for the new widget. You will be able to see that string with the M-x widget-browse ret binary-tree-of-string ret command.

After these mandatory arguments follows the keyword arguments. The most important is :type, which describes the datatype we want to match with this widget. Here a binary-tree-of-string is described as being either a string, or a cons-cell whose car and cdr are themselves both binary-tree-of-string. Note the reference to the widget type we are currently in the process of defining. The :tag attribute is a string to name the widget in the user interface, and the :offset argument are there to ensure that child nodes are indented four spaces relatively to the parent node, making the tree structure apparent in the customization buffer.

The defcustom shows how the new widget can be used as an ordinary customization type.