@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 Copyright (C) 1997-2011 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../info/customize
+@setfilename ../../info/customize
@node Customization, Loading, Macros, Top
@chapter Writing Customization Definitions
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
+cause confusion.}
@kindex group@r{, customization keyword}
@item :group @var{group}
@item :load @var{file}
@kindex load@r{, customization keyword}
Load file @var{file} (a string) before displaying this customization
-item. Loading is done with @code{load-library}, and only if the file is
-not already loaded.
+item (@pxref{Loading}). Loading is done with @code{load}, and only if
+the file is not already loaded.
@item :require @var{feature}
@kindex require@r{, customization keyword}
Use @code{defcustom} to declare user-customizable variables.
@defmac defcustom option standard doc [keyword value]@dots{}
-This construct declares @var{option} as a customizable user option
-variable. You should 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}).
+This macro declares @var{option} as a customizable @dfn{user option}.
+You should not quote @var{option}.
+
+This causes the function @code{user-variable-p} to return @code{t}
+when given @var{option} as an argument. @xref{Defining Variables}.
+The argument @var{doc} specifies the documentation string for the
+variable. (Note that there is no need to start @var{doc} with a
+@samp{*}.)
The argument @var{standard} is an expression that specifies the
standard value for @var{option}. Evaluating the @code{defcustom} form
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:
variables and functions will be defined, so there will not be an error.
@end table
+@item :risky @var{value}
+@kindex risky@r{, @code{defcustom} keyword}
+Set the variable's @code{risky-local-variable} property to
+@var{value} (@pxref{File Local Variables}).
+
+@item :safe @var{function}
+@kindex safe@r{, @code{defcustom} keyword}
+Set the variable's @code{safe-local-variable} property to
+@var{function} (@pxref{File Local Variables}).
+
@item :set-after @var{variables}
@kindex set-after@r{, @code{defcustom} keyword}
When setting variables according to saved customizations, make sure to
those other variables already have their intended values.
@end table
- The @code{:require} keyword 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. You can do that with @code{:require}. @xref{Common
-Keywords}. Here is an example, from the library @file{saveplace.el}:
+ It is useful to specify the @code{:require} keyword for an option
+that ``turns on'' a certain feature. This causes Emacs to load the
+feature, if it is not already loaded, whenever the option is set.
+@xref{Common Keywords}. Here is an example, from the library
+@file{saveplace.el}:
@example
(defcustom save-place nil
Internally, @code{defcustom} uses the symbol property
@code{standard-value} to record the expression for the standard value,
-and @code{saved-value} to record the value saved by the user with the
-customization buffer. Both properties are actually lists whose car is
-an expression which evaluates to the value.
+@code{saved-value} to record the value saved by the user with the
+customization buffer, and @code{customized-value} to record the value
+set by the user with the customization buffer, but not saved.
+@xref{Property Lists}. These properties are lists, the car of which
+is an expression that evaluates to the value.
+
+@defun custom-reevaluate-setting symbol
+This function re-evaluates the standard value of @var{symbol}, which
+should be a user option 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.
+
+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
the symbol. Between the type symbol and its arguments, you can
optionally write keyword-value pairs (@pxref{Type Keywords}).
- Some of the type symbols do not use any arguments; those are called
+ Some 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)}.
+ All customization types are implemented as widgets; see @ref{Top, ,
+Introduction, widget, The Emacs Widget Library}, for details.
+
@menu
-* Simple Types::
-* Composite Types::
-* Splicing into Lists::
-* Type Keywords::
-* Defining New Types::
+* Simple Types:: Simple customization types: sexp, integer, number,
+ string, file, directory, alist.
+* Composite Types:: Build new types from other types or data.
+* Splicing into Lists:: Splice elements into list with @code{:inline}.
+* Type Keywords:: Keyword-argument pairs in a customization type.
+* Defining New Types:: Give your type a name.
@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
@node Composite Types
@subsection Composite Types
-@cindex Composite Types (customization)
+@cindex composite types (customization)
When none of the simple types is appropriate, you can use composite
types, which build new types from other types or from specified data.
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
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
HCoop / bpt / emacs.git / blobdiff