2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1997-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @node Customization, Loading, Macros, Top
6 @chapter Customization Settings
8 @cindex customization item
9 This chapter describes how to declare customizable variables and
10 customization groups for classifying them. We use the term
11 @dfn{customization item} to include customizable variables,
12 customization groups, as well as faces.
14 @xref{Defining Faces}, for the @code{defface} macro, which is used
15 for declaring customizable faces.
18 * Common Keywords:: Common keyword arguments for all kinds of
19 customization declarations.
20 * Group Definitions:: Writing customization group definitions.
21 * Variable Definitions:: Declaring user options.
22 * Customization Types:: Specifying the type of a user option.
23 * Applying Customizations:: Functions to apply customization settings.
24 * Custom Themes:: Writing Custom themes.
28 @section Common Item Keywords
30 @cindex customization keywords
31 The customization declarations that we will describe in the next few
32 sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword
33 arguments for specifying various information. This section describes
34 keywords that apply to all types of customization declarations.
36 All of these keywords, except @code{:tag}, can be used more than once
37 in a given item. Each use of the keyword has an independent effect.
38 The keyword @code{:tag} is an exception because any given item can only
42 @item :tag @var{label}
43 @kindex tag@r{, customization keyword}
44 Use @var{label}, a string, instead of the item's name, to label the
45 item in customization menus and buffers. @strong{Don't use a tag
46 which is substantially different from the item's real name; that would
49 @kindex group@r{, customization keyword}
50 @item :group @var{group}
51 Put this customization item in group @var{group}. When you use
52 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
55 If you use this keyword more than once, you can put a single item into
56 more than one group. Displaying any of those groups will show this
57 item. Please don't overdo this, since the result would be annoying.
59 @item :link @var{link-data}
60 @kindex link@r{, customization keyword}
61 Include an external link after the documentation string for this item.
62 This is a sentence containing an active field which references some
65 There are several alternatives you can use for @var{link-data}:
68 @item (custom-manual @var{info-node})
69 Link to an Info node; @var{info-node} is a string which specifies the
70 node name, as in @code{"(emacs)Top"}. The link appears as
71 @samp{[Manual]} in the customization buffer and enters the built-in
72 Info reader on @var{info-node}.
74 @item (info-link @var{info-node})
75 Like @code{custom-manual} except that the link appears
76 in the customization buffer with the Info node name.
78 @item (url-link @var{url})
79 Link to a web page; @var{url} is a string which specifies the
80 @acronym{URL}. The link appears in the customization buffer as
81 @var{url} and invokes the WWW browser specified by
82 @code{browse-url-browser-function}.
84 @item (emacs-commentary-link @var{library})
85 Link to the commentary section of a library; @var{library} is a string
86 which specifies the library name.
88 @item (emacs-library-link @var{library})
89 Link to an Emacs Lisp library file; @var{library} is a string which
90 specifies the library name.
92 @item (file-link @var{file})
93 Link to a file; @var{file} is a string which specifies the name of the
94 file to visit with @code{find-file} when the user invokes this link.
96 @item (function-link @var{function})
97 Link to the documentation of a function; @var{function} is a string
98 which specifies the name of the function to describe with
99 @code{describe-function} when the user invokes this link.
101 @item (variable-link @var{variable})
102 Link to the documentation of a variable; @var{variable} is a string
103 which specifies the name of the variable to describe with
104 @code{describe-variable} when the user invokes this link.
106 @item (custom-group-link @var{group})
107 Link to another customization group. Invoking it creates a new
108 customization buffer for @var{group}.
111 You can specify the text to use in the customization buffer by adding
112 @code{:tag @var{name}} after the first element of the @var{link-data};
113 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
114 the Emacs manual which appears in the buffer as @samp{foo}.
116 You can use this keyword more than once, to add multiple links.
118 @item :load @var{file}
119 @kindex load@r{, customization keyword}
120 Load file @var{file} (a string) before displaying this customization
121 item (@pxref{Loading}). Loading is done with @code{load}, and only if
122 the file is not already loaded.
124 @item :require @var{feature}
125 @kindex require@r{, customization keyword}
126 Execute @code{(require '@var{feature})} when your saved customizations
127 set the value of this item. @var{feature} should be a symbol.
129 The most common reason to use @code{:require} is when a variable enables
130 a feature such as a minor mode, and just setting the variable won't have
131 any effect unless the code which implements the mode is loaded.
133 @item :version @var{version}
134 @kindex version@r{, customization keyword}
135 This keyword specifies that the item was first introduced in Emacs
136 version @var{version}, or that its default value was changed in that
137 version. The value @var{version} must be a string.
139 @item :package-version '(@var{package} . @var{version})
140 @kindex package-version@r{, customization keyword}
141 This keyword specifies that the item was first introduced in
142 @var{package} version @var{version}, or that its meaning or default
143 value was changed in that version. This keyword takes priority over
146 @var{package} should be the official name of the package, as a symbol
147 (e.g.@: @code{MH-E}). @var{version} should be a string. If the
148 package @var{package} is released as part of Emacs, @var{package} and
149 @var{version} should appear in the value of
150 @code{customize-package-emacs-version-alist}.
153 Packages distributed as part of Emacs that use the
154 @code{:package-version} keyword must also update the
155 @code{customize-package-emacs-version-alist} variable.
157 @defvar customize-package-emacs-version-alist
158 This alist provides a mapping for the versions of Emacs that are
159 associated with versions of a package listed in the
160 @code{:package-version} keyword. Its elements look like this:
163 (@var{package} (@var{pversion} . @var{eversion})@dots{})
166 For each @var{package}, which is a symbol, there are one or more
167 elements that contain a package version @var{pversion} with an
168 associated Emacs version @var{eversion}. These versions are strings.
169 For example, the MH-E package updates this alist with the following:
172 (add-to-list 'customize-package-emacs-version-alist
173 '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
174 ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
175 ("7.4" . "22.1") ("8.0" . "22.1")))
178 The value of @var{package} needs to be unique and it needs to match
179 the @var{package} value appearing in the @code{:package-version}
180 keyword. Since the user might see the value in an error message, a good
181 choice is the official name of the package, such as MH-E or Gnus.
184 @node Group Definitions
185 @section Defining Customization Groups
186 @cindex define customization group
187 @cindex customization groups, defining
189 Each Emacs Lisp package should have one main customization group which
190 contains all the options, faces and other groups in the package. If the
191 package has a small number of options and faces, use just one group and
192 put everything in it. When there are more than twelve or so options and
193 faces, then you should structure them into subgroups, and put the
194 subgroups under the package's main customization group. It is OK to
195 put some of the options and faces in the package's main group alongside
198 The package's main or only group should be a member of one or more of
199 the standard customization groups. (To display the full list of them,
200 use @kbd{M-x customize}.) Choose one or more of them (but not too
201 many), and add your group to each of them using the @code{:group}
204 The way to declare new customization groups is with @code{defgroup}.
206 @defmac defgroup group members doc [keyword value]@dots{}
207 Declare @var{group} as a customization group containing @var{members}.
208 Do not quote the symbol @var{group}. The argument @var{doc} specifies
209 the documentation string for the group.
211 The argument @var{members} is a list specifying an initial set of
212 customization items to be members of the group. However, most often
213 @var{members} is @code{nil}, and you specify the group's members by
214 using the @code{:group} keyword when defining those members.
216 If you want to specify group members through @var{members}, each element
217 should have the form @code{(@var{name} @var{widget})}. Here @var{name}
218 is a symbol, and @var{widget} is a widget type for editing that symbol.
219 Useful widgets are @code{custom-variable} for a variable,
220 @code{custom-face} for a face, and @code{custom-group} for a group.
222 When you introduce a new group into Emacs, use the @code{:version}
223 keyword in the @code{defgroup}; then you need not use it for
224 the individual members of the group.
226 In addition to the common keywords (@pxref{Common Keywords}), you can
227 also use this keyword in @code{defgroup}:
230 @item :prefix @var{prefix}
231 @kindex prefix@r{, @code{defgroup} keyword}
232 If the name of an item in the group starts with @var{prefix}, and the
233 customizable variable @code{custom-unlispify-remove-prefixes} is
234 non-@code{nil}, the item's tag will omit @var{prefix}. A group can
235 have any number of prefixes.
239 @defopt custom-unlispify-remove-prefixes
240 If this variable is non-@code{nil}, the prefixes specified by a
241 group's @code{:prefix} keyword are omitted from tag names, whenever
242 the user customizes the group.
244 The default value is @code{nil}, i.e.@: the prefix-discarding feature
245 is disabled. This is because discarding prefixes often leads to
246 confusing names for options and faces.
249 @node Variable Definitions
250 @section Defining Customization Variables
251 @cindex define customization options
252 @cindex customization variables, how to define
254 @defmac defcustom option standard doc [keyword value]@dots{}
255 This macro declares @var{option} as a user option (i.e.@: a
256 customizable variable). You should not quote @var{option}.
258 The argument @var{standard} is an expression that specifies the
259 standard value for @var{option}. Evaluating the @code{defcustom} form
260 evaluates @var{standard}, but does not necessarily install the
261 standard value. If @var{option} already has a default value,
262 @code{defcustom} does not change it. If the user has saved a
263 customization for @var{option}, @code{defcustom} installs the user's
264 customized value as @var{option}'s default value. If neither of those
265 cases applies, @code{defcustom} installs the result of evaluating
266 @var{standard} as the default value.
268 The expression @var{standard} can be evaluated at various other times,
269 too---whenever the customization facility needs to know @var{option}'s
270 standard value. So be sure to use an expression which is harmless to
271 evaluate at any time.
273 The argument @var{doc} specifies the documentation string for the
276 Every @code{defcustom} should specify @code{:group} at least once.
278 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
279 mode (@code{eval-defun}), a special feature of @code{eval-defun}
280 arranges to set the variable unconditionally, without testing whether
281 its value is void. (The same feature applies to @code{defvar}.)
282 @xref{Defining Variables}.
284 If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
285 (@pxref{Building Emacs}), the standard value installed at dump time
286 might be incorrect, e.g.@: because another variable that it depends on
287 has not been assigned the right value yet. In that case, use
288 @code{custom-reevaluate-setting}, described below, to re-evaluate the
289 standard value after Emacs starts up.
292 @code{defcustom} accepts the following additional keywords:
295 @item :type @var{type}
296 Use @var{type} as the data type for this option. It specifies which
297 values are legitimate, and how to display the value.
298 @xref{Customization Types}, for more information.
300 @item :options @var{value-list}
301 @kindex options@r{, @code{defcustom} keyword}
302 Specify the list of reasonable values for use in this
303 option. The user is not restricted to using only these values, but they
304 are offered as convenient alternatives.
306 This is meaningful only for certain types, currently including
307 @code{hook}, @code{plist} and @code{alist}. See the definition of the
308 individual types for a description of how to use @code{:options}.
310 @item :set @var{setfunction}
311 @kindex set@r{, @code{defcustom} keyword}
312 Specify @var{setfunction} as the way to change the value of this
313 option when using the Customize interface. The function
314 @var{setfunction} should take two arguments, a symbol (the option
315 name) and the new value, and should do whatever is necessary to update
316 the value properly for this option (which may not mean simply setting
317 the option as a Lisp variable). The default for @var{setfunction} is
320 If you specify this keyword, the variable's documentation string
321 should describe how to do the same job in hand-written Lisp code.
323 @item :get @var{getfunction}
324 @kindex get@r{, @code{defcustom} keyword}
325 Specify @var{getfunction} as the way to extract the value of this
326 option. The function @var{getfunction} should take one argument, a
327 symbol, and should return whatever customize should use as the
328 ``current value'' for that symbol (which need not be the symbol's Lisp
329 value). The default is @code{default-value}.
331 You have to really understand the workings of Custom to use
332 @code{:get} correctly. It is meant for values that are treated in
333 Custom as variables but are not actually stored in Lisp variables. It
334 is almost surely a mistake to specify @var{getfunction} for a value
335 that really is stored in a Lisp variable.
337 @item :initialize @var{function}
338 @kindex initialize@r{, @code{defcustom} keyword}
339 @var{function} should be a function used to initialize the variable
340 when the @code{defcustom} is evaluated. It should take two arguments,
341 the option name (a symbol) and the value. Here are some predefined
342 functions meant for use in this way:
345 @item custom-initialize-set
346 Use the variable's @code{:set} function to initialize the variable, but
347 do not reinitialize it if it is already non-void.
349 @item custom-initialize-default
350 Like @code{custom-initialize-set}, but use the function
351 @code{set-default} to set the variable, instead of the variable's
352 @code{:set} function. This is the usual choice for a variable whose
353 @code{:set} function enables or disables a minor mode; with this choice,
354 defining the variable will not call the minor mode function, but
355 customizing the variable will do so.
357 @item custom-initialize-reset
358 Always use the @code{:set} function to initialize the variable. If
359 the variable is already non-void, reset it by calling the @code{:set}
360 function using the current value (returned by the @code{:get} method).
361 This is the default @code{:initialize} function.
363 @item custom-initialize-changed
364 Use the @code{:set} function to initialize the variable, if it is
365 already set or has been customized; otherwise, just use
368 @item custom-initialize-safe-set
369 @itemx custom-initialize-safe-default
370 These functions behave like @code{custom-initialize-set}
371 (@code{custom-initialize-default}, respectively), but catch errors.
372 If an error occurs during initialization, they set the variable to
373 @code{nil} using @code{set-default}, and signal no error.
375 These functions are meant for options defined in pre-loaded files,
376 where the @var{standard} expression may signal an error because some
377 required variable or function is not yet defined. The value normally
378 gets updated in @file{startup.el}, ignoring the value computed by
379 @code{defcustom}. After startup, if one unsets the value and
380 reevaluates the @code{defcustom}, the @var{standard} expression can be
381 evaluated without error.
384 @item :risky @var{value}
385 @kindex risky@r{, @code{defcustom} keyword}
386 Set the variable's @code{risky-local-variable} property to
387 @var{value} (@pxref{File Local Variables}).
389 @item :safe @var{function}
390 @kindex safe@r{, @code{defcustom} keyword}
391 Set the variable's @code{safe-local-variable} property to
392 @var{function} (@pxref{File Local Variables}).
394 @item :set-after @var{variables}
395 @kindex set-after@r{, @code{defcustom} keyword}
396 When setting variables according to saved customizations, make sure to
397 set the variables @var{variables} before this one; in other words, delay
398 setting this variable until after those others have been handled. Use
399 @code{:set-after} if setting this variable won't work properly unless
400 those other variables already have their intended values.
403 It is useful to specify the @code{:require} keyword for an option
404 that ``turns on'' a certain feature. This causes Emacs to load the
405 feature, if it is not already loaded, whenever the option is set.
406 @xref{Common Keywords}. Here is an example, from the library
410 (defcustom save-place nil
411 "Non-nil means automatically save place in each file..."
417 If a customization item has a type such as @code{hook} or
418 @code{alist}, which supports @code{:options}, you can add additional
419 values to the list from outside the @code{defcustom} declaration by
420 calling @code{custom-add-frequent-value}. For example, if you define a
421 function @code{my-lisp-mode-initialization} intended to be called from
422 @code{emacs-lisp-mode-hook}, you might want to add that to the list of
423 reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
424 its definition. You can do it thus:
427 (custom-add-frequent-value 'emacs-lisp-mode-hook
428 'my-lisp-mode-initialization)
431 @defun custom-add-frequent-value symbol value
432 For the customization option @var{symbol}, add @var{value} to the
433 list of reasonable values.
435 The precise effect of adding a value depends on the customization type
439 Internally, @code{defcustom} uses the symbol property
440 @code{standard-value} to record the expression for the standard value,
441 @code{saved-value} to record the value saved by the user with the
442 customization buffer, and @code{customized-value} to record the value
443 set by the user with the customization buffer, but not saved.
444 @xref{Property Lists}. These properties are lists, the car of which
445 is an expression that evaluates to the value.
447 @defun custom-reevaluate-setting symbol
448 This function re-evaluates the standard value of @var{symbol}, which
449 should be a user option declared via @code{defcustom}. If the
450 variable was customized, this function re-evaluates the saved value
451 instead. Then it sets the user option to that value (using the
452 option's @code{:set} property if that is defined).
454 This is useful for customizable options that are defined before their
455 value could be computed correctly. For example, during startup Emacs
456 calls this function for some user options that were defined in
457 pre-loaded Emacs Lisp files, but whose initial values depend on
458 information available only at run-time.
461 @defun custom-variable-p arg
462 This function returns non-@code{nil} if @var{arg} is a customizable
463 variable. A customizable variable is either a variable that has a
464 @code{standard-value} or @code{custom-autoload} property (usually
465 meaning it was declared with @code{defcustom}), or an alias for
466 another customizable variable.
469 @node Customization Types
470 @section Customization Types
472 @cindex customization types
473 When you define a user option with @code{defcustom}, you must specify
474 its @dfn{customization type}. That is a Lisp object which describes (1)
475 which values are legitimate and (2) how to display the value in the
476 customization buffer for editing.
478 @kindex type@r{, @code{defcustom} keyword}
479 You specify the customization type in @code{defcustom} with the
480 @code{:type} keyword. The argument of @code{:type} is evaluated, but
481 only once when the @code{defcustom} is executed, so it isn't useful
482 for the value to vary. Normally we use a quoted constant. For
486 (defcustom diff-command "diff"
487 "The command to use to run diff."
492 In general, a customization type is a list whose first element is a
493 symbol, one of the customization type names defined in the following
494 sections. After this symbol come a number of arguments, depending on
495 the symbol. Between the type symbol and its arguments, you can
496 optionally write keyword-value pairs (@pxref{Type Keywords}).
498 Some type symbols do not use any arguments; those are called
499 @dfn{simple types}. For a simple type, if you do not use any
500 keyword-value pairs, you can omit the parentheses around the type
501 symbol. For example just @code{string} as a customization type is
502 equivalent to @code{(string)}.
504 All customization types are implemented as widgets; see @ref{Top, ,
505 Introduction, widget, The Emacs Widget Library}, for details.
508 * Simple Types:: Simple customization types: sexp, integer, etc.
509 * Composite Types:: Build new types from other types or data.
510 * Splicing into Lists:: Splice elements into list with @code{:inline}.
511 * Type Keywords:: Keyword-argument pairs in a customization type.
512 * Defining New Types:: Give your type a name.
516 @subsection Simple Types
518 This section describes all the simple customization types. For
519 several of these customization types, the customization widget
520 provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}.
524 The value may be any Lisp object that can be printed and read back.
525 You can use @code{sexp} as a fall-back for any option, if you don't
526 want to take the time to work out a more specific type to use.
529 The value must be an integer.
532 The value must be a number (floating point or integer).
535 The value must be a floating point number.
538 The value must be a string. The customization buffer shows the string
539 without delimiting @samp{"} characters or @samp{\} quotes.
542 Like @code{string} except that the string must be a valid regular
546 The value must be a character code. A character code is actually an
547 integer, but this type shows the value by inserting the character in the
548 buffer, rather than by showing the number.
551 The value must be a file name. The widget provides completion.
553 @item (file :must-match t)
554 The value must be a file name for an existing file. The widget
558 The value must be a directory name. The widget provides completion.
561 The value must be a list of functions. This customization type is
562 used for hook variables. You can use the @code{:options} keyword in a
563 hook variable's @code{defcustom} to specify a list of functions
564 recommended for use in the hook; @xref{Variable Definitions}.
567 The value must be a symbol. It appears in the customization buffer as
568 the symbol name. The widget provides completion.
571 The value must be either a lambda expression or a function name. The
572 widget provides completion for function names.
575 The value must be a variable name. The widget provides completion.
578 The value must be a symbol which is a face name. The widget provides
582 The value is boolean---either @code{nil} or @code{t}. Note that by
583 using @code{choice} and @code{const} together (see the next section),
584 you can specify that the value must be @code{nil} or @code{t}, but also
585 specify the text to describe each value in a way that fits the specific
586 meaning of the alternative.
589 The value must be a coding-system name, and you can do completion with
593 The value must be a valid color name. The widget provides completion
594 for color names, as well as a sample and a button for selecting a
595 color name from a list of color names shown in a @file{*Colors*}
599 @node Composite Types
600 @subsection Composite Types
601 @cindex composite types (customization)
603 When none of the simple types is appropriate, you can use composite
604 types, which build new types from other types or from specified data.
605 The specified types or data are called the @dfn{arguments} of the
606 composite type. The composite type normally looks like this:
609 (@var{constructor} @var{arguments}@dots{})
613 but you can also add keyword-value pairs before the arguments, like
617 (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
620 Here is a table of constructors and how to use them to write
624 @item (cons @var{car-type} @var{cdr-type})
625 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
626 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
627 symbol)} is a customization type which matches values such as
628 @code{("foo" . foo)}.
630 In the customization buffer, the @sc{car} and @sc{cdr} are displayed
631 and edited separately, each according to their specified type.
633 @item (list @var{element-types}@dots{})
634 The value must be a list with exactly as many elements as the
635 @var{element-types} given; and each element must fit the
636 corresponding @var{element-type}.
638 For example, @code{(list integer string function)} describes a list of
639 three elements; the first element must be an integer, the second a
640 string, and the third a function.
642 In the customization buffer, each element is displayed and edited
643 separately, according to the type specified for it.
645 @item (group @var{element-types}@dots{})
646 This works like @code{list} except for the formatting
647 of text in the Custom buffer. @code{list} labels each
648 element value with its tag; @code{group} does not.
650 @item (vector @var{element-types}@dots{})
651 Like @code{list} except that the value must be a vector instead of a
652 list. The elements work the same as in @code{list}.
654 @item (alist :key-type @var{key-type} :value-type @var{value-type})
655 The value must be a list of cons-cells, the @sc{car} of each cell
656 representing a key of customization type @var{key-type}, and the
657 @sc{cdr} of the same cell representing a value of customization type
658 @var{value-type}. The user can add and delete key/value pairs, and
659 edit both the key and the value of each pair.
661 If omitted, @var{key-type} and @var{value-type} default to
664 The user can add any key matching the specified key type, but you can
665 give some keys a preferential treatment by specifying them with the
666 @code{:options} (see @ref{Variable Definitions}). The specified keys
667 will always be shown in the customize buffer (together with a suitable
668 value), with a checkbox to include or exclude or disable the key/value
669 pair from the alist. The user will not be able to edit the keys
670 specified by the @code{:options} keyword argument.
672 The argument to the @code{:options} keywords should be a list of
673 specifications for reasonable keys in the alist. Ordinarily, they are
674 simply atoms, which stand for themselves. For example:
677 :options '("foo" "bar" "baz")
681 specifies that there are three ``known'' keys, namely @code{"foo"},
682 @code{"bar"} and @code{"baz"}, which will always be shown first.
684 You may want to restrict the value type for specific keys, for
685 example, the value associated with the @code{"bar"} key can only be an
686 integer. You can specify this by using a list instead of an atom in
687 the list. The first element will specify the key, like before, while
688 the second element will specify the value type. For example:
691 :options '("foo" ("bar" integer) "baz")
694 Finally, you may want to change how the key is presented. By default,
695 the key is simply shown as a @code{const}, since the user cannot change
696 the special keys specified with the @code{:options} keyword. However,
697 you may want to use a more specialized type for presenting the key, like
698 @code{function-item} if you know it is a symbol with a function binding.
699 This is done by using a customization type specification instead of a
703 :options '("foo" ((function-item some-function) integer)
707 Many alists use lists with two elements, instead of cons cells. For
711 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
712 "Each element is a list of the form (KEY VALUE).")
719 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
720 "Each element is a cons-cell (KEY . VALUE).")
723 Because of the way lists are implemented on top of cons cells, you can
724 treat @code{list-alist} in the example above as a cons cell alist, where
725 the value type is a list with a single element containing the real
729 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
730 "Each element is a list of the form (KEY VALUE)."
731 :type '(alist :value-type (group integer)))
734 The @code{group} widget is used here instead of @code{list} only because
735 the formatting is better suited for the purpose.
737 Similarly, you can have alists with more values associated with each
738 key, using variations of this trick:
741 (defcustom person-data '(("brian" 50 t)
744 "Alist of basic info about people.
745 Each element has the form (NAME AGE MALE-FLAG)."
746 :type '(alist :value-type (group integer boolean)))
749 @item (plist :key-type @var{key-type} :value-type @var{value-type})
750 This customization type is similar to @code{alist} (see above), except
751 that (i) the information is stored as a property list,
752 (@pxref{Property Lists}), and (ii) @var{key-type}, if omitted,
753 defaults to @code{symbol} rather than @code{sexp}.
755 @item (choice @var{alternative-types}@dots{})
756 The value must fit one of @var{alternative-types}. For example,
757 @code{(choice integer string)} allows either an integer or a string.
759 In the customization buffer, the user selects an alternative
760 using a menu, and can then edit the value in the usual way for that
763 Normally the strings in this menu are determined automatically from the
764 choices; however, you can specify different strings for the menu by
765 including the @code{:tag} keyword in the alternatives. For example, if
766 an integer stands for a number of spaces, while a string is text to use
767 verbatim, you might write the customization type this way,
770 (choice (integer :tag "Number of spaces")
771 (string :tag "Literal text"))
775 so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
777 In any alternative for which @code{nil} is not a valid value, other than
778 a @code{const}, you should specify a valid default for that alternative
779 using the @code{:value} keyword. @xref{Type Keywords}.
781 If some values are covered by more than one of the alternatives,
782 customize will choose the first alternative that the value fits. This
783 means you should always list the most specific types first, and the
784 most general last. Here's an example of proper usage:
787 (choice (const :tag "Off" nil)
788 symbol (sexp :tag "Other"))
792 This way, the special value @code{nil} is not treated like other
793 symbols, and symbols are not treated like other Lisp expressions.
795 @item (radio @var{element-types}@dots{})
796 This is similar to @code{choice}, except that the choices are displayed
797 using `radio buttons' rather than a menu. This has the advantage of
798 displaying documentation for the choices when applicable and so is often
799 a good choice for a choice between constant functions
800 (@code{function-item} customization types).
802 @item (const @var{value})
803 The value must be @var{value}---nothing else is allowed.
805 The main use of @code{const} is inside of @code{choice}. For example,
806 @code{(choice integer (const nil))} allows either an integer or
809 @code{:tag} is often used with @code{const}, inside of @code{choice}.
813 (choice (const :tag "Yes" t)
814 (const :tag "No" nil)
815 (const :tag "Ask" foo))
819 describes a variable for which @code{t} means yes, @code{nil} means no,
820 and @code{foo} means ``ask''.
822 @item (other @var{value})
823 This alternative can match any Lisp value, but if the user chooses this
824 alternative, that selects the value @var{value}.
826 The main use of @code{other} is as the last element of @code{choice}.
830 (choice (const :tag "Yes" t)
831 (const :tag "No" nil)
832 (other :tag "Ask" foo))
836 describes a variable for which @code{t} means yes, @code{nil} means no,
837 and anything else means ``ask''. If the user chooses @samp{Ask} from
838 the menu of alternatives, that specifies the value @code{foo}; but any
839 other value (not @code{t}, @code{nil} or @code{foo}) displays as
840 @samp{Ask}, just like @code{foo}.
842 @item (function-item @var{function})
843 Like @code{const}, but used for values which are functions. This
844 displays the documentation string as well as the function name.
845 The documentation string is either the one you specify with
846 @code{:doc}, or @var{function}'s own documentation string.
848 @item (variable-item @var{variable})
849 Like @code{const}, but used for values which are variable names. This
850 displays the documentation string as well as the variable name. The
851 documentation string is either the one you specify with @code{:doc}, or
852 @var{variable}'s own documentation string.
854 @item (set @var{types}@dots{})
855 The value must be a list, and each element of the list must match one of
856 the @var{types} specified.
858 This appears in the customization buffer as a checklist, so that each of
859 @var{types} may have either one corresponding element or none. It is
860 not possible to specify two different elements that match the same one
861 of @var{types}. For example, @code{(set integer symbol)} allows one
862 integer and/or one symbol in the list; it does not allow multiple
863 integers or multiple symbols. As a result, it is rare to use
864 nonspecific types such as @code{integer} in a @code{set}.
866 Most often, the @var{types} in a @code{set} are @code{const} types, as
870 (set (const :bold) (const :italic))
873 Sometimes they describe possible elements in an alist:
876 (set (cons :tag "Height" (const height) integer)
877 (cons :tag "Width" (const width) integer))
881 That lets the user specify a height value optionally
882 and a width value optionally.
884 @item (repeat @var{element-type})
885 The value must be a list and each element of the list must fit the type
886 @var{element-type}. This appears in the customization buffer as a
887 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
888 more elements or removing elements.
890 @item (restricted-sexp :match-alternatives @var{criteria})
891 This is the most general composite type construct. The value may be
892 any Lisp object that satisfies one of @var{criteria}. @var{criteria}
893 should be a list, and each element should be one of these
898 A predicate---that is, a function of one argument that has no side
899 effects, and returns either @code{nil} or non-@code{nil} according to
900 the argument. Using a predicate in the list says that objects for which
901 the predicate returns non-@code{nil} are acceptable.
904 A quoted constant---that is, @code{'@var{object}}. This sort of element
905 in the list says that @var{object} itself is an acceptable value.
911 (restricted-sexp :match-alternatives
916 allows integers, @code{t} and @code{nil} as legitimate values.
918 The customization buffer shows all legitimate values using their read
919 syntax, and the user edits them textually.
922 Here is a table of the keywords you can use in keyword-value pairs
927 Use @var{tag} as the name of this alternative, for user communication
928 purposes. This is useful for a type that appears inside of a
931 @item :match-alternatives @var{criteria}
932 @kindex match-alternatives@r{, customization keyword}
933 Use @var{criteria} to match possible values. This is used only in
934 @code{restricted-sexp}.
936 @item :args @var{argument-list}
937 @kindex args@r{, customization keyword}
938 Use the elements of @var{argument-list} as the arguments of the type
939 construct. For instance, @code{(const :args (foo))} is equivalent to
940 @code{(const foo)}. You rarely need to write @code{:args} explicitly,
941 because normally the arguments are recognized automatically as
942 whatever follows the last keyword-value pair.
945 @node Splicing into Lists
946 @subsection Splicing into Lists
948 The @code{:inline} feature lets you splice a variable number of
949 elements into the middle of a @code{list} or @code{vector}
950 customization type. You use it by adding @code{:inline t} to a type
951 specification which is contained in a @code{list} or @code{vector}
954 Normally, each entry in a @code{list} or @code{vector} type
955 specification describes a single element type. But when an entry
956 contains @code{:inline t}, the value it matches is merged directly
957 into the containing sequence. For example, if the entry matches a
958 list with three elements, those become three elements of the overall
959 sequence. This is analogous to @samp{,@@} in a backquote construct
962 For example, to specify a list whose first element must be @code{baz}
963 and whose remaining arguments should be zero or more of @code{foo} and
964 @code{bar}, use this customization type:
967 (list (const baz) (set :inline t (const foo) (const bar)))
971 This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
972 and @code{(baz foo bar)}.
974 When the element-type is a @code{choice}, you use @code{:inline} not
975 in the @code{choice} itself, but in (some of) the alternatives of the
976 @code{choice}. For example, to match a list which must start with a
977 file name, followed either by the symbol @code{t} or two strings, use
978 this customization type:
983 (list :inline t string string)))
987 If the user chooses the first alternative in the choice, then the
988 overall list has two elements and the second element is @code{t}. If
989 the user chooses the second alternative, then the overall list has three
990 elements and the second and third must be strings.
993 @subsection Type Keywords
995 You can specify keyword-argument pairs in a customization type after the
996 type name symbol. Here are the keywords you can use, and their
1000 @item :value @var{default}
1001 Provide a default value.
1003 If @code{nil} is not a valid value for the alternative, then it is
1004 essential to specify a valid default with @code{:value}.
1006 If you use this for a type that appears as an alternative inside of
1007 @code{choice}; it specifies the default value to use, at first, if and
1008 when the user selects this alternative with the menu in the
1009 customization buffer.
1011 Of course, if the actual value of the option fits this alternative, it
1012 will appear showing the actual value, not @var{default}.
1014 @item :format @var{format-string}
1015 @kindex format@r{, customization keyword}
1016 This string will be inserted in the buffer to represent the value
1017 corresponding to the type. The following @samp{%} escapes are available
1018 for use in @var{format-string}:
1021 @item %[@var{button}%]
1022 Display the text @var{button} marked as a button. The @code{:action}
1023 attribute specifies what the button will do if the user invokes it;
1024 its value is a function which takes two arguments---the widget which
1025 the button appears in, and the event.
1027 There is no way to specify two different buttons with different
1030 @item %@{@var{sample}%@}
1031 Show @var{sample} in a special face specified by @code{:sample-face}.
1034 Substitute the item's value. How the value is represented depends on
1035 the kind of item, and (for variables) on the customization type.
1038 Substitute the item's documentation string.
1041 Like @samp{%d}, but if the documentation string is more than one line,
1042 add an active field to control whether to show all of it or just the
1046 Substitute the tag here. You specify the tag with the @code{:tag}
1050 Display a literal @samp{%}.
1053 @item :action @var{action}
1054 @kindex action@r{, customization keyword}
1055 Perform @var{action} if the user clicks on a button.
1057 @item :button-face @var{face}
1058 @kindex button-face@r{, customization keyword}
1059 Use the face @var{face} (a face name or a list of face names) for button
1060 text displayed with @samp{%[@dots{}%]}.
1062 @item :button-prefix @var{prefix}
1063 @itemx :button-suffix @var{suffix}
1064 @kindex button-prefix@r{, customization keyword}
1065 @kindex button-suffix@r{, customization keyword}
1066 These specify the text to display before and after a button.
1071 No text is inserted.
1074 The string is inserted literally.
1077 The symbol's value is used.
1080 @item :tag @var{tag}
1081 Use @var{tag} (a string) as the tag for the value (or part of the value)
1082 that corresponds to this type.
1084 @item :doc @var{doc}
1085 @kindex doc@r{, customization keyword}
1086 Use @var{doc} as the documentation string for this value (or part of the
1087 value) that corresponds to this type. In order for this to work, you
1088 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
1091 The usual reason to specify a documentation string for a type is to
1092 provide more information about the meanings of alternatives inside a
1093 @code{:choice} type or the parts of some other composite type.
1095 @item :help-echo @var{motion-doc}
1096 @kindex help-echo@r{, customization keyword}
1097 When you move to this item with @code{widget-forward} or
1098 @code{widget-backward}, it will display the string @var{motion-doc} in
1099 the echo area. In addition, @var{motion-doc} is used as the mouse
1100 @code{help-echo} string and may actually be a function or form evaluated
1101 to yield a help string. If it is a function, it is called with one
1102 argument, the widget.
1104 @item :match @var{function}
1105 @kindex match@r{, customization keyword}
1106 Specify how to decide whether a value matches the type. The
1107 corresponding value, @var{function}, should be a function that accepts
1108 two arguments, a widget and a value; it should return non-@code{nil} if
1109 the value is acceptable.
1111 @item :validate @var{function}
1112 Specify a validation function for input. @var{function} takes a
1113 widget as an argument, and should return @code{nil} if the widget's
1114 current value is valid for the widget. Otherwise, it should return
1115 the widget containing the invalid data, and set that widget's
1116 @code{:error} property to a string explaining the error.
1119 @item :indent @var{columns}
1120 Indent this item by @var{columns} columns. The indentation is used for
1121 @samp{%n}, and automatically for group names, for checklists and radio
1122 buttons, and for editable lists. It affects the whole of the
1123 item except for the first line.
1125 @item :offset @var{extra}
1126 Indent the subitems of this item @var{extra} columns more than this
1127 item itself. By default, subitems are indented the same as their
1130 @item :extra-offset @var{n}
1131 Add @var{n} extra spaces to this item's indentation, compared to its
1132 parent's indentation.
1134 @item :notify @var{function}
1135 Call @var{function} each time the item or a subitem is changed. The
1136 function gets two or three arguments. The first argument is the item
1137 itself, the second argument is the item that was changed, and the
1138 third argument is the event leading to the change, if any.
1140 @item :menu-tag @var{tag-string}
1141 Use @var{tag-string} in the menu when the widget is used as an option
1142 in a @code{menu-choice} widget.
1145 A function used for finding the tag when the widget is used as an option
1146 in a @code{menu-choice} widget. By default, the tag used will be either the
1147 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
1148 representation of the @code{:value} property if not.
1151 Specify the order in which widgets are traversed with
1152 @code{widget-forward} or @code{widget-backward}. This is only partially
1157 Widgets with tabbing order @code{-1} are ignored.
1160 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
1161 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
1162 whichever comes first.
1165 When on a widget with no tabbing order specified, go to the next widget
1166 in the buffer with a positive tabbing order, or @code{nil}
1170 The parent of a nested widget (e.g., a @code{menu-choice} item or an
1171 element of a @code{editable-list} widget).
1174 This keyword is only used for members of a @code{radio-button-choice} or
1175 @code{checklist}. The value should be a list of extra keyword
1176 arguments, which will be used when creating the @code{radio-button} or
1177 @code{checkbox} associated with this item.
1181 @node Defining New Types
1182 @subsection Defining New Types
1184 In the previous sections we have described how to construct elaborate
1185 type specifications for @code{defcustom}. In some cases you may want
1186 to give such a type specification a name. The obvious case is when
1187 you are using the same type for many user options: rather than repeat
1188 the specification for each option, you can give the type specification
1189 a name, and use that name each @code{defcustom}. The other case is
1190 when a user option's value is a recursive data structure. To make it
1191 possible for a datatype to refer to itself, it needs to have a name.
1193 Since custom types are implemented as widgets, the way to define a new
1194 customize type is to define a new widget. We are not going to describe
1195 the widget interface here in details, see @ref{Top, , Introduction,
1196 widget, The Emacs Widget Library}, for that. Instead we are going to
1197 demonstrate the minimal functionality needed for defining new customize
1198 types by a simple example.
1201 (define-widget 'binary-tree-of-string 'lazy
1202 "A binary tree made of cons-cells and strings."
1205 :type '(choice (string :tag "Leaf" :value "")
1206 (cons :tag "Interior"
1208 binary-tree-of-string
1209 binary-tree-of-string)))
1211 (defcustom foo-bar ""
1212 "Sample variable holding a binary tree of strings."
1213 :type 'binary-tree-of-string)
1216 The function to define a new widget is called @code{define-widget}. The
1217 first argument is the symbol we want to make a new widget type. The
1218 second argument is a symbol representing an existing widget, the new
1219 widget is going to be defined in terms of difference from the existing
1220 widget. For the purpose of defining new customization types, the
1221 @code{lazy} widget is perfect, because it accepts a @code{:type} keyword
1222 argument with the same syntax as the keyword argument to
1223 @code{defcustom} with the same name. The third argument is a
1224 documentation string for the new widget. You will be able to see that
1225 string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
1228 After these mandatory arguments follow the keyword arguments. The most
1229 important is @code{:type}, which describes the data type we want to match
1230 with this widget. Here a @code{binary-tree-of-string} is described as
1231 being either a string, or a cons-cell whose car and cdr are themselves
1232 both @code{binary-tree-of-string}. Note the reference to the widget
1233 type we are currently in the process of defining. The @code{:tag}
1234 attribute is a string to name the widget in the user interface, and the
1235 @code{:offset} argument is there to ensure that child nodes are
1236 indented four spaces relative to the parent node, making the tree
1237 structure apparent in the customization buffer.
1239 The @code{defcustom} shows how the new widget can be used as an ordinary
1242 The reason for the name @code{lazy} is that the other composite
1243 widgets convert their inferior widgets to internal form when the
1244 widget is instantiated in a buffer. This conversion is recursive, so
1245 the inferior widgets will convert @emph{their} inferior widgets. If
1246 the data structure is itself recursive, this conversion is an infinite
1247 recursion. The @code{lazy} widget prevents the recursion: it convert
1248 its @code{:type} argument only when needed.
1250 @node Applying Customizations
1251 @section Applying Customizations
1253 The following functions are responsible for installing the user's
1254 customization settings for variables and faces, respectively. When
1255 the user invokes @samp{Save for future sessions} in the Customize
1256 interface, that takes effect by writing a @code{custom-set-variables}
1257 and/or a @code{custom-set-faces} form into the custom file, to be
1258 evaluated the next time Emacs starts up.
1260 @defun custom-set-variables &rest args
1261 This function installs the variable customizations specified by
1262 @var{args}. Each argument in @var{args} should have the form
1265 (@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
1269 @var{var} is a variable name (a symbol), and @var{expression} is an
1270 expression which evaluates to the desired customized value.
1272 If the @code{defcustom} form for @var{var} has been evaluated prior to
1273 this @code{custom-set-variables} call, @var{expression} is immediately
1274 evaluated, and the variable's value is set to the result. Otherwise,
1275 @var{expression} is stored into the variable's @code{saved-value}
1276 property, to be evaluated when the relevant @code{defcustom} is called
1277 (usually when the library defining that variable is loaded into
1280 The @var{now}, @var{request}, and @var{comment} entries are for
1281 internal use only, and may be omitted. @var{now}, if non-@code{nil},
1282 means to set the variable's value now, even if the variable's
1283 @code{defcustom} form has not been evaluated. @var{request} is a list
1284 of features to be loaded immediately (@pxref{Named Features}).
1285 @var{comment} is a string describing the customization.
1288 @defun custom-set-faces &rest args
1289 This function installs the face customizations specified by
1290 @var{args}. Each argument in @var{args} should have the form
1293 (@var{face} @var{spec} [@var{now} [@var{comment}]])
1297 @var{face} is a face name (a symbol), and @var{spec} is the customized
1298 face specification for that face (@pxref{Defining Faces}).
1300 The @var{now} and @var{comment} entries are for internal use only, and
1301 may be omitted. @var{now}, if non-@code{nil}, means to install the
1302 face specification now, even if the @code{defface} form has not been
1303 evaluated. @var{comment} is a string describing the customization.
1307 @section Custom Themes
1309 @dfn{Custom themes} are collections of settings that can be enabled
1310 or disabled as a unit. @xref{Custom Themes,,, emacs, The GNU Emacs
1311 Manual}. Each Custom theme is defined by an Emacs Lisp source file,
1312 which should follow the conventions described in this section.
1313 (Instead of writing a Custom theme by hand, you can also create one
1314 using a Customize-like interface; @pxref{Creating Custom Themes,,,
1315 emacs, The GNU Emacs Manual}.)
1317 A Custom theme file should be named @file{@var{foo}-theme.el}, where
1318 @var{foo} is the theme name. The first Lisp form in the file should
1319 be a call to @code{deftheme}, and the last form should be a call to
1320 @code{provide-theme}.
1322 @defmac deftheme theme &optional doc
1323 This macro declares @var{theme} (a symbol) as the name of a Custom
1324 theme. The optional argument @var{doc} should be a string describing
1325 the theme; this is the description shown when the user invokes the
1326 @code{describe-theme} command or types @kbd{?} in the @samp{*Custom
1329 Two special theme names are disallowed: @code{user} is a ``dummy''
1330 theme which stores the user's direct customization settings, and
1331 @code{changed} is a ``dummy'' theme which stores changes made outside
1332 of the Customize system. If you specify either of these as the
1333 @var{theme} argument, @code{deftheme} signals an error.
1336 @defmac provide-theme theme
1337 This macro declares that the theme named @var{theme} has been fully
1341 In between @code{deftheme} and @code{provide-theme} are Lisp forms
1342 specifying the theme settings: usually a call to
1343 @code{custom-theme-set-variables} and/or a call to
1344 @code{custom-theme-set-faces}.
1346 @defun custom-theme-set-variables theme &rest args
1347 This function specifies the Custom theme @var{theme}'s variable
1348 settings. @var{theme} should be a symbol. Each argument in
1349 @var{args} should be a list of the form
1352 (@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
1356 where the list entries have the same meanings as in
1357 @code{custom-set-variables}. @xref{Applying Customizations}.
1360 @defun custom-theme-set-faces theme &rest args
1361 This function specifies the Custom theme @var{theme}'s face settings.
1362 @var{theme} should be a symbol. Each argument in @var{args} should be
1366 (@var{face} @var{spec} [@var{now} [@var{comment}]])
1370 where the list entries have the same meanings as in
1371 @code{custom-set-faces}. @xref{Applying Customizations}.
1374 In theory, a theme file can also contain other Lisp forms, which
1375 would be evaluated when loading the theme, but that is ``bad form''.
1376 To protect against loading themes containing malicious code, Emacs
1377 displays the source file and asks for confirmation from the user
1378 before loading any non-built-in theme for the first time.
1380 The following functions are useful for programmatically enabling and
1381 disabling Custom themes:
1383 @defun custom-theme-p theme
1384 This function return a non-@code{nil} value if @var{theme} (a symbol)
1385 is the name of a Custom theme (i.e.@: a Custom theme which has been
1386 loaded into Emacs, whether or not the theme is enabled). Otherwise,
1387 it returns @code{nil}.
1390 @deffn Command load-theme theme &optional no-confirm no-enable
1391 This function loads the Custom theme named @var{theme} from its source
1392 file, looking for the source file in the directories specified by the
1393 variable @code{custom-theme-load-path}. @xref{Custom Themes,,, emacs,
1394 The GNU Emacs Manual}. It also @dfn{enables} the theme, causing its
1395 variable and face settings to take effect.
1397 If the optional argument @var{no-confirm} is non-@code{nil}, this
1398 skips prompting the user for confirmation before loading the theme.
1400 If the optional argument @var{no-enable} is non-@code{nil}, the theme
1401 is loaded but not enabled.
1404 @deffn Command enable-theme theme
1405 This function enables the Custom theme named @var{theme}. It signals
1406 an error if no such theme has been loaded.
1409 @deffn Command disable-theme theme
1410 This function disables the Custom theme named @var{theme}. The theme
1411 remains loaded, so that a subsequent call to @code{enable-theme} will