Next: , Previous: Group Definitions, Up: Customization

14.3 Defining Customization Variables

Use defcustom to declare user-customizable variables.

— Macro: defcustom option standard doc [keyword value]...

This construct declares option as a customizable user option variable. You should not quote option. The argument doc specifies the documentation string for the variable. There is no need to start it with a `*', because defcustom automatically marks option as a user option (see Defining Variables).

The argument standard is an expression that specifies the standard value for option. Evaluating the defcustom form evaluates standard, but does not necessarily install the standard value. If option already has a default value, defcustom does not change it. If the user has saved a customization for option, defcustom installs the user's customized value as option's default value. If neither of those cases applies, defcustom installs the result of evaluating standard as the default value.

The expression standard can be evaluated at various other times, too—whenever the customization facility needs to know option's standard value. So be sure to use an expression which is harmless to evaluate at any time. We recommend avoiding backquotes in standard, because they are not expanded when editing the value, so list values will appear to have the wrong structure.

Every defcustom should specify :group at least once.

If you specify the :set keyword, 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 defcustom form with C-M-x in Emacs Lisp mode (eval-defun), a special feature of eval-defun arranges to set the variable unconditionally, without testing whether its value is void. (The same feature applies to defvar.) See Defining Variables.

defcustom accepts the following additional keywords:

:type type
Use type as the data type for this option. It specifies which values are legitimate, and how to display the value. See Customization Types, for more information.
:options value-list
Specify the list of reasonable values for use in this option. The user is not restricted to using only these values, but they are offered as convenient alternatives.

This is meaningful only for certain types, currently including hook, plist and alist. See the definition of the individual types for a description of how to use :options.

:set setfunction
Specify setfunction as the way to change the value of this option. The function 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 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 whatever customize should use as the “current value” for that symbol (which need not be the symbol's Lisp value). The default is default-value.

You have to really understand the workings of Custom to use :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 getfunction for a value that really is stored in a Lisp variable.

:initialize function
function should be a function used to initialize the variable when the 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:
custom-initialize-set
Use the variable's :set function to initialize the variable, but do not reinitialize it if it is already non-void.
custom-initialize-default
Like custom-initialize-set, but use the function set-default to set the variable, instead of the variable's :set function. This is the usual choice for a variable whose :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.
custom-initialize-reset
Always use the :set function to initialize the variable. If the variable is already non-void, reset it by calling the :set function using the current value (returned by the :get method). This is the default :initialize function.
custom-initialize-changed
Use the :set function to initialize the variable, if it is already set or has been customized; otherwise, just use set-default.
custom-initialize-safe-set
custom-initialize-safe-default
These functions behave like custom-initialize-set (custom-initialize-default, respectively), but catch errors. If an error occurs during initialization, they set the variable to nil using set-default, and throw no error.

These two functions are only meant for options defined in pre-loaded files, where some variables or functions used to compute the option's value may not yet be defined. The option normally gets updated in startup.el, ignoring the previously computed value. Because of this typical usage, the value which these two functions compute normally only matters when, after startup, one unsets the option's value and then reevaluates the defcustom. By that time, the necessary variables and functions will be defined, so there will not be an error.


:set-after variables
When setting variables according to saved customizations, make sure to set the variables variables before this one; in other words, delay setting this variable until after those others have been handled. Use :set-after if setting this variable won't work properly unless those other variables already have their intended values.

The :require keyword 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 :require. See Common Keywords. Here is an example, from the library saveplace.el: 

     (defcustom save-place nil
       "Non-nil means automatically save place in each file..."
       :type 'boolean
       :require 'saveplace
       :group 'save-place)

If a customization item has a type such as hook or alist, which supports :options, you can add additional values to the list from outside the defcustom declaration by calling custom-add-frequent-value. For example, if you define a function my-lisp-mode-initialization intended to be called from emacs-lisp-mode-hook, you might want to add that to the list of reasonable values for emacs-lisp-mode-hook, but not by editing its definition. You can do it thus: 

     (custom-add-frequent-value 'emacs-lisp-mode-hook
        'my-lisp-mode-initialization)
— Function: custom-add-frequent-value symbol value

For the customization option symbol, add value to the list of reasonable values.

The precise effect of adding a value depends on the customization type of symbol.

Internally, defcustom uses the symbol property standard-value to record the expression for the standard value, and saved-value to record the value saved by the user with the customization buffer. Both properties are actually lists whose car is an expression which evaluates to the value.