defcustom is a Lisp macro in `
(defcustom SYMBOL STANDARD DOC &rest ARGS)
Declare SYMBOL as a customizable variable.
SYMBOL is the variable name; it should not be quoted.
STANDARD is an expression specifying the variable's standard
value. It should not be quoted. It is evaluated once by
`defcustom', and the value is assigned to SYMBOL if the variable
is unbound. The expression itself is also stored, so that
Customize can re-evaluate it later to get the standard value.
DOC is the variable documentation.
This macro uses `defvar' as a subroutine, which also marks the
variable as "special", so that it is always dynamically bound
even when `lexical-binding' is t.
The remaining arguments to `defcustom' should have the form
The following keywords are meaningful:
:type VALUE should be a widget type for editing the symbol's value.
:options VALUE should be a list of valid members of the widget type.
VALUE should be a function used to initialize the
variable. It takes two arguments, the symbol and value
given in the `defcustom' call. The default is
:set VALUE should be a function to set the value of the symbol
when using the Customize user interface. It takes two arguments,
the symbol to set and the value to give it. The function should
not modify its value argument destructively. The default choice
of function is `set-default'.
:get VALUE should be a function to extract the value of symbol.
The function takes one argument, a symbol, and should return
the current value for that symbol. The default choice of function
VALUE should be a feature symbol. If you save a value
for this option, then when your init file loads the value,
it does (require VALUE) first.
Specifies that SYMBOL should be set after the list of variables
VARIABLES when both have been customized.
:risky Set SYMBOL's `risky-local-variable' property to VALUE.
:safe Set SYMBOL's `safe-local-variable' property to VALUE.
See Info node `(elisp) File Local Variables'.
The following common keywords are also meaningful.
:group VALUE should be a customization group.
Add SYMBOL (or FACE with `defface') to that group.
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 several alternatives you can use for LINK-DATA:
Link to an Info node; INFO-NODE is a string which specifies
the node name, as in "(emacs)Top".
Like `custom-manual' except that the link appears in the
customization buffer with the Info node name.
Link to a web page; URL is a string which specifies the URL.
Link to the commentary section of LIBRARY.
Link to an Emacs Lisp LIBRARY file.
Link to FILE.
Link to the documentation of FUNCTION.
Link to the documentation of VARIABLE.
Link to another customization GROUP.
You can specify the text to use in the customization buffer by
adding `:tag NAME' after the first element of the LINK-DATA; for
example, (info-link :tag "foo" "(emacs)Top") makes a link to the
Emacs manual which appears in the buffer as `foo'.
An item can have more than one external link; however, most items
have none at all.
VALUE should be a string specifying that the variable was
first introduced, or its default value was changed, in Emacs
VALUE should be a list with the form (PACKAGE . VERSION)
specifying that the variable was first introduced, or its
default value was changed, in PACKAGE version VERSION. This
keyword takes priority over :version. The PACKAGE and VERSION
must appear in the alist `customize-package-emacs-version-alist'.
Since PACKAGE must be unique and the user might see it in an
error message, a good choice is the official name of the
package, such as MH-E or Gnus.
Use LABEL, a string, instead of the item's name, to label the item
in customization menus and buffers.
Load file FILE (a string) before displaying this customization
item. Loading is done with `load', and only if the file is
not already loaded.
If SYMBOL has a local binding, then this form affects the local
binding. This is normally not what you want. Thus, if you need
to load a file defining variables with this form, or with
`defvar' or `defconst', you should always load that file
_outside_ any bindings for these variables. (`defvar' and
`defconst' behave similarly in this respect.)
See Info node `(elisp) Customization' in the Emacs Lisp manual
for more information.