@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998, 1999 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
@menu
* Common Keywords::
-* Group Definitions::
-* Variable Definitions::
+* Group Definitions::
+* Variable Definitions::
* Customization Types::
@end menu
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})
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}.
+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}.
+
+@item (emacs-commentary-link @var{library})
+Link to the commentary section of a library; @var{library} is a string
+which specifies the library name.
@end table
You can specify the text to use in the customization buffer by adding
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"
* 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
@end smallexample
@noindent
-instead of
+instead of
@smallexample
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
key, using variations of this trick:
@smallexample
-(defcustom person-data '(("brian" 50 t)
+(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 age boolean)))
-(defcustom pets '(("brian")
+(defcustom pets '(("brian")
("dorith" "dog" "guppy")
("ken" "cat"))
"Alist of people's pets.
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.
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
keyword.
@item %%
-Display a literal @samp{%}.
+Display a literal @samp{%}.
@end table
@item :action @var{action}
@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 as for @code{help-echo} text properties.
-@xref{Text help-echo}.
+to yield a help string. If it is a function, it is called with one
+argument, the widget.
+@c @xref{Text help-echo}.
@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 once, and use that name each @code{defcustom}. The other case is
+when a user option accept a recursive datastructure. 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 name @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 accept 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 follows the keyword arguments. The most
+important is @code{:type}, which describes the datatype 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 are there to ensure that child nodes are
+indented four spaces relatively 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.
+
+If you wonder about the name @code{lazy}, know 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
+datastructure is itself recursive, this conversion will go on forever,
+or at least until Emacs run out of stack space. The @code{lazy} widget
+stop this recursion, it will only convert its @code{:type} argument when
+needed.
+
+@ignore
+ arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
+@end ignore