emacs/lispref/customize.texi

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1997, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
@chapter Writing Customization Definitions

  This chapter describes how to declare user options for customization,
and also customization groups for classifying them.  We use the term
@dfn{customization item} to include both kinds of customization
definitions---as well as face definitions (@pxref{Defining Faces}).

@menu
* Common Keywords::
* Group Definitions::            
* Variable Definitions::         
* Customization Types::
@end menu

@node Common Keywords
@section Common Keywords for All Kinds of Items

  All kinds of customization declarations (for variables and groups, and
for faces) accept keyword arguments for specifying various information.
This section describes some keywords that apply to all kinds.

  All of these keywords, except @code{:tag}, can be used more than once
in a given item.  Each use of the keyword has an independent effect.
The keyword @code{:tag} is an exception because any given item can only
display one name.

@table @code
@item :tag @var{name}
Use @var{name}, a string, instead of the item's name, to label the item
in customization menus and buffers.

@item :group @var{group}
Put this customization item in group @var{group}.  When you use
@code{:group} in a @code{defgroup}, it makes the new group a subgroup of
@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 :link @var{link-data}
Include an external link after the documentation string for this item.
This is a sentence containing an active field which references some
other documentation.

There are three alternatives you can use for @var{link-data}:

@table @code
@item (custom-manual @var{info-node})
Link to an Info node; @var{info-node} is a string which specifies the
node name, as in @code{"(emacs)Top"}.  The link appears as
@samp{[manual]} in the customization buffer.

@item (info-link @var{info-node})
Like @code{custom-manual} except that the link appears
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}.
The link appears in the customization buffer as @var{url}.
@end table

You can specify the text to use in the customization buffer by adding
@code{:tag @var{name}} after the first element of the @var{link-data};
for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
the Emacs manual which appears in the buffer as @samp{foo}.

An item can have more than one external link; however, most items have
none at all.

@item :load @var{file}
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 :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}.

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.
@end table

@node Group Definitions
@section Defining Custom Groups

  Each Emacs Lisp package should have one main customization group which
contains all the options, faces and other groups in the package.  If the
package has a small number of options and faces, use just one group and
put everything in it.  When there are more than twelve or so options and
faces, then you should structure them into subgroups, and put the
subgroups under the package's main customization group.  It is OK to
put some of the options and faces in the package's main group alongside
the subgroups.

  The package's main or only group should be a member of one or more of
the standard customization groups.  (To display the full list of them,
use @kbd{M-x customize}.)  Choose one or more of them (but not too
many), and add your group to each of them using the @code{:group}
keyword.

  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 argument @var{members} is a list specifying an initial set of
customization items to be members of the group.  However, most often
@var{members} is @code{nil}, and you specify the group's members by
using the @code{:group} keyword when defining those members.

If you want to specify group members through @var{members}, each element
should have the form @code{(@var{name} @var{widget})}.  Here @var{name}
is a symbol, and @var{widget} is a widget type for editing that symbol.
Useful widgets are @code{custom-variable} for a variable,
@code{custom-face} for a face, and @code{custom-group} for a group.

In addition to the common keywords (@pxref{Common Keywords}), you can
use this keyword in @code{defgroup}:

@table @code
@item :prefix @var{prefix}
If the name of an item in the group starts with @var{prefix}, then the
tag for that item is constructed (by default) by omitting @var{prefix}.

One group can have any number of prefixes.
@end table
@end defmac

  The prefix-discarding feature is currently turned off, which means
that @code{:prefix} currently has no effect.  We did this because we
found that discarding the specified prefixes often led to confusing
names for options.  This happened because the people who wrote the
@code{defgroup} definitions for various groups added @code{:prefix}
keywords whenever they make logical sense---that is, whenever the
variables in the library have a common prefix.

  In order to obtain good results with @code{:prefix}, it would be
necessary to check the specific effects of discarding a particular
prefix, given the specific items in a group and their names and
documentation.  If the resulting text is not clear, then @code{:prefix}
should not be used in that case.

  It should be possible to recheck all the customization groups, delete
the @code{:prefix} specifications which give unclear results, and then
turn this feature back on, if someone would like to do the work.

@node Variable Definitions
@section Defining Customization Variables

  Use @code{defcustom} to declare user-editable variables.

@defmac defcustom option default doc [keyword value]...
@tindex defcustom
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.

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.
@end defmac

  @code{defcustom} accepts the following additional keywords:

