Customization Settings
**********************

Users of Emacs can customize variables and faces without writing Lisp code, by using the Customize interface.  See Easy Customization (The GNU Emacs Manual).  This chapter describes how to define customization items that users can interact with through the Customize interface.

Customization items include customizable variables, which are defined with the defcustom macro (see Variable Definitions); customizable faces, which are defined with defface (described separately in Defining Faces); and customization groups, defined with defgroup (see Group Definitions), which act as containers for groups of related customization items.

Common Item Keywords
====================

The customization declarations that we will describe in the next few sections---defcustom, defgroup, etc.---all accept keyword arguments (see Constant Variables) for specifying various information.  This section describes keywords that apply to all types of customization declarations.

All of these keywords, except :tag, can be used more than once in a given item.  Each use of the keyword has an independent effect. The keyword :tag is an exception because any given item can only display one name.

:tag LABEL
     Use LABEL, a string, instead of the item's name, to label the item in customization menus and buffers.  Don't use a tag which is substantially different from the item's real name; that would cause confusion.

:group GROUP
     Put this customization item in group GROUP.  If this keyword is missing from a customization item, it'll be placed in the same group that was last defined (in the current file).

     When you use :group in a defgroup, it makes the new group a subgroup of GROUP.

     If you use this keyword more than once, you can put a single item into more than one group.  Displaying any of those groups will show this item.  Please don't overdo this, since the result would be annoying.

:link LINK-DATA
     Include an external link after the documentation string for this item. This is a sentence containing a button that references some other documentation.

     There are several alternatives you can use for LINK-DATA:

     (custom-manual INFO-NODE)
          Link to an Info node; INFO-NODE is a string which specifies the node name, as in "(emacs)Top".  The link appears as [Manual] in the customization buffer and enters the built-in Info reader on INFO-NODE.

     (info-link INFO-NODE)
          Like custom-manual except that the link appears in the customization buffer with the Info node name.

     (url-link URL)
          Link to a web page; URL is a string which specifies the URL.  The link appears in the customization buffer as URL and invokes the WWW browser specified by browse-url-browser-function.

     (emacs-commentary-link LIBRARY)
          Link to the commentary section of a library; LIBRARY is a string which specifies the library name.  See Library Headers.

     (emacs-library-link LIBRARY)
          Link to an Emacs Lisp library file; LIBRARY is a string which specifies the library name.

     (file-link FILE)
          Link to a file; FILE is a string which specifies the name of the file to visit with find-file when the user invokes this link.

     (function-link FUNCTION)
          Link to the documentation of a function; FUNCTION is a string which specifies the name of the function to describe with describe-function when the user invokes this link.

     (variable-link VARIABLE)
          Link to the documentation of a variable; VARIABLE is a string which specifies the name of the variable to describe with describe-variable when the user invokes this link.

     (custom-group-link GROUP)
          Link to another customization group.  Invoking it creates a new customization buffer for 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.

     You can use this keyword more than once, to add multiple links.

:load FILE
     Load file FILE (a string) before displaying this customization item (see Loading).  Loading is done with load, and only if the file is not already loaded.

:require FEATURE
     Execute (require 'FEATURE) when your saved customizations set the value of this item.  FEATURE should be a symbol.

     The most common reason to use :require is when a variable enables a feature such as a minor mode, and just setting the variable won't have any effect unless the code which implements the mode is loaded.

:version VERSION
     This keyword specifies that the item was first introduced in Emacs version VERSION, or that its default value was changed in that version.  The value VERSION must be a string.

:package-version '(PACKAGE . VERSION)
     This keyword specifies that the item was first introduced in PACKAGE version VERSION, or that its meaning or default value was changed in that version.  This keyword takes priority over :version.

     PACKAGE should be the official name of the package, as a symbol (e.g., MH-E).  VERSION should be a string.  If the package PACKAGE is released as part of Emacs, PACKAGE and VERSION should appear in the value of customize-package-emacs-version-alist.

Packages distributed as part of Emacs that use the :package-version keyword must also update the customize-package-emacs-version-alist variable.

 -- Variable: customize-package-emacs-version-alist
     This alist provides a mapping for the versions of Emacs that are associated with versions of a package listed in the :package-version keyword.  Its elements are:

          (PACKAGE (PVERSION . EVERSION)...)

     For each PACKAGE, which is a symbol, there are one or more elements that contain a package version PVERSION with an associated Emacs version EVERSION.  These versions are strings. For example, the MH-E package updates this alist with the following:

          (add-to-list 'customize-package-emacs-version-alist
                       '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
                              ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
                              ("7.4" . "22.1") ("8.0" . "22.1")))

     The value of PACKAGE needs to be unique and it needs to match the PACKAGE value appearing in the :package-version keyword.  Since the user might see the value in an error message, a good choice is the official name of the package, such as MH-E or Gnus.

