@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998, 1999, 2000 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
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})
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
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
-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 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
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},
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.
+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))
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
-(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)))
+ :type '(alist :value-type (group integer boolean)))
-(defcustom pets '(("brian")
+(defcustom pets '(("brian")
("dorith" "dog" "guppy")
("ken" "cat"))
"Alist of people's pets.
@item color
The value must be a valid color name, and you can do completion with
-@kbd{M-@key{TAB}}. A sample is provided,
+@kbd{M-@key{TAB}}. A sample is provided.
@end table
@node Composite Types
@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
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
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
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.
-@c @xref{Text help-echo}.
+to yield a help string. If it is a function, it is called with one
+argument, the widget.
+@xref{Text help-echo}.
@item :match @var{function}
Specify how to decide whether a value matches the type. The
@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, 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
+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 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 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.
+
+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 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.
+
+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
+@end ignore
HCoop / bpt / emacs.git / blobdiff