| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 38.11.2 Defining Faces).
14.1 Common Item Keywords 14.2 Defining Custom Groups 14.3 Defining Customization Variables 14.4 Customization Types
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 label
: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. Please don't overdo this, since the result would be annoying.
:link link-data
There are three alternatives you can use for 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)
(emacs-commentary-link library)
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-library, and only if the file is
not already loaded.
:require feature
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
defcustom; that convention is for variables only.
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.
When a new group is introduced into Emacs, use this keyword in
defgroup:
:version version
Tag the group with a version like this when it is introduced, rather than the individual members (see section 14.3 Defining Customization Variables).
In addition to the common keywords (see section 14.1 Common Item Keywords), you can
also use this keyword in defgroup:
:prefix prefix
One group can have any number of prefixes.
The 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Use defcustom to declare user-editable variables.
set-variable; examples of the
former are global minor mode options such as
global-font-lock-mode and examples of the latter are hooks.
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. You should normally avoid using backquotes in
default because they are not expanded when editing the value,
causing list values to appear to have the wrong structure.
When you evaluate a defcustom form with C-M-x in Emacs Lisp
mode (eval-defun), a special feature of eval-defun
arranges to set the variable unconditionally, without testing whether
its value is void. (The same feature applies to defvar.)
See section 11.5 Defining Global Variables.
defcustom accepts the following additional keywords:
:type type
:options list
This is meaningful only for certain types, currently including
hook, plist and alist. See the definition of the
individual types for a description of how to use :options.
:version version
(defcustom foo-max 34 "*Maximum number of foo's allowed." :type 'integer :group 'foo :version "20.3") |
:set setfunction
set-default.
:get getfunction
default-value.
:initialize function
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
: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
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
: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.
:set-after variables
:set-after if setting this variable won't work properly unless
those other variables already have their intended values.
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 14.1 Common Item Keywords. 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)
|
If a customization item has a type such as hook or alist,
which supports :options, you can add additional options to the
item, outside the defcustom declaration, by calling
custom-add-option. For example, if you define a function
my-lisp-mode-initialization intended to be called from
emacs-lisp-mode-hook, you might want to add that to the list of
options for emacs-lisp-mode-hook, but not by editing its
definition. You can do it thus:
(custom-add-option 'emacs-lisp-mode-hook
'my-lisp-mode-initialization)
|
The precise effect of adding option depends on the customization type of symbol.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 14.4.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).
14.4.1 Simple Types 14.4.2 Composite Types 14.4.3 Splicing into Lists 14.4.4 Type Keywords
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
string except that the string must be a valid regular
expression.
character
file
(file :must-match t)
directory
hook
:options keyword in a hook variable's
defcustom to specify a list of functions recommended for use in
the hook; see 14.3 Defining Customization Variables.
alist
You can specify the key and value types like this:
(alist :key-type key-type :value-type value-type) |
where key-type and value-type are customization type
specifications. The default key type is sexp, and the default
value type is sexp.
The user can add any key matching the specified key type, but you can
give some keys a preferential treatment by specifying them with the
:options (see 14.3 Defining Customization Variables). The specified keys
will always be shown in the customize buffer (together with a suitable
value), with a checkbox to include or exclude or disable the key/value
pair from the alist. The user will not be able to edit the keys
specified by the :options keyword argument.
The argument to the :options keywords should be a list of option
specifications. Ordinarily, the options are simply atoms, which are the
specified keys. For example:
:options '("foo" "bar" "baz")
|
specifies that there are three "known" keys, namely "foo",
"bar" and "baz", which will always be shown first.
You may want to restrict the value type for specific keys, for example,
the value associated with the "bar" key can only be an integer.
You can specify this by using a list instead of an atom in the option
specification. The first element will specify the key, like before,
while the second element will specify the value type.
:options '("foo" ("bar" integer) "baz")
|
Finally, you may want to change how the key is presented. By default,
the key is simply shown as a const, since the user cannot change
the special keys specified with the :options keyword. However,
you may want to use a more specialized type for presenting the key, like
function-item if you know it is a symbol with a function binding.
This is done by using a customization type specification instead of a
symbol for the key.
:options '("foo" ((function-item some-function) integer) "baz")
|
Many alists use lists with two elements, instead of cons cells. For example,
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE).")
|
instead of
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
"Each element is a cons-cell (KEY . VALUE).")
|
Because of the way lists are implemented on top of cons cells, you can
treat list-alist in the example above as a cons cell alist, where
the value type is a list with a single element containing the real
value.
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE)."
:type '(alist :value-type (group integer)))
|
The group widget is used here instead of list only because
the formatting is better suited for the purpose.
Similarily, you can have alists with more values associated with each key, using variations of this trick:
(defcustom person-data '(("brian" 50 t)
("dorith" 55 nil)
("ken" 52 t))
"Alist of basic info about people.
Each element has the form (NAME AGE MALE-FLAG)."
:type '(alist :value-type (group age boolean)))
(defcustom pets '(("brian")
("dorith" "dog" "guppy")
("ken" "cat"))
"Alist of people's pets.
In an element (KEY . VALUE), KEY is the person's name,
and the VALUE is a list of that person's pets."
:type '(alist :value-type (repeat string)))
|
plist
plist custom type is similar to the alist (see above),
except that the information is stored as a property list, i.e. a list of
this form:
(key value key value key value ...) |
The default :key-type for plist is symbol,
rather than sexp.
symbol
function
variable
face
boolean
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.
coding-system
color
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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)
(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...)
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, 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 14.4.4 Type Keywords.
(radio element-types...)
choice, except that the choices are displayed
using `radio buttons' rather than a menu. This has the advantage of
displaying documentation for the choices when applicable and so is often
a good choice for a choice between constant functions
(function-item customization types).
(const value)
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))
|
describes a variable for which t means yes, nil means no,
and foo means "ask."
(other value)
The main use of 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 types...)
This appears in the customization buffer as a checklist, so that each of
types may have either one corresponding element or none. It is
not possible to specify two different elements that match the same one
of types. For example, (set integer symbol) allows one
integer and/or one symbol in the list; it does not allow multiple
integers or multiple symbols. As a result, it is rare to use
nonspecific types such as integer in a set.
Most often, the types in a set are const types, as
shown here:
(set (const :bold) (const :italic)) |
Sometimes they describe possible elements in an alist:
(set (cons :tag "Height" (const height) integer)
(cons :tag "Width" (const width) integer))
|
That lets the user specify a height value optionally and a width value optionally.
(repeat element-type)
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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 suffix
nil
: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-doc
widget-forward or
widget-backward, it will display the string motion-doc in
the echo area. In addition, motion-doc is used as the mouse
help-echo string and may actually be a function or form evaluated
to yield a help string as for help-echo text properties.
:match function
nil if
the value is acceptable.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |