[ < ] | [ > ] | [ << ] | [ 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.
19.1 Common Keywords for All Kinds of Items | ||
19.2 Defining Custom Groups | ||
19.3 Defining Customization Variables | ||
19.4 Face Definitions | ||
19.5 Customization Types | ||
19.5.5 Enabling Behavior |
[ < ] | [ > ] | [ << ] | [ 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 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.
[ < ] | [ > ] | [ << ] | [ 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
.
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 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Use defcustom
to declare user-editable variables.
For face declarations, use defface
instead. See section Face Definitions.
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 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 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Use defface
to declare a new face. Conventions used in
specifying properties are similar to those for general customizable
variables. See section Defining Customization Variables.
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
.
[ < ] | [ > ] | [ << ] | [ 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 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 | ||
19.5.2 Composite Types | ||
19.5.3 Splicing into Lists | ||
19.5.4 Type Keywords | ||
19.5.6 Defining New Types |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ 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)
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:
nil
if the argument fits a certain type. This means that objects of that type
are acceptable.
'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 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.
[ < ] | [ > ] | [ << ] | [ 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
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:
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.
Show sample in a special face specified by :sample-face
.
Substitute the item’s value. How the value is represented depends on the kind of item, and (for variables) on the customization type.
Substitute the item’s documentation string.
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.
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.
The string is inserted literally.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
Internal table of registered behaviors.
History of entered behaviors.
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.
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. Completion and the Minibuffer. The default value of history is
behavior-history
.
Return non-nil if the behavior registered under name is enabled.
Unimplemented in 21.5.6.
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.
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.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.