14.3 Defining Customization Variables

Use defcustom to declare user-editable variables.

Macro: defcustom option default doc [keyword value]...

Declare option as a customizable user option variable. Do not quote option. The argument doc specifies the documentation string for the variable. It should often start with a `*' to mark it as a user option (see section 11.5 Defining Global Variables). Do not start the documentation string with `*' for options which cannot or normally should not be set with set-variable; examples of the former are global minor mode options such as global-font-lock-mode and examples of the latter are hooks.

If option is void, defcustom initializes it to default. default should be an expression to compute the value; be careful in writing it, because it can be evaluated on more than one occasion. You should normally avoid using backquotes in default because they are not expanded when editing the value, causing list values to appear to have the wrong structure.

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 section 11.5 Defining Global 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 section 14.4 Customization Types, for more information.

:options list

Specify list as 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.

:version version

This option specifies that the variable was first introduced, or its default value was changed, in Emacs version version. The value version must be a string. For example,

(defcustom foo-max 34 "*Maximum number of foo's allowed." :type 'integer :group 'foo :version "20.3")

: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, but do not reinitialize it if it is already non-void. This is the default :initialize function.

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

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.

: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 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 :require. See section 14.1 Common Item Keywords. Here is an example, from the library `paren.el':

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

If a customization item has a type such as hook or alist, which supports :options, you can add additional options to the item, outside the defcustom declaration, by calling custom-add-option. 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 options for emacs-lisp-mode-hook, but not by editing its definition. You can do it thus:

(custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization)

Function: custom-add-option symbol option

To the customization symbol, add option.

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

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.