@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
+@c 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/customize
@node Customization, Loading, Macros, Top
arranges to set the variable unconditionally, without testing whether
its value is void. (The same feature applies to @code{defvar}.)
@xref{Defining Variables}.
+
+If you put a @code{defcustom} in a file that is preloaded at dump time
+(@pxref{Building Emacs}), and the standard value installed for the
+variable at that time might not be correct, use
+@code{custom-reevaluate-setting}, described below, to re-evaluate the
+standard value during or after Emacs startup.
@end defmac
@code{defcustom} accepts the following additional keywords:
customization buffer. Both properties are actually lists whose car is
an expression which evaluates to the value.
+@defun custom-reevaluate-setting symbol
+This function re-evaluates the standard value of a user-customizable
+variable declared via @code{defcustom}. (If the variable was
+customized, this function re-evaluates the saved value instead.) This
+is useful for customizable options that are defined before their value
+could be computed correctly, such as variables defined in packages
+that are loaded at dump time, but depend on the run-time information.
+For example, the value could be a file whose precise name depends on
+the hierarchy of files when Emacs runs, or a name of a program that
+needs to be searched at run time.
+
+The argument @var{symbol} is the symbol of the variable whose value
+you want to re-evaluate.
+
+A good place to put calls to this function is in the function
+@code{command-line} that is run during startup (@pxref{Startup Summary})
+or in the various hooks it calls.
+@end defun
+
@node Customization Types
@section Customization Types
In the customization buffer, each element is displayed and edited
separately, according to the type specified for it.
+@item (group @var{element-types}@dots{})
+This works like @code{list} except for the formatting
+of text in the Custom buffer. @code{list} labels each
+element value with its tag; @code{group} does not.
+
@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}.
two arguments, a widget and a value; it should return non-@code{nil} if
the value is acceptable.
+@item :validate @var{function}
+Specify a validation function for input. @var{function} takes a
+widget as an argument, and should 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.
+
@ignore
@item :indent @var{columns}
Indent this item by @var{columns} columns. The indentation is used for
buttons, and for editable lists. It affects the whole of the
item except for the first line.
-@item :offset @var{columns}
-An integer indicating how many extra spaces to indent the subitems of
-this item. By default, subitems are indented the same as their parent.
+@item :offset @var{extra}
+Indent the subitems of this item @var{extra} columns more than this
+item itself. By default, subitems are indented the same as their
+parent.
-@item :extra-offset
-An integer indicating how many extra spaces to add to this item's
-indentation, compared to its parent.
+@item :extra-offset @var{n}
+Add @var{n} extra spaces to this item's indentation, compared to its
+parent's indentation.
-@item :notify
-A function called each time the item or a subitem is changed. The
-function is called with two or three arguments. The first argument is
-the item itself, the second argument is the item that was changed, and
-the third argument is the event leading to the change, if any.
+@item :notify @var{function}
+Call @var{function} each time the item or a subitem is changed. The
+function gets two or three arguments. The first argument is the item
+itself, the second argument is the item that was changed, and the
+third argument is the event leading to the change, if any.
-@item :menu-tag
-A tag used in the menu when the widget is used as an option in a
-@code{menu-choice} widget.
+@item :menu-tag @var{tag-string}
+Use @var{tag-string} in the menu when the widget is used as an option
+in a @code{menu-choice} widget.
@item :menu-tag-get
A function used for finding the tag when the widget is used as an option
@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 @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 :tab-order
Specify the order in which widgets are traversed with
@code{widget-forward} or @code{widget-backward}. This is only partially
HCoop / bpt / emacs.git / blobdiff