Defining Customization Groups
=============================

Each Emacs Lisp package should have one main customization group which contains all the options, faces and other groups in the package. If the package has a small number of options and faces, use just one group and put everything in it.  When there are more than twenty or so options and faces, then you should structure them into subgroups, and put the subgroups under the package's main customization group.  It is OK to put some of the options and faces in the package's main group alongside the subgroups.

The package's main or only group should be a member of one or more of the standard customization groups.  (To display the full list of them, use M-x customize.)  Choose one or more of them (but not too many), and add your group to each of them using the :group keyword.

The way to declare new customization groups is with defgroup.

 -- Macro: defgroup group members doc [keyword value]...
     Declare GROUP as a customization group containing MEMBERS. Do not quote the symbol GROUP.  The argument DOC specifies the documentation string for the group.

     The argument MEMBERS is a list specifying an initial set of customization items to be members of the group.  However, most often MEMBERS is nil, and you specify the group's members by using the :group keyword when defining those members.

     If you want to specify group members through MEMBERS, each element should have the form (NAME WIDGET).  Here NAME is a symbol, and WIDGET is a widget type for editing that symbol. Useful widgets are custom-variable for a variable, custom-face for a face, and custom-group for a group.

     When you introduce a new group into Emacs, use the :version keyword in the defgroup; then you need not use it for the individual members of the group.

     In addition to the common keywords (see Common Keywords), you can also use this keyword in defgroup:

     :prefix PREFIX
          If the name of an item in the group starts with PREFIX, and the customizable variable custom-unlispify-remove-prefixes is non-nil, the item's tag will omit PREFIX.  A group can have any number of prefixes.

     The variables and subgroups of a group are stored in the custom-group property of the group's symbol.  See Symbol Plists.  The value of that property is a list of pairs whose car is the variable or subgroup symbol and the cdr is either custom-variable or custom-group.

 -- User Option: custom-unlispify-remove-prefixes
     If this variable is non-nil, the prefixes specified by a group's :prefix keyword are omitted from tag names, whenever the user customizes the group.

     The default value is nil, i.e., the prefix-discarding feature is disabled.  This is because discarding prefixes often leads to confusing names for options and faces.

Defining Customization Variables
================================

Customizable variables, also called user options, are global Lisp variables whose values can be set through the Customize interface.  Unlike other global variables, which are defined with defvar (see Defining Variables), customizable variables are defined using the defcustom macro.  In addition to calling defvar as a subroutine, defcustom states how the variable should be displayed in the Customize interface, the values it is allowed to take, etc.

 -- Macro: defcustom option standard doc [keyword value]...
     This macro declares OPTION as a user option (i.e., a customizable variable).  You should not quote OPTION.

     The argument STANDARD is an expression that specifies the standard value for OPTION.  Evaluating the defcustom form evaluates STANDARD, but does not necessarily bind the option to that value.  If OPTION already has a default value, it is left unchanged.  If the user has already saved a customization for OPTION, the user's customized value is installed as the default value.  Otherwise, the result of evaluating STANDARD is installed as the default value.

     Like defvar, this macro marks option as a special variable, meaning that it should always be dynamically bound.  If OPTION is already lexically bound, that lexical binding remains in effect until the binding construct exits.  See Variable Scoping.

     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.

     The argument DOC specifies the documentation string for the variable.

     If a defcustom does not specify any :group, the last group defined with defgroup in the same file will be used.  This way, most defcustom do not need an explicit :group.

     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.)  Using eval-defun on a defcustom that is already defined calls the :set function (see below), if there is one.

     If you put a defcustom in a pre-loaded Emacs Lisp file (see Building Emacs), the standard value installed at dump time might be incorrect, e.g., because another variable that it depends on has not been assigned the right value yet.  In that case, use custom-reevaluate-setting, described below, to re-evaluate the standard value after Emacs starts up.