@table @code
@item :type @var{type}
Use @var{type} as the data type for this option.  It specifies which
values are legitimate, and how to display the value.
@xref{Customization Types}, for more information.

@item :options @var{list}
Specify @var{list} as the list of reasonable values for use in this
option.

Currently this is meaningful only when the type is @code{hook}.  In that
case, the elements of @var{list} should be functions that are useful as
elements of the hook value.  The user is not restricted to using only
these functions, but they are offered as convenient alternatives.

@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}.

@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}.

@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:

@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.

@item custom-initialize-default
Like @code{custom-initialize-set}, but use the function
@code{set-default} to set the variable, instead of the variable's
@code{:set} function.  This is the usual choice for a variable whose
@code{:set} function enables or disables a minor mode; with this choice,
defining the variable will not call the minor mode function, but
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}
function using the current value (returned by the @code{:get} method).

@item custom-initialize-changed
Use the @code{:set} function to initialize the variable, if it is
already set or has been customized; otherwise, just use
@code{set-default}.
@end table
@end table

  The @code{:require} option 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{paren.el}:

@example
(defcustom show-paren-mode nil
  "Toggle Show Paren mode@enddots{}"
  :set (lambda (symbol value)
         (show-paren-mode (or value 0)))
  :initialize 'custom-initialize-default
  :type 'boolean
  :group 'paren-showing
  :require 'paren)
@end example

@ignore
Use @code{custom-add-option} to specify that a specific function is
useful as an member of a hook.

@defun custom-add-option symbol option
To the variable @var{symbol} add @var{option}.

If @var{symbol} is a hook variable, @var{option} should be a hook
member.  For other types variables, the effect is undefined."
@end defun
@end ignore

Internally, @code{defcustom} uses the symbol property
@code{standard-value} to record the expression for the default value,
and @code{saved-value} to record the value saved by the user with the
customization buffer.  The @code{saved-value} property is actually a
list whose car is an expression which evaluates to the value.

@node Customization Types
@section Customization Types

  When you define a user option with @code{defcustom}, you must specify
its @dfn{customization type}.  That is a Lisp object which describes (1)
which values are legitimate and (2) how to display the value in the
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:

@example
(defcustom diff-command "diff"
  "*The command to use to run diff."
  :type '(string)
  :group 'diff)
@end example

  In general, a customization type is a list whose first element is a
symbol, one of the customization type names defined in the following
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
@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)}.

@menu
* Simple Types::
* Composite Types::
* Splicing into Lists::
* Type Keywords::
@end menu

@node Simple Types
@subsection Simple Types

  This section describes all the simple customization types.

@table @code
@item sexp
The value may be any Lisp object that can be printed and read back.  You
can use @code{sexp} as a fall-back for any option, if you don't want to
take the time to work out a more specific type to use.

@item integer
The value must be an integer, and is represented textually
in the customization buffer.

@item number
The value must be a number, and is represented textually in the
customization buffer.

