X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/ba69b876ac836a88877dab99e6fc2352dd36c855..9e375bf0716af60e50aef49a9dc5ef085ab31a8c:/doc/lispref/customize.texi diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 7c723a29f2..01a4feb1fe 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -1,7 +1,7 @@ @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, 2009 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/customize @node Customization, Loading, Macros, Top @@ -40,13 +40,7 @@ display one name. 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} @@ -266,12 +260,14 @@ turn this feature back on, if someone would like to do the work. 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 @@ -302,6 +298,12 @@ mode (@code{eval-defun}), a special feature of @code{eval-defun} 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: @@ -395,11 +397,13 @@ variables and functions will be defined, so there will not be an error. @item :risky @var{value} @kindex risky@r{, @code{defcustom} keyword} -Set this variable's @code{risky-local-variable} property to @var{value}. +Set this 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 this variable's @code{safe-local-variable} property to @var{function}. +Set this 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} @@ -410,11 +414,11 @@ setting this variable until after those others have been handled. Use 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 @@ -448,9 +452,27 @@ of @var{symbol}. 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 @@ -481,12 +503,15 @@ sections. After this symbol come a number of arguments, depending on 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:: @@ -495,9 +520,6 @@ equivalent to @code{(string)}. * 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 @@ -755,6 +777,11 @@ string, and the third a function. 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}. @@ -1116,6 +1143,13 @@ corresponding value, @var{function}, should be a function that accepts 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 @@ -1123,23 +1157,24 @@ 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 @@ -1147,15 +1182,6 @@ 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 @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