In addition to the keywords listed in Common Keywords, this macro accepts the following 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).  Every defcustom should specify a value for this keyword.

: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 when using the Customize interface.  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); preferably, though, it should not modify its value argument destructively.  The default for SETFUNCTION is set-default.

     If you specify this keyword, the variable's documentation string should describe how to do the same job in hand-written Lisp code.

: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 signal no error.

          These functions are meant for options defined in pre-loaded files, where the STANDARD expression may signal an error because some required variable or function is not yet defined.  The value normally gets updated in startup.el, ignoring the value computed by defcustom.  After startup, if one unsets the value and reevaluates the defcustom, the STANDARD expression can be evaluated without error.

:risky VALUE
     Set the variable's risky-local-variable property to VALUE (see File Local Variables).

:safe FUNCTION
     Set the variable's safe-local-variable property to FUNCTION (see File Local Variables).

:set-after VARIABLES
     When setting variables according to saved customizations, make sure to set the variables VARIABLES before this one; i.e., 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.

It is useful to specify the :require keyword for an option that turns on a certain feature.  This causes Emacs to load the feature, if it is not already loaded, whenever the option is set. 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, saved-value to record the value saved by the user with the customization buffer, and customized-value to record the value set by the user with the customization buffer, but not saved. See Symbol Properties.  These properties are lists, the car of which is an expression that evaluates to the value.

 -- Function: custom-reevaluate-setting symbol
     This function re-evaluates the standard value of SYMBOL, which should be a user option declared via defcustom.  If the variable was customized, this function re-evaluates the saved value instead.  Then it sets the user option to that value (using the option's :set property if that is defined).

     This is useful for customizable options that are defined before their value could be computed correctly.  For example, during startup Emacs calls this function for some user options that were defined in pre-loaded Emacs Lisp files, but whose initial values depend on information available only at run-time.

 -- Function: custom-variable-p arg
     This function returns non-nil if ARG is a customizable variable.  A customizable variable is either a variable that has a standard-value or custom-autoload property (usually meaning it was declared with defcustom), or an alias for another customizable variable.

Customization Types
===================

When you define a user option with defcustom, you must specify its customization type.  That is a Lisp object which describes (1) which values are legitimate and (2) how to display the value in the customization buffer for editing.

You specify the customization type in defcustom with the :type keyword.  The argument of :type is evaluated, but only once when the defcustom is executed, so it isn't useful for the value to vary.  Normally we use a quoted constant.  For example:

     (defcustom diff-command "diff"
       "The command to use to run diff."
       :type '(string)
       :group 'diff)

In general, a customization type is a list whose first element is a symbol, one of the customization type names defined in the following sections.  After this symbol come a number of arguments, depending on the symbol.  Between the type symbol and its arguments, you can optionally write keyword-value pairs (see Type Keywords).

Some type symbols do not use any arguments; those are called simple types.  For a simple type, if you do not use any keyword-value pairs, you can omit the parentheses around the type symbol.  For example just string as a customization type is equivalent to (string).

All customization types are implemented as widgets; see Introduction (The Emacs Widget Library), for details.

Simple Types
------------

This section describes all the simple customization types.  For several of these customization types, the customization widget provides inline completion with C-M-i or M-TAB.

sexp
     The value may be any Lisp object that can be printed and read back. You can use sexp as a fall-back for any option, if you don't want to take the time to work out a more specific type to use.

integer
     The value must be an integer.

number
     The value must be a number (floating point or integer).

float
     The value must be floating point.

string
     The value must be a string.  The customization buffer shows the string without delimiting " characters or \ quotes.

regexp
     Like string except that the string must be a valid regular expression.

character
     The value must be a character code.  A character code is actually an integer, but this type shows the value by inserting the character in the buffer, rather than by showing the number.

file
     The value must be a file name.  The widget provides completion.

(file :must-match t)
     The value must be a file name for an existing file.  The widget provides completion.

directory
     The value must be a directory.  The widget provides completion.

hook
     The value must be a list of functions.  This customization type is used for hook variables.  You can use the :options keyword in a hook variable's defcustom to specify a list of functions recommended for use in the hook; see Variable Definitions.

symbol
     The value must be a symbol.  It appears in the customization buffer as the symbol name.  The widget provides completion.

function
     The value must be either a lambda expression or a function name.  The widget provides completion for function names.

variable
     The value must be a variable name.  The widget provides completion.

face
     The value must be a symbol which is a face name.  The widget provides completion.

boolean
     The value is boolean---either nil or t.  Note that by using choice and const together (see the next section), you can specify that the value must be nil or t, but also specify the text to describe each value in a way that fits the specific meaning of the alternative.

key-sequence
     The value is a key sequence.  The customization buffer shows the key sequence using the same syntax as the kbd function.  See Key Sequences.

coding-system
     The value must be a coding-system name, and you can do completion with M-TAB.

color
     The value must be a valid color name.  The widget provides completion for color names, as well as a sample and a button for selecting a color name from a list of color names shown in a *Colors* buffer.

Composite Types
---------------

When none of the simple types is appropriate, you can use composite types, which build new types from other types or from specified data. The specified types or data are called the arguments of the composite type.  The composite type normally looks like this:

     (CONSTRUCTOR ARGUMENTS...)

but you can also add keyword-value pairs before the arguments, like this:

     (CONSTRUCTOR {KEYWORD VALUE}... ARGUMENTS...)

Here is a table of constructors and how to use them to write composite types:

(cons CAR-TYPE CDR-TYPE)
     The value must be a cons cell, its CAR must fit CAR-TYPE, and its CDR must fit CDR-TYPE.  For example, (cons string symbol) is a customization type which matches values such as ("foo" . foo).

     In the customization buffer, the CAR and CDR are displayed and edited separately, each according to their specified type.

(list ELEMENT-TYPES...)
     The value must be a list with exactly as many elements as the ELEMENT-TYPES given; and each element must fit the corresponding ELEMENT-TYPE.

     For example, (list integer string function) describes a list of three elements; the first element must be an integer, the second a string, and the third a function.

     In the customization buffer, each element is displayed and edited separately, according to the type specified for it.

(group ELEMENT-TYPES...)
     This works like list except for the formatting of text in the Custom buffer.  list labels each element value with its tag; group does not.

(vector ELEMENT-TYPES...)
     Like list except that the value must be a vector instead of a list.  The elements work the same as in list.

(alist :key-type KEY-TYPE :value-type VALUE-TYPE)
     The value must be a list of cons-cells, the CAR of each cell representing a key of customization type KEY-TYPE, and the CDR of the same cell representing a value of customization type VALUE-TYPE.  The user can add and delete key/value pairs, and edit both the key and the value of each pair.

     If omitted, KEY-TYPE and VALUE-TYPE default to sexp.

     The user can add any key matching the specified key type, but you can give some keys a preferential treatment by specifying them with the :options (see Variable Definitions).  The specified keys will always be shown in the customize buffer (together with a suitable value), with a checkbox to include or exclude or disable the key/value pair from the alist.  The user will not be able to edit the keys specified by the :options keyword argument.

     The argument to the :options keywords should be a list of specifications for reasonable keys in the alist.  Ordinarily, they are simply atoms, which stand for themselves.  For example:

          :options '("foo" "bar" "baz")

     specifies that there are three known keys, namely "foo", "bar" and "baz", which will always be shown first.

     You may want to restrict the value type for specific keys, for example, the value associated with the "bar" key can only be an integer.  You can specify this by using a list instead of an atom in the list.  The first element will specify the key, like before, while the second element will specify the value type.  For example:

          :options '("foo" ("bar" integer) "baz")

     Finally, you may want to change how the key is presented.  By default, the key is simply shown as a const, since the user cannot change the special keys specified with the :options keyword.  However, you may want to use a more specialized type for presenting the key, like function-item if you know it is a symbol with a function binding. This is done by using a customization type specification instead of a symbol for the key.

          :options '("foo"
                     ((function-item some-function) integer)
                     "baz")

     Many alists use lists with two elements, instead of cons cells.  For example,

          (defcustom list-alist
            '(("foo" 1) ("bar" 2) ("baz" 3))
            "Each element is a list of the form (KEY VALUE).")

     instead of

          (defcustom cons-alist
            '(("foo" . 1) ("bar" . 2) ("baz" . 3))
            "Each element is a cons-cell (KEY . VALUE).")

     Because of the way lists are implemented on top of cons cells, you can treat list-alist in the example above as a cons cell alist, where the value type is a list with a single element containing the real value.

          (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
            "Each element is a list of the form (KEY VALUE)."
            :type '(alist :value-type (group integer)))

     The group widget is used here instead of list only because the formatting is better suited for the purpose.

     Similarly, you can have alists with more values associated with each key, using variations of this trick:

          (defcustom person-data '(("brian"  50 t)
                                   ("dorith" 55 nil)
                                   ("ken"    52 t))
            "Alist of basic info about people.
          Each element has the form (NAME AGE MALE-FLAG)."
            :type '(alist :value-type (group integer boolean)))

(plist :key-type KEY-TYPE :value-type VALUE-TYPE)
     This customization type is similar to alist (see above), except that (i) the information is stored as a property list, (see Property Lists), and (ii) KEY-TYPE, if omitted, defaults to symbol rather than sexp.

(choice ALTERNATIVE-TYPES...)
     The value must fit one of ALTERNATIVE-TYPES.  For example, (choice integer string) allows either an integer or a string.

     In the customization buffer, the user selects an alternative using a menu, and can then edit the value in the usual way for that alternative.

     Normally the strings in this menu are determined automatically from the choices; however, you can specify different strings for the menu by including the :tag keyword in the alternatives.  For example, if an integer stands for a number of spaces, while a string is text to use verbatim, you might write the customization type this way,

          (choice (integer :tag "Number of spaces")
                  (string :tag "Literal text"))

     so that the menu offers Number of spaces and Literal text.

     In any alternative for which nil is not a valid value, other than a const, you should specify a valid default for that alternative using the :value keyword.  See Type Keywords.

     If some values are covered by more than one of the alternatives, customize will choose the first alternative that the value fits.  This means you should always list the most specific types first, and the most general last.  Here's an example of proper usage:

          (choice (const :tag "Off" nil)
                  symbol (sexp :tag "Other"))

     This way, the special value nil is not treated like other symbols, and symbols are not treated like other Lisp expressions.

(radio ELEMENT-TYPES...)
     This is similar to choice, except that the choices are displayed using radio buttons rather than a menu.  This has the advantage of displaying documentation for the choices when applicable and so is often a good choice for a choice between constant functions (function-item customization types).

(const VALUE)
     The value must be VALUE---nothing else is allowed.

     The main use of const is inside of choice.  For example, (choice integer (const nil)) allows either an integer or nil.

     :tag is often used with const, inside of choice. For example,

          (choice (const :tag "Yes" t)
                  (const :tag "No" nil)
                  (const :tag "Ask" foo))

     describes a variable for which t means yes, nil means no, and foo means ``ask''.

(other VALUE)
     This alternative can match any Lisp value, but if the user chooses this alternative, that selects the value VALUE.

     The main use of other is as the last element of choice. For example,

          (choice (const :tag "Yes" t)
                  (const :tag "No" nil)
                  (other :tag "Ask" foo))

     describes a variable for which t means yes, nil means no, and anything else means ``ask''.  If the user chooses Ask from the menu of alternatives, that specifies the value foo; but any other value (not t, nil or foo) displays as Ask, just like foo.

(function-item FUNCTION)
     Like const, but used for values which are functions.  This displays the documentation string as well as the function name. The documentation string is either the one you specify with :doc, or FUNCTION's own documentation string.

(variable-item VARIABLE)
     Like const, but used for values which are variable names.  This displays the documentation string as well as the variable name.  The documentation string is either the one you specify with :doc, or VARIABLE's own documentation string.

(set TYPES...)
     The value must be a list, and each element of the list must match one of the TYPES specified.

     This appears in the customization buffer as a checklist, so that each of TYPES may have either one corresponding element or none.  It is not possible to specify two different elements that match the same one of TYPES.  For example, (set integer symbol) allows one integer and/or one symbol in the list; it does not allow multiple integers or multiple symbols.  As a result, it is rare to use nonspecific types such as integer in a set.

     Most often, the TYPES in a set are const types, as shown here:

          (set (const :bold) (const :italic))

     Sometimes they describe possible elements in an alist:

          (set (cons :tag "Height" (const height) integer)
               (cons :tag "Width" (const width) integer))

     That lets the user specify a height value optionally and a width value optionally.

(repeat ELEMENT-TYPE)
     The value must be a list and each element of the list must fit the type ELEMENT-TYPE.  This appears in the customization buffer as a list of elements, with [INS] and [DEL] buttons for adding more elements or removing elements.

(restricted-sexp :match-alternatives CRITERIA)
     This is the most general composite type construct.  The value may be any Lisp object that satisfies one of CRITERIA.  CRITERIA should be a list, and each element should be one of these possibilities:

       * A predicate---that is, a function of one argument that has no side effects, and returns either nil or non-nil according to the argument.  Using a predicate in the list says that objects for which the predicate returns non-nil are acceptable.

       * A quoted constant---that is, 'OBJECT.  This sort of element in the list says that OBJECT itself is an acceptable value.

     For example,

          (restricted-sexp :match-alternatives
                           (integerp 't 'nil))

     allows integers, t and nil as legitimate values.

     The customization buffer shows all legitimate values using their read syntax, and the user edits them textually.

Here is a table of the keywords you can use in keyword-value pairs in a composite type:

:tag TAG
     Use TAG as the name of this alternative, for user communication purposes.  This is useful for a type that appears inside of a choice.

:match-alternatives CRITERIA
     Use CRITERIA to match possible values.  This is used only in restricted-sexp.

:args ARGUMENT-LIST
     Use the elements of ARGUMENT-LIST as the arguments of the type construct.  For instance, (const :args (foo)) is equivalent to (const foo).  You rarely need to write :args explicitly, because normally the arguments are recognized automatically as whatever follows the last keyword-value pair.

Splicing into Lists
-------------------

The :inline feature lets you splice a variable number of elements into the middle of a list or vector customization type.  You use it by adding :inline t to a type specification which is contained in a list or vector specification.

Normally, each entry in a list or vector type specification describes a single element type.  But when an entry contains :inline t, the value it matches is merged directly into the containing sequence.  For example, if the entry matches a list with three elements, those become three elements of the overall sequence.  This is analogous to ,@ in a backquote construct (see Backquote).

For example, to specify a list whose first element must be baz and whose remaining arguments should be zero or more of foo and bar, use this customization type:

     (list (const baz) (set :inline t (const foo) (const bar)))

This matches values such as (baz), (baz foo), (baz bar) and (baz foo bar).

When the element-type is a choice, you use :inline not in the choice itself, but in (some of) the alternatives of the choice.  For example, to match a list which must start with a file name, followed either by the symbol t or two strings, use this customization type:

     (list file
           (choice (const t)
                   (list :inline t string string)))

If the user chooses the first alternative in the choice, then the overall list has two elements and the second element is t.  If the user chooses the second alternative, then the overall list has three elements and the second and third must be strings.

Type Keywords
-------------

You can specify keyword-argument pairs in a customization type after the type name symbol.  Here are the keywords you can use, and their meanings:

:value DEFAULT
     Provide a default value.

     If nil is not a valid value for the alternative, then it is essential to specify a valid default with :value.

     If you use this for a type that appears as an alternative inside of choice; it specifies the default value to use, at first, if and when the user selects this alternative with the menu in the customization buffer.

     Of course, if the actual value of the option fits this alternative, it will appear showing the actual value, not DEFAULT.

:format FORMAT-STRING
     This string will be inserted in the buffer to represent the value corresponding to the type.  The following % escapes are available for use in FORMAT-STRING:

     %[BUTTON%]
          Display the text BUTTON marked as a button.  The :action attribute specifies what the button will do if the user invokes it; its value is a function which takes two arguments---the widget which the button appears in, and the event.

          There is no way to specify two different buttons with different actions.

     %{SAMPLE%}
          Show SAMPLE in a special face specified by :sample-face.

     %v
          Substitute the item's value.  How the value is represented depends on the kind of item, and (for variables) on the customization type.

     %d
          Substitute the item's documentation string.

     %h
          Like %d, but if the documentation string is more than one line, add a button to control whether to show all of it or just the first line.

     %t
          Substitute the tag here.  You specify the tag with the :tag keyword.

     %%
          Display a literal %.

:action ACTION
     Perform ACTION if the user clicks on a button.

:button-face FACE
     Use the face FACE (a face name or a list of face names) for button text displayed with %[...%].

:button-prefix PREFIX
:button-suffix SUFFIX
     These specify the text to display before and after a button. Each can be:

     nil
          No text is inserted.

     a string
          The string is inserted literally.

     a symbol
          The symbol's value is used.

:tag TAG
     Use TAG (a string) as the tag for the value (or part of the value) that corresponds to this type.

:doc DOC
     Use DOC as the documentation string for this value (or part of the value) that corresponds to this type.  In order for this to work, you must specify a value for :format, and use %d or %h in that value.

     The usual reason to specify a documentation string for a type is to provide more information about the meanings of alternatives inside a :choice type or the parts of some other composite type.

:help-echo MOTION-DOC
     When you move to this item with widget-forward or widget-backward, it will display the string MOTION-DOC in the echo area.  In addition, MOTION-DOC is used as the mouse help-echo string and may actually be a function or form evaluated to yield a help string.  If it is a function, it is called with one argument, the widget.

:match FUNCTION
     Specify how to decide whether a value matches the type.  The corresponding value, FUNCTION, should be a function that accepts two arguments, a widget and a value; it should return non-nil if the value is acceptable.

:validate FUNCTION
     Specify a validation function for input.  FUNCTION takes a widget as an argument, and should return nil if the widget's current value is valid for the widget.  Otherwise, it should return the widget containing the invalid data, and set that widget's :error property to a string explaining the error.

Defining New Types
------------------

In the previous sections we have described how to construct elaborate type specifications for defcustom.  In some cases you may want to give such a type specification a name.  The obvious case is when you are using the same type for many user options: rather than repeat the specification for each option, you can give the type specification a name, and use that name each defcustom.  The other case is when a user option's value is a recursive data structure.  To make it possible for a datatype to refer to itself, it needs to have a name.

Since custom types are implemented as widgets, the way to define a new customize type is to define a new widget.  We are not going to describe the widget interface here in details, see Introduction (The Emacs Widget Library), for that.  Instead we are going to demonstrate the minimal functionality needed for defining new customize types by a simple example.

     (define-widget 'binary-tree-of-string 'lazy
       "A binary tree made of cons-cells and strings."
       :offset 4
       :tag "Node"
       :type '(choice (string :tag "Leaf" :value "")
                      (cons :tag "Interior"
                            :value ("" . "")
                            binary-tree-of-string
                            binary-tree-of-string)))

     (defcustom foo-bar ""
       "Sample variable holding a binary tree of strings."
       :type 'binary-tree-of-string)

The function to define a new widget is called define-widget.  The first argument is the symbol we want to make a new widget type.  The second argument is a symbol representing an existing widget, the new widget is going to be defined in terms of difference from the existing widget.  For the purpose of defining new customization types, the lazy widget is perfect, because it accepts a :type keyword argument with the same syntax as the keyword argument to defcustom with the same name.  The third argument is a documentation string for the new widget.  You will be able to see that string with the M-x widget-browse RET binary-tree-of-string RET command.

After these mandatory arguments follow the keyword arguments.  The most important is :type, which describes the data type we want to match with this widget.  Here a binary-tree-of-string is described as being either a string, or a cons-cell whose car and cdr are themselves both binary-tree-of-string.  Note the reference to the widget type we are currently in the process of defining.  The :tag attribute is a string to name the widget in the user interface, and the :offset argument is there to ensure that child nodes are indented four spaces relative to the parent node, making the tree structure apparent in the customization buffer.

The defcustom shows how the new widget can be used as an ordinary customization type.

The reason for the name lazy is that the other composite widgets convert their inferior widgets to internal form when the widget is instantiated in a buffer.  This conversion is recursive, so the inferior widgets will convert their inferior widgets.  If the data structure is itself recursive, this conversion is an infinite recursion.  The lazy widget prevents the recursion: it convert its :type argument only when needed.

Applying Customizations
=======================

The following functions are responsible for installing the user's customization settings for variables and faces, respectively.  When the user invokes Save for future sessions in the Customize interface, that takes effect by writing a custom-set-variables and/or a custom-set-faces form into the custom file, to be evaluated the next time Emacs starts.

 -- Function: custom-set-variables &rest args
     This function installs the variable customizations specified by ARGS.  Each argument in ARGS should have the form

          (VAR EXPRESSION [NOW [REQUEST [COMMENT]]])

     VAR is a variable name (a symbol), and EXPRESSION is an expression which evaluates to the desired customized value.

     If the defcustom form for VAR has been evaluated prior to this custom-set-variables call, EXPRESSION is immediately evaluated, and the variable's value is set to the result.  Otherwise, EXPRESSION is stored into the variable's saved-value property, to be evaluated when the relevant defcustom is called (usually when the library defining that variable is loaded into Emacs).

     The NOW, REQUEST, and COMMENT entries are for internal use only, and may be omitted.  NOW, if non-nil, means to set the variable's value now, even if the variable's defcustom form has not been evaluated.  REQUEST is a list of features to be loaded immediately (see Named Features). COMMENT is a string describing the customization.

 -- Function: custom-set-faces &rest args
     This function installs the face customizations specified by ARGS.  Each argument in ARGS should have the form

          (FACE SPEC [NOW [COMMENT]])

     FACE is a face name (a symbol), and SPEC is the customized face specification for that face (see Defining Faces).

     The NOW and COMMENT entries are for internal use only, and may be omitted.  NOW, if non-nil, means to install the face specification now, even if the defface form has not been evaluated.  COMMENT is a string describing the customization.

Custom Themes
=============

Custom themes are collections of settings that can be enabled or disabled as a unit.  See Custom Themes (The GNU Emacs Manual).  Each Custom theme is defined by an Emacs Lisp source file, which should follow the conventions described in this section. (Instead of writing a Custom theme by hand, you can also create one using a Customize-like interface; see Creating Custom Themes (The GNU Emacs Manual).)

A Custom theme file should be named FOO-theme.el, where FOO is the theme name.  The first Lisp form in the file should be a call to deftheme, and the last form should be a call to provide-theme.

 -- Macro: deftheme theme &optional doc
     This macro declares THEME (a symbol) as the name of a Custom theme.  The optional argument DOC should be a string describing the theme; this is the description shown when the user invokes the describe-theme command or types ? in the *Custom Themes* buffer.

     Two special theme names are disallowed (using them causes an error): user is a dummy theme that stores the user's direct customization settings, and changed is a dummy theme that stores changes made outside of the Customize system.

 -- Macro: provide-theme theme
     This macro declares that the theme named THEME has been fully specified.

In between deftheme and provide-theme are Lisp forms specifying the theme settings: usually a call to custom-theme-set-variables and/or a call to custom-theme-set-faces.

 -- Function: custom-theme-set-variables theme &rest args
     This function specifies the Custom theme THEME's variable settings.  THEME should be a symbol.  Each argument in ARGS should be a list of the form

          (VAR EXPRESSION [NOW [REQUEST [COMMENT]]])

     where the list entries have the same meanings as in custom-set-variables.  See Applying Customizations.

 -- Function: custom-theme-set-faces theme &rest args
     This function specifies the Custom theme THEME's face settings. THEME should be a symbol.  Each argument in ARGS should be a list of the form

          (FACE SPEC [NOW [COMMENT]])

     where the list entries have the same meanings as in custom-set-faces.  See Applying Customizations.

In theory, a theme file can also contain other Lisp forms, which would be evaluated when loading the theme, but that is bad form. To protect against loading themes containing malicious code, Emacs displays the source file and asks for confirmation from the user before loading any non-built-in theme for the first time.  As such, themes are not ordinarily byte-compiled, and source files always take precedence when Emacs is looking for a theme to load.

The following functions are useful for programmatically enabling and disabling themes:

 -- Function: custom-theme-p theme
     This function return a non-nil value if THEME (a symbol) is the name of a Custom theme (i.e., a Custom theme which has been loaded into Emacs, whether or not the theme is enabled).  Otherwise, it returns nil.

 -- Variable: custom-known-themes
     The value of this variable is a list of themes loaded into Emacs. Each theme is represented by a Lisp symbol (the theme name).  The default value of this variable is a list containing two dummy themes: (user changed).  The changed theme stores settings made before any Custom themes are applied (e.g., variables set outside of Customize).  The user theme stores settings the user has customized and saved.  Any additional themes declared with the deftheme macro are added to the front of this list.

 -- Command: load-theme theme &optional no-confirm no-enable
     This function loads the Custom theme named THEME from its source file, looking for the source file in the directories specified by the variable custom-theme-load-path.  See Custom Themes (The GNU Emacs Manual).  It also enables the theme (unless the optional argument NO-ENABLE is non-nil), causing its variable and face settings to take effect.  It prompts the user for confirmation before loading the theme, unless the optional argument NO-CONFIRM is non-nil.

 -- Command: enable-theme theme
     This function enables the Custom theme named THEME.  It signals an error if no such theme has been loaded.

 -- Command: disable-theme theme
     This function disables the Custom theme named THEME.  The theme remains loaded, so that a subsequent call to enable-theme will re-enable it.