@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
@end menu
@node Common Keywords
-@section Common Keywords for All Kinds of Items
+@section Common Item Keywords
All kinds of customization declarations (for variables and groups, and
for faces) accept keyword arguments for specifying various information.
display one name.
@table @code
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
+@item :tag @var{label}
+Use @var{label}, a string, instead of the item's name, to label the item
in customization menus and buffers.
@item :group @var{group}
If you use this keyword more than once, you can put a single item into
more than one group. Displaying any of those groups will show this
-item. Be careful not to overdo this!
+item. Please don't overdo this, since the result would be annoying.
@item :link @var{link-data}
Include an external link after the documentation string for this item.
@item (url-link @var{url})
Link to a web page; @var{url} is a string which specifies the @sc{url}.
The link appears in the customization buffer as @var{url}.
+
+@item (emacs-commentary-link @var{library})
+Link to the commentary section of a library; @var{library} is a string
+which specifies the library name.
@end table
You can specify the text to use in the customization buffer by adding
The way to declare new customization groups is with @code{defgroup}.
@defmac defgroup group members doc [keyword value]...
-@tindex defgroup
Declare @var{group} as a customization group containing @var{members}.
Do not quote the symbol @var{group}. The argument @var{doc} specifies
-the documentation string for the group.
+the documentation string for the group. It should not start with a
+@samp{*} as in @code{defcustom}; that convention is for variables only.
The argument @var{members} is a list specifying an initial set of
customization items to be members of the group. However, most often
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}).
+
In addition to the common keywords (@pxref{Common Keywords}), you can
-use this keyword in @code{defgroup}:
+also use this keyword in @code{defgroup}:
@table @code
@item :prefix @var{prefix}
Use @code{defcustom} to declare user-editable variables.
-@defmac defcustom option default doc [keyword value]...
-@tindex defcustom
+@defmac defcustom option default doc [keyword value]@dots{}
Declare @var{option} as a customizable user option variable. Do not
quote @var{option}. The argument @var{doc} specifies the documentation
-string for the variable.
+string for the variable. It should often start with a @samp{*} to mark
+it as a @dfn{user option} (@pxref{Defining Variables}). Do not start
+the documentation string with @samp{*} for options which cannot or
+normally should not be set with @code{set-variable}; examples of the
+former are global minor mode options such as
+@code{global-font-lock-mode} and examples of the latter are hooks.
If @var{option} is void, @code{defcustom} initializes it to
@var{default}. @var{default} should be an expression to compute the
value; be careful in writing it, because it can be evaluated on more
-than one occasion.
+than one occasion. You should normally avoid using backquotes in
+@var{default} because they are not expanded when editing the value,
+causing list values to appear to have the wrong structure.
+
+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
+its value is void. (The same feature applies to @code{defvar}.)
+@xref{Defining Variables}.
@end defmac
@code{defcustom} accepts the following additional keywords:
already set or has been customized; otherwise, just use
@code{set-default}.
@end table
+
+@item :set-after @var{variables}
+When setting variables according to saved customizations, make sure to
+set the variables @var{variables} before this one; in other words, delay
+setting this variable until after those others have been handled. Use
+@code{:set-after} if setting this variable won't work properly unless
+those other variables already have their intended values.
@end table
The @code{:require} option is useful for an option that turns on the
@example
(defcustom show-paren-mode nil
- "Toggle Show Paren mode@enddots{}"
+ "Toggle Show Paren mode..."
:set (lambda (symbol value)
(show-paren-mode (or value 0)))
:initialize 'custom-initialize-default
definition. You can do it thus:
@example
-(custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization)
+(custom-add-option 'emacs-lisp-mode-hook
+ 'my-lisp-mode-initialization)
@end example
@defun custom-add-option symbol option
* Type Keywords::
@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
the hook; see @ref{Variable Definitions}.
@item alist
-The value must be a list of cons-cells, the car of each cell
-representing a key, and the cdr of the same cell representing and
-associated value. The use can add and a delete key/value pairs, and
+The value must be a list of cons-cells, the @sc{car} of each cell
+representing a key, and the @sc{cdr} of the same cell representing an
+associated value. The user can add and delete key/value pairs, and
edit both the key and the value of each pair.
You can specify the key and value types like this:
-@example
-(alist :key-type @var{key-type}
- :value-type @var{value-type})
-@end example
+@smallexample
+(alist :key-type @var{key-type} :value-type @var{value-type})
+@end smallexample
@noindent
where @var{key-type} and @var{value-type} are customization type
specifications. Ordinarily, the options are simply atoms, which are the
specified keys. For example:
-@example
+@smallexample
:options '("foo" "bar" "baz")
-@end example
+@end smallexample
@noindent
specifies that there are three ``known'' keys, namely @code{"foo"},
specification. The first element will specify the key, like before,
while the second element will specify the value type.
-@example
+@smallexample
:options '("foo" ("bar" integer) "baz")
-@end example
+@end smallexample
Finally, you may want to change how the key is presented. By default,
the key is simply shown as a @code{const}, since the user cannot change
This is done by using a customization type specification instead of a
symbol for the key.
-@example
+@smallexample
:options '("foo" ((function-item some-function) integer) "baz")
-@end example
+@end smallexample
-Many alist uses lists with two elements, instead of cons cells. For
+Many alists use lists with two elements, instead of cons cells. For
example,
-@example
+@smallexample
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE).")
-@end example
+@end smallexample
@noindent
instead of
-@example
+@smallexample
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
"Each element is a cons-cell (KEY . VALUE).")
-@end example
+@end smallexample
Because of the way lists are implemented on top of cons cells, you can
treat @code{list-alist} in the example above as a cons cell alist, where
the value type is a list with a single element containing the real
value.
-@example
+@smallexample
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE)."
:type '(alist :value-type (group integer)))
-@end example
+@end smallexample
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
key, using variations of this trick:
-@example
+@smallexample
(defcustom person-data '(("brian" 50 t)
("dorith" 55 nil)
("ken" 52 t))
- "Alist of people, each element has the form (NAME AGE MALE)."
+ "Alist of basic info about people.
+Each element has the form (NAME AGE MALE-FLAG)."
:type '(alist :value-type (group age boolean)))
(defcustom pets '(("brian")
("dorith" "dog" "guppy")
("ken" "cat"))
- "Alist where the KEY is a person, and the VALUE is a list of pets."
+ "Alist of people's pets.
+In an element (KEY . VALUE), KEY is the person's name,
+and the VALUE is a list of that person's pets."
:type '(alist :value-type (repeat string)))
-@end example
+@end smallexample
@item plist
The @code{plist} custom type is similar to the @code{alist} (see above),
except that the information is stored as a property list, i.e. a list of
this form:
-@example
+@smallexample
(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
-@end example
+@end smallexample
The default @code{:key-type} for @code{plist} is @code{symbol},
rather than @code{sexp}.
you can specify that the value must be @code{nil} or @code{t}, but also
specify the text to describe each value in a way that fits the specific
meaning of the alternative.
+
+@item coding-system
+The value must be a coding-system name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item color
+The value must be a valid color name, and you can do completion with
+@kbd{M-@key{TAB}}. A sample is provided,
@end table
@node Composite Types
Like @code{list} except that the value must be a vector instead of a
list. The elements work the same as in @code{list}.
-@item (choice @var{alternative-types}...)
+@item (choice @var{alternative-types}@dots{})
The value must fit at least one of @var{alternative-types}.
For example, @code{(choice integer string)} allows either an
integer or a string.
a @code{const}, you should specify a valid default for that alternative
using the @code{:value} keyword. @xref{Type Keywords}.
+@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
+displaying documentation for the choices when applicable and so is often
+a good choice for a choice between constant functions
+(@code{function-item} customization types).
+
@item (const @var{value})
The value must be @var{value}---nothing else is allowed.
@item :help-echo @var{motion-doc}
When you move to this item with @code{widget-forward} or
-@code{widget-backward}, it will display the string @var{motion-doc}
-in the echo area.
+@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}.
@item :match @var{function}
Specify how to decide whether a value matches the type. The
HCoop / bpt / emacs.git / blobdiff