Next: Defining Customization Groups, Up: Customization Settings   [Contents][Index]

15.1 Common Item Keywords ¶

The customization declarations that we will describe in the next few sections—defcustom, defgroup, etc.—all accept keyword arguments (see Variables that Never Change) 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 Conventional Headers for Emacs Libraries.

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

(face-link face)

Link to the documentation of a face; face is a string which specifies the name of the face to describe with describe-face 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.

Next: Defining Customization Variables, Previous: Common Item Keywords, Up: Customization Settings   [Contents][Index]

15.2 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 Item 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, faces, and subgroups of a group are stored in the custom-group property of the group’s symbol. See Accessing Symbol Properties. The value of that property is a list of pairs whose car is the symbol of the variable or the face or the subgroup, and the cdr is one of the corresponding symbols custom-variable, custom-face, 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.

Next: Customization Types, Previous: Defining Customization Groups, Up: Customization Settings   [Contents][Index]

15.3 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 Global 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 Scoping Rules for Variable Bindings.

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 Global 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 Item 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.

Re-evaluating a defcustom form with a different :options value does not clear the values added by previous evaluations, or added by calls to custom-add-frequent-value (see below).

: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 or three arguments, a symbol (the option name), the new value, and an optional buffer-local indicator. setfunction 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. If optional buffer-local is non-nil, the new value should be set buffer locally and not affect its global or default values. The default for setfunction is set-default-toplevel-value.

If defined, setfunction will also be called when evaluating a defcustom form with C-M-x in Emacs Lisp mode and when the option’s value is changed via the setopt macro (see setopt).

If you specify this keyword, the variable’s documentation string should describe how to do the same job in hand-written Lisp code, either by invoking setfunction directly or by using setopt or setopt-local.

: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-toplevel-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-toplevel-value 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-toplevel-value.

custom-initialize-after-file-load

This function behaves like custom-initialize-set, but it delays the actual initialization until after the containing file is loaded. This can be useful to break the common dependency where the setter is (or uses) a function which needs to be defined after the variable, such as when a global minor mode has a non-nil :init-value.

custom-initialize-delay

This function behaves like custom-initialize-set, but it delays the actual initialization to the next Emacs start. This should be used in Lisp files that are preloaded (loaded when Emacs is built), when it is important to ensure that the initialization is performed in the run-time context (which could be on a different system or programming environment). See custom-initialize-delay.

:local value ¶

If the value is t, mark option as automatically buffer-local; if the value is permanent, also set options permanent-local property to t. Finally, if the value is permanent-only, set options permanent-local property to t without marking it as automatically buffer-local. See Creating and Deleting Buffer-Local Bindings.

: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 Item Keywords. Here is an example:

(defcustom frobnicate-automatically nil
  "Non-nil means automatically frobnicate all buffers."
  :type 'boolean
  :require 'frobnicate-mode
  :group 'frobnicate)

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.

Since evaluating a defcustom form does not clear values added previously, Lisp programs can use this function to add values for user options not yet defined.

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. In addition, there’s themed-value, which is used to record the value set by a theme (see Custom Themes). 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.

Next: Applying Customizations, Previous: Defining Customization Variables, Up: Customization Settings   [Contents][Index]

15.4 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 in The Emacs Widget Library, for details.

• Simple Types
• Composite Types
• Splicing into Lists
• Type Keywords
• Defining New Types

(constructor arguments...)

(constructor {keyword value}... arguments...)

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

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

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

Next: Custom Themes, Previous: Customization Types, Up: Customization Settings   [Contents][Index]

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

Previous: Applying Customizations, Up: Customization Settings   [Contents][Index]

15.6 Custom Themes ¶

Custom themes are collections of settings that can be enabled or disabled as a unit. See Custom Themes in 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 in 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 &rest properties ¶

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. The remaining arguments properties are used pass a property list with theme attributes.

The following attributes are supported:

:family

A symbol designating what “family” a theme belongs to. A family of themes is a set of similar themes that differ by minor aspects, such as face colors that are meant for the light vs dark background of the frame.

:kind

A symbol. If a theme is enabled and this property has the value color-scheme, then the theme-choose-variant command will look for other available themes that belong to the same family in order to switch the themes. Other values are currently unspecified and should not be used.

:background-mode

A symbol, either light or dark. This attribute is currently unused, but should still be specified.

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 usually 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 in 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.

Function: require-theme feature &optional noerror ¶

This function searches custom-theme-load-path for a file that provides feature and then loads it. This is like the function require (see Features), except it searches custom-theme-load-path instead of load-path (see Library Search). This can be useful in Custom themes that need to load supporting Lisp files when require is unsuitable for that.

If feature, which should be a symbol, is not already present in the current Emacs session according to featurep, then require-theme searches for a file named feature with an added ‘.elc’ or ‘.el’ suffix, in that order, in the directories specified by custom-theme-load-path.

If a file providing feature is successfully found and loaded, then require-theme returns feature. The optional argument noerror determines what happens if the search or loading fails. If it is nil, the function signals an error; otherwise, it returns nil. If the file loads successfully but does not provide feature, then require-theme signals an error; this cannot be suppressed.

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.