2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1997-2014 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
6 @chapter Customization Settings
8 @cindex customization item
9 Users of Emacs can customize variables and faces without writing
10 Lisp code, by using the Customize interface. @xref{Easy
11 Customization,,, emacs, The GNU Emacs Manual}. This chapter describes
12 how to define @dfn{customization items} that users can interact with
13 through the Customize interface.
15 Customization items include customizable variables, which are
18 @code{defcustom} macro (@pxref{Variable Definitions});
21 @code{defcustom} macro;
23 customizable faces, which are defined with @code{defface} (described
24 separately in @ref{Defining Faces}); and @dfn{customization groups},
27 @code{defgroup} (@pxref{Group Definitions}),
32 which act as containers for groups of related customization items.
35 * Common Keywords:: Common keyword arguments for all kinds of
36 customization declarations.
37 * Group Definitions:: Writing customization group definitions.
38 * Variable Definitions:: Declaring user options.
39 * Customization Types:: Specifying the type of a user option.
40 * Applying Customizations:: Functions to apply customization settings.
41 * Custom Themes:: Writing Custom themes.
45 @section Common Item Keywords
47 @cindex customization keywords
48 The customization declarations that we will describe in the next few
49 sections---@code{defcustom}, @code{defgroup}, etc.---all accept
50 keyword arguments (@pxref{Constant Variables}) for specifying various
51 information. This section describes keywords that apply to all types
52 of customization declarations.
54 All of these keywords, except @code{:tag}, can be used more than once
55 in a given item. Each use of the keyword has an independent effect.
56 The keyword @code{:tag} is an exception because any given item can only
60 @item :tag @var{label}
61 @kindex tag@r{, customization keyword}
62 Use @var{label}, a string, instead of the item's name, to label the
63 item in customization menus and buffers. @strong{Don't use a tag
64 which is substantially different from the item's real name; that would
67 @kindex group@r{, customization keyword}
68 @item :group @var{group}
69 Put this customization item in group @var{group}. When you use
70 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
73 If you use this keyword more than once, you can put a single item into
74 more than one group. Displaying any of those groups will show this
75 item. Please don't overdo this, since the result would be annoying.
77 @item :link @var{link-data}
78 @kindex link@r{, customization keyword}
79 Include an external link after the documentation string for this item.
80 This is a sentence containing a button that references some
83 There are several alternatives you can use for @var{link-data}:
86 @item (custom-manual @var{info-node})
87 Link to an Info node; @var{info-node} is a string which specifies the
88 node name, as in @code{"(emacs)Top"}. The link appears as
89 @samp{[Manual]} in the customization buffer and enters the built-in
90 Info reader on @var{info-node}.
92 @item (info-link @var{info-node})
93 Like @code{custom-manual} except that the link appears
94 in the customization buffer with the Info node name.
96 @item (url-link @var{url})
97 Link to a web page; @var{url} is a string which specifies the
98 @acronym{URL}. The link appears in the customization buffer as
99 @var{url} and invokes the WWW browser specified by
100 @code{browse-url-browser-function}.
102 @item (emacs-commentary-link @var{library})
103 Link to the commentary section of a library; @var{library} is a string
104 which specifies the library name. @xref{Library Headers}.
106 @item (emacs-library-link @var{library})
107 Link to an Emacs Lisp library file; @var{library} is a string which
108 specifies the library name.
110 @item (file-link @var{file})
111 Link to a file; @var{file} is a string which specifies the name of the
112 file to visit with @code{find-file} when the user invokes this link.
114 @item (function-link @var{function})
115 Link to the documentation of a function; @var{function} is a string
116 which specifies the name of the function to describe with
117 @code{describe-function} when the user invokes this link.
119 @item (variable-link @var{variable})
120 Link to the documentation of a variable; @var{variable} is a string
121 which specifies the name of the variable to describe with
122 @code{describe-variable} when the user invokes this link.
124 @item (custom-group-link @var{group})
125 Link to another customization group. Invoking it creates a new
126 customization buffer for @var{group}.
129 You can specify the text to use in the customization buffer by adding
130 @code{:tag @var{name}} after the first element of the @var{link-data};
131 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
132 the Emacs manual which appears in the buffer as @samp{foo}.
134 You can use this keyword more than once, to add multiple links.
136 @item :load @var{file}
137 @kindex load@r{, customization keyword}
138 Load file @var{file} (a string) before displaying this customization
139 item (@pxref{Loading}). Loading is done with @code{load}, and only if
140 the file is not already loaded.
142 @item :require @var{feature}
143 @kindex require@r{, customization keyword}
144 Execute @code{(require '@var{feature})} when your saved customizations
145 set the value of this item. @var{feature} should be a symbol.
147 The most common reason to use @code{:require} is when a variable enables
148 a feature such as a minor mode, and just setting the variable won't have
149 any effect unless the code which implements the mode is loaded.
151 @item :version @var{version}
152 @kindex version@r{, customization keyword}
153 This keyword specifies that the item was first introduced in Emacs
154 version @var{version}, or that its default value was changed in that
155 version. The value @var{version} must be a string.
157 @item :package-version '(@var{package} . @var{version})
158 @kindex package-version@r{, customization keyword}
159 This keyword specifies that the item was first introduced in
160 @var{package} version @var{version}, or that its meaning or default
161 value was changed in that version. This keyword takes priority over
164 @var{package} should be the official name of the package, as a symbol
165 (e.g., @code{MH-E}). @var{version} should be a string. If the
166 package @var{package} is released as part of Emacs, @var{package} and
167 @var{version} should appear in the value of
168 @code{customize-package-emacs-version-alist}.
171 Packages distributed as part of Emacs that use the
172 @code{:package-version} keyword must also update the
173 @code{customize-package-emacs-version-alist} variable.
175 @defvar customize-package-emacs-version-alist
176 This alist provides a mapping for the versions of Emacs that are
177 associated with versions of a package listed in the
178 @code{:package-version} keyword. Its elements are:
181 (@var{package} (@var{pversion} . @var{eversion})@dots{})
184 For each @var{package}, which is a symbol, there are one or more
185 elements that contain a package version @var{pversion} with an
186 associated Emacs version @var{eversion}. These versions are strings.
187 For example, the MH-E package updates this alist with the following:
189 @c Must be small else too wide.
190 @c FIXME obviously this is out of date (in the code).
192 (add-to-list 'customize-package-emacs-version-alist
193 '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
194 ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
195 ("7.4" . "22.1") ("8.0" . "22.1")))
198 The value of @var{package} needs to be unique and it needs to match
199 the @var{package} value appearing in the @code{:package-version}
200 keyword. Since the user might see the value in an error message, a good
201 choice is the official name of the package, such as MH-E or Gnus.
204 @node Group Definitions
205 @section Defining Customization Groups
206 @cindex define customization group
207 @cindex customization groups, defining
209 Each Emacs Lisp package should have one main customization group
210 which contains all the options, faces and other groups in the package.
211 If the package has a small number of options and faces, use just one
212 group and put everything in it. When there are more than twenty or so
213 options and faces, then you should structure them into subgroups, and
214 put the subgroups under the package's main customization group. It is
215 OK to put some of the options and faces in the package's main group
216 alongside the subgroups.
218 The package's main or only group should be a member of one or more of
219 the standard customization groups. (To display the full list of them,
220 use @kbd{M-x customize}.) Choose one or more of them (but not too
221 many), and add your group to each of them using the @code{:group}
224 The way to declare new customization groups is with @code{defgroup}.
226 @defmac defgroup group members doc [keyword value]@dots{}
227 Declare @var{group} as a customization group containing @var{members}.
228 Do not quote the symbol @var{group}. The argument @var{doc} specifies
229 the documentation string for the group.
231 The argument @var{members} is a list specifying an initial set of
232 customization items to be members of the group. However, most often
233 @var{members} is @code{nil}, and you specify the group's members by
234 using the @code{:group} keyword when defining those members.
236 If you want to specify group members through @var{members}, each element
237 should have the form @code{(@var{name} @var{widget})}. Here @var{name}
238 is a symbol, and @var{widget} is a widget type for editing that symbol.
239 Useful widgets are @code{custom-variable} for a variable,
240 @code{custom-face} for a face, and @code{custom-group} for a group.
242 When you introduce a new group into Emacs, use the @code{:version}
243 keyword in the @code{defgroup}; then you need not use it for
244 the individual members of the group.
246 In addition to the common keywords (@pxref{Common Keywords}), you can
247 also use this keyword in @code{defgroup}:
250 @item :prefix @var{prefix}
251 @kindex prefix@r{, @code{defgroup} keyword}
252 If the name of an item in the group starts with @var{prefix}, and the
253 customizable variable @code{custom-unlispify-remove-prefixes} is
254 non-@code{nil}, the item's tag will omit @var{prefix}. A group can
255 have any number of prefixes.
259 @defopt custom-unlispify-remove-prefixes
260 If this variable is non-@code{nil}, the prefixes specified by a
261 group's @code{:prefix} keyword are omitted from tag names, whenever
262 the user customizes the group.
264 The default value is @code{nil}, i.e., the prefix-discarding feature
265 is disabled. This is because discarding prefixes often leads to
266 confusing names for options and faces.
269 @node Variable Definitions
270 @section Defining Customization Variables
271 @cindex define customization options
272 @cindex customizable variables, how to define
273 @cindex user options, how to define
275 @dfn{Customizable variables}, also called @dfn{user options}, are
276 global Lisp variables whose values can be set through the Customize
277 interface. Unlike other global variables, which are defined with
278 @code{defvar} (@pxref{Defining Variables}), customizable variables are
279 defined using the @code{defcustom} macro. In addition to calling
280 @code{defvar} as a subroutine, @code{defcustom} states how the
281 variable should be displayed in the Customize interface, the values it
282 is allowed to take, etc.
284 @defmac defcustom option standard doc [keyword value]@dots{}
285 This macro declares @var{option} as a user option (i.e., a
286 customizable variable). You should not quote @var{option}.
288 The argument @var{standard} is an expression that specifies the
289 standard value for @var{option}. Evaluating the @code{defcustom} form
290 evaluates @var{standard}, but does not necessarily bind the option to
291 that value. If @var{option} already has a default value, it is left
292 unchanged. If the user has already saved a customization for
293 @var{option}, the user's customized value is installed as the default
294 value. Otherwise, the result of evaluating @var{standard} is
295 installed as the default value.
297 Like @code{defvar}, this macro marks @code{option} as a special
298 variable, meaning that it should always be dynamically bound. If
299 @var{option} is already lexically bound, that lexical binding remains
300 in effect until the binding construct exits. @xref{Variable Scoping}.
302 The expression @var{standard} can be evaluated at various other times,
303 too---whenever the customization facility needs to know @var{option}'s
304 standard value. So be sure to use an expression which is harmless to
305 evaluate at any time.
307 The argument @var{doc} specifies the documentation string for the
310 If a @code{defcustom} does not specify any @code{:group}, the last group
311 defined with @code{defgroup} in the same file will be used. This way, most
312 @code{defcustom} do not need an explicit @code{:group}.
314 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
315 mode (@code{eval-defun}), a special feature of @code{eval-defun}
316 arranges to set the variable unconditionally, without testing whether
317 its value is void. (The same feature applies to @code{defvar},
318 @pxref{Defining Variables}.) Using @code{eval-defun} on a defcustom
319 that is already defined calls the @code{:set} function (see below),
322 If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
323 (@pxref{Building Emacs}), the standard value installed at dump time
324 might be incorrect, e.g., because another variable that it depends on
325 has not been assigned the right value yet. In that case, use
326 @code{custom-reevaluate-setting}, described below, to re-evaluate the
327 standard value after Emacs starts up.
330 In addition to the keywords listed in @ref{Common Keywords}, this
331 macro accepts the following keywords:
334 @item :type @var{type}
335 Use @var{type} as the data type for this option. It specifies which
336 values are legitimate, and how to display the value
337 (@pxref{Customization Types}).
339 @item :options @var{value-list}
340 @kindex options@r{, @code{defcustom} keyword}
341 Specify the list of reasonable values for use in this
342 option. The user is not restricted to using only these values, but they
343 are offered as convenient alternatives.
345 This is meaningful only for certain types, currently including
346 @code{hook}, @code{plist} and @code{alist}. See the definition of the
347 individual types for a description of how to use @code{:options}.
349 @item :set @var{setfunction}
350 @kindex set@r{, @code{defcustom} keyword}
351 Specify @var{setfunction} as the way to change the value of this
352 option when using the Customize interface. The function
353 @var{setfunction} should take two arguments, a symbol (the option
354 name) and the new value, and should do whatever is necessary to update
355 the value properly for this option (which may not mean simply setting
356 the option as a Lisp variable). The default for @var{setfunction} is
359 If you specify this keyword, the variable's documentation string
360 should describe how to do the same job in hand-written Lisp code.
362 @item :get @var{getfunction}
363 @kindex get@r{, @code{defcustom} keyword}
364 Specify @var{getfunction} as the way to extract the value of this
365 option. The function @var{getfunction} should take one argument, a
366 symbol, and should return whatever customize should use as the
367 ``current value'' for that symbol (which need not be the symbol's Lisp
368 value). The default is @code{default-value}.
370 You have to really understand the workings of Custom to use
371 @code{:get} correctly. It is meant for values that are treated in
372 Custom as variables but are not actually stored in Lisp variables. It
373 is almost surely a mistake to specify @var{getfunction} for a value
374 that really is stored in a Lisp variable.
376 @item :initialize @var{function}
377 @kindex initialize@r{, @code{defcustom} keyword}
378 @var{function} should be a function used to initialize the variable
379 when the @code{defcustom} is evaluated. It should take two arguments,
380 the option name (a symbol) and the value. Here are some predefined
381 functions meant for use in this way:
384 @item custom-initialize-set
385 Use the variable's @code{:set} function to initialize the variable, but
386 do not reinitialize it if it is already non-void.
388 @item custom-initialize-default
389 Like @code{custom-initialize-set}, but use the function
390 @code{set-default} to set the variable, instead of the variable's
391 @code{:set} function. This is the usual choice for a variable whose
392 @code{:set} function enables or disables a minor mode; with this choice,
393 defining the variable will not call the minor mode function, but
394 customizing the variable will do so.
396 @item custom-initialize-reset
397 Always use the @code{:set} function to initialize the variable. If
398 the variable is already non-void, reset it by calling the @code{:set}
399 function using the current value (returned by the @code{:get} method).
400 This is the default @code{:initialize} function.
402 @item custom-initialize-changed
403 Use the @code{:set} function to initialize the variable, if it is
404 already set or has been customized; otherwise, just use
407 @item custom-initialize-safe-set
408 @itemx custom-initialize-safe-default
409 These functions behave like @code{custom-initialize-set}
410 (@code{custom-initialize-default}, respectively), but catch errors.
411 If an error occurs during initialization, they set the variable to
412 @code{nil} using @code{set-default}, and signal no error.
414 These functions are meant for options defined in pre-loaded files,
415 where the @var{standard} expression may signal an error because some
416 required variable or function is not yet defined. The value normally
417 gets updated in @file{startup.el}, ignoring the value computed by
418 @code{defcustom}. After startup, if one unsets the value and
419 reevaluates the @code{defcustom}, the @var{standard} expression can be
420 evaluated without error.
423 @item :risky @var{value}
424 @kindex risky@r{, @code{defcustom} keyword}
425 Set the variable's @code{risky-local-variable} property to
426 @var{value} (@pxref{File Local Variables}).
428 @item :safe @var{function}
429 @kindex safe@r{, @code{defcustom} keyword}
430 Set the variable's @code{safe-local-variable} property to
431 @var{function} (@pxref{File Local Variables}).
433 @item :set-after @var{variables}
434 @kindex set-after@r{, @code{defcustom} keyword}
435 When setting variables according to saved customizations, make sure to
436 set the variables @var{variables} before this one; i.e., delay
437 setting this variable until after those others have been handled. Use
438 @code{:set-after} if setting this variable won't work properly unless
439 those other variables already have their intended values.
442 It is useful to specify the @code{:require} keyword for an option
443 that ``turns on'' a certain feature. This causes Emacs to load the
444 feature, if it is not already loaded, whenever the option is set.
445 @xref{Common Keywords}. Here is an example, from the library
449 (defcustom save-place nil
450 "Non-nil means automatically save place in each file..."
456 If a customization item has a type such as @code{hook} or
457 @code{alist}, which supports @code{:options}, you can add additional
458 values to the list from outside the @code{defcustom} declaration by
459 calling @code{custom-add-frequent-value}. For example, if you define a
460 function @code{my-lisp-mode-initialization} intended to be called from
461 @code{emacs-lisp-mode-hook}, you might want to add that to the list of
462 reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
463 its definition. You can do it thus:
466 (custom-add-frequent-value 'emacs-lisp-mode-hook
467 'my-lisp-mode-initialization)
470 @defun custom-add-frequent-value symbol value
471 For the customization option @var{symbol}, add @var{value} to the
472 list of reasonable values.
474 The precise effect of adding a value depends on the customization type
478 Internally, @code{defcustom} uses the symbol property
479 @code{standard-value} to record the expression for the standard value,
480 @code{saved-value} to record the value saved by the user with the
481 customization buffer, and @code{customized-value} to record the value
482 set by the user with the customization buffer, but not saved.
483 @xref{Symbol Properties}. These properties are lists, the car of
484 which is an expression that evaluates to the value.
486 @defun custom-reevaluate-setting symbol
487 This function re-evaluates the standard value of @var{symbol}, which
488 should be a user option declared via @code{defcustom}. If the
489 variable was customized, this function re-evaluates the saved value
490 instead. Then it sets the user option to that value (using the
491 option's @code{:set} property if that is defined).
493 This is useful for customizable options that are defined before their
494 value could be computed correctly. For example, during startup Emacs
495 calls this function for some user options that were defined in
496 pre-loaded Emacs Lisp files, but whose initial values depend on
497 information available only at run-time.
500 @defun custom-variable-p arg
501 This function returns non-@code{nil} if @var{arg} is a customizable
502 variable. A customizable variable is either a variable that has a
503 @code{standard-value} or @code{custom-autoload} property (usually
504 meaning it was declared with @code{defcustom}), or an alias for
505 another customizable variable.
508 @node Customization Types
509 @section Customization Types
511 @cindex customization types
512 When you define a user option with @code{defcustom}, you must specify
513 its @dfn{customization type}. That is a Lisp object which describes (1)
514 which values are legitimate and (2) how to display the value in the
515 customization buffer for editing.
517 @kindex type@r{, @code{defcustom} keyword}
518 You specify the customization type in @code{defcustom} with the
519 @code{:type} keyword. The argument of @code{:type} is evaluated, but
520 only once when the @code{defcustom} is executed, so it isn't useful
521 for the value to vary. Normally we use a quoted constant. For
525 (defcustom diff-command "diff"
526 "The command to use to run diff."
531 In general, a customization type is a list whose first element is a
532 symbol, one of the customization type names defined in the following
533 sections. After this symbol come a number of arguments, depending on
534 the symbol. Between the type symbol and its arguments, you can
535 optionally write keyword-value pairs (@pxref{Type Keywords}).
537 Some type symbols do not use any arguments; those are called
538 @dfn{simple types}. For a simple type, if you do not use any
539 keyword-value pairs, you can omit the parentheses around the type
540 symbol. For example just @code{string} as a customization type is
541 equivalent to @code{(string)}.
543 All customization types are implemented as widgets; see @ref{Top, ,
544 Introduction, widget, The Emacs Widget Library}, for details.
547 * Simple Types:: Simple customization types: sexp, integer, etc.
548 * Composite Types:: Build new types from other types or data.
549 * Splicing into Lists:: Splice elements into list with @code{:inline}.
550 * Type Keywords:: Keyword-argument pairs in a customization type.
551 * Defining New Types:: Give your type a name.
555 @subsection Simple Types
557 This section describes all the simple customization types. For
558 several of these customization types, the customization widget
559 provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}.
563 The value may be any Lisp object that can be printed and read back.
564 You can use @code{sexp} as a fall-back for any option, if you don't
565 want to take the time to work out a more specific type to use.
568 The value must be an integer.
571 The value must be a number (floating point or integer).
574 The value must be a floating point number.
577 The value must be a string. The customization buffer shows the string
578 without delimiting @samp{"} characters or @samp{\} quotes.
581 Like @code{string} except that the string must be a valid regular
585 The value must be a character code. A character code is actually an
586 integer, but this type shows the value by inserting the character in the
587 buffer, rather than by showing the number.
590 The value must be a file name. The widget provides completion.
592 @item (file :must-match t)
593 The value must be a file name for an existing file. The widget
597 The value must be a directory name. The widget provides completion.
600 The value must be a list of functions. This customization type is
601 used for hook variables. You can use the @code{:options} keyword in a
602 hook variable's @code{defcustom} to specify a list of functions
603 recommended for use in the hook; @xref{Variable Definitions}.
606 The value must be a symbol. It appears in the customization buffer as
607 the symbol name. The widget provides completion.
610 The value must be either a lambda expression or a function name. The
611 widget provides completion for function names.
614 The value must be a variable name. The widget provides completion.
617 The value must be a symbol which is a face name. The widget provides
621 The value is boolean---either @code{nil} or @code{t}. Note that by
622 using @code{choice} and @code{const} together (see the next section),
623 you can specify that the value must be @code{nil} or @code{t}, but also
624 specify the text to describe each value in a way that fits the specific
625 meaning of the alternative.
628 The value is a key sequence. The customization buffer shows the key
629 sequence using the same syntax as the @kbd{kbd} function. @xref{Key
633 The value must be a coding-system name, and you can do completion with
637 The value must be a valid color name. The widget provides completion
638 for color names, as well as a sample and a button for selecting a
639 color name from a list of color names shown in a @file{*Colors*}
643 @node Composite Types
644 @subsection Composite Types
645 @cindex composite types (customization)
647 When none of the simple types is appropriate, you can use composite
648 types, which build new types from other types or from specified data.
649 The specified types or data are called the @dfn{arguments} of the
650 composite type. The composite type normally looks like this:
653 (@var{constructor} @var{arguments}@dots{})
657 but you can also add keyword-value pairs before the arguments, like
661 (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
664 Here is a table of constructors and how to use them to write
668 @item (cons @var{car-type} @var{cdr-type})
669 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
670 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
671 symbol)} is a customization type which matches values such as
672 @code{("foo" . foo)}.
674 In the customization buffer, the @sc{car} and @sc{cdr} are displayed
675 and edited separately, each according to their specified type.
677 @item (list @var{element-types}@dots{})
678 The value must be a list with exactly as many elements as the
679 @var{element-types} given; and each element must fit the
680 corresponding @var{element-type}.
682 For example, @code{(list integer string function)} describes a list of
683 three elements; the first element must be an integer, the second a
684 string, and the third a function.
686 In the customization buffer, each element is displayed and edited
687 separately, according to the type specified for it.
689 @item (group @var{element-types}@dots{})
690 This works like @code{list} except for the formatting
691 of text in the Custom buffer. @code{list} labels each
692 element value with its tag; @code{group} does not.
694 @item (vector @var{element-types}@dots{})
695 Like @code{list} except that the value must be a vector instead of a
696 list. The elements work the same as in @code{list}.
698 @item (alist :key-type @var{key-type} :value-type @var{value-type})
699 The value must be a list of cons-cells, the @sc{car} of each cell
700 representing a key of customization type @var{key-type}, and the
701 @sc{cdr} of the same cell representing a value of customization type
702 @var{value-type}. The user can add and delete key/value pairs, and
703 edit both the key and the value of each pair.
705 If omitted, @var{key-type} and @var{value-type} default to
708 The user can add any key matching the specified key type, but you can
709 give some keys a preferential treatment by specifying them with the
710 @code{:options} (see @ref{Variable Definitions}). The specified keys
711 will always be shown in the customize buffer (together with a suitable
712 value), with a checkbox to include or exclude or disable the key/value
713 pair from the alist. The user will not be able to edit the keys
714 specified by the @code{:options} keyword argument.
716 The argument to the @code{:options} keywords should be a list of
717 specifications for reasonable keys in the alist. Ordinarily, they are
718 simply atoms, which stand for themselves. For example:
721 :options '("foo" "bar" "baz")
725 specifies that there are three ``known'' keys, namely @code{"foo"},
726 @code{"bar"} and @code{"baz"}, which will always be shown first.
728 You may want to restrict the value type for specific keys, for
729 example, the value associated with the @code{"bar"} key can only be an
730 integer. You can specify this by using a list instead of an atom in
731 the list. The first element will specify the key, like before, while
732 the second element will specify the value type. For example:
735 :options '("foo" ("bar" integer) "baz")
738 Finally, you may want to change how the key is presented. By default,
739 the key is simply shown as a @code{const}, since the user cannot change
740 the special keys specified with the @code{:options} keyword. However,
741 you may want to use a more specialized type for presenting the key, like
742 @code{function-item} if you know it is a symbol with a function binding.
743 This is done by using a customization type specification instead of a
748 ((function-item some-function) integer)
752 Many alists use lists with two elements, instead of cons cells. For
756 (defcustom list-alist
757 '(("foo" 1) ("bar" 2) ("baz" 3))
758 "Each element is a list of the form (KEY VALUE).")
765 (defcustom cons-alist
766 '(("foo" . 1) ("bar" . 2) ("baz" . 3))
767 "Each element is a cons-cell (KEY . VALUE).")
770 Because of the way lists are implemented on top of cons cells, you can
771 treat @code{list-alist} in the example above as a cons cell alist, where
772 the value type is a list with a single element containing the real
776 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
777 "Each element is a list of the form (KEY VALUE)."
778 :type '(alist :value-type (group integer)))
781 The @code{group} widget is used here instead of @code{list} only because
782 the formatting is better suited for the purpose.
784 Similarly, you can have alists with more values associated with each
785 key, using variations of this trick:
788 (defcustom person-data '(("brian" 50 t)
791 "Alist of basic info about people.
792 Each element has the form (NAME AGE MALE-FLAG)."
793 :type '(alist :value-type (group integer boolean)))
796 @item (plist :key-type @var{key-type} :value-type @var{value-type})
797 This customization type is similar to @code{alist} (see above), except
798 that (i) the information is stored as a property list,
799 (@pxref{Property Lists}), and (ii) @var{key-type}, if omitted,
800 defaults to @code{symbol} rather than @code{sexp}.
802 @item (choice @var{alternative-types}@dots{})
803 The value must fit one of @var{alternative-types}. For example,
804 @code{(choice integer string)} allows either an integer or a string.
806 In the customization buffer, the user selects an alternative
807 using a menu, and can then edit the value in the usual way for that
810 Normally the strings in this menu are determined automatically from the
811 choices; however, you can specify different strings for the menu by
812 including the @code{:tag} keyword in the alternatives. For example, if
813 an integer stands for a number of spaces, while a string is text to use
814 verbatim, you might write the customization type this way,
817 (choice (integer :tag "Number of spaces")
818 (string :tag "Literal text"))
822 so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
824 In any alternative for which @code{nil} is not a valid value, other than
825 a @code{const}, you should specify a valid default for that alternative
826 using the @code{:value} keyword. @xref{Type Keywords}.
828 If some values are covered by more than one of the alternatives,
829 customize will choose the first alternative that the value fits. This
830 means you should always list the most specific types first, and the
831 most general last. Here's an example of proper usage:
834 (choice (const :tag "Off" nil)
835 symbol (sexp :tag "Other"))
839 This way, the special value @code{nil} is not treated like other
840 symbols, and symbols are not treated like other Lisp expressions.
842 @item (radio @var{element-types}@dots{})
843 This is similar to @code{choice}, except that the choices are displayed
844 using `radio buttons' rather than a menu. This has the advantage of
845 displaying documentation for the choices when applicable and so is often
846 a good choice for a choice between constant functions
847 (@code{function-item} customization types).
849 @item (const @var{value})
850 The value must be @var{value}---nothing else is allowed.
852 The main use of @code{const} is inside of @code{choice}. For example,
853 @code{(choice integer (const nil))} allows either an integer or
856 @code{:tag} is often used with @code{const}, inside of @code{choice}.
860 (choice (const :tag "Yes" t)
861 (const :tag "No" nil)
862 (const :tag "Ask" foo))
866 describes a variable for which @code{t} means yes, @code{nil} means no,
867 and @code{foo} means ``ask''.
869 @item (other @var{value})
870 This alternative can match any Lisp value, but if the user chooses this
871 alternative, that selects the value @var{value}.
873 The main use of @code{other} is as the last element of @code{choice}.
877 (choice (const :tag "Yes" t)
878 (const :tag "No" nil)
879 (other :tag "Ask" foo))
883 describes a variable for which @code{t} means yes, @code{nil} means no,
884 and anything else means ``ask''. If the user chooses @samp{Ask} from
885 the menu of alternatives, that specifies the value @code{foo}; but any
886 other value (not @code{t}, @code{nil} or @code{foo}) displays as
887 @samp{Ask}, just like @code{foo}.
889 @item (function-item @var{function})
890 Like @code{const}, but used for values which are functions. This
891 displays the documentation string as well as the function name.
892 The documentation string is either the one you specify with
893 @code{:doc}, or @var{function}'s own documentation string.
895 @item (variable-item @var{variable})
896 Like @code{const}, but used for values which are variable names. This
897 displays the documentation string as well as the variable name. The
898 documentation string is either the one you specify with @code{:doc}, or
899 @var{variable}'s own documentation string.
901 @item (set @var{types}@dots{})
902 The value must be a list, and each element of the list must match one of
903 the @var{types} specified.
905 This appears in the customization buffer as a checklist, so that each of
906 @var{types} may have either one corresponding element or none. It is
907 not possible to specify two different elements that match the same one
908 of @var{types}. For example, @code{(set integer symbol)} allows one
909 integer and/or one symbol in the list; it does not allow multiple
910 integers or multiple symbols. As a result, it is rare to use
911 nonspecific types such as @code{integer} in a @code{set}.
913 Most often, the @var{types} in a @code{set} are @code{const} types, as
917 (set (const :bold) (const :italic))
920 Sometimes they describe possible elements in an alist:
923 (set (cons :tag "Height" (const height) integer)
924 (cons :tag "Width" (const width) integer))
928 That lets the user specify a height value optionally
929 and a width value optionally.
931 @item (repeat @var{element-type})
932 The value must be a list and each element of the list must fit the type
933 @var{element-type}. This appears in the customization buffer as a
934 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
935 more elements or removing elements.
937 @item (restricted-sexp :match-alternatives @var{criteria})
938 This is the most general composite type construct. The value may be
939 any Lisp object that satisfies one of @var{criteria}. @var{criteria}
940 should be a list, and each element should be one of these
945 A predicate---that is, a function of one argument that has no side
946 effects, and returns either @code{nil} or non-@code{nil} according to
947 the argument. Using a predicate in the list says that objects for which
948 the predicate returns non-@code{nil} are acceptable.
951 A quoted constant---that is, @code{'@var{object}}. This sort of element
952 in the list says that @var{object} itself is an acceptable value.
958 (restricted-sexp :match-alternatives
963 allows integers, @code{t} and @code{nil} as legitimate values.
965 The customization buffer shows all legitimate values using their read
966 syntax, and the user edits them textually.
969 Here is a table of the keywords you can use in keyword-value pairs
974 Use @var{tag} as the name of this alternative, for user communication
975 purposes. This is useful for a type that appears inside of a
978 @item :match-alternatives @var{criteria}
979 @kindex match-alternatives@r{, customization keyword}
980 Use @var{criteria} to match possible values. This is used only in
981 @code{restricted-sexp}.
983 @item :args @var{argument-list}
984 @kindex args@r{, customization keyword}
985 Use the elements of @var{argument-list} as the arguments of the type
986 construct. For instance, @code{(const :args (foo))} is equivalent to
987 @code{(const foo)}. You rarely need to write @code{:args} explicitly,
988 because normally the arguments are recognized automatically as
989 whatever follows the last keyword-value pair.
992 @node Splicing into Lists
993 @subsection Splicing into Lists
995 The @code{:inline} feature lets you splice a variable number of
996 elements into the middle of a @code{list} or @code{vector}
997 customization type. You use it by adding @code{:inline t} to a type
998 specification which is contained in a @code{list} or @code{vector}
1001 Normally, each entry in a @code{list} or @code{vector} type
1002 specification describes a single element type. But when an entry
1003 contains @code{:inline t}, the value it matches is merged directly
1004 into the containing sequence. For example, if the entry matches a
1005 list with three elements, those become three elements of the overall
1006 sequence. This is analogous to @samp{,@@} in a backquote construct
1007 (@pxref{Backquote}).
1009 For example, to specify a list whose first element must be @code{baz}
1010 and whose remaining arguments should be zero or more of @code{foo} and
1011 @code{bar}, use this customization type:
1014 (list (const baz) (set :inline t (const foo) (const bar)))
1018 This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
1019 and @code{(baz foo bar)}.
1021 When the element-type is a @code{choice}, you use @code{:inline} not
1022 in the @code{choice} itself, but in (some of) the alternatives of the
1023 @code{choice}. For example, to match a list which must start with a
1024 file name, followed either by the symbol @code{t} or two strings, use
1025 this customization type:
1030 (list :inline t string string)))
1034 If the user chooses the first alternative in the choice, then the
1035 overall list has two elements and the second element is @code{t}. If
1036 the user chooses the second alternative, then the overall list has three
1037 elements and the second and third must be strings.
1040 @subsection Type Keywords
1042 You can specify keyword-argument pairs in a customization type after the
1043 type name symbol. Here are the keywords you can use, and their
1047 @item :value @var{default}
1048 Provide a default value.
1050 If @code{nil} is not a valid value for the alternative, then it is
1051 essential to specify a valid default with @code{:value}.
1053 If you use this for a type that appears as an alternative inside of
1054 @code{choice}; it specifies the default value to use, at first, if and
1055 when the user selects this alternative with the menu in the
1056 customization buffer.
1058 Of course, if the actual value of the option fits this alternative, it
1059 will appear showing the actual value, not @var{default}.
1061 @item :format @var{format-string}
1062 @kindex format@r{, customization keyword}
1063 This string will be inserted in the buffer to represent the value
1064 corresponding to the type. The following @samp{%} escapes are available
1065 for use in @var{format-string}:
1068 @item %[@var{button}%]
1069 Display the text @var{button} marked as a button. The @code{:action}
1070 attribute specifies what the button will do if the user invokes it;
1071 its value is a function which takes two arguments---the widget which
1072 the button appears in, and the event.
1074 There is no way to specify two different buttons with different
1077 @item %@{@var{sample}%@}
1078 Show @var{sample} in a special face specified by @code{:sample-face}.
1081 Substitute the item's value. How the value is represented depends on
1082 the kind of item, and (for variables) on the customization type.
1085 Substitute the item's documentation string.
1088 Like @samp{%d}, but if the documentation string is more than one line,
1089 add a button to control whether to show all of it or just the first line.
1092 Substitute the tag here. You specify the tag with the @code{:tag}
1096 Display a literal @samp{%}.
1099 @item :action @var{action}
1100 @kindex action@r{, customization keyword}
1101 Perform @var{action} if the user clicks on a button.
1103 @item :button-face @var{face}
1104 @kindex button-face@r{, customization keyword}
1105 Use the face @var{face} (a face name or a list of face names) for button
1106 text displayed with @samp{%[@dots{}%]}.
1108 @item :button-prefix @var{prefix}
1109 @itemx :button-suffix @var{suffix}
1110 @kindex button-prefix@r{, customization keyword}
1111 @kindex button-suffix@r{, customization keyword}
1112 These specify the text to display before and after a button.
1117 No text is inserted.
1120 The string is inserted literally.
1123 The symbol's value is used.
1126 @item :tag @var{tag}
1127 Use @var{tag} (a string) as the tag for the value (or part of the value)
1128 that corresponds to this type.
1130 @item :doc @var{doc}
1131 @kindex doc@r{, customization keyword}
1132 Use @var{doc} as the documentation string for this value (or part of the
1133 value) that corresponds to this type. In order for this to work, you
1134 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
1137 The usual reason to specify a documentation string for a type is to
1138 provide more information about the meanings of alternatives inside a
1139 @code{:choice} type or the parts of some other composite type.
1141 @item :help-echo @var{motion-doc}
1142 @kindex help-echo@r{, customization keyword}
1143 When you move to this item with @code{widget-forward} or
1144 @code{widget-backward}, it will display the string @var{motion-doc} in
1145 the echo area. In addition, @var{motion-doc} is used as the mouse
1146 @code{help-echo} string and may actually be a function or form evaluated
1147 to yield a help string. If it is a function, it is called with one
1148 argument, the widget.
1150 @item :match @var{function}
1151 @kindex match@r{, customization keyword}
1152 Specify how to decide whether a value matches the type. The
1153 corresponding value, @var{function}, should be a function that accepts
1154 two arguments, a widget and a value; it should return non-@code{nil} if
1155 the value is acceptable.
1157 @item :validate @var{function}
1158 Specify a validation function for input. @var{function} takes a
1159 widget as an argument, and should return @code{nil} if the widget's
1160 current value is valid for the widget. Otherwise, it should return
1161 the widget containing the invalid data, and set that widget's
1162 @code{:error} property to a string explaining the error.
1165 @item :indent @var{columns}
1166 Indent this item by @var{columns} columns. The indentation is used for
1167 @samp{%n}, and automatically for group names, for checklists and radio
1168 buttons, and for editable lists. It affects the whole of the
1169 item except for the first line.
1171 @item :offset @var{extra}
1172 Indent the subitems of this item @var{extra} columns more than this
1173 item itself. By default, subitems are indented the same as their
1176 @item :extra-offset @var{n}
1177 Add @var{n} extra spaces to this item's indentation, compared to its
1178 parent's indentation.
1180 @item :notify @var{function}
1181 Call @var{function} each time the item or a subitem is changed. The
1182 function gets two or three arguments. The first argument is the item
1183 itself, the second argument is the item that was changed, and the
1184 third argument is the event leading to the change, if any.
1186 @item :menu-tag @var{tag-string}
1187 Use @var{tag-string} in the menu when the widget is used as an option
1188 in a @code{menu-choice} widget.
1191 A function used for finding the tag when the widget is used as an option
1192 in a @code{menu-choice} widget. By default, the tag used will be either the
1193 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
1194 representation of the @code{:value} property if not.
1197 Specify the order in which widgets are traversed with
1198 @code{widget-forward} or @code{widget-backward}. This is only partially
1203 Widgets with tabbing order @code{-1} are ignored.
1206 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
1207 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
1208 whichever comes first.
1211 When on a widget with no tabbing order specified, go to the next widget
1212 in the buffer with a positive tabbing order, or @code{nil}
1216 The parent of a nested widget (e.g., a @code{menu-choice} item or an
1217 element of a @code{editable-list} widget).
1220 This keyword is only used for members of a @code{radio-button-choice} or
1221 @code{checklist}. The value should be a list of extra keyword
1222 arguments, which will be used when creating the @code{radio-button} or
1223 @code{checkbox} associated with this item.
1227 @node Defining New Types
1228 @subsection Defining New Types
1230 In the previous sections we have described how to construct elaborate
1231 type specifications for @code{defcustom}. In some cases you may want
1232 to give such a type specification a name. The obvious case is when
1233 you are using the same type for many user options: rather than repeat
1234 the specification for each option, you can give the type specification
1235 a name, and use that name each @code{defcustom}. The other case is
1236 when a user option's value is a recursive data structure. To make it
1237 possible for a datatype to refer to itself, it needs to have a name.
1239 Since custom types are implemented as widgets, the way to define a new
1240 customize type is to define a new widget. We are not going to describe
1241 the widget interface here in details, see @ref{Top, , Introduction,
1242 widget, The Emacs Widget Library}, for that. Instead we are going to
1243 demonstrate the minimal functionality needed for defining new customize
1244 types by a simple example.
1247 (define-widget 'binary-tree-of-string 'lazy
1248 "A binary tree made of cons-cells and strings."
1251 :type '(choice (string :tag "Leaf" :value "")
1252 (cons :tag "Interior"
1254 binary-tree-of-string
1255 binary-tree-of-string)))
1257 (defcustom foo-bar ""
1258 "Sample variable holding a binary tree of strings."
1259 :type 'binary-tree-of-string)
1262 The function to define a new widget is called @code{define-widget}. The
1263 first argument is the symbol we want to make a new widget type. The
1264 second argument is a symbol representing an existing widget, the new
1265 widget is going to be defined in terms of difference from the existing
1266 widget. For the purpose of defining new customization types, the
1267 @code{lazy} widget is perfect, because it accepts a @code{:type} keyword
1268 argument with the same syntax as the keyword argument to
1269 @code{defcustom} with the same name. The third argument is a
1270 documentation string for the new widget. You will be able to see that
1271 string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
1274 After these mandatory arguments follow the keyword arguments. The most
1275 important is @code{:type}, which describes the data type we want to match
1276 with this widget. Here a @code{binary-tree-of-string} is described as
1277 being either a string, or a cons-cell whose car and cdr are themselves
1278 both @code{binary-tree-of-string}. Note the reference to the widget
1279 type we are currently in the process of defining. The @code{:tag}
1280 attribute is a string to name the widget in the user interface, and the
1281 @code{:offset} argument is there to ensure that child nodes are
1282 indented four spaces relative to the parent node, making the tree
1283 structure apparent in the customization buffer.
1285 The @code{defcustom} shows how the new widget can be used as an ordinary
1288 The reason for the name @code{lazy} is that the other composite
1289 widgets convert their inferior widgets to internal form when the
1290 widget is instantiated in a buffer. This conversion is recursive, so
1291 the inferior widgets will convert @emph{their} inferior widgets. If
1292 the data structure is itself recursive, this conversion is an infinite
1293 recursion. The @code{lazy} widget prevents the recursion: it convert
1294 its @code{:type} argument only when needed.
1296 @node Applying Customizations
1297 @section Applying Customizations
1299 The following functions are responsible for installing the user's
1300 customization settings for variables and faces, respectively. When
1301 the user invokes @samp{Save for future sessions} in the Customize
1302 interface, that takes effect by writing a @code{custom-set-variables}
1303 and/or a @code{custom-set-faces} form into the custom file, to be
1304 evaluated the next time Emacs starts.
1306 @defun custom-set-variables &rest args
1307 This function installs the variable customizations specified by
1308 @var{args}. Each argument in @var{args} should have the form
1311 (@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
1315 @var{var} is a variable name (a symbol), and @var{expression} is an
1316 expression which evaluates to the desired customized value.
1318 If the @code{defcustom} form for @var{var} has been evaluated prior to
1319 this @code{custom-set-variables} call, @var{expression} is immediately
1320 evaluated, and the variable's value is set to the result. Otherwise,
1321 @var{expression} is stored into the variable's @code{saved-value}
1322 property, to be evaluated when the relevant @code{defcustom} is called
1323 (usually when the library defining that variable is loaded into
1326 The @var{now}, @var{request}, and @var{comment} entries are for
1327 internal use only, and may be omitted. @var{now}, if non-@code{nil},
1328 means to set the variable's value now, even if the variable's
1329 @code{defcustom} form has not been evaluated. @var{request} is a list
1330 of features to be loaded immediately (@pxref{Named Features}).
1331 @var{comment} is a string describing the customization.
1334 @defun custom-set-faces &rest args
1335 This function installs the face customizations specified by
1336 @var{args}. Each argument in @var{args} should have the form
1339 (@var{face} @var{spec} [@var{now} [@var{comment}]])
1343 @var{face} is a face name (a symbol), and @var{spec} is the customized
1344 face specification for that face (@pxref{Defining Faces}).
1346 The @var{now} and @var{comment} entries are for internal use only, and
1347 may be omitted. @var{now}, if non-@code{nil}, means to install the
1348 face specification now, even if the @code{defface} form has not been
1349 evaluated. @var{comment} is a string describing the customization.
1353 @section Custom Themes
1355 @dfn{Custom themes} are collections of settings that can be enabled
1356 or disabled as a unit. @xref{Custom Themes,,, emacs, The GNU Emacs
1357 Manual}. Each Custom theme is defined by an Emacs Lisp source file,
1358 which should follow the conventions described in this section.
1359 (Instead of writing a Custom theme by hand, you can also create one
1360 using a Customize-like interface; @pxref{Creating Custom Themes,,,
1361 emacs, The GNU Emacs Manual}.)
1363 A Custom theme file should be named @file{@var{foo}-theme.el}, where
1364 @var{foo} is the theme name. The first Lisp form in the file should
1365 be a call to @code{deftheme}, and the last form should be a call to
1366 @code{provide-theme}.
1368 @defmac deftheme theme &optional doc
1369 This macro declares @var{theme} (a symbol) as the name of a Custom
1370 theme. The optional argument @var{doc} should be a string describing
1371 the theme; this is the description shown when the user invokes the
1372 @code{describe-theme} command or types @kbd{?} in the @samp{*Custom
1375 Two special theme names are disallowed (using them causes an error):
1376 @code{user} is a ``dummy'' theme that stores the user's direct
1377 customization settings, and @code{changed} is a ``dummy'' theme that
1378 stores changes made outside of the Customize system.
1381 @defmac provide-theme theme
1382 This macro declares that the theme named @var{theme} has been fully
1386 In between @code{deftheme} and @code{provide-theme} are Lisp forms
1387 specifying the theme settings: usually a call to
1388 @code{custom-theme-set-variables} and/or a call to
1389 @code{custom-theme-set-faces}.
1391 @defun custom-theme-set-variables theme &rest args
1392 This function specifies the Custom theme @var{theme}'s variable
1393 settings. @var{theme} should be a symbol. Each argument in
1394 @var{args} should be a list of the form
1397 (@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
1401 where the list entries have the same meanings as in
1402 @code{custom-set-variables}. @xref{Applying Customizations}.
1405 @defun custom-theme-set-faces theme &rest args
1406 This function specifies the Custom theme @var{theme}'s face settings.
1407 @var{theme} should be a symbol. Each argument in @var{args} should be
1411 (@var{face} @var{spec} [@var{now} [@var{comment}]])
1415 where the list entries have the same meanings as in
1416 @code{custom-set-faces}. @xref{Applying Customizations}.
1419 In theory, a theme file can also contain other Lisp forms, which
1420 would be evaluated when loading the theme, but that is ``bad form''.
1421 To protect against loading themes containing malicious code, Emacs
1422 displays the source file and asks for confirmation from the user
1423 before loading any non-built-in theme for the first time.
1425 The following functions are useful for programmatically enabling and
1428 @defun custom-theme-p theme
1429 This function return a non-@code{nil} value if @var{theme} (a symbol)
1430 is the name of a Custom theme (i.e., a Custom theme which has been
1431 loaded into Emacs, whether or not the theme is enabled). Otherwise,
1432 it returns @code{nil}.
1435 @defvar custom-known-themes
1436 The value of this variable is a list of themes loaded into Emacs.
1437 Each theme is represented by a Lisp symbol (the theme name). The
1438 default value of this variable is a list containing two ``dummy''
1439 themes: @code{(user changed)}. The @code{changed} theme stores
1440 settings made before any Custom themes are applied (e.g., variables
1441 set outside of Customize). The @code{user} theme stores settings the
1442 user has customized and saved. Any additional themes declared with
1443 the @code{deftheme} macro are added to the front of this list.
1446 @deffn Command load-theme theme &optional no-confirm no-enable
1447 This function loads the Custom theme named @var{theme} from its source
1448 file, looking for the source file in the directories specified by the
1449 variable @code{custom-theme-load-path}. @xref{Custom Themes,,, emacs,
1450 The GNU Emacs Manual}. It also @dfn{enables} the theme (unless the
1451 optional argument @var{no-enable} is non-@code{nil}), causing its
1452 variable and face settings to take effect. It prompts the user for
1453 confirmation before loading the theme, unless the optional argument
1454 @var{no-confirm} is non-@code{nil}.
1457 @deffn Command enable-theme theme
1458 This function enables the Custom theme named @var{theme}. It signals
1459 an error if no such theme has been loaded.
1462 @deffn Command disable-theme theme
1463 This function disables the Custom theme named @var{theme}. The theme
1464 remains loaded, so that a subsequent call to @code{enable-theme} will