Update Customization chapter of Lisp manual.
[emacs.git] / doc / lispref / customize.texi
blob4c3adee0db5c2e30b2a94a8f11b19451f95a4862
1 @c -*-texinfo-*-
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}).
15 @menu
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.
21 @end menu
23 @node Common Keywords
24 @section Common Item Keywords
26 @cindex customization keywords
27   The customization declarations that we will describe in the next few
28 sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword
29 arguments for specifying various information.  This section describes
30 keywords that apply to all types of customization declarations.
32   All of these keywords, except @code{:tag}, can be used more than once
33 in a given item.  Each use of the keyword has an independent effect.
34 The keyword @code{:tag} is an exception because any given item can only
35 display one name.
37 @table @code
38 @item :tag @var{label}
39 @kindex tag@r{, customization keyword}
40 Use @var{label}, a string, instead of the item's name, to label the
41 item in customization menus and buffers.  @strong{Don't use a tag
42 which is substantially different from the item's real name; that would
43 cause confusion.}
45 @kindex group@r{, customization keyword}
46 @item :group @var{group}
47 Put this customization item in group @var{group}.  When you use
48 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
49 @var{group}.
51 If you use this keyword more than once, you can put a single item into
52 more than one group.  Displaying any of those groups will show this
53 item.  Please don't overdo this, since the result would be annoying.
55 @item :link @var{link-data}
56 @kindex link@r{, customization keyword}
57 Include an external link after the documentation string for this item.
58 This is a sentence containing an active field which references some
59 other documentation.
61 There are several alternatives you can use for @var{link-data}:
63 @table @code
64 @item (custom-manual @var{info-node})
65 Link to an Info node; @var{info-node} is a string which specifies the
66 node name, as in @code{"(emacs)Top"}.  The link appears as
67 @samp{[Manual]} in the customization buffer and enters the built-in
68 Info reader on @var{info-node}.
70 @item (info-link @var{info-node})
71 Like @code{custom-manual} except that the link appears
72 in the customization buffer with the Info node name.
74 @item (url-link @var{url})
75 Link to a web page; @var{url} is a string which specifies the
76 @acronym{URL}.  The link appears in the customization buffer as
77 @var{url} and invokes the WWW browser specified by
78 @code{browse-url-browser-function}.
80 @item (emacs-commentary-link @var{library})
81 Link to the commentary section of a library; @var{library} is a string
82 which specifies the library name.
84 @item (emacs-library-link @var{library})
85 Link to an Emacs Lisp library file; @var{library} is a string which
86 specifies the library name.
88 @item (file-link @var{file})
89 Link to a file; @var{file} is a string which specifies the name of the
90 file to visit with @code{find-file} when the user invokes this link.
92 @item (function-link @var{function})
93 Link to the documentation of a function; @var{function} is a string
94 which specifies the name of the function to describe with
95 @code{describe-function} when the user invokes this link.
97 @item (variable-link @var{variable})
98 Link to the documentation of a variable; @var{variable} is a string
99 which specifies the name of the variable to describe with
100 @code{describe-variable} when the user invokes this link.
102 @item (custom-group-link @var{group})
103 Link to another customization group.  Invoking it creates a new
104 customization buffer for @var{group}.
105 @end table
107 You can specify the text to use in the customization buffer by adding
108 @code{:tag @var{name}} after the first element of the @var{link-data};
109 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
110 the Emacs manual which appears in the buffer as @samp{foo}.
112 You can use this keyword more than once, to add multiple links.
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.  This keyword takes priority over
140 @code{:version}.
142 @var{package} should be the official name of the package, as a symbol
143 (e.g.@: @code{MH-E}).  @var{version} should be a string.  If the
144 package @var{package} is released as part of Emacs, @var{package} and
145 @var{version} should appear in the value of
146 @code{customize-package-emacs-version-alist}.
147 @end table
149 Packages distributed as part of Emacs that use the
150 @code{:package-version} keyword must also update the
151 @code{customize-package-emacs-version-alist} variable.
153 @defvar customize-package-emacs-version-alist
154 This alist provides a mapping for the versions of Emacs that are
155 associated with versions of a package listed in the
156 @code{:package-version} keyword.  Its elements look like this:
158 @example
159 (@var{package} (@var{pversion} . @var{eversion})@dots{})
160 @end example
162 For each @var{package}, which is a symbol, there are one or more
163 elements that contain a package version @var{pversion} with an
164 associated Emacs version @var{eversion}.  These versions are strings.
165 For example, the MH-E package updates this alist with the following:
167 @smallexample
168 (add-to-list 'customize-package-emacs-version-alist
169              '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
170                     ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
171                     ("7.4" . "22.1") ("8.0" . "22.1")))
172 @end smallexample
174 The value of @var{package} needs to be unique and it needs to match
175 the @var{package} value appearing in the @code{:package-version}
176 keyword.  Since the user might see the value in an error message, a good
177 choice is the official name of the package, such as MH-E or Gnus.
178 @end defvar
180 @node Group Definitions
181 @section Defining Customization Groups
182 @cindex define customization group
183 @cindex customization groups, defining
185   Each Emacs Lisp package should have one main customization group which
186 contains all the options, faces and other groups in the package.  If the
187 package has a small number of options and faces, use just one group and
188 put everything in it.  When there are more than twelve or so options and
189 faces, then you should structure them into subgroups, and put the
190 subgroups under the package's main customization group.  It is OK to
191 put some of the options and faces in the package's main group alongside
192 the subgroups.
194   The package's main or only group should be a member of one or more of
195 the standard customization groups.  (To display the full list of them,
196 use @kbd{M-x customize}.)  Choose one or more of them (but not too
197 many), and add your group to each of them using the @code{:group}
198 keyword.
200   The way to declare new customization groups is with @code{defgroup}.
202 @defmac defgroup group members doc [keyword value]@dots{}
203 Declare @var{group} as a customization group containing @var{members}.
204 Do not quote the symbol @var{group}.  The argument @var{doc} specifies
205 the documentation string for the group.
207 The argument @var{members} is a list specifying an initial set of
208 customization items to be members of the group.  However, most often
209 @var{members} is @code{nil}, and you specify the group's members by
210 using the @code{:group} keyword when defining those members.
212 If you want to specify group members through @var{members}, each element
213 should have the form @code{(@var{name} @var{widget})}.  Here @var{name}
214 is a symbol, and @var{widget} is a widget type for editing that symbol.
215 Useful widgets are @code{custom-variable} for a variable,
216 @code{custom-face} for a face, and @code{custom-group} for a group.
218 When you introduce a new group into Emacs, use the @code{:version}
219 keyword in the @code{defgroup}; then you need not use it for
220 the individual members of the group.
222 In addition to the common keywords (@pxref{Common Keywords}), you can
223 also use this keyword in @code{defgroup}:
225 @table @code
226 @item :prefix @var{prefix}
227 @kindex prefix@r{, @code{defgroup} keyword}
228 If the name of an item in the group starts with @var{prefix}, and the
229 customizable variable @code{custom-unlispify-remove-prefixes} is
230 non-@code{nil}, the item's tag will omit @var{prefix}.  A group can
231 have any number of prefixes.
232 @end table
233 @end defmac
235 @defopt custom-unlispify-remove-prefixes
236 If this variable is non-@code{nil}, the prefixes specified by a
237 group's @code{:prefix} keyword are omitted from tag names, whenever
238 the user customizes the group.
240 The default value is @code{nil}, i.e.@: the prefix-discarding feature
241 is disabled.  This is because discarding prefixes often leads to
242 confusing names for options and faces.
243 @end defopt
245 @node Variable Definitions
246 @section Defining Customization Variables
247 @cindex define customization options
248 @cindex customization variables, how to define
250 @defmac defcustom option standard doc [keyword value]@dots{}
251 This macro declares @var{option} as a user option (i.e.@: a
252 customizable variable).  You should not quote @var{option}.
254 The argument @var{standard} is an expression that specifies the
255 standard value for @var{option}.  Evaluating the @code{defcustom} form
256 evaluates @var{standard}, but does not necessarily install the
257 standard value.  If @var{option} already has a default value,
258 @code{defcustom} does not change it.  If the user has saved a
259 customization for @var{option}, @code{defcustom} installs the user's
260 customized value as @var{option}'s default value.  If neither of those
261 cases applies, @code{defcustom} installs the result of evaluating
262 @var{standard} as the default value.
264 The expression @var{standard} can be evaluated at various other times,
265 too---whenever the customization facility needs to know @var{option}'s
266 standard value.  So be sure to use an expression which is harmless to
267 evaluate at any time.
269 The argument @var{doc} specifies the documentation string for the
270 variable.
272 Every @code{defcustom} should specify @code{:group} at least once.
274 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
275 mode (@code{eval-defun}), a special feature of @code{eval-defun}
276 arranges to set the variable unconditionally, without testing whether
277 its value is void.  (The same feature applies to @code{defvar}.)
278 @xref{Defining Variables}.
280 If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
281 (@pxref{Building Emacs}), the standard value installed at dump time
282 might be incorrect, e.g.@: because another variable that it depends on
283 has not been assigned the right value yet.  In that case, use
284 @code{custom-reevaluate-setting}, described below, to re-evaluate the
285 standard value after Emacs starts up.
286 @end defmac
288   @code{defcustom} accepts the following additional keywords:
290 @table @code
291 @item :type @var{type}
292 Use @var{type} as the data type for this option.  It specifies which
293 values are legitimate, and how to display the value.
294 @xref{Customization Types}, for more information.
296 @item :options @var{value-list}
297 @kindex options@r{, @code{defcustom} keyword}
298 Specify the list of reasonable values for use in this
299 option.  The user is not restricted to using only these values, but they
300 are offered as convenient alternatives.
302 This is meaningful only for certain types, currently including
303 @code{hook}, @code{plist} and @code{alist}.  See the definition of the
304 individual types for a description of how to use @code{:options}.
306 @item :set @var{setfunction}
307 @kindex set@r{, @code{defcustom} keyword}
308 Specify @var{setfunction} as the way to change the value of this
309 option when using the Customize user interface.  The function
310 @var{setfunction} should take two arguments, a symbol (the option
311 name) and the new value, and should do whatever is necessary to update
312 the value properly for this option (which may not mean simply setting
313 the option as a Lisp variable).  The default for @var{setfunction} is
314 @code{set-default}.
316 If you specify this keyword, the variable's documentation string
317 should describe how to do the same job in hand-written Lisp code.
319 @item :get @var{getfunction}
320 @kindex get@r{, @code{defcustom} keyword}
321 Specify @var{getfunction} as the way to extract the value of this
322 option.  The function @var{getfunction} should take one argument, a
323 symbol, and should return whatever customize should use as the
324 ``current value'' for that symbol (which need not be the symbol's Lisp
325 value).  The default is @code{default-value}.
327 You have to really understand the workings of Custom to use
328 @code{:get} correctly.  It is meant for values that are treated in
329 Custom as variables but are not actually stored in Lisp variables.  It
330 is almost surely a mistake to specify @var{getfunction} for a value
331 that really is stored in a Lisp variable.
333 @item :initialize @var{function}
334 @kindex initialize@r{, @code{defcustom} keyword}
335 @var{function} should be a function used to initialize the variable
336 when the @code{defcustom} is evaluated.  It should take two arguments,
337 the option name (a symbol) and the value.  Here are some predefined
338 functions meant for use in this way:
340 @table @code
341 @item custom-initialize-set
342 Use the variable's @code{:set} function to initialize the variable, but
343 do not reinitialize it if it is already non-void.
345 @item custom-initialize-default
346 Like @code{custom-initialize-set}, but use the function
347 @code{set-default} to set the variable, instead of the variable's
348 @code{:set} function.  This is the usual choice for a variable whose
349 @code{:set} function enables or disables a minor mode; with this choice,
350 defining the variable will not call the minor mode function, but
351 customizing the variable will do so.
353 @item custom-initialize-reset
354 Always use the @code{:set} function to initialize the variable.  If
355 the variable is already non-void, reset it by calling the @code{:set}
356 function using the current value (returned by the @code{:get} method).
357 This is the default @code{:initialize} function.
359 @item custom-initialize-changed
360 Use the @code{:set} function to initialize the variable, if it is
361 already set or has been customized; otherwise, just use
362 @code{set-default}.
364 @item custom-initialize-safe-set
365 @itemx custom-initialize-safe-default
366 These functions behave like @code{custom-initialize-set}
367 (@code{custom-initialize-default}, respectively), but catch errors.
368 If an error occurs during initialization, they set the variable to
369 @code{nil} using @code{set-default}, and signal no error.
371 These functions are meant for options defined in pre-loaded files,
372 where the @var{standard} expression may signal an error because some
373 required variable or function is not yet defined.  The value normally
374 gets updated in @file{startup.el}, ignoring the value computed by
375 @code{defcustom}.  After startup, if one unsets the value and
376 reevaluates the @code{defcustom}, the @var{standard} expression can be
377 evaluated without error.
378 @end table
380 @item :risky @var{value}
381 @kindex risky@r{, @code{defcustom} keyword}
382 Set the variable's @code{risky-local-variable} property to
383 @var{value} (@pxref{File Local Variables}).
385 @item :safe @var{function}
386 @kindex safe@r{, @code{defcustom} keyword}
387 Set the variable's @code{safe-local-variable} property to
388 @var{function} (@pxref{File Local Variables}).
390 @item :set-after @var{variables}
391 @kindex set-after@r{, @code{defcustom} keyword}
392 When setting variables according to saved customizations, make sure to
393 set the variables @var{variables} before this one; in other words, delay
394 setting this variable until after those others have been handled.  Use
395 @code{:set-after} if setting this variable won't work properly unless
396 those other variables already have their intended values.
397 @end table
399   It is useful to specify the @code{:require} keyword for an option
400 that ``turns on'' a certain feature.  This causes Emacs to load the
401 feature, if it is not already loaded, whenever the option is set.
402 @xref{Common Keywords}.  Here is an example, from the library
403 @file{saveplace.el}:
405 @example
406 (defcustom save-place nil
407   "Non-nil means automatically save place in each file..."
408   :type 'boolean
409   :require 'saveplace
410   :group 'save-place)
411 @end example
413 If a customization item has a type such as @code{hook} or
414 @code{alist}, which supports @code{:options}, you can add additional
415 values to the list from outside the @code{defcustom} declaration by
416 calling @code{custom-add-frequent-value}.  For example, if you define a
417 function @code{my-lisp-mode-initialization} intended to be called from
418 @code{emacs-lisp-mode-hook}, you might want to add that to the list of
419 reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
420 its definition.  You can do it thus:
422 @example
423 (custom-add-frequent-value 'emacs-lisp-mode-hook
424    'my-lisp-mode-initialization)
425 @end example
427 @defun custom-add-frequent-value symbol value
428 For the customization option @var{symbol}, add @var{value} to the
429 list of reasonable values.
431 The precise effect of adding a value depends on the customization type
432 of @var{symbol}.
433 @end defun
435 Internally, @code{defcustom} uses the symbol property
436 @code{standard-value} to record the expression for the standard value,
437 @code{saved-value} to record the value saved by the user with the
438 customization buffer, and @code{customized-value} to record the value
439 set by the user with the customization buffer, but not saved.
440 @xref{Property Lists}.  These properties are lists, the car of which
441 is an expression that evaluates to the value.
443 @defun custom-reevaluate-setting symbol
444 This function re-evaluates the standard value of @var{symbol}, which
445 should be a user option declared via @code{defcustom}.  If the
446 variable was customized, this function re-evaluates the saved value
447 instead.  Then it sets the user option to that value (using the
448 option's @code{:set} property if that is defined).
450 This is useful for customizable options that are defined before their
451 value could be computed correctly.  For example, during startup Emacs
452 calls this function for some user options that were defined in
453 pre-loaded Emacs Lisp files, but whose initial values depend on
454 information available only at run-time.
455 @end defun
457 @defun custom-variable-p arg
458 This function returns non-@code{nil} if @var{arg} is a customizable
459 variable.  A customizable variable is either a variable that has a
460 @code{standard-value} or @code{custom-autoload} property (usually
461 meaning it was declared with @code{defcustom}), or an alias for
462 another customizable variable.
463 @end defun
465 @defun user-variable-p arg
466 This function is like @code{custom-variable-p}, except it also returns
467 @code{t} if the first character of the variable's documentation string
468 is the character @samp{*}.  That is an obsolete way of indicating a
469 user option, so for most purposes you may consider
470 @code{user-variable-p} as equivalent to @code{custom-variable-p}.
471 @end defun
473 @node Customization Types
474 @section Customization Types
476 @cindex customization types
477   When you define a user option with @code{defcustom}, you must specify
478 its @dfn{customization type}.  That is a Lisp object which describes (1)
479 which values are legitimate and (2) how to display the value in the
480 customization buffer for editing.
482 @kindex type@r{, @code{defcustom} keyword}
483   You specify the customization type in @code{defcustom} with the
484 @code{:type} keyword.  The argument of @code{:type} is evaluated, but
485 only once when the @code{defcustom} is executed, so it isn't useful
486 for the value to vary.  Normally we use a quoted constant.  For
487 example:
489 @example
490 (defcustom diff-command "diff"
491   "The command to use to run diff."
492   :type '(string)
493   :group 'diff)
494 @end example
496   In general, a customization type is a list whose first element is a
497 symbol, one of the customization type names defined in the following
498 sections.  After this symbol come a number of arguments, depending on
499 the symbol.  Between the type symbol and its arguments, you can
500 optionally write keyword-value pairs (@pxref{Type Keywords}).
502   Some type symbols do not use any arguments; those are called
503 @dfn{simple types}.  For a simple type, if you do not use any
504 keyword-value pairs, you can omit the parentheses around the type
505 symbol.  For example just @code{string} as a customization type is
506 equivalent to @code{(string)}.
508   All customization types are implemented as widgets; see @ref{Top, ,
509 Introduction, widget, The Emacs Widget Library}, for details.
511 @menu
512 * Simple Types::            Simple customization types: sexp, integer, etc.
513 * Composite Types::         Build new types from other types or data.
514 * Splicing into Lists::     Splice elements into list with @code{:inline}.
515 * Type Keywords::           Keyword-argument pairs in a customization type.
516 * Defining New Types::      Give your type a name.
517 @end menu
519 @node Simple Types
520 @subsection Simple Types
522   This section describes all the simple customization types.  For
523 several of these customization types, the customization widget
524 provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}.
526 @table @code
527 @item sexp
528 The value may be any Lisp object that can be printed and read back.
529 You can use @code{sexp} as a fall-back for any option, if you don't
530 want to take the time to work out a more specific type to use.
532 @item integer
533 The value must be an integer.
535 @item number
536 The value must be a number (floating point or integer).
538 @item float
539 The value must be a floating point number.
541 @item string
542 The value must be a string.  The customization buffer shows the string
543 without delimiting @samp{"} characters or @samp{\} quotes.
545 @item regexp
546 Like @code{string} except that the string must be a valid regular
547 expression.
549 @item character
550 The value must be a character code.  A character code is actually an
551 integer, but this type shows the value by inserting the character in the
552 buffer, rather than by showing the number.
554 @item file
555 The value must be a file name.  The widget provides completion.
557 @item (file :must-match t)
558 The value must be a file name for an existing file.  The widget
559 provides completion.
561 @item directory
562 The value must be a directory name.  The widget provides completion.
564 @item hook
565 The value must be a list of functions.  This customization type is
566 used for hook variables.  You can use the @code{:options} keyword in a
567 hook variable's @code{defcustom} to specify a list of functions
568 recommended for use in the hook; @xref{Variable Definitions}.
570 @item symbol
571 The value must be a symbol.  It appears in the customization buffer as
572 the symbol name.  The widget provides completion.
574 @item function
575 The value must be either a lambda expression or a function name.  The
576 widget provides completion for function names.
578 @item variable
579 The value must be a variable name.  The widget provides completion.
581 @item face
582 The value must be a symbol which is a face name.  The widget provides
583 completion.
585 @item boolean
586 The value is boolean---either @code{nil} or @code{t}.  Note that by
587 using @code{choice} and @code{const} together (see the next section),
588 you can specify that the value must be @code{nil} or @code{t}, but also
589 specify the text to describe each value in a way that fits the specific
590 meaning of the alternative.
592 @item coding-system
593 The value must be a coding-system name, and you can do completion with
594 @kbd{M-@key{TAB}}.
596 @item color
597 The value must be a valid color name.  The widget provides completion
598 for color names, as well as a sample and a button for selecting a
599 color name from a list of color names shown in a @samp{*Colors*}
600 buffer.
601 @end table
603 @node Composite Types
604 @subsection Composite Types
605 @cindex composite types (customization)
607   When none of the simple types is appropriate, you can use composite
608 types, which build new types from other types or from specified data.
609 The specified types or data are called the @dfn{arguments} of the
610 composite type.  The composite type normally looks like this:
612 @example
613 (@var{constructor} @var{arguments}@dots{})
614 @end example
616 @noindent
617 but you can also add keyword-value pairs before the arguments, like
618 this:
620 @example
621 (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
622 @end example
624   Here is a table of constructors and how to use them to write
625 composite types:
627 @table @code
628 @item (cons @var{car-type} @var{cdr-type})
629 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
630 its @sc{cdr} must fit @var{cdr-type}.  For example, @code{(cons string
631 symbol)} is a customization type which matches values such as
632 @code{("foo" . foo)}.
634 In the customization buffer, the @sc{car} and @sc{cdr} are displayed
635 and edited separately, each according to their specified type.
637 @item (list @var{element-types}@dots{})
638 The value must be a list with exactly as many elements as the
639 @var{element-types} given; and each element must fit the
640 corresponding @var{element-type}.
642 For example, @code{(list integer string function)} describes a list of
643 three elements; the first element must be an integer, the second a
644 string, and the third a function.
646 In the customization buffer, each element is displayed and edited
647 separately, according to the type specified for it.
649 @item (group @var{element-types}@dots{})
650 This works like @code{list} except for the formatting
651 of text in the Custom buffer.  @code{list} labels each
652 element value with its tag; @code{group} does not.
654 @item (vector @var{element-types}@dots{})
655 Like @code{list} except that the value must be a vector instead of a
656 list.  The elements work the same as in @code{list}.
658 @item (alist :key-type @var{key-type} :value-type @var{value-type})
659 The value must be a list of cons-cells, the @sc{car} of each cell
660 representing a key of customization type @var{key-type}, and the
661 @sc{cdr} of the same cell representing a value of customization type
662 @var{value-type}.  The user can add and delete key/value pairs, and
663 edit both the key and the value of each pair.
665 If omitted, @var{key-type} and @var{value-type} default to
666 @code{sexp}.
668 The user can add any key matching the specified key type, but you can
669 give some keys a preferential treatment by specifying them with the
670 @code{:options} (see @ref{Variable Definitions}).  The specified keys
671 will always be shown in the customize buffer (together with a suitable
672 value), with a checkbox to include or exclude or disable the key/value
673 pair from the alist.  The user will not be able to edit the keys
674 specified by the @code{:options} keyword argument.
676 The argument to the @code{:options} keywords should be a list of
677 specifications for reasonable keys in the alist.  Ordinarily, they are
678 simply atoms, which stand for themselves.  For example:
680 @smallexample
681 :options '("foo" "bar" "baz")
682 @end smallexample
684 @noindent
685 specifies that there are three ``known'' keys, namely @code{"foo"},
686 @code{"bar"} and @code{"baz"}, which will always be shown first.
688 You may want to restrict the value type for specific keys, for
689 example, the value associated with the @code{"bar"} key can only be an
690 integer.  You can specify this by using a list instead of an atom in
691 the list.  The first element will specify the key, like before, while
692 the second element will specify the value type.  For example:
694 @smallexample
695 :options '("foo" ("bar" integer) "baz")
696 @end smallexample
698 Finally, you may want to change how the key is presented.  By default,
699 the key is simply shown as a @code{const}, since the user cannot change
700 the special keys specified with the @code{:options} keyword.  However,
701 you may want to use a more specialized type for presenting the key, like
702 @code{function-item} if you know it is a symbol with a function binding.
703 This is done by using a customization type specification instead of a
704 symbol for the key.
706 @smallexample
707 :options '("foo" ((function-item some-function) integer)
708            "baz")
709 @end smallexample
711 Many alists use lists with two elements, instead of cons cells.  For
712 example,
714 @smallexample
715 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
716   "Each element is a list of the form (KEY VALUE).")
717 @end smallexample
719 @noindent
720 instead of
722 @smallexample
723 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
724   "Each element is a cons-cell (KEY . VALUE).")
725 @end smallexample
727 Because of the way lists are implemented on top of cons cells, you can
728 treat @code{list-alist} in the example above as a cons cell alist, where
729 the value type is a list with a single element containing the real
730 value.
732 @smallexample
733 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
734   "Each element is a list of the form (KEY VALUE)."
735   :type '(alist :value-type (group integer)))
736 @end smallexample
738 The @code{group} widget is used here instead of @code{list} only because
739 the formatting is better suited for the purpose.
741 Similarly, you can have alists with more values associated with each
742 key, using variations of this trick:
744 @smallexample
745 (defcustom person-data '(("brian"  50 t)
746                          ("dorith" 55 nil)
747                          ("ken"    52 t))
748   "Alist of basic info about people.
749 Each element has the form (NAME AGE MALE-FLAG)."
750   :type '(alist :value-type (group integer boolean)))
751 @end smallexample
753 @item (plist :key-type @var{key-type} :value-type @var{value-type})
754 This customization type is similar to @code{alist} (see above), except
755 that (i) the information is stored as a property list,
756 (@pxref{Property Lists}), and (ii) @var{key-type}, if omitted,
757 defaults to @code{symbol} rather than @code{sexp}.
759 @item (choice @var{alternative-types}@dots{})
760 The value must fit one of @var{alternative-types}.  For example,
761 @code{(choice integer string)} allows either an integer or a string.
763 In the customization buffer, the user selects an alternative
764 using a menu, and can then edit the value in the usual way for that
765 alternative.
767 Normally the strings in this menu are determined automatically from the
768 choices; however, you can specify different strings for the menu by
769 including the @code{:tag} keyword in the alternatives.  For example, if
770 an integer stands for a number of spaces, while a string is text to use
771 verbatim, you might write the customization type this way,
773 @example
774 (choice (integer :tag "Number of spaces")
775         (string :tag "Literal text"))
776 @end example
778 @noindent
779 so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
781 In any alternative for which @code{nil} is not a valid value, other than
782 a @code{const}, you should specify a valid default for that alternative
783 using the @code{:value} keyword.  @xref{Type Keywords}.
785 If some values are covered by more than one of the alternatives,
786 customize will choose the first alternative that the value fits.  This
787 means you should always list the most specific types first, and the
788 most general last.  Here's an example of proper usage:
790 @example
791 (choice (const :tag "Off" nil)
792         symbol (sexp :tag "Other"))
793 @end example
795 @noindent
796 This way, the special value @code{nil} is not treated like other
797 symbols, and symbols are not treated like other Lisp expressions.
799 @item (radio @var{element-types}@dots{})
800 This is similar to @code{choice}, except that the choices are displayed
801 using `radio buttons' rather than a menu.  This has the advantage of
802 displaying documentation for the choices when applicable and so is often
803 a good choice for a choice between constant functions
804 (@code{function-item} customization types).
806 @item (const @var{value})
807 The value must be @var{value}---nothing else is allowed.
809 The main use of @code{const} is inside of @code{choice}.  For example,
810 @code{(choice integer (const nil))} allows either an integer or
811 @code{nil}.
813 @code{:tag} is often used with @code{const}, inside of @code{choice}.
814 For example,
816 @example
817 (choice (const :tag "Yes" t)
818         (const :tag "No" nil)
819         (const :tag "Ask" foo))
820 @end example
822 @noindent
823 describes a variable for which @code{t} means yes, @code{nil} means no,
824 and @code{foo} means ``ask.''
826 @item (other @var{value})
827 This alternative can match any Lisp value, but if the user chooses this
828 alternative, that selects the value @var{value}.
830 The main use of @code{other} is as the last element of @code{choice}.
831 For example,
833 @example
834 (choice (const :tag "Yes" t)
835         (const :tag "No" nil)
836         (other :tag "Ask" foo))
837 @end example
839 @noindent
840 describes a variable for which @code{t} means yes, @code{nil} means no,
841 and anything else means ``ask.''  If the user chooses @samp{Ask} from
842 the menu of alternatives, that specifies the value @code{foo}; but any
843 other value (not @code{t}, @code{nil} or @code{foo}) displays as
844 @samp{Ask}, just like @code{foo}.
846 @item (function-item @var{function})
847 Like @code{const}, but used for values which are functions.  This
848 displays the documentation string as well as the function name.
849 The documentation string is either the one you specify with
850 @code{:doc}, or @var{function}'s own documentation string.
852 @item (variable-item @var{variable})
853 Like @code{const}, but used for values which are variable names.  This
854 displays the documentation string as well as the variable name.  The
855 documentation string is either the one you specify with @code{:doc}, or
856 @var{variable}'s own documentation string.
858 @item (set @var{types}@dots{})
859 The value must be a list, and each element of the list must match one of
860 the @var{types} specified.
862 This appears in the customization buffer as a checklist, so that each of
863 @var{types} may have either one corresponding element or none.  It is
864 not possible to specify two different elements that match the same one
865 of @var{types}.  For example, @code{(set integer symbol)} allows one
866 integer and/or one symbol in the list; it does not allow multiple
867 integers or multiple symbols.  As a result, it is rare to use
868 nonspecific types such as @code{integer} in a @code{set}.
870 Most often, the @var{types} in a @code{set} are @code{const} types, as
871 shown here:
873 @example
874 (set (const :bold) (const :italic))
875 @end example
877 Sometimes they describe possible elements in an alist:
879 @example
880 (set (cons :tag "Height" (const height) integer)
881      (cons :tag "Width" (const width) integer))
882 @end example
884 @noindent
885 That lets the user specify a height value optionally
886 and a width value optionally.
888 @item (repeat @var{element-type})
889 The value must be a list and each element of the list must fit the type
890 @var{element-type}.  This appears in the customization buffer as a
891 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
892 more elements or removing elements.
894 @item (restricted-sexp :match-alternatives @var{criteria})
895 This is the most general composite type construct.  The value may be
896 any Lisp object that satisfies one of @var{criteria}.  @var{criteria}
897 should be a list, and each element should be one of these
898 possibilities:
900 @itemize @bullet
901 @item
902 A predicate---that is, a function of one argument that has no side
903 effects, and returns either @code{nil} or non-@code{nil} according to
904 the argument.  Using a predicate in the list says that objects for which
905 the predicate returns non-@code{nil} are acceptable.
907 @item
908 A quoted constant---that is, @code{'@var{object}}.  This sort of element
909 in the list says that @var{object} itself is an acceptable value.
910 @end itemize
912 For example,
914 @example
915 (restricted-sexp :match-alternatives
916                  (integerp 't 'nil))
917 @end example
919 @noindent
920 allows integers, @code{t} and @code{nil} as legitimate values.
922 The customization buffer shows all legitimate values using their read
923 syntax, and the user edits them textually.
924 @end table
926   Here is a table of the keywords you can use in keyword-value pairs
927 in a composite type:
929 @table @code
930 @item :tag @var{tag}
931 Use @var{tag} as the name of this alternative, for user communication
932 purposes.  This is useful for a type that appears inside of a
933 @code{choice}.
935 @item :match-alternatives @var{criteria}
936 @kindex match-alternatives@r{, customization keyword}
937 Use @var{criteria} to match possible values.  This is used only in
938 @code{restricted-sexp}.
940 @item :args @var{argument-list}
941 @kindex args@r{, customization keyword}
942 Use the elements of @var{argument-list} as the arguments of the type
943 construct.  For instance, @code{(const :args (foo))} is equivalent to
944 @code{(const foo)}.  You rarely need to write @code{:args} explicitly,
945 because normally the arguments are recognized automatically as
946 whatever follows the last keyword-value pair.
947 @end table
949 @node Splicing into Lists
950 @subsection Splicing into Lists
952   The @code{:inline} feature lets you splice a variable number of
953 elements into the middle of a @code{list} or @code{vector}
954 customization type.  You use it by adding @code{:inline t} to a type
955 specification which is contained in a @code{list} or @code{vector}
956 specification.
958   Normally, each entry in a @code{list} or @code{vector} type
959 specification describes a single element type.  But when an entry
960 contains @code{:inline t}, the value it matches is merged directly
961 into the containing sequence.  For example, if the entry matches a
962 list with three elements, those become three elements of the overall
963 sequence.  This is analogous to @samp{,@@} in a backquote construct
964 (@pxref{Backquote}).
966   For example, to specify a list whose first element must be @code{baz}
967 and whose remaining arguments should be zero or more of @code{foo} and
968 @code{bar}, use this customization type:
970 @example
971 (list (const baz) (set :inline t (const foo) (const bar)))
972 @end example
974 @noindent
975 This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
976 and @code{(baz foo bar)}.
978   When the element-type is a @code{choice}, you use @code{:inline} not
979 in the @code{choice} itself, but in (some of) the alternatives of the
980 @code{choice}.  For example, to match a list which must start with a
981 file name, followed either by the symbol @code{t} or two strings, use
982 this customization type:
984 @example
985 (list file
986       (choice (const t)
987               (list :inline t string string)))
988 @end example
990 @noindent
991 If the user chooses the first alternative in the choice, then the
992 overall list has two elements and the second element is @code{t}.  If
993 the user chooses the second alternative, then the overall list has three
994 elements and the second and third must be strings.
996 @node Type Keywords
997 @subsection Type Keywords
999 You can specify keyword-argument pairs in a customization type after the
1000 type name symbol.  Here are the keywords you can use, and their
1001 meanings:
1003 @table @code
1004 @item :value @var{default}
1005 Provide a default value.
1007 If @code{nil} is not a valid value for the alternative, then it is
1008 essential to specify a valid default with @code{:value}.
1010 If you use this for a type that appears as an alternative inside of
1011 @code{choice}; it specifies the default value to use, at first, if and
1012 when the user selects this alternative with the menu in the
1013 customization buffer.
1015 Of course, if the actual value of the option fits this alternative, it
1016 will appear showing the actual value, not @var{default}.
1018 @item :format @var{format-string}
1019 @kindex format@r{, customization keyword}
1020 This string will be inserted in the buffer to represent the value
1021 corresponding to the type.  The following @samp{%} escapes are available
1022 for use in @var{format-string}:
1024 @table @samp
1025 @item %[@var{button}%]
1026 Display the text @var{button} marked as a button.  The @code{:action}
1027 attribute specifies what the button will do if the user invokes it;
1028 its value is a function which takes two arguments---the widget which
1029 the button appears in, and the event.
1031 There is no way to specify two different buttons with different
1032 actions.
1034 @item %@{@var{sample}%@}
1035 Show @var{sample} in a special face specified by @code{:sample-face}.
1037 @item %v
1038 Substitute the item's value.  How the value is represented depends on
1039 the kind of item, and (for variables) on the customization type.
1041 @item %d
1042 Substitute the item's documentation string.
1044 @item %h
1045 Like @samp{%d}, but if the documentation string is more than one line,
1046 add an active field to control whether to show all of it or just the
1047 first line.
1049 @item %t
1050 Substitute the tag here.  You specify the tag with the @code{:tag}
1051 keyword.
1053 @item %%
1054 Display a literal @samp{%}.
1055 @end table
1057 @item :action @var{action}
1058 @kindex action@r{, customization keyword}
1059 Perform @var{action} if the user clicks on a button.
1061 @item :button-face @var{face}
1062 @kindex button-face@r{, customization keyword}
1063 Use the face @var{face} (a face name or a list of face names) for button
1064 text displayed with @samp{%[@dots{}%]}.
1066 @item :button-prefix @var{prefix}
1067 @itemx :button-suffix @var{suffix}
1068 @kindex button-prefix@r{, customization keyword}
1069 @kindex button-suffix@r{, customization keyword}
1070 These specify the text to display before and after a button.
1071 Each can be:
1073 @table @asis
1074 @item @code{nil}
1075 No text is inserted.
1077 @item a string
1078 The string is inserted literally.
1080 @item a symbol
1081 The symbol's value is used.
1082 @end table
1084 @item :tag @var{tag}
1085 Use @var{tag} (a string) as the tag for the value (or part of the value)
1086 that corresponds to this type.
1088 @item :doc @var{doc}
1089 @kindex doc@r{, customization keyword}
1090 Use @var{doc} as the documentation string for this value (or part of the
1091 value) that corresponds to this type.  In order for this to work, you
1092 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
1093 in that value.
1095 The usual reason to specify a documentation string for a type is to
1096 provide more information about the meanings of alternatives inside a
1097 @code{:choice} type or the parts of some other composite type.
1099 @item :help-echo @var{motion-doc}
1100 @kindex help-echo@r{, customization keyword}
1101 When you move to this item with @code{widget-forward} or
1102 @code{widget-backward}, it will display the string @var{motion-doc} in
1103 the echo area.  In addition, @var{motion-doc} is used as the mouse
1104 @code{help-echo} string and may actually be a function or form evaluated
1105 to yield a help string.  If it is a function, it is called with one
1106 argument, the widget.
1108 @item :match @var{function}
1109 @kindex match@r{, customization keyword}
1110 Specify how to decide whether a value matches the type.  The
1111 corresponding value, @var{function}, should be a function that accepts
1112 two arguments, a widget and a value; it should return non-@code{nil} if
1113 the value is acceptable.
1115 @item :validate @var{function}
1116 Specify a validation function for input.  @var{function} takes a
1117 widget as an argument, and should return @code{nil} if the widget's
1118 current value is valid for the widget.  Otherwise, it should return
1119 the widget containing the invalid data, and set that widget's
1120 @code{:error} property to a string explaining the error.
1122 @ignore
1123 @item :indent @var{columns}
1124 Indent this item by @var{columns} columns.  The indentation is used for
1125 @samp{%n}, and automatically for group names, for checklists and radio
1126 buttons, and for editable lists.  It affects the whole of the
1127 item except for the first line.
1129 @item :offset @var{extra}
1130 Indent the subitems of this item @var{extra} columns more than this
1131 item itself.  By default, subitems are indented the same as their
1132 parent.
1134 @item :extra-offset @var{n}
1135 Add @var{n} extra spaces to this item's indentation, compared to its
1136 parent's indentation.
1138 @item :notify @var{function}
1139 Call @var{function} each time the item or a subitem is changed.  The
1140 function gets two or three arguments.  The first argument is the item
1141 itself, the second argument is the item that was changed, and the
1142 third argument is the event leading to the change, if any.
1144 @item :menu-tag @var{tag-string}
1145 Use @var{tag-string} in the menu when the widget is used as an option
1146 in a @code{menu-choice} widget.
1148 @item :menu-tag-get
1149 A function used for finding the tag when the widget is used as an option
1150 in a @code{menu-choice} widget.  By default, the tag used will be either the
1151 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
1152 representation of the @code{:value} property if not.
1154 @item :tab-order
1155 Specify the order in which widgets are traversed with
1156 @code{widget-forward} or @code{widget-backward}.  This is only partially
1157 implemented.
1159 @enumerate a
1160 @item
1161 Widgets with tabbing order @code{-1} are ignored.
1163 @item
1164 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
1165 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
1166 whichever comes first.
1168 @item
1169 When on a widget with no tabbing order specified, go to the next widget
1170 in the buffer with a positive tabbing order, or @code{nil}
1171 @end enumerate
1173 @item :parent
1174 The parent of a nested widget (e.g., a @code{menu-choice} item or an
1175 element of a @code{editable-list} widget).
1177 @item :sibling-args
1178 This keyword is only used for members of a @code{radio-button-choice} or
1179 @code{checklist}.  The value should be a list of extra keyword
1180 arguments, which will be used when creating the @code{radio-button} or
1181 @code{checkbox} associated with this item.
1182 @end ignore
1183 @end table
1185 @node Defining New Types
1186 @subsection Defining New Types
1188 In the previous sections we have described how to construct elaborate
1189 type specifications for @code{defcustom}.  In some cases you may want
1190 to give such a type specification a name.  The obvious case is when
1191 you are using the same type for many user options: rather than repeat
1192 the specification for each option, you can give the type specification
1193 a name, and use that name each @code{defcustom}.  The other case is
1194 when a user option's value is a recursive data structure.  To make it
1195 possible for a datatype to refer to itself, it needs to have a name.
1197 Since custom types are implemented as widgets, the way to define a new
1198 customize type is to define a new widget.  We are not going to describe
1199 the widget interface here in details, see @ref{Top, , Introduction,
1200 widget, The Emacs Widget Library}, for that.  Instead we are going to
1201 demonstrate the minimal functionality needed for defining new customize
1202 types by a simple example.
1204 @example
1205 (define-widget 'binary-tree-of-string 'lazy
1206   "A binary tree made of cons-cells and strings."
1207   :offset 4
1208   :tag "Node"
1209   :type '(choice (string :tag "Leaf" :value "")
1210                  (cons :tag "Interior"
1211                        :value ("" . "")
1212                        binary-tree-of-string
1213                        binary-tree-of-string)))
1215 (defcustom foo-bar ""
1216   "Sample variable holding a binary tree of strings."
1217   :type 'binary-tree-of-string)
1218 @end example
1220 The function to define a new widget is called @code{define-widget}.  The
1221 first argument is the symbol we want to make a new widget type.  The
1222 second argument is a symbol representing an existing widget, the new
1223 widget is going to be defined in terms of difference from the existing
1224 widget.  For the purpose of defining new customization types, the
1225 @code{lazy} widget is perfect, because it accepts a @code{:type} keyword
1226 argument with the same syntax as the keyword argument to
1227 @code{defcustom} with the same name.  The third argument is a
1228 documentation string for the new widget.  You will be able to see that
1229 string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
1230 @key{RET}} command.
1232 After these mandatory arguments follow the keyword arguments.  The most
1233 important is @code{:type}, which describes the data type we want to match
1234 with this widget.  Here a @code{binary-tree-of-string} is described as
1235 being either a string, or a cons-cell whose car and cdr are themselves
1236 both @code{binary-tree-of-string}.  Note the reference to the widget
1237 type we are currently in the process of defining.  The @code{:tag}
1238 attribute is a string to name the widget in the user interface, and the
1239 @code{:offset} argument is there to ensure that child nodes are
1240 indented four spaces relative to the parent node, making the tree
1241 structure apparent in the customization buffer.
1243 The @code{defcustom} shows how the new widget can be used as an ordinary
1244 customization type.
1246 The reason for the name @code{lazy} is that the other composite
1247 widgets convert their inferior widgets to internal form when the
1248 widget is instantiated in a buffer.  This conversion is recursive, so
1249 the inferior widgets will convert @emph{their} inferior widgets.  If
1250 the data structure is itself recursive, this conversion is an infinite
1251 recursion.  The @code{lazy} widget prevents the recursion: it convert
1252 its @code{:type} argument only when needed.