Go to the first, previous, next, last section, table of contents.


Customization Types

When you define a user option with defcustom, you must specify its customization type. That is a Lisp object which indictaes (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 it is 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 appears 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. Some of the type symbols do not use any arguments; those are called simple types.

In between the type symbol and its arguments, you can optionally write keyword-value pairs. See section Type Keywords.

For a simple type, if you do not use any keyword-value pairs, you can omit the parentheses around the type symbol. The above example does this, using just string as the customization type. But (string) would mean the same thing.

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 `"' characters or quoting with `\'.
regexp
The value must be a string which is 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.
boolean
The value is boolean--either nil or t.

Composite Types

When none of the simple types is appropriate, you can use composite types, which build from simple 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: 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, (const string symbol) is a customization type which matches values such as ("foo" . foo). In the customization buffeer, 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 buffeer, 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'.
(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.
(function-item function)
Like const, but used for values which are functions. This displays the documentation string of the function function as well as its name.
(variable-item variable)
Like const, but used for values which are variable names. This displays the documentation string of the variable variable as well as its name.
(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.

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.

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.
: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:
`%{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 `%'.
:button-face face
Use face face for text displayed with `%[...%]'.
:button-prefix
:button-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.
:doc doc
Use doc as the documentation string for this item.
:tag tag
Use tag (a string) as the tag for this item.
: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. function should be a function that accepts two arguments, a widget and a value; it should return non-nil if the value is acceptable.


Go to the first, previous, next, last section, table of contents.