@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003, 2004,
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
definitions---as well as face definitions (@pxref{Defining Faces}).
@menu
-* Common Keywords::
-* Group Definitions::
-* Variable Definitions::
-* Customization Types::
+* Common Keywords:: Common keyword arguments for all kinds of
+ customization declarations.
+* Group Definitions:: Writing customization group definitions.
+* Variable Definitions:: Declaring user options.
+* Customization Types:: Specifying the type of a user option.
@end menu
@node Common Keywords
-@section Common Keywords for All Kinds of Items
+@section Common Item Keywords
All kinds of customization declarations (for variables and groups, and
for faces) accept keyword arguments for specifying various information.
display one name.
@table @code
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
+@item :tag @var{label}
+Use @var{label}, a string, instead of the item's name, to label the
+item in customization menus and buffers. @strong{Don't use a tag
+which is substantially different from the item's real name; that would
+cause confusion.} One legitimate case for use of @code{:tag} is to
+specify a dash where normally a hyphen would be converted to a space:
+
+@example
+(defcustom cursor-in-non-selected-windows @dots{}
+ :tag "Cursor In Non-selected Windows"
+@end example
@item :group @var{group}
Put this customization item in group @var{group}. When you use
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!
+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}:
+There are several 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.
+@samp{[Manual]} in the customization buffer and enters the built-in
+Info reader on @var{info-node}.
@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}.
+Link to a web page; @var{url} is a string which specifies the
+@acronym{URL}. The link appears in the customization buffer as
+@var{url} and invokes the WWW browser specified by
+@code{browse-url-browser-function}.
+
+@item (emacs-commentary-link @var{library})
+Link to the commentary section of a library; @var{library} is a string
+which specifies the library name.
+
+@item (emacs-library-link @var{library})
+Link to an Emacs Lisp library file; @var{library} is a string which
+specifies the library name.
+
+@item (file-link @var{file})
+Link to a file; @var{file} is a string which specifies the name of the
+file to visit with @code{find-file} when the user invokes this link.
+
+@item (function-link @var{function})
+Link to the documentation of a function; @var{function} is a string
+which specifies the name of the function to describe with
+@code{describe-function} when the user invokes this link.
+
+@item (variable-link @var{variable})
+Link to the documentation of a variable; @var{variable} is a string
+which specifies the name of the variable to describe with
+@code{describe-variable} when the user invokes this link.
+
+@item (custom-group-link @var{group})
+Link to another customization group. Invoking it creates a new
+customization buffer for @var{group}.
@end table
You can specify the text to use in the customization buffer by adding
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}.
+Execute @code{(require '@var{feature})} when your saved customizations
+set the value of this item. @var{feature} should be a symbol.
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.
+
+@item :version @var{version}
+This option specifies that the item was first introduced in Emacs
+version @var{version}, or that its default value was changed in that
+version. The value @var{version} must be a string.
+
+@item :package-version '(@var{package} . @var{version})
+This option specifies that the item was first introduced in
+@var{package} version @var{version}, or that its default value was
+changed in that version. This keyword takes priority over :version.
+The value of @var{package} is a symbol and @var{version} is a string.
+The @var{package} and @var{version} must appear in the alist
+@code{customize-package-emacs-version-alist}. Since @var{package} must
+be unique and the user might see it in an error message, a good choice
+is the official name of the package, such as MH-E or Gnus.
+
@end table
+Packages that use the @code{:package-version} keyword must also update
+the @code{customize-package-emacs-version-alist} variable.
+
+@defvar customize-package-emacs-version-alist
+This alist provides a mapping for the versions of Emacs that are
+associated with versions of a package listed in the
+@code{:package-version} keyword. Its elements look like this:
+
+@example
+(@var{package} (@var{pversion} . @var{eversion})@dots{})
+@end example
+
+For each @var{package}, which is a symbol, there are one or more
+elements that contain a package version @var{pversion} with an
+associated Emacs version @var{eversion}. These versions are strings.
+For example, the MH-E package updates this alist with the following:
+
+@smallexample
+(add-to-list 'customize-package-emacs-version-alist
+ '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
+ ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
+ ("7.4" . "22.1") ("8.0" . "22.1")))
+@end smallexample
+
+The value of @var{package} needs to be unique and it needs to match
+the @var{package} value appearing in the @code{:package-version}
+keyword. Since the user might see the value in a error message, a good
+choice is the official name of the package, such as MH-E or Gnus.
+@end defvar
+
@node Group Definitions
@section Defining Custom Groups
The way to declare new customization groups is with @code{defgroup}.
-@defmac defgroup group members doc [keyword value]...
-@tindex defgroup
+@defmac defgroup group members doc [keyword value]@dots{}
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.
Useful widgets are @code{custom-variable} for a variable,
@code{custom-face} for a face, and @code{custom-group} for a group.
+When you introduce a new group into Emacs, use the @code{:version}
+keyword in the @code{defgroup}; then you need not use it for
+the individual members of the group.
+
In addition to the common keywords (@pxref{Common Keywords}), you can
-use this keyword in @code{defgroup}:
+also use this keyword in @code{defgroup}:
@table @code
@item :prefix @var{prefix}
Use @code{defcustom} to declare user-editable variables.
-@defmac defcustom option default doc [keyword value]...
-@tindex defcustom
+@defmac defcustom option default doc [keyword value]@dots{}
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.
+string for the variable. There is no need to start it with a @samp{*}
+because @code{defcustom} automatically marks @var{option} as a
+@dfn{user option} (@pxref{Defining Variables}).
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.
+than one occasion. You should normally avoid using backquotes in
+@var{default} because they are not expanded when editing the value,
+causing list values to appear to have the wrong structure.
+
+If you specify the @code{:set} option, to make the variable take other
+special actions when set through the customization buffer, the
+variable's documentation string should tell the user specifically how
+to do the same job in hand-written Lisp code.
+
+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
-The following additional keywords are accepted:
+ @code{defcustom} accepts the following additional keywords:
@table @code
@item :type @var{type}
@item :options @var{list}
Specify @var{list} as the list of reasonable values for use in this
-option.
-
-Currently this is meaningful only when the type is @code{hook}. In that
-case, the elements of @var{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.
-
-@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,
+option. The user is not restricted to using only these values, but they
+are offered as convenient alternatives.
-@example
-(defcustom foo-max 34
- "*Maximum number of foo's allowed."
- :type 'integer
- :group 'foo
- :version "20.3")
-@end example
+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 :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}.
+Specify @var{setfunction} as the way to change the value of this
+option. The function @var{setfunction} should take two arguments, a
+symbol (the option name) 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}.
+symbol, and should return whatever customize should use as the
+``current value'' for that symbol (which need not be the symbol's Lisp
+value). The default is @code{default-value}.
+
+You have to really understand the workings of Custom to use
+@code{:get} correctly. It is meant for values that are treated in
+Custom as variables but are not actually stored in Lisp variables. It
+is almost surely a mistake to specify @code{getfunction} for a value
+that really is stored in a Lisp variable.
@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:
+@var{function} should be a function used to initialize the variable
+when the @code{defcustom} is evaluated. It should take two arguments,
+the option name (a symbol) and the 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.
+do not reinitialize it if it is already non-void.
@item custom-initialize-default
Like @code{custom-initialize-set}, but use the function
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}
+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).
+This is the default @code{:initialize} function.
@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}.
+
+@item custom-initialize-safe-set
+@itemx custom-initialize-safe-default
+These functions behave like @code{custom-initialize-set}
+(@code{custom-initialize-default}, respectively), but catch errors.
+If an error occurs during initialization, they set the variable to
+@code{nil} using @code{set-default}, and throw no error.
+
+These two functions are only meant for options defined in pre-loaded
+files, where some variables or functions used to compute the option's
+value may not yet be defined. The option normally gets updated in
+@file{startup.el}, ignoring the previously computed value. Because of
+this typical usage, the value which these two functions compute
+normally only matters when, after startup, one unsets the option's
+value and then reevaluates the defcustom. By that time, the necessary
+variables and functions will be defined, so there will not be an error.
@end table
+
+@item :set-after @var{variables}
+When setting variables according to saved customizations, make sure to
+set the variables @var{variables} before this one; in other words, delay
+setting this variable until after those others have been handled. Use
+@code{:set-after} if setting this variable won't work properly unless
+those other variables already have their intended values.
@end table
-@end defmac
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}:
+Keywords}. Here is an example, from the library @file{saveplace.el}:
@example
-(defcustom show-paren-mode nil
- "Toggle Show Paren mode@enddots{}"
- :set (lambda (symbol value)
- (show-paren-mode (or value 0)))
- :initialize 'custom-initialize-default
+(defcustom save-place nil
+ "*Non-nil means automatically save place in each file..."
:type 'boolean
- :group 'paren-showing
- :require 'paren)
+ :require 'saveplace
+ :group 'save-place)
@end example
-@ignore
-Use @code{custom-add-option} to specify that a specific function is
-useful as an member of a hook.
+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 variable @var{symbol} add @var{option}.
+To the customization @var{symbol}, add @var{option}.
-If @var{symbol} is a hook variable, @var{option} should be a hook
-member. For other types variables, the effect is undefined."
+The precise effect of adding @var{option} depends on the customization
+type of @var{symbol}.
@end defun
-@end ignore
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.
+customization buffer. Both properties are actually lists whose car is
+an expression which evaluates to the value.
@node Customization Types
@section Customization Types
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:
+@code{:type} keyword. The argument of @code{:type} is evaluated, but
+only once when the @code{defcustom} is executed, so it isn't useful
+for the value to vary. Normally we use a quoted constant. For
+example:
@example
(defcustom diff-command "diff"
* Composite Types::
* Splicing into Lists::
* Type Keywords::
+* Defining New Types::
@end menu
+All customization types are implemented as widgets; see @ref{Top, ,
+Introduction, widget, The Emacs Widget Library}, for details.
+
@node Simple Types
@subsection Simple Types
in the customization buffer.
@item number
-The value must be a number, and is represented textually in the
-customization buffer.
+The value must be a number (floating point or integer), and is
+represented textually in the customization buffer.
+
+@item float
+The value must be a floating point number, and is represented
+textually in the customization buffer.
@item string
The value must be a string, and the customization buffer shows just the
@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.
+
+Similarly, 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 basic info about people.
+Each element has the form (NAME AGE MALE-FLAG)."
+ :type '(alist :value-type (group integer 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)))
+@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.
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.
+
+@item coding-system
+The value must be a coding-system name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item color
+The value must be a valid color name, and you can do completion with
+@kbd{M-@key{TAB}}. A sample is provided.
@end table
@node Composite Types
@subsection Composite Types
+@cindex arguments (of composite type)
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,
+types, which build new types from other types or from specified data.
+The specified types or data are called the @dfn{arguments} of the
+composite type. The composite type normally looks like this:
@example
-(restricted-sexp :match-alternatives
- (integerp 't 'nil))
+(@var{constructor} @var{arguments}@dots{})
@end example
@noindent
-allows integers, @code{t} and @code{nil} as legitimate values.
+but you can also add keyword-value pairs before the arguments, like
+this:
-The customization buffer shows all legitimate values using their read
-syntax, and the user edits them textually.
+@example
+(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
+@end example
+ Here is a table of constructors and how to use them to write
+composite types:
+
+@table @code
@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
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}...)
+@item (choice @var{alternative-types}@dots{})
The value must fit at least one of @var{alternative-types}.
For example, @code{(choice integer string)} allows either an
integer or a string.
@end example
@noindent
-so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
+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}.
+If some values are covered by more than one of the alternatives,
+customize will choose the first alternative that the value fits. This
+means you should always list the most specific types first, and the
+most general last. Here's an example of proper usage:
+
+@example
+(choice (const :tag "Off" nil)
+ symbol (sexp :tag "Other"))
+@end example
+
+@noindent
+This way, the special value @code{nil} is not treated like other
+symbols, and symbols are not treated like other Lisp expressions.
+
+@item (radio @var{element-types}@dots{})
+This is similar to @code{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
+(@code{function-item} customization types).
+
@item (const @var{value})
The value must be @var{value}---nothing else is allowed.
(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.
documentation string is either the one you specify with @code{:doc}, or
@var{variable}'s own documentation string.
-@item (set @var{elements}@dots{})
-The value must be a list and each element of the list must be one of the
-@var{elements} specified. This appears in the customization buffer as a
-checklist.
+@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.
+
+@item (restricted-sexp :match-alternatives @var{criteria})
+This is the most general composite type construct. 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.
+@end table
+
+ Here is a table of the keywords you can use in keyword-value pairs
+in a composite type:
+
+@table @code
+@item :tag @var{tag}
+Use @var{tag} as the name of this alternative, for user communication
+purposes. This is useful for a type that appears inside of a
+@code{choice}.
+
+@item :match-alternatives @var{criteria}
+Use @var{criteria} to match possible values. This is used only in
+@code{restricted-sexp}.
+
+@item :args @var{argument-list}
+Use the elements of @var{argument-list} as the arguments of the type
+construct. For instance, @code{(const :args (foo))} is equivalent to
+@code{(const foo)}. You rarely need to write @code{:args} explicitly,
+because normally the arguments are recognized automatically as
+whatever follows the last keyword-value pair.
@end table
@node Splicing into Lists
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}
+ For example, to specify a list whose first element must be @code{baz}
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))
+(list (const baz) (set :inline t (const foo) (const bar)))
@end example
@noindent
-This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
-and @code{(t foo bar)}.
+This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
+and @code{(baz 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
keyword.
@item %%
-Display a literal @samp{%}.
+Display a literal @samp{%}.
@end table
@item :action @var{action}
@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.
+@code{widget-backward}, it will display the string @var{motion-doc} in
+the echo area. In addition, @var{motion-doc} is used as the mouse
+@code{help-echo} string and may actually be a function or form evaluated
+to yield a help string. If it is a function, it is called with one
+argument, the widget.
@item :match @var{function}
Specify how to decide whether a value matches the type. The
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
+A 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
+A 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.
+A function which takes a widget as an argument, and return @code{nil}
+if the widget's current value is valid for the widget. Otherwise, it
+should return the widget containing the invalid data, and set that
+widget's @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
Widgets with tabbing order @code{-1} are ignored.
-@item
+@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.
@code{checkbox} associated with this item.
@end ignore
@end table
+
+@node Defining New Types
+@subsection Defining New Types
+
+In the previous sections we have described how to construct elaborate
+type specifications for @code{defcustom}. In some cases you may want
+to give such a type specification a name. The obvious case is when
+you are using the same type for many user options: rather than repeat
+the specification for each option, you can give the type specification
+a name, and use that name each @code{defcustom}. The other case is
+when a user option's value is a recursive data structure. To make it
+possible for a datatype to refer to itself, it needs to have a name.
+
+Since custom types are implemented as widgets, the way to define a new
+customize type is to define a new widget. We are not going to describe
+the widget interface here in details, see @ref{Top, , Introduction,
+widget, The Emacs Widget Library}, for that. Instead we are going to
+demonstrate the minimal functionality needed for defining new customize
+types by a simple example.
+
+@example
+(define-widget 'binary-tree-of-string 'lazy
+ "A binary tree made of cons-cells and strings."
+ :offset 4
+ :tag "Node"
+ :type '(choice (string :tag "Leaf" :value "")
+ (cons :tag "Interior"
+ :value ("" . "")
+ binary-tree-of-string
+ binary-tree-of-string)))
+
+(defcustom foo-bar ""
+ "Sample variable holding a binary tree of strings."
+ :type 'binary-tree-of-string)
+@end example
+
+The function to define a new widget is called @code{define-widget}. The
+first argument is the symbol we want to make a new widget type. The
+second argument is a symbol representing an existing widget, the new
+widget is going to be defined in terms of difference from the existing
+widget. For the purpose of defining new customization types, the
+@code{lazy} widget is perfect, because it accepts a @code{:type} keyword
+argument with the same syntax as the keyword argument to
+@code{defcustom} with the same name. The third argument is a
+documentation string for the new widget. You will be able to see that
+string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
+@key{RET}} command.
+
+After these mandatory arguments follow the keyword arguments. The most
+important is @code{:type}, which describes the data type we want to match
+with this widget. Here a @code{binary-tree-of-string} is described as
+being either a string, or a cons-cell whose car and cdr are themselves
+both @code{binary-tree-of-string}. Note the reference to the widget
+type we are currently in the process of defining. The @code{:tag}
+attribute is a string to name the widget in the user interface, and the
+@code{:offset} argument is there to ensure that child nodes are
+indented four spaces relative to the parent node, making the tree
+structure apparent in the customization buffer.
+
+The @code{defcustom} shows how the new widget can be used as an ordinary
+customization type.
+
+The reason for the name @code{lazy} is that the other composite
+widgets convert their inferior widgets to internal form when the
+widget is instantiated in a buffer. This conversion is recursive, so
+the inferior widgets will convert @emph{their} inferior widgets. If
+the data structure is itself recursive, this conversion is an infinite
+recursion. The @code{lazy} widget prevents the recursion: it convert
+its @code{:type} argument only when needed.
+
+@ignore
+ arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
+@end ignore