@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003, 2004,
+@c 2005 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
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.
@end table
@node Group Definitions
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}).
+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
also use this keyword in @code{defgroup}:
@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
@code{hook}, @code{plist} and @code{alist}. See the definition of the
individual types for a description of how to use @code{:options}.
-@item :version @var{version}
-This option specifies that the variable was first introduced, or its
-default value was changed, in Emacs version @var{version}. The value
-@var{version} must be a string. For example,
-
-@example
-(defcustom foo-max 34
- "*Maximum number of foo's allowed."
- :type 'integer
- :group 'foo
- :version "20.3")
-@end example
-
@item :set @var{setfunction}
-Specify @var{setfunction} as the way to change the value of this option.
-The function @var{setfunction} should take two arguments, a symbol and
-the new value, and should do whatever is necessary to update the value
-properly for this option (which may not mean simply setting the option
-as a Lisp variable). The default for @var{setfunction} is
-@code{set-default}.
+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
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 @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}
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..."
- :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
If a customization item has a type such as @code{hook} or @code{alist},
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
The @code{group} widget is used here instead of @code{list} only because
the formatting is better suited for the purpose.
-Similarily, you can have alists with more values associated with each
+Similarly, you can have alists with more values associated with each
key, using variations of this trick:
@smallexample
("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)))
+ :type '(alist :value-type (group integer boolean)))
(defcustom pets '(("brian")
("dorith" "dog" "guppy")
@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
most general last. Here's an example of proper usage:
@example
-(choice (const :tag "Off" nil) symbol (sexp :tag "Other"))
+(choice (const :tag "Off" nil)
+ symbol (sexp :tag "Other"))
@end example
@noindent
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
+@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
@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.
-@c @xref{Text help-echo}.
+@xref{Text help-echo}.
@item :match @var{function}
Specify how to decide whether a value matches the type. The
@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
+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
:type 'binary-tree-of-string)
@end example
-The function to define a new widget is name @code{define-widget}. The
+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 accept a @code{:type} keyword
+@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.
+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
+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 are there to ensure that child nodes are
-indented four spaces relatively to the parent node, making the tree
+@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.
-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.
+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