GNU Info

Info Node: (elisp)Variable Definitions

(elisp)Variable Definitions


Next: Customization Types Prev: Group Definitions Up: Customization
Enter node , (file) or (file)node

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" (Note: Defining 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'.)  Note:
     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.  Note:
     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'.  Note: Common
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.


automatically generated by info2www version 1.2.2.9