mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-15 09:47:20 +00:00
944 lines
34 KiB
Plaintext
944 lines
34 KiB
Plaintext
@c -*-texinfo-*-
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
|
@c Copyright (C) 1997, 1998 Free Software Foundation, Inc.
|
|
@c See the file elisp.texi for copying conditions.
|
|
@setfilename ../info/customize
|
|
@node Customization, Loading, Macros, Top
|
|
@chapter Writing Customization Definitions
|
|
|
|
This chapter describes how to declare user options for customization,
|
|
and also customization groups for classifying them. We use the term
|
|
@dfn{customization item} to include both kinds of customization
|
|
definitions---as well as face definitions (@pxref{Defining Faces}).
|
|
|
|
@menu
|
|
* Common Keywords::
|
|
* Group Definitions::
|
|
* Variable Definitions::
|
|
* Customization Types::
|
|
@end menu
|
|
|
|
@node Common Keywords
|
|
@section Common Item Keywords
|
|
|
|
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 @code{:tag}, can be used more than once
|
|
in a given item. Each use of the keyword has an independent effect.
|
|
The keyword @code{:tag} is an exception because any given item can only
|
|
display one name.
|
|
|
|
@table @code
|
|
@item :tag @var{label}
|
|
Use @var{label}, a string, instead of the item's name, to label the item
|
|
in customization menus and buffers.
|
|
|
|
@item :group @var{group}
|
|
Put this customization item in group @var{group}. When you use
|
|
@code{:group} in a @code{defgroup}, it makes the new group a subgroup of
|
|
@var{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.
|
|
|
|
@item :link @var{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 @var{link-data}:
|
|
|
|
@table @code
|
|
@item (custom-manual @var{info-node})
|
|
Link to an Info node; @var{info-node} is a string which specifies the
|
|
node name, as in @code{"(emacs)Top"}. The link appears as
|
|
@samp{[manual]} in the customization buffer.
|
|
|
|
@item (info-link @var{info-node})
|
|
Like @code{custom-manual} except that the link appears
|
|
in the customization buffer with the Info node name.
|
|
|
|
@item (url-link @var{url})
|
|
Link to a web page; @var{url} is a string which specifies the @sc{url}.
|
|
The link appears in the customization buffer as @var{url}.
|
|
@end table
|
|
|
|
You can specify the text to use in the customization buffer by adding
|
|
@code{:tag @var{name}} after the first element of the @var{link-data};
|
|
for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
|
|
the Emacs manual which appears in the buffer as @samp{foo}.
|
|
|
|
An item can have more than one external link; however, most items have
|
|
none at all.
|
|
|
|
@item :load @var{file}
|
|
Load file @var{file} (a string) before displaying this customization
|
|
item. Loading is done with @code{load-library}, and only if the file is
|
|
not already loaded.
|
|
|
|
@item :require @var{feature}
|
|
Require feature @var{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 @code{require}.
|
|
|
|
The most common reason to use @code{: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.
|
|
@end table
|
|
|
|
@node Group Definitions
|
|
@section Defining Custom Groups
|
|
|
|
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 @kbd{M-x customize}.) Choose one or more of them (but not too
|
|
many), and add your group to each of them using the @code{:group}
|
|
keyword.
|
|
|
|
The way to declare new customization groups is with @code{defgroup}.
|
|
|
|
@defmac defgroup group members doc [keyword value]...
|
|
@tindex defgroup
|
|
Declare @var{group} as a customization group containing @var{members}.
|
|
Do not quote the symbol @var{group}. The argument @var{doc} specifies
|
|
the documentation string for the group. It should not start with a
|
|
@samp{*} as in @code{defcustom}; that convention is for variables only.
|
|
|
|
The argument @var{members} is a list specifying an initial set of
|
|
customization items to be members of the group. However, most often
|
|
@var{members} is @code{nil}, and you specify the group's members by
|
|
using the @code{:group} keyword when defining those members.
|
|
|
|
If you want to specify group members through @var{members}, each element
|
|
should have the form @code{(@var{name} @var{widget})}. Here @var{name}
|
|
is a symbol, and @var{widget} is a widget type for editing that symbol.
|
|
Useful widgets are @code{custom-variable} for a variable,
|
|
@code{custom-face} for a face, and @code{custom-group} for a group.
|
|
|
|
In addition to the common keywords (@pxref{Common Keywords}), you can
|
|
use this keyword in @code{defgroup}:
|
|
|
|
@table @code
|
|
@item :prefix @var{prefix}
|
|
If the name of an item in the group starts with @var{prefix}, then the
|
|
tag for that item is constructed (by default) by omitting @var{prefix}.
|
|
|
|
One group can have any number of prefixes.
|
|
@end table
|
|
@end defmac
|
|
|
|
The prefix-discarding feature is currently turned off, which means
|
|
that @code{: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
|
|
@code{defgroup} definitions for various groups added @code{: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 @code{: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 @code{:prefix}
|
|
should not be used in that case.
|
|
|
|
It should be possible to recheck all the customization groups, delete
|
|
the @code{:prefix} specifications which give unclear results, and then
|
|
turn this feature back on, if someone would like to do the work.
|
|
|
|
@node Variable Definitions
|
|
@section Defining Customization Variables
|
|
|
|
Use @code{defcustom} to declare user-editable variables.
|
|
|
|
@defmac defcustom option default doc [keyword value]...
|
|
@tindex defcustom
|
|
Declare @var{option} as a customizable user option variable. Do not
|
|
quote @var{option}. The argument @var{doc} specifies the documentation
|
|
string for the variable; it should normally start with a @samp{*}. This
|
|
marks the variable, for other purposes, as one that users may want to
|
|
customize.
|
|
|
|
If @var{option} is void, @code{defcustom} initializes it to
|
|
@var{default}. @var{default} should be an expression to compute the
|
|
value; be careful in writing it, because it can be evaluated on more
|
|
than one occasion.
|
|
|
|
When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
|
|
mode (@code{eval-defun}), a special feature of @code{eval-defun}
|
|
arranges to set the variable unconditionally, without testing whether
|
|
its value is void. (The same feature applies to @code{defvar}.)
|
|
@xref{Defining Variables}.
|
|
@end defmac
|
|
|
|
@code{defcustom} accepts the following additional keywords:
|
|
|
|
@table @code
|
|
@item :type @var{type}
|
|
Use @var{type} as the data type for this option. It specifies which
|
|
values are legitimate, and how to display the value.
|
|
@xref{Customization Types}, for more information.
|
|
|
|
@item :options @var{list}
|
|
Specify @var{list} as the list of reasonable values for use in this
|
|
option. The user is not restricted to using only these values, but they
|
|
are offered as convenient alternatives.
|
|
|
|
This is meaningful only for certain types, currently including
|
|
@code{hook}, @code{plist} and @code{alist}. See the definition of the
|
|
individual types for a description of how to use @code{:options}.
|
|
|
|
@item :version @var{version}
|
|
This option specifies that the variable was first introduced, or its
|
|
default value was changed, in Emacs version @var{version}. The value
|
|
@var{version} must be a string. For example,
|
|
|
|
@example
|
|
(defcustom foo-max 34
|
|
"*Maximum number of foo's allowed."
|
|
:type 'integer
|
|
:group 'foo
|
|
:version "20.3")
|
|
@end example
|
|
|
|
@item :set @var{setfunction}
|
|
Specify @var{setfunction} as the way to change the value of this option.
|
|
The function @var{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 @var{setfunction} is
|
|
@code{set-default}.
|
|
|
|
@item :get @var{getfunction}
|
|
Specify @var{getfunction} as the way to extract the value of this
|
|
option. The function @var{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
|
|
@code{default-value}.
|
|
|
|
@item :initialize @var{function}
|
|
@var{function} should be a function used to initialize the variable when
|
|
the @code{defcustom} is evaluated. It should take two arguments, the
|
|
symbol and value. Here are some predefined functions meant for use in
|
|
this way:
|
|
|
|
@table @code
|
|
@item custom-initialize-set
|
|
Use the variable's @code{:set} function to initialize the variable, but
|
|
do not reinitialize it if it is already non-void. This is the default
|
|
@code{:initialize} function.
|
|
|
|
@item custom-initialize-default
|
|
Like @code{custom-initialize-set}, but use the function
|
|
@code{set-default} to set the variable, instead of the variable's
|
|
@code{:set} function. This is the usual choice for a variable whose
|
|
@code{: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.
|
|
|
|
@item custom-initialize-reset
|
|
Always use the @code{:set} function to initialize the variable. If the
|
|
variable is already non-void, reset it by calling the @code{:set}
|
|
function using the current value (returned by the @code{:get} method).
|
|
|
|
@item custom-initialize-changed
|
|
Use the @code{:set} function to initialize the variable, if it is
|
|
already set or has been customized; otherwise, just use
|
|
@code{set-default}.
|
|
@end table
|
|
@end table
|
|
|
|
The @code{: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 @code{:require}. @xref{Common
|
|
Keywords}. Here is an example, from the library @file{paren.el}:
|
|
|
|
@example
|
|
(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)
|
|
@end example
|
|
|
|
If a customization item has a type such as @code{hook} or @code{alist},
|
|
which supports @code{:options}, you can add additional options to the
|
|
item, outside the @code{defcustom} declaration, by calling
|
|
@code{custom-add-option}. For example, if you define a function
|
|
@code{my-lisp-mode-initialization} intended to be called from
|
|
@code{emacs-lisp-mode-hook}, you might want to add that to the list of
|
|
options for @code{emacs-lisp-mode-hook}, but not by editing its
|
|
definition. You can do it thus:
|
|
|
|
@example
|
|
(custom-add-option 'emacs-lisp-mode-hook
|
|
'my-lisp-mode-initialization)
|
|
@end example
|
|
|
|
@defun custom-add-option symbol option
|
|
To the customization @var{symbol}, add @var{option}.
|
|
|
|
The precise effect of adding @var{option} depends on the customization
|
|
type of @var{symbol}.
|
|
@end defun
|
|
|
|
Internally, @code{defcustom} uses the symbol property
|
|
@code{standard-value} to record the expression for the default value,
|
|
and @code{saved-value} to record the value saved by the user with the
|
|
customization buffer. The @code{saved-value} property is actually a
|
|
list whose car is an expression which evaluates to the value.
|
|
|
|
@node Customization Types
|
|
@section Customization Types
|
|
|
|
When you define a user option with @code{defcustom}, you must specify
|
|
its @dfn{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 @code{defcustom} with the
|
|
@code{:type} keyword. The argument of @code{:type} is evaluated; since
|
|
types that vary at run time are rarely useful, normally you use a quoted
|
|
constant. For example:
|
|
|
|
@example
|
|
(defcustom diff-command "diff"
|
|
"*The command to use to run diff."
|
|
:type '(string)
|
|
:group 'diff)
|
|
@end example
|
|
|
|
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 (@pxref{Type Keywords}).
|
|
|
|
Some of the type symbols do not use any arguments; those are called
|
|
@dfn{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 @code{string} as a customization type is
|
|
equivalent to @code{(string)}.
|
|
|
|
@menu
|
|
* Simple Types::
|
|
* Composite Types::
|
|
* Splicing into Lists::
|
|
* Type Keywords::
|
|
@end menu
|
|
|
|
@node Simple Types
|
|
@subsection Simple Types
|
|
|
|
This section describes all the simple customization types.
|
|
|
|
@table @code
|
|
@item sexp
|
|
The value may be any Lisp object that can be printed and read back. You
|
|
can use @code{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.
|
|
|
|
@item integer
|
|
The value must be an integer, and is represented textually
|
|
in the customization buffer.
|
|
|
|
@item number
|
|
The value must be a number, and is represented textually in the
|
|
customization buffer.
|
|
|
|
@item string
|
|
The value must be a string, and the customization buffer shows just the
|
|
contents, with no delimiting @samp{"} characters and no quoting with
|
|
@samp{\}.
|
|
|
|
@item regexp
|
|
Like @code{string} except that the string must be a valid regular
|
|
expression.
|
|
|
|
@item 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.
|
|
|
|
@item file
|
|
The value must be a file name, and you can do completion with
|
|
@kbd{M-@key{TAB}}.
|
|
|
|
@item (file :must-match t)
|
|
The value must be a file name for an existing file, and you can do
|
|
completion with @kbd{M-@key{TAB}}.
|
|
|
|
@item directory
|
|
The value must be a directory name, and you can do completion with
|
|
@kbd{M-@key{TAB}}.
|
|
|
|
@item hook
|
|
The value must be a list of functions (or a single function, but that is
|
|
obsolete usage). This customization type is used for hook variables.
|
|
You can use the @code{:options} keyword in a hook variable's
|
|
@code{defcustom} to specify a list of functions recommended for use in
|
|
the hook; see @ref{Variable Definitions}.
|
|
|
|
@item alist
|
|
The value must be a list of cons-cells, the @sc{car} of each cell
|
|
representing a key, and the @sc{cdr} of the same cell representing an
|
|
associated value. The user can add and delete key/value pairs, and
|
|
edit both the key and the value of each pair.
|
|
|
|
You can specify the key and value types like this:
|
|
|
|
@smallexample
|
|
(alist :key-type @var{key-type} :value-type @var{value-type})
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where @var{key-type} and @var{value-type} are customization type
|
|
specifications. The default key type is @code{sexp}, and the default
|
|
value type is @code{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
|
|
@code{:options} (see @ref{Variable Definitions}). 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 @code{:options} keyword argument.
|
|
|
|
The argument to the @code{:options} keywords should be a list of option
|
|
specifications. Ordinarily, the options are simply atoms, which are the
|
|
specified keys. For example:
|
|
|
|
@smallexample
|
|
:options '("foo" "bar" "baz")
|
|
@end smallexample
|
|
|
|
@noindent
|
|
specifies that there are three ``known'' keys, namely @code{"foo"},
|
|
@code{"bar"} and @code{"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 @code{"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.
|
|
|
|
@smallexample
|
|
:options '("foo" ("bar" integer) "baz")
|
|
@end smallexample
|
|
|
|
Finally, you may want to change how the key is presented. By default,
|
|
the key is simply shown as a @code{const}, since the user cannot change
|
|
the special keys specified with the @code{:options} keyword. However,
|
|
you may want to use a more specialized type for presenting the key, like
|
|
@code{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.
|
|
|
|
@smallexample
|
|
:options '("foo" ((function-item some-function) integer) "baz")
|
|
@end smallexample
|
|
|
|
Many alists use lists with two elements, instead of cons cells. For
|
|
example,
|
|
|
|
@smallexample
|
|
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
|
|
"Each element is a list of the form (KEY VALUE).")
|
|
@end smallexample
|
|
|
|
@noindent
|
|
instead of
|
|
|
|
@smallexample
|
|
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
|
|
"Each element is a cons-cell (KEY . VALUE).")
|
|
@end smallexample
|
|
|
|
Because of the way lists are implemented on top of cons cells, you can
|
|
treat @code{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.
|
|
|
|
@smallexample
|
|
(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)))
|
|
@end smallexample
|
|
|
|
The @code{group} widget is used here instead of @code{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:
|
|
|
|
@smallexample
|
|
(defcustom person-data '(("brian" 50 t)
|
|
("dorith" 55 nil)
|
|
("ken" 52 t))
|
|
"Alist of people, each element has the form (NAME AGE MALE)."
|
|
:type '(alist :value-type (group age boolean)))
|
|
|
|
(defcustom pets '(("brian")
|
|
("dorith" "dog" "guppy")
|
|
("ken" "cat"))
|
|
"Alist where the KEY is a person, and the VALUE is a list of pets."
|
|
:type '(alist :value-type (repeat string)))
|
|
@end smallexample
|
|
|
|
@item plist
|
|
The @code{plist} custom type is similar to the @code{alist} (see above),
|
|
except that the information is stored as a property list, i.e. a list of
|
|
this form:
|
|
|
|
@smallexample
|
|
(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
|
|
@end smallexample
|
|
|
|
The default @code{:key-type} for @code{plist} is @code{symbol},
|
|
rather than @code{sexp}.
|
|
|
|
@item symbol
|
|
The value must be a symbol. It appears in the customization buffer as
|
|
the name of the symbol.
|
|
|
|
@item function
|
|
The value must be either a lambda expression or a function name. When
|
|
it is a function name, you can do completion with @kbd{M-@key{TAB}}.
|
|
|
|
@item variable
|
|
The value must be a variable name, and you can do completion with
|
|
@kbd{M-@key{TAB}}.
|
|
|
|
@item face
|
|
The value must be a symbol which is a face name, and you can do
|
|
completion with @kbd{M-@key{TAB}}.
|
|
|
|
@item boolean
|
|
The value is boolean---either @code{nil} or @code{t}. Note that by
|
|
using @code{choice} and @code{const} together (see the next section),
|
|
you can specify that the value must be @code{nil} or @code{t}, but also
|
|
specify the text to describe each value in a way that fits the specific
|
|
meaning of the alternative.
|
|
@end table
|
|
|
|
@node Composite Types
|
|
@subsection Composite Types
|
|
|
|
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:
|
|
|
|
@table @code
|
|
@item (restricted-sexp :match-alternatives @var{criteria})
|
|
The value may be any Lisp object that satisfies one of @var{criteria}.
|
|
@var{criteria} should be a list, and each element should be
|
|
one of these possibilities:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A predicate---that is, a function of one argument that has no side
|
|
effects, and returns either @code{nil} or non-@code{nil} according to
|
|
the argument. Using a predicate in the list says that objects for which
|
|
the predicate returns non-@code{nil} are acceptable.
|
|
|
|
@item
|
|
A quoted constant---that is, @code{'@var{object}}. This sort of element
|
|
in the list says that @var{object} itself is an acceptable value.
|
|
@end itemize
|
|
|
|
For example,
|
|
|
|
@example
|
|
(restricted-sexp :match-alternatives
|
|
(integerp 't 'nil))
|
|
@end example
|
|
|
|
@noindent
|
|
allows integers, @code{t} and @code{nil} as legitimate values.
|
|
|
|
The customization buffer shows all legitimate values using their read
|
|
syntax, and the user edits them textually.
|
|
|
|
@item (cons @var{car-type} @var{cdr-type})
|
|
The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
|
|
its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
|
|
symbol)} is a customization type which matches values such as
|
|
@code{("foo" . foo)}.
|
|
|
|
In the customization buffer, the @sc{car} and the @sc{cdr} are
|
|
displayed and edited separately, each according to the type
|
|
that you specify for it.
|
|
|
|
@item (list @var{element-types}@dots{})
|
|
The value must be a list with exactly as many elements as the
|
|
@var{element-types} you have specified; and each element must fit the
|
|
corresponding @var{element-type}.
|
|
|
|
For example, @code{(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.
|
|
|
|
@item (vector @var{element-types}@dots{})
|
|
Like @code{list} except that the value must be a vector instead of a
|
|
list. The elements work the same as in @code{list}.
|
|
|
|
@item (choice @var{alternative-types}...)
|
|
The value must fit at least one of @var{alternative-types}.
|
|
For example, @code{(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 @code{: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,
|
|
|
|
@example
|
|
(choice (integer :tag "Number of spaces")
|
|
(string :tag "Literal text"))
|
|
@end example
|
|
|
|
@noindent
|
|
so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
|
|
|
|
In any alternative for which @code{nil} is not a valid value, other than
|
|
a @code{const}, you should specify a valid default for that alternative
|
|
using the @code{:value} keyword. @xref{Type Keywords}.
|
|
|
|
@item (const @var{value})
|
|
The value must be @var{value}---nothing else is allowed.
|
|
|
|
The main use of @code{const} is inside of @code{choice}. For example,
|
|
@code{(choice integer (const nil))} allows either an integer or
|
|
@code{nil}.
|
|
|
|
@code{:tag} is often used with @code{const}, inside of @code{choice}.
|
|
For example,
|
|
|
|
@example
|
|
(choice (const :tag "Yes" t)
|
|
(const :tag "No" nil)
|
|
(const :tag "Ask" foo))
|
|
@end example
|
|
|
|
@noindent
|
|
describes a variable for which @code{t} means yes, @code{nil} means no,
|
|
and @code{foo} means ``ask.''
|
|
|
|
@item (other @var{value})
|
|
This alternative can match any Lisp value, but if the user chooses this
|
|
alternative, that selects the value @var{value}.
|
|
|
|
The main use of @code{other} is as the last element of @code{choice}.
|
|
For example,
|
|
|
|
@example
|
|
(choice (const :tag "Yes" t)
|
|
(const :tag "No" nil)
|
|
(other :tag "Ask" foo))
|
|
@end example
|
|
|
|
@noindent
|
|
describes a variable for which @code{t} means yes, @code{nil} means no,
|
|
and anything else means ``ask.'' If the user chooses @samp{Ask} from
|
|
the menu of alternatives, that specifies the value @code{foo}; but any
|
|
other value (not @code{t}, @code{nil} or @code{foo}) displays as
|
|
@samp{Ask}, just like @code{foo}.
|
|
|
|
@item (function-item @var{function})
|
|
Like @code{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
|
|
@code{:doc}, or @var{function}'s own documentation string.
|
|
|
|
@item (variable-item @var{variable})
|
|
Like @code{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 @code{:doc}, or
|
|
@var{variable}'s own documentation string.
|
|
|
|
@item (set @var{types}@dots{})
|
|
The value must be a list, and each element of the list must match one of
|
|
the @var{types} specified.
|
|
|
|
This appears in the customization buffer as a checklist, so that each of
|
|
@var{types} may have either one corresponding element or none. It is
|
|
not possible to specify two different elements that match the same one
|
|
of @var{types}. For example, @code{(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 @code{integer} in a @code{set}.
|
|
|
|
Most often, the @var{types} in a @code{set} are @code{const} types, as
|
|
shown here:
|
|
|
|
@example
|
|
(set (const :bold) (const :italic))
|
|
@end example
|
|
|
|
Sometimes they describe possible elements in an alist:
|
|
|
|
@example
|
|
(set (cons :tag "Height" (const height) integer)
|
|
(cons :tag "Width" (const width) integer))
|
|
@end example
|
|
|
|
@noindent
|
|
That lets the user specify a height value optionally
|
|
and a width value optionally.
|
|
|
|
@item (repeat @var{element-type})
|
|
The value must be a list and each element of the list must fit the type
|
|
@var{element-type}. This appears in the customization buffer as a
|
|
list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
|
|
more elements or removing elements.
|
|
@end table
|
|
|
|
@node Splicing into Lists
|
|
@subsection Splicing into Lists
|
|
|
|
The @code{:inline} feature lets you splice a variable number of
|
|
elements into the middle of a list or vector. You use it in a
|
|
@code{set}, @code{choice} or @code{repeat} type which appears among the
|
|
element-types of a @code{list} or @code{vector}.
|
|
|
|
Normally, each of the element-types in a @code{list} or @code{vector}
|
|
describes one and only one element of the list or vector. Thus, if an
|
|
element-type is a @code{repeat}, that specifies a list of unspecified
|
|
length which appears as one element.
|
|
|
|
But when the element-type uses @code{: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 @samp{,@@} in the backquote
|
|
construct.
|
|
|
|
For example, to specify a list whose first element must be @code{t}
|
|
and whose remaining arguments should be zero or more of @code{foo} and
|
|
@code{bar}, use this customization type:
|
|
|
|
@example
|
|
(list (const t) (set :inline t foo bar))
|
|
@end example
|
|
|
|
@noindent
|
|
This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
|
|
and @code{(t foo bar)}.
|
|
|
|
When the element-type is a @code{choice}, you use @code{:inline} not
|
|
in the @code{choice} itself, but in (some of) the alternatives of the
|
|
@code{choice}. For example, to match a list which must start with a
|
|
file name, followed either by the symbol @code{t} or two strings, use
|
|
this customization type:
|
|
|
|
@example
|
|
(list file
|
|
(choice (const t)
|
|
(list :inline t string string)))
|
|
@end example
|
|
|
|
@noindent
|
|
If the user chooses the first alternative in the choice, then the
|
|
overall list has two elements and the second element is @code{t}. If
|
|
the user chooses the second alternative, then the overall list has three
|
|
elements and the second and third must be strings.
|
|
|
|
@node Type Keywords
|
|
@subsection 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:
|
|
|
|
@table @code
|
|
@item :value @var{default}
|
|
This is used for a type that appears as an alternative inside of
|
|
@code{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 @var{default}.
|
|
|
|
If @code{nil} is not a valid value for the alternative, then it is
|
|
essential to specify a valid default with @code{:value}.
|
|
|
|
@item :format @var{format-string}
|
|
This string will be inserted in the buffer to represent the value
|
|
corresponding to the type. The following @samp{%} escapes are available
|
|
for use in @var{format-string}:
|
|
|
|
@table @samp
|
|
@item %[@var{button}%]
|
|
Display the text @var{button} marked as a button. The @code{: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.
|
|
|
|
@item %@{@var{sample}%@}
|
|
Show @var{sample} in a special face specified by @code{:sample-face}.
|
|
|
|
@item %v
|
|
Substitute the item's value. How the value is represented depends on
|
|
the kind of item, and (for variables) on the customization type.
|
|
|
|
@item %d
|
|
Substitute the item's documentation string.
|
|
|
|
@item %h
|
|
Like @samp{%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.
|
|
|
|
@item %t
|
|
Substitute the tag here. You specify the tag with the @code{:tag}
|
|
keyword.
|
|
|
|
@item %%
|
|
Display a literal @samp{%}.
|
|
@end table
|
|
|
|
@item :action @var{action}
|
|
Perform @var{action} if the user clicks on a button.
|
|
|
|
@item :button-face @var{face}
|
|
Use the face @var{face} (a face name or a list of face names) for button
|
|
text displayed with @samp{%[@dots{}%]}.
|
|
|
|
@item :button-prefix @var{prefix}
|
|
@itemx :button-suffix @var{suffix}
|
|
These specify the text to display before and after a button.
|
|
Each can be:
|
|
|
|
@table @asis
|
|
@item @code{nil}
|
|
No text is inserted.
|
|
|
|
@item a string
|
|
The string is inserted literally.
|
|
|
|
@item a symbol
|
|
The symbol's value is used.
|
|
@end table
|
|
|
|
@item :tag @var{tag}
|
|
Use @var{tag} (a string) as the tag for the value (or part of the value)
|
|
that corresponds to this type.
|
|
|
|
@item :doc @var{doc}
|
|
Use @var{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 @code{:format}, and use @samp{%d} or @samp{%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
|
|
@code{:choice} type or the parts of some other composite type.
|
|
|
|
@item :help-echo @var{motion-doc}
|
|
When you move to this item with @code{widget-forward} or
|
|
@code{widget-backward}, it will display the string @var{motion-doc}
|
|
in the echo area.
|
|
|
|
@item :match @var{function}
|
|
Specify how to decide whether a value matches the type. The
|
|
corresponding value, @var{function}, should be a function that accepts
|
|
two arguments, a widget and a value; it should return non-@code{nil} if
|
|
the value is acceptable.
|
|
|
|
@ignore
|
|
@item :indent @var{columns}
|
|
Indent this item by @var{columns} columns. The indentation is used for
|
|
@samp{%n}, and automatically for group names, for checklists and radio
|
|
buttons, and for editable lists. It affects the whole of the
|
|
item except for the first line.
|
|
|
|
@item :offset @var{columns}
|
|
An integer indicating how many extra spaces to indent the subitems of
|
|
this item. By default, subitems are indented the same as their parent.
|
|
|
|
@item :extra-offset
|
|
An integer indicating how many extra spaces to add to this item's
|
|
indentation, compared to its parent.
|
|
|
|
@item :notify
|
|
A function called each time the item or a subitem is changed. The
|
|
function is called with two or three arguments. The first argument is
|
|
the item itself, the second argument is the item that was changed, and
|
|
the third argument is the event leading to the change, if any.
|
|
|
|
@item :menu-tag
|
|
Tag used in the menu when the widget is used as an option in a
|
|
@code{menu-choice} widget.
|
|
|
|
@item :menu-tag-get
|
|
Function used for finding the tag when the widget is used as an option
|
|
in a @code{menu-choice} widget. By default, the tag used will be either the
|
|
@code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
|
|
representation of the @code{:value} property if not.
|
|
|
|
@item :validate
|
|
A function which takes a widget as an argument, and return nil if the
|
|
widgets current value is valid for the widget. Otherwise, it should
|
|
return the widget containing the invalid data, and set that widgets
|
|
@code{:error} property to a string explaining the error.
|
|
|
|
You can use the function @code{widget-children-validate} for this job;
|
|
it tests that all children of @var{widget} are valid.
|
|
|
|
@item :tab-order
|
|
Specify the order in which widgets are traversed with
|
|
@code{widget-forward} or @code{widget-backward}. This is only partially
|
|
implemented.
|
|
|
|
@enumerate a
|
|
@item
|
|
Widgets with tabbing order @code{-1} are ignored.
|
|
|
|
@item
|
|
(Unimplemented) When on a widget with tabbing order @var{n}, go to the
|
|
next widget in the buffer with tabbing order @var{n+1} or @code{nil},
|
|
whichever comes first.
|
|
|
|
@item
|
|
When on a widget with no tabbing order specified, go to the next widget
|
|
in the buffer with a positive tabbing order, or @code{nil}
|
|
@end enumerate
|
|
|
|
@item :parent
|
|
The parent of a nested widget (e.g., a @code{menu-choice} item or an
|
|
element of a @code{editable-list} widget).
|
|
|
|
@item :sibling-args
|
|
This keyword is only used for members of a @code{radio-button-choice} or
|
|
@code{checklist}. The value should be a list of extra keyword
|
|
arguments, which will be used when creating the @code{radio-button} or
|
|
@code{checkbox} associated with this item.
|
|
@end ignore
|
|
@end table
|