@item string
The value must be a string, and the customization buffer shows just the
contents, with no delimiting @samp{"} characters and no quoting with
@samp{\}.

@item regexp
Like @code{string} except that the string must be a valid regular
expression.

@item character
The value must be a character code.  A character code is actually an
integer, but this type shows the value by inserting the character in the
buffer, rather than by showing the number.

@item file
The value must be a file name, and you can do completion with
@kbd{M-@key{TAB}}.

@item (file :must-match t)
The value must be a file name for an existing file, and you can do
completion with @kbd{M-@key{TAB}}.

@item directory
The value must be a directory name, and you can do completion with
@kbd{M-@key{TAB}}.

@item hook
The value must be a list of functions (or a single function, but that is
obsolete usage).  This customization type is used for hook variables.
You can use the @code{:options} keyword in a hook variable's
@code{defcustom} to specify a list of functions recommended for use in
the hook; see @ref{Variable Definitions}.

@item symbol
The value must be a symbol.  It appears in the customization buffer as
the name of the symbol.

@item function
The value must be either a lambda expression or a function name.  When
it is a function name, you can do completion with @kbd{M-@key{TAB}}.

@item variable
The value must be a variable name, and you can do completion with
@kbd{M-@key{TAB}}.

@item face
The value must be a symbol which is a face name, and you can do
completion with @kbd{M-@key{TAB}}.

@item boolean
The value is boolean---either @code{nil} or @code{t}.  Note that by
using @code{choice} and @code{const} together (see the next section),
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.
@end table

@node Composite Types
@subsection Composite Types

  When none of the simple types is appropriate, you can use composite
types, which build new types from other types.  Here are several ways of
doing that:

@table @code
@item (restricted-sexp :match-alternatives @var{criteria})
The value may be any Lisp object that satisfies one of @var{criteria}.
@var{criteria} should be a list, and each element should be
one of these possibilities:

@itemize @bullet
@item
A predicate---that is, a function of one argument that has no side
effects, and returns either @code{nil} or non-@code{nil} according to
the argument.  Using a predicate in the list says that objects for which
the predicate returns non-@code{nil} are acceptable.

@item
A quoted constant---that is, @code{'@var{object}}.  This sort of element
in the list says that @var{object} itself is an acceptable value.
@end itemize

For example,

@example
(restricted-sexp :match-alternatives
                 (integerp 't 'nil))
@end example

@noindent
allows integers, @code{t} and @code{nil} as legitimate values.

The customization buffer shows all legitimate values using their read
syntax, and the user edits them textually.

@item (cons @var{car-type} @var{cdr-type})
The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
its @sc{cdr} must fit @var{cdr-type}.  For example, @code{(cons string
symbol)} is a customization type which matches values such as
@code{("foo" . foo)}.

In the customization buffer, the @sc{car} and the @sc{cdr} are
displayed and edited separately, each according to the type
that you specify for it.

@item (list @var{element-types}@dots{})
The value must be a list with exactly as many elements as the
@var{element-types} you have specified; and each element must fit the
corresponding @var{element-type}.

For example, @code{(list integer string function)} describes a list of
three elements; the first element must be an integer, the second a
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 (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}.

@item (choice @var{alternative-types}...)
The value must fit at least one of @var{alternative-types}.
For example, @code{(choice integer string)} allows either an
integer or a string.

In the customization buffer, the user selects one of the alternatives
using a menu, and can then edit the value in the usual way for that
alternative.

Normally the strings in this menu are determined automatically from the
choices; however, you can specify different strings for the menu by
including the @code{:tag} keyword in the alternatives.  For example, if
an integer stands for a number of spaces, while a string is text to use
verbatim, you might write the customization type this way,

@example
(choice (integer :tag "Number of spaces")
        (string :tag "Literal text"))
@end example

@noindent
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}.

@item (const @var{value})
The value must be @var{value}---nothing else is allowed.

The main use of @code{const} is inside of @code{choice}.  For example,
@code{(choice integer (const nil))} allows either an integer or
@code{nil}.

@code{:tag} is often used with @code{const}, inside of @code{choice}.
For example,

@example
(choice (const :tag "Yes" t)
        (const :tag "No" nil)
        (const :tag "Ask" foo))
@end example

@noindent
describes a variable for which @code{t} means yes, @code{nil} means no,
and @code{foo} means ``ask.''

@item (other @var{value})
This alternative can match any Lisp value, but if the user chooses this
alternative, that selects the value @var{value}.

The main use of @code{other} is as the last element of @code{choice}.
For example,

@example
(choice (const :tag "Yes" t)
        (const :tag "No" nil)
        (other :tag "Ask" foo))
@end example

@noindent
describes a variable for which @code{t} means yes, @code{nil} means no,
and anything else means ``ask.''  If the user chooses @samp{Ask} from
the menu of alternatives, that specifies the value @code{foo}; but any
other value (not @code{t}, @code{nil} or @code{foo}) displays as
@samp{Ask}, just like @code{foo}.

@item (function-item @var{function})
Like @code{const}, but used for values which are functions.  This
displays the documentation string as well as the function name.
The documentation string is either the one you specify with
@code{:doc}, or @var{function}'s own documentation string.

@item (variable-item @var{variable})
Like @code{const}, but used for values which are variable names.  This
displays the documentation string as well as the variable name.  The
documentation string is either the one you specify with @code{:doc}, or
@var{variable}'s own documentation string.

@item (set @var{elements}@dots{})
The value must be a list and each element of the list must be one of the
@var{elements} specified.  This appears in the customization buffer as a
checklist.

@item (repeat @var{element-type})
The value must be a list and each element of the list must fit the type
@var{element-type}.  This appears in the customization buffer as a
list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
more elements or removing elements.
@end table

@node Splicing into Lists
@subsection Splicing into Lists

  The @code{:inline} feature lets you splice a variable number of
elements into the middle of a list or vector.  You use it in a
@code{set}, @code{choice} or @code{repeat} type which appears among the
element-types of a @code{list} or @code{vector}.

  Normally, each of the element-types in a @code{list} or @code{vector}
describes one and only one element of the list or vector.  Thus, if an
element-type is a @code{repeat}, that specifies a list of unspecified
length which appears as one element.

  But when the element-type uses @code{:inline}, the value it matches is
merged directly into the containing sequence.  For example, if it
matches a list with three elements, those become three elements of the
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}
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))
@end example

