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.
This section describes all the simple customization types.
sexp
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
number
string
regexp
character
file
(file :must-match t)
directory
symbol
function
variable
boolean
nil
or t
.
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)
nil
if the argument fits a certain type. This means that objects of that type
are acceptable.
'object
. This means that
object is an acceptable value.
(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)
(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...)
(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...)
list
except that the value must be a vector instead of a
list. The elements work the same as in list
.
(choice alternative-types...)
(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)
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)
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)
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...)
(repeat element-type)
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.
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
: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
:sample-face
.
:tag
keyword.
:button-face face
:button-prefix
:button-suffix
nil
:doc doc
:tag tag
:help-echo motion-doc
widget-forward
or
widget-backward
, it will display the string motion-doc
in the echo area.
:match function
nil
if the value is acceptable.
Go to the first, previous, next, last section, table of contents.