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 (see section Defining Faces).
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:group group: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(custom-manual info-node)"(emacs)Top". The link
appears as `[manual]' in the customization
buffer.
(info-link info-node)custom-manual except that the link appears in
the customization buffer with the Info node name.
(url-link url):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 fileload-library,
and only if the file is not already loaded.
:require featurerequire. 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.
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.
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 Common Keywords for All Kinds of
Items), you can use this keyword in defgroup:
:prefix prefixThe prefix-discarding feature is currently turned off, which
means that :prefix currently has no effect. We did
this because we found that discarding the specified prefixes often
led to confusing names for options. This happened because the
people who wrote the defgroup definitions for various
groups added :prefix keywords whenever they make
logical sense--that is, whenever the variables in the library have
a common prefix.
In order to obtain good results with :prefix, it
would be necessary to check the specific effects of discarding a
particular prefix, given the specific items in a group and their
names and documentation. If the resulting text is not clear, then
:prefix should not be used in that case.
It should be possible to recheck all the customization groups,
delete the :prefix specifications which give unclear
results, and then turn this feature back on, if someone would like
to do the work.
Use defcustom to declare user-editable
variables.
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.
defcustom accepts the following additional
keywords:
:type type:options listhook. 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(defcustom foo-max 34 "*Maximum number of foo's allowed." :type 'integer :group 'foo :version "20.3")
:set setfunctionset-default.
:get getfunctiondefault-value.
:initialize functiondefcustom 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: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-defaultcustom-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: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: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 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@enddots{}"
: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.
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 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).
This section describes all the simple customization types.
sexpsexp 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.
integernumberstringregexpstring except that the string must be a valid
regular expression.
characterfile(file :must-match t)directoryhook:options keyword in a
hook variable's defcustom to specify a list of
functions recommended for use in the hook; see section Defining Customization Variables.
symbolfunctionvariablefacebooleannil 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.
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)nil or
non-nil according to the argument. Using a predicate
in the list says that objects for which the predicate returns
non-nil are acceptable.
'object.
This sort of element in the list says that object itself
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)(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...)(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, 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'. 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 Type Keywords.
(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, inside of
choice. For example,
(choice (const :tag "Yes" t)
(const :tag "No" nil)
(const :tag "Ask" foo))
describes a variable for which t means yes,
nil means no, and foo means "ask."
(other value)other is as the last element of
choice. For example,
(choice (const :tag "Yes" t)
(const :tag "No" nil)
(other :tag "Ask" foo))
describes a variable for which t means yes,
nil means no, and anything else means "ask." If the
user chooses `Ask' from the menu of alternatives, that
specifies the value foo; but any other value (not
t, nil or foo) displays as
`Ask', just like foo.
(function-item function)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)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...)(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 defaultchoice; 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: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-face.
:tag keyword.
:action action:button-face face:button-prefix prefix:button-suffix suffixnil:tag tag:doc doc: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-docwidget-forward or
widget-backward, it will display the string
motion-doc in the echo area.
:match functionnil if the value is acceptable.