@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
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 four alternatives you can use for @var{link-data}:
@table @code
@item (custom-manual @var{info-node})
Useful widgets are @code{custom-variable} for a variable,
@code{custom-face} for a face, and @code{custom-group} for a group.
+When a new group is introduced into Emacs, use this keyword in
+@code{defgroup}:
+
+@table @code
+@item :version @var{version}
+This option specifies that the group was first introduced in Emacs
+version @var{version}. The value @var{version} must be a string.
+@end table
+
+Tag the group with a version like this when it is introduced, rather
+than the individual members (@pxref{Variable Definitions}).
+
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]...
+@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; it should normally start with a @samp{*}. This
-marks the variable, for other purposes, as one that users may want to
-customize.
+string for the variable. It should often start with a @samp{*} to mark
+it as a @dfn{user option} (@pxref{Defining Variables}). Do not start
+the documentation string with @samp{*} for options which cannot or
+normally should not be set with @code{set-variable}; examples of the
+former are global minor mode options such as
+@code{global-font-lock-mode} and examples of the latter are hooks.
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.
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}
@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
@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
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"
* Type Keywords::
@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
@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.
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.
@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{argumentlist}
+Use the elements of @var{argumentlist} 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
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.