@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
@chapter Writing Customization Definitions
-This chapter describes how to declare customization groups, variables,
-and faces. We use the term @dfn{customization item} to include all
-three of those. This has few examples, but please look at the file
-@file{cus-edit.el}, which contains many declarations you can learn from.
+ 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::
-* Face 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 three kinds of customization declarations (for groups, variables,
-and faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all three.
+ 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 item.
+ 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. @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
@code{:group} in a @code{defgroup}, it makes the new group a subgroup of
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 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 :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
+@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 @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
-Each Emacs Lisp package should have one main customization group which
+ 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
-have some of the options and faces in the package's main group alongside
+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. Type press @kbd{C-h p} to display a
-list of finder keywords; them choose some of them add your group to each
-of them, using the @code{:group} keyword.
+ 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}.
+ The way to declare new customization groups is with @code{defgroup}.
-@tindex defgroup
-@defmac defgroup group members doc [keyword value]...
+@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.
-The arguments @var{members} can be an alist whose elements specify
-members of the group; however, normally @var{members} is @code{nil}, and
-you specify the group's members by using the @code{:group} keyword when
-defining those members.
+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.
-@ignore
-@code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and
-@var{widget} is a widget for editing that symbol. Useful widgets are
-@code{custom-variable} for editing variables, @code{custom-face} for
-editing faces, and @code{custom-group} for editing groups.
-@end ignore
+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.
+
+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}
@end table
@end defmac
-The @code{:prefix} 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 they say that there was a
-common prefix for the option names in a library.
-
-In order to obtain good results with @code{:prefix}, it is 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 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.
-
-@tindex defcustom
-@defmac defcustom option value doc [keyword value]...
-Declare @var{option} as a customizable user option variable that
-defaults to @var{value}. Do not quote @var{option}. @var{value} should
-be an expression to compute the value; it will be be evaluated on more
-than one occasion.
-
-If @var{option} is void, @code{defcustom} initializes it to @var{value}.
-
-The argument @var{doc} specifies the documentation string for the variable.
+ Use @code{defcustom} to declare user-editable variables.
+
+@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. 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. 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 defined:
+ @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.
+option. The user is not restricted to using only these values, but they
+are offered as convenient alternatives.
-Currently this is meaningful only when type is @code{hook}. The
-elements of @var{list} are functions that you might likely want to use
-as elements of the hook value. The user is not actually restricted to
-using only these functions, but they are offered as convenient
-alternatives.
-
-@item :version @var{version}
-This option specifies that the variable's default value was changed in
-Emacs version @var{version}. For example,
-
-@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. Do
-not reinitialize it if it is already non-void. This is the default
-@code{:initialize} function.
+Use the variable's @code{:set} function to initialize the variable, but
+do not reinitialize it if it is already non-void.
@item custom-initialize-default
-Always use @code{set-default} to initialize the variable, even if some
-other @code{:set} function has been specified.
+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
-Even 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).
+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
-Like @code{custom-initialize-reset}, except use @code{set-default}
-(rather than the @code{:set} function) to initialize the variable if it
-is not bound and has not been set already.
+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 :require @var{feature}
-If the user saves a customized value for this item, them Emacs should do
-@code{(require @var{feature})} after installing the saved value.
+@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
-The place to use this feature is for an option that turns on the
+ 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. That is what @code{:require} is for.
-@end table
-@end defmac
+to be loaded. You can do that with @code{:require}. @xref{Common
+Keywords}. Here is an example, from the library @file{saveplace.el}:
-@ignore
-Use @code{custom-add-option} to specify that a specific function is
-useful as an member of a hook.
+@example
+(defcustom save-place nil
+ "*Non-nil means automatically save place in each file..."
+ :type 'boolean
+ :require 'saveplace
+ :group 'save-place)
+@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 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.
-
-@node Face Definitions
-@section Defining Faces
-
-Faces are declared with @code{defface}.
-
-@tindex defface
-@defmac defface face spec doc [keyword value]...
-Declare @var{face} as a customizable face that defaults according to
-@var{spec}. Do not quote the symbol @var{face}.
-
-@var{doc} is the face documentation.
-
-@var{spec} should be an alist whose elements have the form
-@code{(@var{display} @var{atts})} (see below). When @code{defface}
-executes, it defines the face according to @var{spec}, then uses any
-customizations saved in the @file{.emacs} file to override that
-specification.
-
-In each element of @var{spec}, @var{atts} is a list of face attributes
-and their values. The possible attributes are defined in the variable
-@code{custom-face-attributes}.
-
-The @var{display} part of an element of @var{spec} determines which
-frames the element applies to. If more than one element of @var{spec}
-matches a given frame, the first matching element is the only one used
-for that frame.
-
-If @var{display} is @code{t} in a @var{spec} element, that element
-matches all frames. (This means that any subsequent elements of
-@var{spec} are never used.)
-
-Alternatively, @var{display} can be an alist whose elements have the
-form @code{(@var{characteristic} @var{value}@dots{})}. Here
-@var{characteristic} specifies a way of classifying frames, and the
-@var{value}s are possible classifications which @var{display} should
-apply to. Here are the possible values of @var{characteristic}:
-
-@table @code
-@item type
-The kind of window system the frame uses---either @code{x}, @code{pc}
-(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
-@code{tty}.
-
-@item class
-What kinds of colors the frame supports---either @code{color},
-@code{grayscale}, or @code{mono}.
-
-@item background
-The kind of background--- either @code{light} or @code{dark}.
-@end table
-
-If an element of @var{display} specifies more than one
-@var{value} for a given @var{characteristic}, any of those values
-is acceptable. If an element of @var{display} has elements for
-more than one @var{characteristic}, then @var{each} characteristic
-of the frame must match one of the values specified for it.
-@end defmac
-
-Internally, @code{defface} uses the symbol property
-@code{face-defface-spec} to record the face attributes specified in
-@code{defface}, @code{saved-face} for the attributes saved by the user
-with the customization buffer, and @code{face-documentation} for the
-documentation string.
+customization buffer. Both properties are actually lists 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 indictaes (1)
+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 it is 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"
"*The command to use to run diff."
- :type 'string
+ :type '(string)
:group 'diff)
@end example
- In general, a customization type appears 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. Some of the type symbols do not use any
-arguments; those are called @dfn{simple types}.
-
- In between the type symbol and its arguments, you can optionally
-write keyword-value pairs. @xref{Type Keywords}.
+ 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}).
- For a simple type, if you do not use any keyword-value pairs, you can
-omit the parentheses around the type symbol. The above example does
-this, using just @code{string} as the customization type.
-But @code{(string)} would mean the same thing.
+ 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::
+* 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
-contents, with no @samp{"} characters or quoting with @samp{\}.
+contents, with no delimiting @samp{"} characters and no quoting with
+@samp{\}.
@item regexp
-The value must be a string which is a valid regular expression.
+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
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.
+
+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.
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}.
+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.
+
+@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 from simple 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 elements should be
-one of these possibilities:
-
-@itemize @bullet
-@item
-A predicate---that is, a function of one argument that returns non-@code{nil}
-if the argument fits a certain type. This means that objects of that type
-are acceptable.
-
-@item
-A quoted constant---that is, @code{'@var{object}}. This means that
-@var{object} 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{(const string
+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 buffeer, the @sc{car} and the @sc{cdr} are
+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.
three elements; the first element must be an integer, the second a
string, and the third a function.
-In the customization buffeer, the each element is displayed and edited
+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}...)
+@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.
an integer stands for a number of spaces, while a string is text to use
verbatim, you might write the customization type this way,
-@smallexample
+@example
(choice (integer :tag "Number of spaces")
(string :tag "Literal text"))
-@end smallexample
+@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.
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}.
+@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 of the function @var{function}
-as well as its name.
+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 of the variable @var{variable} as well
-as its name.
+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
-@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.
+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
@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
+@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
-@ignore
@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;
the button appears in, and the event.
There is no way to specify two different buttons with different
-actions; but perhaps there is no need for one.
-@end ignore
+actions.
@item %@{@var{sample}%@}
Show @var{sample} in a special face specified by @code{:sample-face}.
keyword.
@item %%
-Display a literal @samp{%}.
+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 face @var{face} for text displayed with @samp{%[@dots{}%]}.
+Use the face @var{face} (a face name or a list of face names) for button
+text displayed with @samp{%[@dots{}%]}.
-@item :button-prefix
-@itemx :button-suffix
+@item :button-prefix @var{prefix}
+@itemx :button-suffix @var{suffix}
These specify the text to display before and after a button.
Each can be:
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 item.
+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.
-@item :tag @var{tag}
-Use @var{tag} (a string) as the tag for this item.
+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.
+@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. @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.
+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}
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.
@end enumerate
@item :parent
-The parent of a nested widget (e.g. a @code{menu-choice} item or an
+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
@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