2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1997-2011 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 This causes the function @code{user-variable-p} to return @code{t}
266 when given @var{option} as an argument. @xref{Defining Variables}.
267 The argument @var{doc} specifies the documentation string for the
268 variable. (Note that there is no need to start @var{doc} with a
271 The argument @var{standard} is an expression that specifies the
272 standard value for @var{option}. Evaluating the @code{defcustom} form
273 evaluates @var{standard}, but does not necessarily install the
274 standard value. If @var{option} already has a default value,
275 @code{defcustom} does not change it. If the user has saved a
276 customization for @var{option}, @code{defcustom} installs the user's
277 customized value as @var{option}'s default value. If neither of those
278 cases applies, @code{defcustom} installs the result of evaluating
279 @var{standard} as the default value.
281 The expression @var{standard} can be evaluated at various other times,
282 too---whenever the customization facility needs to know @var{option}'s
283 standard value. So be sure to use an expression which is harmless to
284 evaluate at any time. We recommend avoiding backquotes in
285 @var{standard}, because they are not expanded when editing the value,
286 so list values will appear to have the wrong structure.
288 Every @code{defcustom} should specify @code{:group} at least once.
290 If you specify the @code{:set} keyword, to make the variable take other
291 special actions when set through the customization buffer, the
292 variable's documentation string should tell the user specifically how
293 to do the same job in hand-written Lisp code.
295 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
296 mode (@code{eval-defun}), a special feature of @code{eval-defun}
297 arranges to set the variable unconditionally, without testing whether
298 its value is void. (The same feature applies to @code{defvar}.)
299 @xref{Defining Variables}.
301 If you put a @code{defcustom} in a file that is preloaded at dump time
302 (@pxref{Building Emacs}), and the standard value installed for the
303 variable at that time might not be correct, use
304 @code{custom-reevaluate-setting}, described below, to re-evaluate the
305 standard value during or after Emacs startup.
308 @code{defcustom} accepts the following additional keywords:
311 @item :type @var{type}
312 Use @var{type} as the data type for this option. It specifies which
313 values are legitimate, and how to display the value.
314 @xref{Customization Types}, for more information.
316 @item :options @var{value-list}
317 @kindex options@r{, @code{defcustom} keyword}
318 Specify the list of reasonable values for use in this
319 option. The user is not restricted to using only these values, but they
320 are offered as convenient alternatives.
322 This is meaningful only for certain types, currently including
323 @code{hook}, @code{plist} and @code{alist}. See the definition of the
324 individual types for a description of how to use @code{:options}.
326 @item :set @var{setfunction}
327 @kindex set@r{, @code{defcustom} keyword}
328 Specify @var{setfunction} as the way to change the value of this
329 option when using the Customize user interface. The function
330 @var{setfunction} should take two arguments, a symbol (the option
331 name) and the new value, and should do whatever is necessary to update
332 the value properly for this option (which may not mean simply setting
333 the option as a Lisp variable). The default for @var{setfunction} is
336 @item :get @var{getfunction}
337 @kindex get@r{, @code{defcustom} keyword}
338 Specify @var{getfunction} as the way to extract the value of this
339 option. The function @var{getfunction} should take one argument, a
340 symbol, and should return whatever customize should use as the
341 ``current value'' for that symbol (which need not be the symbol's Lisp
342 value). The default is @code{default-value}.
344 You have to really understand the workings of Custom to use
345 @code{:get} correctly. It is meant for values that are treated in
346 Custom as variables but are not actually stored in Lisp variables. It
347 is almost surely a mistake to specify @code{getfunction} for a value
348 that really is stored in a Lisp variable.
350 @item :initialize @var{function}
351 @kindex initialize@r{, @code{defcustom} keyword}
352 @var{function} should be a function used to initialize the variable
353 when the @code{defcustom} is evaluated. It should take two arguments,
354 the option name (a symbol) and the value. Here are some predefined
355 functions meant for use in this way:
358 @item custom-initialize-set
359 Use the variable's @code{:set} function to initialize the variable, but
360 do not reinitialize it if it is already non-void.
362 @item custom-initialize-default
363 Like @code{custom-initialize-set}, but use the function
364 @code{set-default} to set the variable, instead of the variable's
365 @code{:set} function. This is the usual choice for a variable whose
366 @code{:set} function enables or disables a minor mode; with this choice,
367 defining the variable will not call the minor mode function, but
368 customizing the variable will do so.
370 @item custom-initialize-reset
371 Always use the @code{:set} function to initialize the variable. If
372 the variable is already non-void, reset it by calling the @code{:set}
373 function using the current value (returned by the @code{:get} method).
374 This is the default @code{:initialize} function.
376 @item custom-initialize-changed
377 Use the @code{:set} function to initialize the variable, if it is
378 already set or has been customized; otherwise, just use
381 @item custom-initialize-safe-set
382 @itemx custom-initialize-safe-default
383 These functions behave like @code{custom-initialize-set}
384 (@code{custom-initialize-default}, respectively), but catch errors.
385 If an error occurs during initialization, they set the variable to
386 @code{nil} using @code{set-default}, and throw no error.
388 These two functions are only meant for options defined in pre-loaded
389 files, where some variables or functions used to compute the option's
390 value may not yet be defined. The option normally gets updated in
391 @file{startup.el}, ignoring the previously computed value. Because of
392 this typical usage, the value which these two functions compute
393 normally only matters when, after startup, one unsets the option's
394 value and then reevaluates the defcustom. By that time, the necessary
395 variables and functions will be defined, so there will not be an error.
398 @item :risky @var{value}
399 @kindex risky@r{, @code{defcustom} keyword}
400 Set the variable's @code{risky-local-variable} property to
401 @var{value} (@pxref{File Local Variables}).
403 @item :safe @var{function}
404 @kindex safe@r{, @code{defcustom} keyword}
405 Set the variable's @code{safe-local-variable} property to
406 @var{function} (@pxref{File Local Variables}).
408 @item :set-after @var{variables}
409 @kindex set-after@r{, @code{defcustom} keyword}
410 When setting variables according to saved customizations, make sure to
411 set the variables @var{variables} before this one; in other words, delay
412 setting this variable until after those others have been handled. Use
413 @code{:set-after} if setting this variable won't work properly unless
414 those other variables already have their intended values.
417 It is useful to specify the @code{:require} keyword for an option
418 that ``turns on'' a certain feature. This causes Emacs to load the
419 feature, if it is not already loaded, whenever the option is set.
420 @xref{Common Keywords}. Here is an example, from the library
424 (defcustom save-place nil
425 "Non-nil means automatically save place in each file..."
431 If a customization item has a type such as @code{hook} or
432 @code{alist}, which supports @code{:options}, you can add additional
433 values to the list from outside the @code{defcustom} declaration by
434 calling @code{custom-add-frequent-value}. For example, if you define a
435 function @code{my-lisp-mode-initialization} intended to be called from
436 @code{emacs-lisp-mode-hook}, you might want to add that to the list of
437 reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
438 its definition. You can do it thus:
441 (custom-add-frequent-value 'emacs-lisp-mode-hook
442 'my-lisp-mode-initialization)
445 @defun custom-add-frequent-value symbol value
446 For the customization option @var{symbol}, add @var{value} to the
447 list of reasonable values.
449 The precise effect of adding a value depends on the customization type
453 Internally, @code{defcustom} uses the symbol property
454 @code{standard-value} to record the expression for the standard value,
455 @code{saved-value} to record the value saved by the user with the
456 customization buffer, and @code{customized-value} to record the value
457 set by the user with the customization buffer, but not saved.
458 @xref{Property Lists}. These properties are lists, the car of which
459 is an expression that evaluates to the value.
461 @defun custom-reevaluate-setting symbol
462 This function re-evaluates the standard value of @var{symbol}, which
463 should be a user option declared via @code{defcustom}. (If the
464 variable was customized, this function re-evaluates the saved value
465 instead.) This is useful for customizable options that are defined
466 before their value could be computed correctly, such as variables
467 defined in packages that are loaded at dump time, but depend on the
468 run-time information. For example, the value could be a file whose
469 precise name depends on the hierarchy of files when Emacs runs, or a
470 name of a program that needs to be searched at run time.
472 A good place to put calls to this function is in the function
473 @code{command-line} that is run during startup (@pxref{Startup Summary})
474 or in the various hooks it calls.
477 @node Customization Types
478 @section Customization Types
480 @cindex customization types
481 When you define a user option with @code{defcustom}, you must specify
482 its @dfn{customization type}. That is a Lisp object which describes (1)
483 which values are legitimate and (2) how to display the value in the
484 customization buffer for editing.
486 @kindex type@r{, @code{defcustom} keyword}
487 You specify the customization type in @code{defcustom} with the
488 @code{:type} keyword. The argument of @code{:type} is evaluated, but
489 only once when the @code{defcustom} is executed, so it isn't useful
490 for the value to vary. Normally we use a quoted constant. For
494 (defcustom diff-command "diff"
495 "The command to use to run diff."
500 In general, a customization type is a list whose first element is a
501 symbol, one of the customization type names defined in the following
502 sections. After this symbol come a number of arguments, depending on
503 the symbol. Between the type symbol and its arguments, you can
504 optionally write keyword-value pairs (@pxref{Type Keywords}).
506 Some type symbols do not use any arguments; those are called
507 @dfn{simple types}. For a simple type, if you do not use any
508 keyword-value pairs, you can omit the parentheses around the type
509 symbol. For example just @code{string} as a customization type is
510 equivalent to @code{(string)}.
512 All customization types are implemented as widgets; see @ref{Top, ,
513 Introduction, widget, The Emacs Widget Library}, for details.
516 * Simple Types:: Simple customization types: sexp, integer, number,
517 string, file, directory, alist.
518 * Composite Types:: Build new types from other types or data.
519 * Splicing into Lists:: Splice elements into list with @code{:inline}.
520 * Type Keywords:: Keyword-argument pairs in a customization type.
521 * Defining New Types:: Give your type a name.
525 @subsection Simple Types
527 This section describes all the simple customization types.
531 The value may be any Lisp object that can be printed and read back. You
532 can use @code{sexp} as a fall-back for any option, if you don't want to
533 take the time to work out a more specific type to use.
536 The value must be an integer, and is represented textually
537 in the customization buffer.
540 The value must be a number (floating point or integer), and is
541 represented textually in the customization buffer.
544 The value must be a floating point number, and is represented
545 textually in the customization buffer.
548 The value must be a string, and the customization buffer shows just the
549 contents, with no delimiting @samp{"} characters and no quoting with
553 Like @code{string} except that the string must be a valid regular
557 The value must be a character code. A character code is actually an
558 integer, but this type shows the value by inserting the character in the
559 buffer, rather than by showing the number.
562 The value must be a file name, and you can do completion with
565 @item (file :must-match t)
566 The value must be a file name for an existing file, and you can do
567 completion with @kbd{M-@key{TAB}}.
570 The value must be a directory name, and you can do completion with
574 The value must be a list of functions (or a single function, but that is
575 obsolete usage). This customization type is used for hook variables.
576 You can use the @code{:options} keyword in a hook variable's
577 @code{defcustom} to specify a list of functions recommended for use in
578 the hook; see @ref{Variable Definitions}.
581 The value must be a list of cons-cells, the @sc{car} of each cell
582 representing a key, and the @sc{cdr} of the same cell representing an
583 associated value. The user can add and delete key/value pairs, and
584 edit both the key and the value of each pair.
586 You can specify the key and value types like this:
589 (alist :key-type @var{key-type} :value-type @var{value-type})
593 where @var{key-type} and @var{value-type} are customization type
594 specifications. The default key type is @code{sexp}, and the default
595 value type is @code{sexp}.
597 The user can add any key matching the specified key type, but you can
598 give some keys a preferential treatment by specifying them with the
599 @code{:options} (see @ref{Variable Definitions}). The specified keys
600 will always be shown in the customize buffer (together with a suitable
601 value), with a checkbox to include or exclude or disable the key/value
602 pair from the alist. The user will not be able to edit the keys
603 specified by the @code{:options} keyword argument.
605 The argument to the @code{:options} keywords should be a list of
606 specifications for reasonable keys in the alist. Ordinarily, they are
607 simply atoms, which stand for themselves as. For example:
610 :options '("foo" "bar" "baz")
614 specifies that there are three ``known'' keys, namely @code{"foo"},
615 @code{"bar"} and @code{"baz"}, which will always be shown first.
617 You may want to restrict the value type for specific keys, for
618 example, the value associated with the @code{"bar"} key can only be an
619 integer. You can specify this by using a list instead of an atom in
620 the list. The first element will specify the key, like before, while
621 the second element will specify the value type. For example:
624 :options '("foo" ("bar" integer) "baz")
627 Finally, you may want to change how the key is presented. By default,
628 the key is simply shown as a @code{const}, since the user cannot change
629 the special keys specified with the @code{:options} keyword. However,
630 you may want to use a more specialized type for presenting the key, like
631 @code{function-item} if you know it is a symbol with a function binding.
632 This is done by using a customization type specification instead of a
636 :options '("foo" ((function-item some-function) integer)
640 Many alists use lists with two elements, instead of cons cells. For
644 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
645 "Each element is a list of the form (KEY VALUE).")
652 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
653 "Each element is a cons-cell (KEY . VALUE).")
656 Because of the way lists are implemented on top of cons cells, you can
657 treat @code{list-alist} in the example above as a cons cell alist, where
658 the value type is a list with a single element containing the real
662 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
663 "Each element is a list of the form (KEY VALUE)."
664 :type '(alist :value-type (group integer)))
667 The @code{group} widget is used here instead of @code{list} only because
668 the formatting is better suited for the purpose.
670 Similarly, you can have alists with more values associated with each
671 key, using variations of this trick:
674 (defcustom person-data '(("brian" 50 t)
677 "Alist of basic info about people.
678 Each element has the form (NAME AGE MALE-FLAG)."
679 :type '(alist :value-type (group integer boolean)))
681 (defcustom pets '(("brian")
682 ("dorith" "dog" "guppy")
684 "Alist of people's pets.
685 In an element (KEY . VALUE), KEY is the person's name,
686 and the VALUE is a list of that person's pets."
687 :type '(alist :value-type (repeat string)))
691 The @code{plist} custom type is similar to the @code{alist} (see above),
692 except that the information is stored as a property list, i.e. a list of
696 (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
699 The default @code{:key-type} for @code{plist} is @code{symbol},
700 rather than @code{sexp}.
703 The value must be a symbol. It appears in the customization buffer as
704 the name of the symbol.
707 The value must be either a lambda expression or a function name. When
708 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
711 The value must be a variable name, and you can do completion with
715 The value must be a symbol which is a face name, and you can do
716 completion with @kbd{M-@key{TAB}}.
719 The value is boolean---either @code{nil} or @code{t}. Note that by
720 using @code{choice} and @code{const} together (see the next section),
721 you can specify that the value must be @code{nil} or @code{t}, but also
722 specify the text to describe each value in a way that fits the specific
723 meaning of the alternative.
726 The value must be a coding-system name, and you can do completion with
730 The value must be a valid color name, and you can do completion with
731 @kbd{M-@key{TAB}}. A sample is provided.
734 @node Composite Types
735 @subsection Composite Types
736 @cindex composite types (customization)
738 When none of the simple types is appropriate, you can use composite
739 types, which build new types from other types or from specified data.
740 The specified types or data are called the @dfn{arguments} of the
741 composite type. The composite type normally looks like this:
744 (@var{constructor} @var{arguments}@dots{})
748 but you can also add keyword-value pairs before the arguments, like
752 (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
755 Here is a table of constructors and how to use them to write
759 @item (cons @var{car-type} @var{cdr-type})
760 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
761 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
762 symbol)} is a customization type which matches values such as
763 @code{("foo" . foo)}.
765 In the customization buffer, the @sc{car} and the @sc{cdr} are
766 displayed and edited separately, each according to the type
767 that you specify for it.
769 @item (list @var{element-types}@dots{})
770 The value must be a list with exactly as many elements as the
771 @var{element-types} given; and each element must fit the
772 corresponding @var{element-type}.
774 For example, @code{(list integer string function)} describes a list of
775 three elements; the first element must be an integer, the second a
776 string, and the third a function.
778 In the customization buffer, each element is displayed and edited
779 separately, according to the type specified for it.
781 @item (group @var{element-types}@dots{})
782 This works like @code{list} except for the formatting
783 of text in the Custom buffer. @code{list} labels each
784 element value with its tag; @code{group} does not.
786 @item (vector @var{element-types}@dots{})
787 Like @code{list} except that the value must be a vector instead of a
788 list. The elements work the same as in @code{list}.
790 @item (choice @var{alternative-types}@dots{})
791 The value must fit at least one of @var{alternative-types}.
792 For example, @code{(choice integer string)} allows either an
795 In the customization buffer, the user selects an alternative
796 using a menu, and can then edit the value in the usual way for that
799 Normally the strings in this menu are determined automatically from the
800 choices; however, you can specify different strings for the menu by
801 including the @code{:tag} keyword in the alternatives. For example, if
802 an integer stands for a number of spaces, while a string is text to use
803 verbatim, you might write the customization type this way,
806 (choice (integer :tag "Number of spaces")
807 (string :tag "Literal text"))
811 so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
813 In any alternative for which @code{nil} is not a valid value, other than
814 a @code{const}, you should specify a valid default for that alternative
815 using the @code{:value} keyword. @xref{Type Keywords}.
817 If some values are covered by more than one of the alternatives,
818 customize will choose the first alternative that the value fits. This
819 means you should always list the most specific types first, and the
820 most general last. Here's an example of proper usage:
823 (choice (const :tag "Off" nil)
824 symbol (sexp :tag "Other"))
828 This way, the special value @code{nil} is not treated like other
829 symbols, and symbols are not treated like other Lisp expressions.
831 @item (radio @var{element-types}@dots{})
832 This is similar to @code{choice}, except that the choices are displayed
833 using `radio buttons' rather than a menu. This has the advantage of
834 displaying documentation for the choices when applicable and so is often
835 a good choice for a choice between constant functions
836 (@code{function-item} customization types).
838 @item (const @var{value})
839 The value must be @var{value}---nothing else is allowed.
841 The main use of @code{const} is inside of @code{choice}. For example,
842 @code{(choice integer (const nil))} allows either an integer or
845 @code{:tag} is often used with @code{const}, inside of @code{choice}.
849 (choice (const :tag "Yes" t)
850 (const :tag "No" nil)
851 (const :tag "Ask" foo))
855 describes a variable for which @code{t} means yes, @code{nil} means no,
856 and @code{foo} means ``ask.''
858 @item (other @var{value})
859 This alternative can match any Lisp value, but if the user chooses this
860 alternative, that selects the value @var{value}.
862 The main use of @code{other} is as the last element of @code{choice}.
866 (choice (const :tag "Yes" t)
867 (const :tag "No" nil)
868 (other :tag "Ask" foo))
872 describes a variable for which @code{t} means yes, @code{nil} means no,
873 and anything else means ``ask.'' If the user chooses @samp{Ask} from
874 the menu of alternatives, that specifies the value @code{foo}; but any
875 other value (not @code{t}, @code{nil} or @code{foo}) displays as
876 @samp{Ask}, just like @code{foo}.
878 @item (function-item @var{function})
879 Like @code{const}, but used for values which are functions. This
880 displays the documentation string as well as the function name.
881 The documentation string is either the one you specify with
882 @code{:doc}, or @var{function}'s own documentation string.
884 @item (variable-item @var{variable})
885 Like @code{const}, but used for values which are variable names. This
886 displays the documentation string as well as the variable name. The
887 documentation string is either the one you specify with @code{:doc}, or
888 @var{variable}'s own documentation string.
890 @item (set @var{types}@dots{})
891 The value must be a list, and each element of the list must match one of
892 the @var{types} specified.
894 This appears in the customization buffer as a checklist, so that each of
895 @var{types} may have either one corresponding element or none. It is
896 not possible to specify two different elements that match the same one
897 of @var{types}. For example, @code{(set integer symbol)} allows one
898 integer and/or one symbol in the list; it does not allow multiple
899 integers or multiple symbols. As a result, it is rare to use
900 nonspecific types such as @code{integer} in a @code{set}.
902 Most often, the @var{types} in a @code{set} are @code{const} types, as
906 (set (const :bold) (const :italic))
909 Sometimes they describe possible elements in an alist:
912 (set (cons :tag "Height" (const height) integer)
913 (cons :tag "Width" (const width) integer))
917 That lets the user specify a height value optionally
918 and a width value optionally.
920 @item (repeat @var{element-type})
921 The value must be a list and each element of the list must fit the type
922 @var{element-type}. This appears in the customization buffer as a
923 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
924 more elements or removing elements.
926 @item (restricted-sexp :match-alternatives @var{criteria})
927 This is the most general composite type construct. The value may be
928 any Lisp object that satisfies one of @var{criteria}. @var{criteria}
929 should be a list, and each element should be one of these
934 A predicate---that is, a function of one argument that has no side
935 effects, and returns either @code{nil} or non-@code{nil} according to
936 the argument. Using a predicate in the list says that objects for which
937 the predicate returns non-@code{nil} are acceptable.
940 A quoted constant---that is, @code{'@var{object}}. This sort of element
941 in the list says that @var{object} itself is an acceptable value.
947 (restricted-sexp :match-alternatives
952 allows integers, @code{t} and @code{nil} as legitimate values.
954 The customization buffer shows all legitimate values using their read
955 syntax, and the user edits them textually.
958 Here is a table of the keywords you can use in keyword-value pairs
963 Use @var{tag} as the name of this alternative, for user communication
964 purposes. This is useful for a type that appears inside of a
967 @item :match-alternatives @var{criteria}
968 @kindex match-alternatives@r{, customization keyword}
969 Use @var{criteria} to match possible values. This is used only in
970 @code{restricted-sexp}.
972 @item :args @var{argument-list}
973 @kindex args@r{, customization keyword}
974 Use the elements of @var{argument-list} as the arguments of the type
975 construct. For instance, @code{(const :args (foo))} is equivalent to
976 @code{(const foo)}. You rarely need to write @code{:args} explicitly,
977 because normally the arguments are recognized automatically as
978 whatever follows the last keyword-value pair.
981 @node Splicing into Lists
982 @subsection Splicing into Lists
984 The @code{:inline} feature lets you splice a variable number of
985 elements into the middle of a list or vector. You use it in a
986 @code{set}, @code{choice} or @code{repeat} type which appears among the
987 element-types of a @code{list} or @code{vector}.
989 Normally, each of the element-types in a @code{list} or @code{vector}
990 describes one and only one element of the list or vector. Thus, if an
991 element-type is a @code{repeat}, that specifies a list of unspecified
992 length which appears as one element.
994 But when the element-type uses @code{:inline}, the value it matches is
995 merged directly into the containing sequence. For example, if it
996 matches a list with three elements, those become three elements of the
997 overall sequence. This is analogous to using @samp{,@@} in the backquote
1000 For example, to specify a list whose first element must be @code{baz}
1001 and whose remaining arguments should be zero or more of @code{foo} and
1002 @code{bar}, use this customization type:
1005 (list (const baz) (set :inline t (const foo) (const bar)))
1009 This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
1010 and @code{(baz foo bar)}.
1012 When the element-type is a @code{choice}, you use @code{:inline} not
1013 in the @code{choice} itself, but in (some of) the alternatives of the
1014 @code{choice}. For example, to match a list which must start with a
1015 file name, followed either by the symbol @code{t} or two strings, use
1016 this customization type:
1021 (list :inline t string string)))
1025 If the user chooses the first alternative in the choice, then the
1026 overall list has two elements and the second element is @code{t}. If
1027 the user chooses the second alternative, then the overall list has three
1028 elements and the second and third must be strings.
1031 @subsection Type Keywords
1033 You can specify keyword-argument pairs in a customization type after the
1034 type name symbol. Here are the keywords you can use, and their
1038 @item :value @var{default}
1039 Provide a default value.
1041 If @code{nil} is not a valid value for the alternative, then it is
1042 essential to specify a valid default with @code{:value}.
1044 If you use this for a type that appears as an alternative inside of
1045 @code{choice}; it specifies the default value to use, at first, if and
1046 when the user selects this alternative with the menu in the
1047 customization buffer.
1049 Of course, if the actual value of the option fits this alternative, it
1050 will appear showing the actual value, not @var{default}.
1052 @item :format @var{format-string}
1053 @kindex format@r{, customization keyword}
1054 This string will be inserted in the buffer to represent the value
1055 corresponding to the type. The following @samp{%} escapes are available
1056 for use in @var{format-string}:
1059 @item %[@var{button}%]
1060 Display the text @var{button} marked as a button. The @code{:action}
1061 attribute specifies what the button will do if the user invokes it;
1062 its value is a function which takes two arguments---the widget which
1063 the button appears in, and the event.
1065 There is no way to specify two different buttons with different
1068 @item %@{@var{sample}%@}
1069 Show @var{sample} in a special face specified by @code{:sample-face}.
1072 Substitute the item's value. How the value is represented depends on
1073 the kind of item, and (for variables) on the customization type.
1076 Substitute the item's documentation string.
1079 Like @samp{%d}, but if the documentation string is more than one line,
1080 add an active field to control whether to show all of it or just the
1084 Substitute the tag here. You specify the tag with the @code{:tag}
1088 Display a literal @samp{%}.
1091 @item :action @var{action}
1092 @kindex action@r{, customization keyword}
1093 Perform @var{action} if the user clicks on a button.
1095 @item :button-face @var{face}
1096 @kindex button-face@r{, customization keyword}
1097 Use the face @var{face} (a face name or a list of face names) for button
1098 text displayed with @samp{%[@dots{}%]}.
1100 @item :button-prefix @var{prefix}
1101 @itemx :button-suffix @var{suffix}
1102 @kindex button-prefix@r{, customization keyword}
1103 @kindex button-suffix@r{, customization keyword}
1104 These specify the text to display before and after a button.
1109 No text is inserted.
1112 The string is inserted literally.
1115 The symbol's value is used.
1118 @item :tag @var{tag}
1119 Use @var{tag} (a string) as the tag for the value (or part of the value)
1120 that corresponds to this type.
1122 @item :doc @var{doc}
1123 @kindex doc@r{, customization keyword}
1124 Use @var{doc} as the documentation string for this value (or part of the
1125 value) that corresponds to this type. In order for this to work, you
1126 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
1129 The usual reason to specify a documentation string for a type is to
1130 provide more information about the meanings of alternatives inside a
1131 @code{:choice} type or the parts of some other composite type.
1133 @item :help-echo @var{motion-doc}
1134 @kindex help-echo@r{, customization keyword}
1135 When you move to this item with @code{widget-forward} or
1136 @code{widget-backward}, it will display the string @var{motion-doc} in
1137 the echo area. In addition, @var{motion-doc} is used as the mouse
1138 @code{help-echo} string and may actually be a function or form evaluated
1139 to yield a help string. If it is a function, it is called with one
1140 argument, the widget.
1142 @item :match @var{function}
1143 @kindex match@r{, customization keyword}
1144 Specify how to decide whether a value matches the type. The
1145 corresponding value, @var{function}, should be a function that accepts
1146 two arguments, a widget and a value; it should return non-@code{nil} if
1147 the value is acceptable.
1149 @item :validate @var{function}
1150 Specify a validation function for input. @var{function} takes a
1151 widget as an argument, and should return @code{nil} if the widget's
1152 current value is valid for the widget. Otherwise, it should return
1153 the widget containing the invalid data, and set that widget's
1154 @code{:error} property to a string explaining the error.
1157 @item :indent @var{columns}
1158 Indent this item by @var{columns} columns. The indentation is used for
1159 @samp{%n}, and automatically for group names, for checklists and radio
1160 buttons, and for editable lists. It affects the whole of the
1161 item except for the first line.
1163 @item :offset @var{extra}
1164 Indent the subitems of this item @var{extra} columns more than this
1165 item itself. By default, subitems are indented the same as their
1168 @item :extra-offset @var{n}
1169 Add @var{n} extra spaces to this item's indentation, compared to its
1170 parent's indentation.
1172 @item :notify @var{function}
1173 Call @var{function} each time the item or a subitem is changed. The
1174 function gets two or three arguments. The first argument is the item
1175 itself, the second argument is the item that was changed, and the
1176 third argument is the event leading to the change, if any.
1178 @item :menu-tag @var{tag-string}
1179 Use @var{tag-string} in the menu when the widget is used as an option
1180 in a @code{menu-choice} widget.
1183 A function used for finding the tag when the widget is used as an option
1184 in a @code{menu-choice} widget. By default, the tag used will be either the
1185 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
1186 representation of the @code{:value} property if not.
1189 Specify the order in which widgets are traversed with
1190 @code{widget-forward} or @code{widget-backward}. This is only partially
1195 Widgets with tabbing order @code{-1} are ignored.
1198 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
1199 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
1200 whichever comes first.
1203 When on a widget with no tabbing order specified, go to the next widget
1204 in the buffer with a positive tabbing order, or @code{nil}
1208 The parent of a nested widget (e.g., a @code{menu-choice} item or an
1209 element of a @code{editable-list} widget).
1212 This keyword is only used for members of a @code{radio-button-choice} or
1213 @code{checklist}. The value should be a list of extra keyword
1214 arguments, which will be used when creating the @code{radio-button} or
1215 @code{checkbox} associated with this item.
1219 @node Defining New Types
1220 @subsection Defining New Types
1222 In the previous sections we have described how to construct elaborate
1223 type specifications for @code{defcustom}. In some cases you may want
1224 to give such a type specification a name. The obvious case is when
1225 you are using the same type for many user options: rather than repeat
1226 the specification for each option, you can give the type specification
1227 a name, and use that name each @code{defcustom}. The other case is
1228 when a user option's value is a recursive data structure. To make it
1229 possible for a datatype to refer to itself, it needs to have a name.
1231 Since custom types are implemented as widgets, the way to define a new
1232 customize type is to define a new widget. We are not going to describe
1233 the widget interface here in details, see @ref{Top, , Introduction,
1234 widget, The Emacs Widget Library}, for that. Instead we are going to
1235 demonstrate the minimal functionality needed for defining new customize
1236 types by a simple example.
1239 (define-widget 'binary-tree-of-string 'lazy
1240 "A binary tree made of cons-cells and strings."
1243 :type '(choice (string :tag "Leaf" :value "")
1244 (cons :tag "Interior"
1246 binary-tree-of-string
1247 binary-tree-of-string)))
1249 (defcustom foo-bar ""
1250 "Sample variable holding a binary tree of strings."
1251 :type 'binary-tree-of-string)
1254 The function to define a new widget is called @code{define-widget}. The
1255 first argument is the symbol we want to make a new widget type. The
1256 second argument is a symbol representing an existing widget, the new
1257 widget is going to be defined in terms of difference from the existing
1258 widget. For the purpose of defining new customization types, the
1259 @code{lazy} widget is perfect, because it accepts a @code{:type} keyword
1260 argument with the same syntax as the keyword argument to
1261 @code{defcustom} with the same name. The third argument is a
1262 documentation string for the new widget. You will be able to see that
1263 string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
1266 After these mandatory arguments follow the keyword arguments. The most
1267 important is @code{:type}, which describes the data type we want to match
1268 with this widget. Here a @code{binary-tree-of-string} is described as
1269 being either a string, or a cons-cell whose car and cdr are themselves
1270 both @code{binary-tree-of-string}. Note the reference to the widget
1271 type we are currently in the process of defining. The @code{:tag}
1272 attribute is a string to name the widget in the user interface, and the
1273 @code{:offset} argument is there to ensure that child nodes are
1274 indented four spaces relative to the parent node, making the tree
1275 structure apparent in the customization buffer.
1277 The @code{defcustom} shows how the new widget can be used as an ordinary
1280 The reason for the name @code{lazy} is that the other composite
1281 widgets convert their inferior widgets to internal form when the
1282 widget is instantiated in a buffer. This conversion is recursive, so
1283 the inferior widgets will convert @emph{their} inferior widgets. If
1284 the data structure is itself recursive, this conversion is an infinite
1285 recursion. The @code{lazy} widget prevents the recursion: it convert
1286 its @code{:type} argument only when needed.