@noindent
This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
and @code{(t 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
@code{choice}.  For example, to match a list which must start with a
file name, followed either by the symbol @code{t} or two strings, use
this customization type:

@example
(list file
      (choice (const t)
              (list :inline t string string)))
@end example

@noindent
If the user chooses the first alternative in the choice, then the
overall list has two elements and the second element is @code{t}.  If
the user chooses the second alternative, then the overall list has three
elements and the second and third must be strings.

@node Type Keywords
@subsection Type Keywords

You can specify keyword-argument pairs in a customization type after the
type name symbol.  Here are the keywords you can use, and their
meanings:

@table @code
@item :value @var{default}
This is used for a type that appears as an alternative inside of
@code{choice}; it specifies the default value to use, at first, if and
when the user selects this alternative with the menu in the
customization buffer.

Of course, if the actual value of the option fits this alternative, it
will appear showing the actual value, not @var{default}.

If @code{nil} is not a valid value for the alternative, then it is
essential to specify a valid default with @code{:value}.

@item :format @var{format-string}
This string will be inserted in the buffer to represent the value
corresponding to the type.  The following @samp{%} escapes are available
for use in @var{format-string}:

@table @samp
@item %[@var{button}%]
Display the text @var{button} marked as a button.  The @code{:action}
attribute specifies what the button will do if the user invokes it;
its value is a function which takes two arguments---the widget which
the button appears in, and the event.

There is no way to specify two different buttons with different
actions.

@item %@{@var{sample}%@}
Show @var{sample} in a special face specified by @code{:sample-face}.

@item %v
Substitute the item's value.  How the value is represented depends on
the kind of item, and (for variables) on the customization type.

@item %d
Substitute the item's documentation string.

@item %h
Like @samp{%d}, but if the documentation string is more than one line,
add an active field to control whether to show all of it or just the
first line.

@item %t
Substitute the tag here.  You specify the tag with the @code{:tag}
keyword.

@item %%
Display a literal @samp{%}. 
@end table

@item :action @var{action}
Perform @var{action} if the user clicks on a button.

@item :button-face @var{face}
Use the face @var{face} (a face name or a list of face names) for button
text displayed with @samp{%[@dots{}%]}.

@item :button-prefix @var{prefix}
@itemx :button-suffix @var{suffix}
These specify the text to display before and after a button.
Each can be:

@table @asis
@item @code{nil}
No text is inserted.

@item a string
The string is inserted literally.

@item a symbol
The symbol's value is used.
@end table

@item :tag @var{tag}
Use @var{tag} (a string) as the tag for the value (or part of the value)
that corresponds to this type.

@item :doc @var{doc}
Use @var{doc} as the documentation string for this value (or part of the
value) that corresponds to this type.  In order for this to work, you
must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
in that value.

The usual reason to specify a documentation string for a type is to
provide more information about the meanings of alternatives inside a
@code{:choice} type or the parts of some other composite type.

@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.

@item :match @var{function}
Specify how to decide whether a value matches the type.  The
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.

@ignore
@item :indent @var{columns}
Indent this item by @var{columns} columns.  The indentation is used for
@samp{%n}, and automatically for group names, for checklists and radio
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 :extra-offset
An integer indicating how many extra spaces to add to this item's
indentation, compared to its parent.

@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 :menu-tag
Tag used in the menu when the widget is used as an option in a
@code{menu-choice} widget.

@item :menu-tag-get
Function used for finding the tag when the widget is used as an option
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 nil if the
widgets current value is valid for the widget.  Otherwise, it should
return the widget containing the invalid data, and set that widgets
@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
implemented.

@enumerate a
@item
Widgets with tabbing order @code{-1} are ignored.

@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.

@item
When on a widget with no tabbing order specified, go to the next widget
in the buffer with a positive tabbing order, or @code{nil}
@end enumerate

@item :parent
The parent of a nested widget (e.g., a @code{menu-choice} item or an
element of a @code{editable-list} widget).

@item :sibling-args
This keyword is only used for members of a @code{radio-button-choice} or
@code{checklist}.  The value should be a list of extra keyword
arguments, which will be used when creating the @code{radio-button} or
@code{checkbox} associated with this item.
@end ignore
@end table