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 @setfilename ../../info/customize
6 @node Customization, Loading, Macros, Top
7 @chapter Writing Customization Definitions
9 @cindex customization definitions
10 This chapter describes how to declare user options for customization,
11 and also customization groups for classifying them. We use the term
12 @dfn{customization item} to include both kinds of customization
13 definitions---as well as face definitions (@pxref{Defining Faces}).
16 * Common Keywords:: Common keyword arguments for all kinds of
17 customization declarations.
18 * Group Definitions:: Writing customization group definitions.
19 * Variable Definitions:: Declaring user options.
20 * Customization Types:: Specifying the type of a user option.
24 @section Common Item Keywords
26 @cindex customization keywords
27 All kinds of customization declarations (for variables and groups, and
28 for faces) accept keyword arguments for specifying various information.
29 This section describes some keywords that apply to all kinds.
31 All of these keywords, except @code{:tag}, can be used more than once
32 in a given item. Each use of the keyword has an independent effect.
33 The keyword @code{:tag} is an exception because any given item can only
37 @item :tag @var{label}
38 @kindex tag@r{, customization keyword}
39 Use @var{label}, a string, instead of the item's name, to label the
40 item in customization menus and buffers. @strong{Don't use a tag
41 which is substantially different from the item's real name; that would
44 @kindex group@r{, customization keyword}
45 @item :group @var{group}
46 Put this customization item in group @var{group}. When you use
47 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
50 If you use this keyword more than once, you can put a single item into
51 more than one group. Displaying any of those groups will show this
52 item. Please don't overdo this, since the result would be annoying.
54 @item :link @var{link-data}
55 @kindex link@r{, customization keyword}
56 Include an external link after the documentation string for this item.
57 This is a sentence containing an active field which references some
60 There are several alternatives you can use for @var{link-data}:
63 @item (custom-manual @var{info-node})
64 Link to an Info node; @var{info-node} is a string which specifies the
65 node name, as in @code{"(emacs)Top"}. The link appears as
66 @samp{[Manual]} in the customization buffer and enters the built-in
67 Info reader on @var{info-node}.
69 @item (info-link @var{info-node})
70 Like @code{custom-manual} except that the link appears
71 in the customization buffer with the Info node name.
73 @item (url-link @var{url})
74 Link to a web page; @var{url} is a string which specifies the
75 @acronym{URL}. The link appears in the customization buffer as
76 @var{url} and invokes the WWW browser specified by
77 @code{browse-url-browser-function}.
79 @item (emacs-commentary-link @var{library})
80 Link to the commentary section of a library; @var{library} is a string
81 which specifies the library name.
83 @item (emacs-library-link @var{library})
84 Link to an Emacs Lisp library file; @var{library} is a string which
85 specifies the library name.
87 @item (file-link @var{file})
88 Link to a file; @var{file} is a string which specifies the name of the
89 file to visit with @code{find-file} when the user invokes this link.
91 @item (function-link @var{function})
92 Link to the documentation of a function; @var{function} is a string
93 which specifies the name of the function to describe with
94 @code{describe-function} when the user invokes this link.
96 @item (variable-link @var{variable})
97 Link to the documentation of a variable; @var{variable} is a string
98 which specifies the name of the variable to describe with
99 @code{describe-variable} when the user invokes this link.
101 @item (custom-group-link @var{group})
102 Link to another customization group. Invoking it creates a new
103 customization buffer for @var{group}.
106 You can specify the text to use in the customization buffer by adding
107 @code{:tag @var{name}} after the first element of the @var{link-data};
108 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
109 the Emacs manual which appears in the buffer as @samp{foo}.
111 An item can have more than one external link; however, most items have
114 @item :load @var{file}
115 @kindex load@r{, customization keyword}
116 Load file @var{file} (a string) before displaying this customization
117 item (@pxref{Loading}). Loading is done with @code{load}, and only if
118 the file is not already loaded.
120 @item :require @var{feature}
121 @kindex require@r{, customization keyword}
122 Execute @code{(require '@var{feature})} when your saved customizations
123 set the value of this item. @var{feature} should be a symbol.
125 The most common reason to use @code{:require} is when a variable enables
126 a feature such as a minor mode, and just setting the variable won't have
127 any effect unless the code which implements the mode is loaded.
129 @item :version @var{version}
130 @kindex version@r{, customization keyword}
131 This keyword specifies that the item was first introduced in Emacs
132 version @var{version}, or that its default value was changed in that
133 version. The value @var{version} must be a string.
135 @item :package-version '(@var{package} . @var{version})
136 @kindex package-version@r{, customization keyword}
137 This keyword specifies that the item was first introduced in
138 @var{package} version @var{version}, or that its meaning or default
139 value was changed in that version. The value of @var{package} is a
140 symbol and @var{version} is a string.
142 This keyword takes priority over @code{:version}.
144 @var{package} should be the official name of the package, such as MH-E
145 or Gnus. If the package @var{package} is released as part of Emacs,
146 @var{package} and @var{version} should appear in the value of
147 @code{customize-package-emacs-version-alist}.
150 Packages distributed as part of Emacs that use the
151 @code{:package-version} keyword must also update the
152 @code{customize-package-emacs-version-alist} variable.
154 @defvar customize-package-emacs-version-alist
155 This alist provides a mapping for the versions of Emacs that are
156 associated with versions of a package listed in the
157 @code{:package-version} keyword. Its elements look like this:
160 (@var{package} (@var{pversion} . @var{eversion})@dots{})
163 For each @var{package}, which is a symbol, there are one or more
164 elements that contain a package version @var{pversion} with an
165 associated Emacs version @var{eversion}. These versions are strings.
166 For example, the MH-E package updates this alist with the following:
169 (add-to-list 'customize-package-emacs-version-alist
170 '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
171 ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
172 ("7.4" . "22.1") ("8.0" . "22.1")))
175 The value of @var{package} needs to be unique and it needs to match
176 the @var{package} value appearing in the @code{:package-version}
177 keyword. Since the user might see the value in an error message, a good
178 choice is the official name of the package, such as MH-E or Gnus.
181 @node Group Definitions
182 @section Defining Customization Groups
183 @cindex define customization group
184 @cindex customization groups, defining
186 Each Emacs Lisp package should have one main customization group which
187 contains all the options, faces and other groups in the package. If the
188 package has a small number of options and faces, use just one group and
189 put everything in it. When there are more than twelve or so options and
190 faces, then you should structure them into subgroups, and put the
191 subgroups under the package's main customization group. It is OK to
192 put some of the options and faces in the package's main group alongside
195 The package's main or only group should be a member of one or more of
196 the standard customization groups. (To display the full list of them,
197 use @kbd{M-x customize}.) Choose one or more of them (but not too
198 many), and add your group to each of them using the @code{:group}
201 The way to declare new customization groups is with @code{defgroup}.
203 @defmac defgroup group members doc [keyword value]@dots{}
204 Declare @var{group} as a customization group containing @var{members}.
205 Do not quote the symbol @var{group}. The argument @var{doc} specifies
206 the documentation string for the group.
208 The argument @var{members} is a list specifying an initial set of
209 customization items to be members of the group. However, most often
210 @var{members} is @code{nil}, and you specify the group's members by
211 using the @code{:group} keyword when defining those members.
213 If you want to specify group members through @var{members}, each element
214 should have the form @code{(@var{name} @var{widget})}. Here @var{name}
215 is a symbol, and @var{widget} is a widget type for editing that symbol.
216 Useful widgets are @code{custom-variable} for a variable,
217 @code{custom-face} for a face, and @code{custom-group} for a group.
219 When you introduce a new group into Emacs, use the @code{:version}
220 keyword in the @code{defgroup}; then you need not use it for
221 the individual members of the group.
223 In addition to the common keywords (@pxref{Common Keywords}), you can
224 also use this keyword in @code{defgroup}:
227 @item :prefix @var{prefix}
228 @kindex prefix@r{, @code{defgroup} keyword}
229 If the name of an item in the group starts with @var{prefix}, then the
230 tag for that item is constructed (by default) by omitting @var{prefix}.
232 One group can have any number of prefixes.
236 The prefix-discarding feature is currently turned off, which means
237 that @code{:prefix} currently has no effect. We did this because we
238 found that discarding the specified prefixes often led to confusing
239 names for options. This happened because the people who wrote the
240 @code{defgroup} definitions for various groups added @code{:prefix}
241 keywords whenever they make logical sense---that is, whenever the
242 variables in the library have a common prefix.
244 In order to obtain good results with @code{:prefix}, it would be
245 necessary to check the specific effects of discarding a particular
246 prefix, given the specific items in a group and their names and
247 documentation. If the resulting text is not clear, then @code{:prefix}
248 should not be used in that case.
250 It should be possible to recheck all the customization groups, delete
251 the @code{:prefix} specifications which give unclear results, and then
252 turn this feature back on, if someone would like to do the work.
254 @node Variable Definitions
255 @section Defining Customization Variables
256 @cindex define customization options
257 @cindex customization variables, how to define
259 Use @code{defcustom} to declare user-customizable variables.
261 @defmac defcustom option standard doc [keyword value]@dots{}
262 This macro declares @var{option} as a customizable @dfn{user option}.
263 You should not quote @var{option}.
265 The argument @var{standard} is an expression that specifies the
266 standard value for @var{option}. Evaluating the @code{defcustom} form
267 evaluates @var{standard}, but does not necessarily install the
268 standard value. If @var{option} already has a default value,
269 @code{defcustom} does not change it. If the user has saved a
270 customization for @var{option}, @code{defcustom} installs the user's
271 customized value as @var{option}'s default value. If neither of those
272 cases applies, @code{defcustom} installs the result of evaluating
273 @var{standard} as the default value.
275 The expression @var{standard} can be evaluated at various other times,
276 too---whenever the customization facility needs to know @var{option}'s
277 standard value. So be sure to use an expression which is harmless to
278 evaluate at any time. We recommend avoiding backquotes in
279 @var{standard}, because they are not expanded when editing the value,
280 so list values will appear to have the wrong structure.
282 The argument @var{doc} specifies the documentation string for the
285 Every @code{defcustom} should specify @code{:group} at least once.
287 If you specify the @code{:set} keyword, to make the variable take other
288 special actions when set through the customization buffer, the
289 variable's documentation string should tell the user specifically how
290 to do the same job in hand-written Lisp code.
292 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
293 mode (@code{eval-defun}), a special feature of @code{eval-defun}
294 arranges to set the variable unconditionally, without testing whether
295 its value is void. (The same feature applies to @code{defvar}.)
296 @xref{Defining Variables}.
298 If you put a @code{defcustom} in a file that is preloaded at dump time
299 (@pxref{Building Emacs}), and the standard value installed for the
300 variable at that time might not be correct, use
301 @code{custom-reevaluate-setting}, described below, to re-evaluate the
302 standard value during or after Emacs startup.
305 @code{defcustom} accepts the following additional keywords:
308 @item :type @var{type}
309 Use @var{type} as the data type for this option. It specifies which
310 values are legitimate, and how to display the value.
311 @xref{Customization Types}, for more information.
313 @item :options @var{value-list}
314 @kindex options@r{, @code{defcustom} keyword}
315 Specify the list of reasonable values for use in this
316 option. The user is not restricted to using only these values, but they
317 are offered as convenient alternatives.
319 This is meaningful only for certain types, currently including
320 @code{hook}, @code{plist} and @code{alist}. See the definition of the
321 individual types for a description of how to use @code{:options}.
323 @item :set @var{setfunction}
324 @kindex set@r{, @code{defcustom} keyword}
325 Specify @var{setfunction} as the way to change the value of this
326 option when using the Customize user interface. The function
327 @var{setfunction} should take two arguments, a symbol (the option
328 name) and the new value, and should do whatever is necessary to update
329 the value properly for this option (which may not mean simply setting
330 the option as a Lisp variable). The default for @var{setfunction} is
333 @item :get @var{getfunction}
334 @kindex get@r{, @code{defcustom} keyword}
335 Specify @var{getfunction} as the way to extract the value of this
336 option. The function @var{getfunction} should take one argument, a
337 symbol, and should return whatever customize should use as the
338 ``current value'' for that symbol (which need not be the symbol's Lisp
339 value). The default is @code{default-value}.
341 You have to really understand the workings of Custom to use
342 @code{:get} correctly. It is meant for values that are treated in
343 Custom as variables but are not actually stored in Lisp variables. It
344 is almost surely a mistake to specify @code{getfunction} for a value
345 that really is stored in a Lisp variable.
347 @item :initialize @var{function}
348 @kindex initialize@r{, @code{defcustom} keyword}
349 @var{function} should be a function used to initialize the variable
350 when the @code{defcustom} is evaluated. It should take two arguments,
351 the option name (a symbol) and the value. Here are some predefined
352 functions meant for use in this way:
355 @item custom-initialize-set
356 Use the variable's @code{:set} function to initialize the variable, but
357 do not reinitialize it if it is already non-void.
359 @item custom-initialize-default
360 Like @code{custom-initialize-set}, but use the function
361 @code{set-default} to set the variable, instead of the variable's
362 @code{:set} function. This is the usual choice for a variable whose
363 @code{:set} function enables or disables a minor mode; with this choice,
364 defining the variable will not call the minor mode function, but
365 customizing the variable will do so.
367 @item custom-initialize-reset
368 Always use the @code{:set} function to initialize the variable. If
369 the variable is already non-void, reset it by calling the @code{:set}
370 function using the current value (returned by the @code{:get} method).
371 This is the default @code{:initialize} function.
373 @item custom-initialize-changed
374 Use the @code{:set} function to initialize the variable, if it is
375 already set or has been customized; otherwise, just use
378 @item custom-initialize-safe-set
379 @itemx custom-initialize-safe-default
380 These functions behave like @code{custom-initialize-set}
381 (@code{custom-initialize-default}, respectively), but catch errors.
382 If an error occurs during initialization, they set the variable to
383 @code{nil} using @code{set-default}, and throw no error.
385 These two functions are only meant for options defined in pre-loaded
386 files, where some variables or functions used to compute the option's
387 value may not yet be defined. The option normally gets updated in
388 @file{startup.el}, ignoring the previously computed value. Because of
389 this typical usage, the value which these two functions compute
390 normally only matters when, after startup, one unsets the option's
391 value and then reevaluates the defcustom. By that time, the necessary
392 variables and functions will be defined, so there will not be an error.
395 @item :risky @var{value}
396 @kindex risky@r{, @code{defcustom} keyword}
397 Set the variable's @code{risky-local-variable} property to
398 @var{value} (@pxref{File Local Variables}).
400 @item :safe @var{function}
401 @kindex safe@r{, @code{defcustom} keyword}
402 Set the variable's @code{safe-local-variable} property to
403 @var{function} (@pxref{File Local Variables}).
405 @item :set-after @var{variables}
406 @kindex set-after@r{, @code{defcustom} keyword}
407 When setting variables according to saved customizations, make sure to
408 set the variables @var{variables} before this one; in other words, delay
409 setting this variable until after those others have been handled. Use
410 @code{:set-after} if setting this variable won't work properly unless
411 those other variables already have their intended values.
414 It is useful to specify the @code{:require} keyword for an option
415 that ``turns on'' a certain feature. This causes Emacs to load the
416 feature, if it is not already loaded, whenever the option is set.
417 @xref{Common Keywords}. Here is an example, from the library
421 (defcustom save-place nil
422 "Non-nil means automatically save place in each file..."
428 If a customization item has a type such as @code{hook} or
429 @code{alist}, which supports @code{:options}, you can add additional
430 values to the list from outside the @code{defcustom} declaration by
431 calling @code{custom-add-frequent-value}. For example, if you define a
432 function @code{my-lisp-mode-initialization} intended to be called from
433 @code{emacs-lisp-mode-hook}, you might want to add that to the list of
434 reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
435 its definition. You can do it thus:
438 (custom-add-frequent-value 'emacs-lisp-mode-hook
439 'my-lisp-mode-initialization)
442 @defun custom-add-frequent-value symbol value
443 For the customization option @var{symbol}, add @var{value} to the
444 list of reasonable values.
446 The precise effect of adding a value depends on the customization type
450 Internally, @code{defcustom} uses the symbol property
451 @code{standard-value} to record the expression for the standard value,
452 @code{saved-value} to record the value saved by the user with the
453 customization buffer, and @code{customized-value} to record the value
454 set by the user with the customization buffer, but not saved.
455 @xref{Property Lists}. These properties are lists, the car of which
456 is an expression that evaluates to the value.
458 @defun custom-reevaluate-setting symbol
459 This function re-evaluates the standard value of @var{symbol}, which
460 should be a user option declared via @code{defcustom}. (If the
461 variable was customized, this function re-evaluates the saved value
462 instead.) This is useful for customizable options that are defined
463 before their value could be computed correctly, such as variables
464 defined in packages that are loaded at dump time, but depend on the
465 run-time information. For example, the value could be a file whose
466 precise name depends on the hierarchy of files when Emacs runs, or a
467 name of a program that needs to be searched at run time.
469 A good place to put calls to this function is in the function
470 @code{command-line} that is run during startup (@pxref{Startup Summary})
471 or in the various hooks it calls.
474 @defun custom-variable-p arg
475 This function returns non-@code{nil} if @var{arg} is a customizable
476 variable. A customizable variable is either a variable that has a
477 @code{standard-value} or @code{custom-autoload} property (usually
478 meaning it was declared with @code{defcustom}), or an alias for
479 another customizable variable.
482 @defun user-variable-p arg
483 This function is like @code{custom-variable-p}, except it also returns
484 @code{t} if the first character of the variable's documentation string
485 is the character @samp{*}. That is an obsolete way of indicating a
486 user option, so for most purposes you may consider
487 @code{user-variable-p} as equivalent to @code{custom-variable-p}.
490 @node Customization Types
491 @section Customization Types
493 @cindex customization types
494 When you define a user option with @code{defcustom}, you must specify
495 its @dfn{customization type}. That is a Lisp object which describes (1)
496 which values are legitimate and (2) how to display the value in the
497 customization buffer for editing.
499 @kindex type@r{, @code{defcustom} keyword}
500 You specify the customization type in @code{defcustom} with the
501 @code{:type} keyword. The argument of @code{:type} is evaluated, but
502 only once when the @code{defcustom} is executed, so it isn't useful
503 for the value to vary. Normally we use a quoted constant. For
507 (defcustom diff-command "diff"
508 "The command to use to run diff."
513 In general, a customization type is a list whose first element is a
514 symbol, one of the customization type names defined in the following
515 sections. After this symbol come a number of arguments, depending on
516 the symbol. Between the type symbol and its arguments, you can
517 optionally write keyword-value pairs (@pxref{Type Keywords}).
519 Some type symbols do not use any arguments; those are called
520 @dfn{simple types}. For a simple type, if you do not use any
521 keyword-value pairs, you can omit the parentheses around the type
522 symbol. For example just @code{string} as a customization type is
523 equivalent to @code{(string)}.
525 All customization types are implemented as widgets; see @ref{Top, ,
526 Introduction, widget, The Emacs Widget Library}, for details.
529 * Simple Types:: Simple customization types: sexp, integer, etc.
530 * Composite Types:: Build new types from other types or data.
531 * Splicing into Lists:: Splice elements into list with @code{:inline}.
532 * Type Keywords:: Keyword-argument pairs in a customization type.
533 * Defining New Types:: Give your type a name.
537 @subsection Simple Types
539 This section describes all the simple customization types.
543 The value may be any Lisp object that can be printed and read back. You
544 can use @code{sexp} as a fall-back for any option, if you don't want to
545 take the time to work out a more specific type to use.
548 The value must be an integer, and is represented textually
549 in the customization buffer.
552 The value must be a number (floating point or integer), and is
553 represented textually in the customization buffer.
556 The value must be a floating point number, and is represented
557 textually in the customization buffer.
560 The value must be a string, and the customization buffer shows just the
561 contents, with no delimiting @samp{"} characters and no quoting with
565 Like @code{string} except that the string must be a valid regular
569 The value must be a character code. A character code is actually an
570 integer, but this type shows the value by inserting the character in the
571 buffer, rather than by showing the number.
574 The value must be a file name, and you can do completion with
577 @item (file :must-match t)
578 The value must be a file name for an existing file, and you can do
579 completion with @kbd{M-@key{TAB}}.
582 The value must be a directory name, and you can do completion with
586 The value must be a list of functions (or a single function, but that is
587 obsolete usage). This customization type is used for hook variables.
588 You can use the @code{:options} keyword in a hook variable's
589 @code{defcustom} to specify a list of functions recommended for use in
590 the hook; see @ref{Variable Definitions}.
593 The value must be a symbol. It appears in the customization buffer as
594 the name of the symbol.
597 The value must be either a lambda expression or a function name. When
598 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
601 The value must be a variable name, and you can do completion with
605 The value must be a symbol which is a face name, and you can do
606 completion with @kbd{M-@key{TAB}}.
609 The value is boolean---either @code{nil} or @code{t}. Note that by
610 using @code{choice} and @code{const} together (see the next section),
611 you can specify that the value must be @code{nil} or @code{t}, but also
612 specify the text to describe each value in a way that fits the specific
613 meaning of the alternative.
616 The value must be a coding-system name, and you can do completion with
620 The value must be a valid color name, and you can do completion with
621 @kbd{M-@key{TAB}}. A sample is provided.
624 @node Composite Types
625 @subsection Composite Types
626 @cindex composite types (customization)
628 When none of the simple types is appropriate, you can use composite
629 types, which build new types from other types or from specified data.
630 The specified types or data are called the @dfn{arguments} of the
631 composite type. The composite type normally looks like this:
634 (@var{constructor} @var{arguments}@dots{})
638 but you can also add keyword-value pairs before the arguments, like
642 (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
645 Here is a table of constructors and how to use them to write
649 @item (cons @var{car-type} @var{cdr-type})
650 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
651 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
652 symbol)} is a customization type which matches values such as
653 @code{("foo" . foo)}.
655 In the customization buffer, the @sc{car} and the @sc{cdr} are
656 displayed and edited separately, each according to the type
657 that you specify for it.
659 @item (list @var{element-types}@dots{})
660 The value must be a list with exactly as many elements as the
661 @var{element-types} given; and each element must fit the
662 corresponding @var{element-type}.
664 For example, @code{(list integer string function)} describes a list of
665 three elements; the first element must be an integer, the second a
666 string, and the third a function.
668 In the customization buffer, each element is displayed and edited
669 separately, according to the type specified for it.
671 @item (group @var{element-types}@dots{})
672 This works like @code{list} except for the formatting
673 of text in the Custom buffer. @code{list} labels each
674 element value with its tag; @code{group} does not.
676 @item (vector @var{element-types}@dots{})
677 Like @code{list} except that the value must be a vector instead of a
678 list. The elements work the same as in @code{list}.
680 @item (alist :key-type @var{key-type} :value-type @var{value-type})
681 The value must be a list of cons-cells, the @sc{car} of each cell
682 representing a key of customization type @var{key-type}, and the
683 @sc{cdr} of the same cell representing a value of customization type
684 @var{value-type}. The user can add and delete key/value pairs, and
685 edit both the key and the value of each pair.
687 If omitted, @var{key-type} and @var{value-type} default to
690 The user can add any key matching the specified key type, but you can
691 give some keys a preferential treatment by specifying them with the
692 @code{:options} (see @ref{Variable Definitions}). The specified keys
693 will always be shown in the customize buffer (together with a suitable
694 value), with a checkbox to include or exclude or disable the key/value
695 pair from the alist. The user will not be able to edit the keys
696 specified by the @code{:options} keyword argument.
698 The argument to the @code{:options} keywords should be a list of
699 specifications for reasonable keys in the alist. Ordinarily, they are
700 simply atoms, which stand for themselves as. For example:
703 :options '("foo" "bar" "baz")
707 specifies that there are three ``known'' keys, namely @code{"foo"},
708 @code{"bar"} and @code{"baz"}, which will always be shown first.
710 You may want to restrict the value type for specific keys, for
711 example, the value associated with the @code{"bar"} key can only be an
712 integer. You can specify this by using a list instead of an atom in
713 the list. The first element will specify the key, like before, while
714 the second element will specify the value type. For example:
717 :options '("foo" ("bar" integer) "baz")
720 Finally, you may want to change how the key is presented. By default,
721 the key is simply shown as a @code{const}, since the user cannot change
722 the special keys specified with the @code{:options} keyword. However,
723 you may want to use a more specialized type for presenting the key, like
724 @code{function-item} if you know it is a symbol with a function binding.
725 This is done by using a customization type specification instead of a
729 :options '("foo" ((function-item some-function) integer)
733 Many alists use lists with two elements, instead of cons cells. For
737 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
738 "Each element is a list of the form (KEY VALUE).")
745 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
746 "Each element is a cons-cell (KEY . VALUE).")
749 Because of the way lists are implemented on top of cons cells, you can
750 treat @code{list-alist} in the example above as a cons cell alist, where
751 the value type is a list with a single element containing the real
755 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
756 "Each element is a list of the form (KEY VALUE)."
757 :type '(alist :value-type (group integer)))
760 The @code{group} widget is used here instead of @code{list} only because
761 the formatting is better suited for the purpose.
763 Similarly, you can have alists with more values associated with each
764 key, using variations of this trick:
767 (defcustom person-data '(("brian" 50 t)
770 "Alist of basic info about people.
771 Each element has the form (NAME AGE MALE-FLAG)."
772 :type '(alist :value-type (group integer boolean)))
774 (defcustom pets '(("brian")
775 ("dorith" "dog" "guppy")
777 "Alist of people's pets.
778 In an element (KEY . VALUE), KEY is the person's name,
779 and the VALUE is a list of that person's pets."
780 :type '(alist :value-type (repeat string)))
783 @item (plist :key-type @var{key-type} :value-type @var{value-type})
784 This customization type is similar to @code{alist} (see above), except
785 that (i) the information is stored as a property list,
786 (@pxref{Property Lists}), and (ii) @var{key-type}, if omitted,
787 defaults to @code{symbol} rather than @code{sexp}.
789 @item (choice @var{alternative-types}@dots{})
790 The value must fit at least one of @var{alternative-types}.
791 For example, @code{(choice integer string)} allows either an
794 In the customization buffer, the user selects an alternative
795 using a menu, and can then edit the value in the usual way for that
798 Normally the strings in this menu are determined automatically from the
799 choices; however, you can specify different strings for the menu by
800 including the @code{:tag} keyword in the alternatives. For example, if
801 an integer stands for a number of spaces, while a string is text to use
802 verbatim, you might write the customization type this way,
805 (choice (integer :tag "Number of spaces")
806 (string :tag "Literal text"))
810 so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
812 In any alternative for which @code{nil} is not a valid value, other than
813 a @code{const}, you should specify a valid default for that alternative
814 using the @code{:value} keyword. @xref{Type Keywords}.
816 If some values are covered by more than one of the alternatives,
817 customize will choose the first alternative that the value fits. This
818 means you should always list the most specific types first, and the
819 most general last. Here's an example of proper usage:
822 (choice (const :tag "Off" nil)
823 symbol (sexp :tag "Other"))
827 This way, the special value @code{nil} is not treated like other
828 symbols, and symbols are not treated like other Lisp expressions.
830 @item (radio @var{element-types}@dots{})
831 This is similar to @code{choice}, except that the choices are displayed
832 using `radio buttons' rather than a menu. This has the advantage of
833 displaying documentation for the choices when applicable and so is often
834 a good choice for a choice between constant functions
835 (@code{function-item} customization types).
837 @item (const @var{value})
838 The value must be @var{value}---nothing else is allowed.
840 The main use of @code{const} is inside of @code{choice}. For example,
841 @code{(choice integer (const nil))} allows either an integer or
844 @code{:tag} is often used with @code{const}, inside of @code{choice}.
848 (choice (const :tag "Yes" t)
849 (const :tag "No" nil)
850 (const :tag "Ask" foo))
854 describes a variable for which @code{t} means yes, @code{nil} means no,
855 and @code{foo} means ``ask.''
857 @item (other @var{value})
858 This alternative can match any Lisp value, but if the user chooses this
859 alternative, that selects the value @var{value}.
861 The main use of @code{other} is as the last element of @code{choice}.
865 (choice (const :tag "Yes" t)
866 (const :tag "No" nil)
867 (other :tag "Ask" foo))
871 describes a variable for which @code{t} means yes, @code{nil} means no,
872 and anything else means ``ask.'' If the user chooses @samp{Ask} from
873 the menu of alternatives, that specifies the value @code{foo}; but any
874 other value (not @code{t}, @code{nil} or @code{foo}) displays as
875 @samp{Ask}, just like @code{foo}.
877 @item (function-item @var{function})
878 Like @code{const}, but used for values which are functions. This
879 displays the documentation string as well as the function name.
880 The documentation string is either the one you specify with
881 @code{:doc}, or @var{function}'s own documentation string.
883 @item (variable-item @var{variable})
884 Like @code{const}, but used for values which are variable names. This
885 displays the documentation string as well as the variable name. The
886 documentation string is either the one you specify with @code{:doc}, or
887 @var{variable}'s own documentation string.
889 @item (set @var{types}@dots{})
890 The value must be a list, and each element of the list must match one of
891 the @var{types} specified.
893 This appears in the customization buffer as a checklist, so that each of
894 @var{types} may have either one corresponding element or none. It is
895 not possible to specify two different elements that match the same one
896 of @var{types}. For example, @code{(set integer symbol)} allows one
897 integer and/or one symbol in the list; it does not allow multiple
898 integers or multiple symbols. As a result, it is rare to use
899 nonspecific types such as @code{integer} in a @code{set}.
901 Most often, the @var{types} in a @code{set} are @code{const} types, as
905 (set (const :bold) (const :italic))
908 Sometimes they describe possible elements in an alist:
911 (set (cons :tag "Height" (const height) integer)
912 (cons :tag "Width" (const width) integer))
916 That lets the user specify a height value optionally
917 and a width value optionally.
919 @item (repeat @var{element-type})
920 The value must be a list and each element of the list must fit the type
921 @var{element-type}. This appears in the customization buffer as a
922 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
923 more elements or removing elements.
925 @item (restricted-sexp :match-alternatives @var{criteria})
926 This is the most general composite type construct. The value may be
927 any Lisp object that satisfies one of @var{criteria}. @var{criteria}
928 should be a list, and each element should be one of these
933 A predicate---that is, a function of one argument that has no side
934 effects, and returns either @code{nil} or non-@code{nil} according to
935 the argument. Using a predicate in the list says that objects for which
936 the predicate returns non-@code{nil} are acceptable.
939 A quoted constant---that is, @code{'@var{object}}. This sort of element
940 in the list says that @var{object} itself is an acceptable value.
946 (restricted-sexp :match-alternatives
951 allows integers, @code{t} and @code{nil} as legitimate values.
953 The customization buffer shows all legitimate values using their read
954 syntax, and the user edits them textually.
957 Here is a table of the keywords you can use in keyword-value pairs
962 Use @var{tag} as the name of this alternative, for user communication
963 purposes. This is useful for a type that appears inside of a
966 @item :match-alternatives @var{criteria}
967 @kindex match-alternatives@r{, customization keyword}
968 Use @var{criteria} to match possible values. This is used only in
969 @code{restricted-sexp}.
971 @item :args @var{argument-list}
972 @kindex args@r{, customization keyword}
973 Use the elements of @var{argument-list} as the arguments of the type
974 construct. For instance, @code{(const :args (foo))} is equivalent to
975 @code{(const foo)}. You rarely need to write @code{:args} explicitly,
976 because normally the arguments are recognized automatically as
977 whatever follows the last keyword-value pair.
980 @node Splicing into Lists
981 @subsection Splicing into Lists
983 The @code{:inline} feature lets you splice a variable number of
984 elements into the middle of a list or vector. You use it in a
985 @code{set}, @code{choice} or @code{repeat} type which appears among the
986 element-types of a @code{list} or @code{vector}.
988 Normally, each of the element-types in a @code{list} or @code{vector}
989 describes one and only one element of the list or vector. Thus, if an
990 element-type is a @code{repeat}, that specifies a list of unspecified
991 length which appears as one element.
993 But when the element-type uses @code{:inline}, the value it matches is
994 merged directly into the containing sequence. For example, if it
995 matches a list with three elements, those become three elements of the
996 overall sequence. This is analogous to using @samp{,@@} in the backquote
999 For example, to specify a list whose first element must be @code{baz}
1000 and whose remaining arguments should be zero or more of @code{foo} and
1001 @code{bar}, use this customization type:
1004 (list (const baz) (set :inline t (const foo) (const bar)))
1008 This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
1009 and @code{(baz foo bar)}.
1011 When the element-type is a @code{choice}, you use @code{:inline} not
1012 in the @code{choice} itself, but in (some of) the alternatives of the
1013 @code{choice}. For example, to match a list which must start with a
1014 file name, followed either by the symbol @code{t} or two strings, use
1015 this customization type:
1020 (list :inline t string string)))
1024 If the user chooses the first alternative in the choice, then the
1025 overall list has two elements and the second element is @code{t}. If
1026 the user chooses the second alternative, then the overall list has three
1027 elements and the second and third must be strings.
1030 @subsection Type Keywords
1032 You can specify keyword-argument pairs in a customization type after the
1033 type name symbol. Here are the keywords you can use, and their
1037 @item :value @var{default}
1038 Provide a default value.
1040 If @code{nil} is not a valid value for the alternative, then it is
1041 essential to specify a valid default with @code{:value}.
1043 If you use this for a type that appears as an alternative inside of
1044 @code{choice}; it specifies the default value to use, at first, if and
1045 when the user selects this alternative with the menu in the
1046 customization buffer.
1048 Of course, if the actual value of the option fits this alternative, it
1049 will appear showing the actual value, not @var{default}.
1051 @item :format @var{format-string}
1052 @kindex format@r{, customization keyword}
1053 This string will be inserted in the buffer to represent the value
1054 corresponding to the type. The following @samp{%} escapes are available
1055 for use in @var{format-string}:
1058 @item %[@var{button}%]
1059 Display the text @var{button} marked as a button. The @code{:action}
1060 attribute specifies what the button will do if the user invokes it;
1061 its value is a function which takes two arguments---the widget which
1062 the button appears in, and the event.
1064 There is no way to specify two different buttons with different
1067 @item %@{@var{sample}%@}
1068 Show @var{sample} in a special face specified by @code{:sample-face}.
1071 Substitute the item's value. How the value is represented depends on
1072 the kind of item, and (for variables) on the customization type.
1075 Substitute the item's documentation string.
1078 Like @samp{%d}, but if the documentation string is more than one line,
1079 add an active field to control whether to show all of it or just the
1083 Substitute the tag here. You specify the tag with the @code{:tag}
1087 Display a literal @samp{%}.
1090 @item :action @var{action}
1091 @kindex action@r{, customization keyword}
1092 Perform @var{action} if the user clicks on a button.
1094 @item :button-face @var{face}
1095 @kindex button-face@r{, customization keyword}
1096 Use the face @var{face} (a face name or a list of face names) for button
1097 text displayed with @samp{%[@dots{}%]}.
1099 @item :button-prefix @var{prefix}
1100 @itemx :button-suffix @var{suffix}
1101 @kindex button-prefix@r{, customization keyword}
1102 @kindex button-suffix@r{, customization keyword}
1103 These specify the text to display before and after a button.
1108 No text is inserted.
1111 The string is inserted literally.
1114 The symbol's value is used.
1117 @item :tag @var{tag}
1118 Use @var{tag} (a string) as the tag for the value (or part of the value)
1119 that corresponds to this type.
1121 @item :doc @var{doc}
1122 @kindex doc@r{, customization keyword}
1123 Use @var{doc} as the documentation string for this value (or part of the
1124 value) that corresponds to this type. In order for this to work, you
1125 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
1128 The usual reason to specify a documentation string for a type is to
1129 provide more information about the meanings of alternatives inside a
1130 @code{:choice} type or the parts of some other composite type.
1132 @item :help-echo @var{motion-doc}
1133 @kindex help-echo@r{, customization keyword}
1134 When you move to this item with @code{widget-forward} or
1135 @code{widget-backward}, it will display the string @var{motion-doc} in
1136 the echo area. In addition, @var{motion-doc} is used as the mouse
1137 @code{help-echo} string and may actually be a function or form evaluated
1138 to yield a help string. If it is a function, it is called with one
1139 argument, the widget.
1141 @item :match @var{function}
1142 @kindex match@r{, customization keyword}
1143 Specify how to decide whether a value matches the type. The
1144 corresponding value, @var{function}, should be a function that accepts
1145 two arguments, a widget and a value; it should return non-@code{nil} if
1146 the value is acceptable.
1148 @item :validate @var{function}
1149 Specify a validation function for input. @var{function} takes a
1150 widget as an argument, and should return @code{nil} if the widget's
1151 current value is valid for the widget. Otherwise, it should return
1152 the widget containing the invalid data, and set that widget's
1153 @code{:error} property to a string explaining the error.
1156 @item :indent @var{columns}
1157 Indent this item by @var{columns} columns. The indentation is used for
1158 @samp{%n}, and automatically for group names, for checklists and radio
1159 buttons, and for editable lists. It affects the whole of the
1160 item except for the first line.
1162 @item :offset @var{extra}
1163 Indent the subitems of this item @var{extra} columns more than this
1164 item itself. By default, subitems are indented the same as their
1167 @item :extra-offset @var{n}
1168 Add @var{n} extra spaces to this item's indentation, compared to its
1169 parent's indentation.
1171 @item :notify @var{function}
1172 Call @var{function} each time the item or a subitem is changed. The
1173 function gets two or three arguments. The first argument is the item
1174 itself, the second argument is the item that was changed, and the
1175 third argument is the event leading to the change, if any.
1177 @item :menu-tag @var{tag-string}
1178 Use @var{tag-string} in the menu when the widget is used as an option
1179 in a @code{menu-choice} widget.
1182 A function used for finding the tag when the widget is used as an option
1183 in a @code{menu-choice} widget. By default, the tag used will be either the
1184 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
1185 representation of the @code{:value} property if not.
1188 Specify the order in which widgets are traversed with
1189 @code{widget-forward} or @code{widget-backward}. This is only partially
1194 Widgets with tabbing order @code{-1} are ignored.
1197 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
1198 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
1199 whichever comes first.
1202 When on a widget with no tabbing order specified, go to the next widget
1203 in the buffer with a positive tabbing order, or @code{nil}
1207 The parent of a nested widget (e.g., a @code{menu-choice} item or an
1208 element of a @code{editable-list} widget).
1211 This keyword is only used for members of a @code{radio-button-choice} or
1212 @code{checklist}. The value should be a list of extra keyword
1213 arguments, which will be used when creating the @code{radio-button} or
1214 @code{checkbox} associated with this item.
1218 @node Defining New Types
1219 @subsection Defining New Types
1221 In the previous sections we have described how to construct elaborate
1222 type specifications for @code{defcustom}. In some cases you may want
1223 to give such a type specification a name. The obvious case is when
1224 you are using the same type for many user options: rather than repeat
1225 the specification for each option, you can give the type specification
1226 a name, and use that name each @code{defcustom}. The other case is
1227 when a user option's value is a recursive data structure. To make it
1228 possible for a datatype to refer to itself, it needs to have a name.
1230 Since custom types are implemented as widgets, the way to define a new
1231 customize type is to define a new widget. We are not going to describe
1232 the widget interface here in details, see @ref{Top, , Introduction,
1233 widget, The Emacs Widget Library}, for that. Instead we are going to
1234 demonstrate the minimal functionality needed for defining new customize
1235 types by a simple example.
1238 (define-widget 'binary-tree-of-string 'lazy
1239 "A binary tree made of cons-cells and strings."
1242 :type '(choice (string :tag "Leaf" :value "")
1243 (cons :tag "Interior"
1245 binary-tree-of-string
1246 binary-tree-of-string)))
1248 (defcustom foo-bar ""
1249 "Sample variable holding a binary tree of strings."
1250 :type 'binary-tree-of-string)
1253 The function to define a new widget is called @code{define-widget}. The
1254 first argument is the symbol we want to make a new widget type. The
1255 second argument is a symbol representing an existing widget, the new
1256 widget is going to be defined in terms of difference from the existing
1257 widget. For the purpose of defining new customization types, the
1258 @code{lazy} widget is perfect, because it accepts a @code{:type} keyword
1259 argument with the same syntax as the keyword argument to
1260 @code{defcustom} with the same name. The third argument is a
1261 documentation string for the new widget. You will be able to see that
1262 string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
1265 After these mandatory arguments follow the keyword arguments. The most
1266 important is @code{:type}, which describes the data type we want to match
1267 with this widget. Here a @code{binary-tree-of-string} is described as
1268 being either a string, or a cons-cell whose car and cdr are themselves
1269 both @code{binary-tree-of-string}. Note the reference to the widget
1270 type we are currently in the process of defining. The @code{:tag}
1271 attribute is a string to name the widget in the user interface, and the
1272 @code{:offset} argument is there to ensure that child nodes are
1273 indented four spaces relative to the parent node, making the tree
1274 structure apparent in the customization buffer.
1276 The @code{defcustom} shows how the new widget can be used as an ordinary
1279 The reason for the name @code{lazy} is that the other composite
1280 widgets convert their inferior widgets to internal form when the
1281 widget is instantiated in a buffer. This conversion is recursive, so
1282 the inferior widgets will convert @emph{their} inferior widgets. If
1283 the data structure is itself recursive, this conversion is an infinite
1284 recursion. The @code{lazy} widget prevents the recursion: it convert
1285 its @code{:type} argument only when needed.