Go to the first, previous, next, last section, table of contents.


Declaring Variables

Use defcustom to declare user editable variables.

Function: defcustom option value doc [keyword value]...
Declare option as a customizable user option variable that defaults to value. Do not quote option. value should be an expression to compute the value; it will be be evaluated on more than one occasion.

If option is void, defcustom initializes it to value.

The argument doc specifies the documentation string for the variable.

The following additional keywords are defined:

:type type
Use type as the data type for this option. It specifies which values are legitimate, and how to display the value. See section Customization Types, for more information.
:options list
Specify list as the list of reasonable values for use in this option. Currently this is meaningful only when type is hook. The elements of list are functions that you might likely want to use as elements of the hook value. The user is not actually restricted to using only these functions, but they are offered as convenient alternatives.
:set setfunction
Specify setfunction as the way to change the value of this option. The function 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 setfunction is set-default.
:get getfunction
Specify getfunction as the way to extract the value of this option. The function 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 default-value.
:initialize function
function should be a function used to initialize the variable when the defcustom is evaluated. It should take two arguments, the symbol and value. Here are some predefined functions meant for use in this way:
custom-initialize-set
Use the variable's :set function to initialize the variable. Do not reinitialize it if it is already non-void. This is the default :initialize function.
custom-initialize-default
Always use set-default to initialize the variable, even if some other :set function has been specified.
custom-initialize-reset
Even if the variable is already non-void, reset it by calling the :set function using the current value (returned by the :get method).
custom-initialize-changed
Like custom-initialize-reset, except use set-default (rather than the :set function) to initialize the variable if it is not bound and has not been set already.
:require feature
If the user saves a customized value for this item, them Emacs should do (require feature) after installing the saved value. The place to use this feature is 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. That is what :require is for.

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


Go to the first, previous, next, last section, table of contents.