2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1997, 1998, 1999, 2000, 2002 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 This chapter describes how to declare user options for customization,
10 and also customization groups for classifying them. We use the term
11 @dfn{customization item} to include both kinds of customization
12 definitions---as well as face definitions (@pxref{Defining Faces}).
17 * Variable Definitions::
18 * Customization Types::
22 @section Common Item Keywords
24 All kinds of customization declarations (for variables and groups, and
25 for faces) accept keyword arguments for specifying various information.
26 This section describes some keywords that apply to all kinds.
28 All of these keywords, except @code{:tag}, can be used more than once
29 in a given item. Each use of the keyword has an independent effect.
30 The keyword @code{:tag} is an exception because any given item can only
34 @item :tag @var{label}
35 Use @var{label}, a string, instead of the item's name, to label the item
36 in customization menus and buffers.
38 @item :group @var{group}
39 Put this customization item in group @var{group}. When you use
40 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
43 If you use this keyword more than once, you can put a single item into
44 more than one group. Displaying any of those groups will show this
45 item. Please don't overdo this, since the result would be annoying.
47 @item :link @var{link-data}
48 Include an external link after the documentation string for this item.
49 This is a sentence containing an active field which references some
52 There are four alternatives you can use for @var{link-data}:
55 @item (custom-manual @var{info-node})
56 Link to an Info node; @var{info-node} is a string which specifies the
57 node name, as in @code{"(emacs)Top"}. The link appears as
58 @samp{[manual]} in the customization buffer.
60 @item (info-link @var{info-node})
61 Like @code{custom-manual} except that the link appears
62 in the customization buffer with the Info node name.
64 @item (url-link @var{url})
65 Link to a web page; @var{url} is a string which specifies the @sc{url}.
66 The link appears in the customization buffer as @var{url}.
68 @item (emacs-commentary-link @var{library})
69 Link to the commentary section of a library; @var{library} is a string
70 which specifies the library name.
73 You can specify the text to use in the customization buffer by adding
74 @code{:tag @var{name}} after the first element of the @var{link-data};
75 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
76 the Emacs manual which appears in the buffer as @samp{foo}.
78 An item can have more than one external link; however, most items have
81 @item :load @var{file}
82 Load file @var{file} (a string) before displaying this customization
83 item. Loading is done with @code{load-library}, and only if the file is
86 @item :require @var{feature}
87 Require feature @var{feature} (a symbol) when installing a value for
88 this item (an option or a face) that was saved using the customization
89 feature. This is done by calling @code{require}.
91 The most common reason to use @code{:require} is when a variable enables
92 a feature such as a minor mode, and just setting the variable won't have
93 any effect unless the code which implements the mode is loaded.
96 @node Group Definitions
97 @section Defining Custom Groups
99 Each Emacs Lisp package should have one main customization group which
100 contains all the options, faces and other groups in the package. If the
101 package has a small number of options and faces, use just one group and
102 put everything in it. When there are more than twelve or so options and
103 faces, then you should structure them into subgroups, and put the
104 subgroups under the package's main customization group. It is OK to
105 put some of the options and faces in the package's main group alongside
108 The package's main or only group should be a member of one or more of
109 the standard customization groups. (To display the full list of them,
110 use @kbd{M-x customize}.) Choose one or more of them (but not too
111 many), and add your group to each of them using the @code{:group}
114 The way to declare new customization groups is with @code{defgroup}.
116 @defmac defgroup group members doc [keyword value]...
117 Declare @var{group} as a customization group containing @var{members}.
118 Do not quote the symbol @var{group}. The argument @var{doc} specifies
119 the documentation string for the group. It should not start with a
120 @samp{*} as in @code{defcustom}; that convention is for variables only.
122 The argument @var{members} is a list specifying an initial set of
123 customization items to be members of the group. However, most often
124 @var{members} is @code{nil}, and you specify the group's members by
125 using the @code{:group} keyword when defining those members.
127 If you want to specify group members through @var{members}, each element
128 should have the form @code{(@var{name} @var{widget})}. Here @var{name}
129 is a symbol, and @var{widget} is a widget type for editing that symbol.
130 Useful widgets are @code{custom-variable} for a variable,
131 @code{custom-face} for a face, and @code{custom-group} for a group.
133 When a new group is introduced into Emacs, use this keyword in
137 @item :version @var{version}
138 This option specifies that the group was first introduced in Emacs
139 version @var{version}. The value @var{version} must be a string.
142 Tag the group with a version like this when it is introduced, rather
143 than the individual members (@pxref{Variable Definitions}).
145 In addition to the common keywords (@pxref{Common Keywords}), you can
146 also use this keyword in @code{defgroup}:
149 @item :prefix @var{prefix}
150 If the name of an item in the group starts with @var{prefix}, then the
151 tag for that item is constructed (by default) by omitting @var{prefix}.
153 One group can have any number of prefixes.
157 The prefix-discarding feature is currently turned off, which means
158 that @code{:prefix} currently has no effect. We did this because we
159 found that discarding the specified prefixes often led to confusing
160 names for options. This happened because the people who wrote the
161 @code{defgroup} definitions for various groups added @code{:prefix}
162 keywords whenever they make logical sense---that is, whenever the
163 variables in the library have a common prefix.
165 In order to obtain good results with @code{:prefix}, it would be
166 necessary to check the specific effects of discarding a particular
167 prefix, given the specific items in a group and their names and
168 documentation. If the resulting text is not clear, then @code{:prefix}
169 should not be used in that case.
171 It should be possible to recheck all the customization groups, delete
172 the @code{:prefix} specifications which give unclear results, and then
173 turn this feature back on, if someone would like to do the work.
175 @node Variable Definitions
176 @section Defining Customization Variables
178 Use @code{defcustom} to declare user-editable variables.
180 @defmac defcustom option default doc [keyword value]@dots{}
181 Declare @var{option} as a customizable user option variable. Do not
182 quote @var{option}. The argument @var{doc} specifies the documentation
183 string for the variable. It should often start with a @samp{*} to mark
184 it as a @dfn{user option} (@pxref{Defining Variables}). Do not start
185 the documentation string with @samp{*} for options which cannot or
186 normally should not be set with @code{set-variable}; examples of the
187 former are global minor mode options such as
188 @code{global-font-lock-mode} and examples of the latter are hooks.
190 If @var{option} is void, @code{defcustom} initializes it to
191 @var{default}. @var{default} should be an expression to compute the
192 value; be careful in writing it, because it can be evaluated on more
193 than one occasion. You should normally avoid using backquotes in
194 @var{default} because they are not expanded when editing the value,
195 causing list values to appear to have the wrong structure.
197 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
198 mode (@code{eval-defun}), a special feature of @code{eval-defun}
199 arranges to set the variable unconditionally, without testing whether
200 its value is void. (The same feature applies to @code{defvar}.)
201 @xref{Defining Variables}.
204 @code{defcustom} accepts the following additional keywords:
207 @item :type @var{type}
208 Use @var{type} as the data type for this option. It specifies which
209 values are legitimate, and how to display the value.
210 @xref{Customization Types}, for more information.
212 @item :options @var{list}
213 Specify @var{list} as the list of reasonable values for use in this
214 option. The user is not restricted to using only these values, but they
215 are offered as convenient alternatives.
217 This is meaningful only for certain types, currently including
218 @code{hook}, @code{plist} and @code{alist}. See the definition of the
219 individual types for a description of how to use @code{:options}.
221 @item :version @var{version}
222 This option specifies that the variable was first introduced, or its
223 default value was changed, in Emacs version @var{version}. The value
224 @var{version} must be a string. For example,
227 (defcustom foo-max 34
228 "*Maximum number of foo's allowed."
234 @item :set @var{setfunction}
235 Specify @var{setfunction} as the way to change the value of this option.
236 The function @var{setfunction} should take two arguments, a symbol and
237 the new value, and should do whatever is necessary to update the value
238 properly for this option (which may not mean simply setting the option
239 as a Lisp variable). The default for @var{setfunction} is
242 @item :get @var{getfunction}
243 Specify @var{getfunction} as the way to extract the value of this
244 option. The function @var{getfunction} should take one argument, a
245 symbol, and should return whatever customize should use as the
246 ``current value'' for that symbol (which need not be the symbol's Lisp
247 value). The default is @code{default-value}.
249 You have to really understand the workings of Custom to use
250 @code{:get} correctly. It is meant for values that are treated in
251 Custom as variables but are not actually stored in Lisp variables. It
252 is almost surely a mistake to specify @code{getfunction} for a value
253 that really is stored in a Lisp variable.
255 @item :initialize @var{function}
256 @var{function} should be a function used to initialize the variable when
257 the @code{defcustom} is evaluated. It should take two arguments, the
258 symbol and value. Here are some predefined functions meant for use in
262 @item custom-initialize-set
263 Use the variable's @code{:set} function to initialize the variable, but
264 do not reinitialize it if it is already non-void.
266 @item custom-initialize-default
267 Like @code{custom-initialize-set}, but use the function
268 @code{set-default} to set the variable, instead of the variable's
269 @code{:set} function. This is the usual choice for a variable whose
270 @code{:set} function enables or disables a minor mode; with this choice,
271 defining the variable will not call the minor mode function, but
272 customizing the variable will do so.
274 @item custom-initialize-reset
275 Always use the @code{:set} function to initialize the variable. If
276 the variable is already non-void, reset it by calling the @code{:set}
277 function using the current value (returned by the @code{:get} method).
278 This is the default @code{:initialize} function.
280 @item custom-initialize-changed
281 Use the @code{:set} function to initialize the variable, if it is
282 already set or has been customized; otherwise, just use
286 @item :set-after @var{variables}
287 When setting variables according to saved customizations, make sure to
288 set the variables @var{variables} before this one; in other words, delay
289 setting this variable until after those others have been handled. Use
290 @code{:set-after} if setting this variable won't work properly unless
291 those other variables already have their intended values.
294 The @code{:require} option is useful for an option that turns on the
295 operation of a certain feature. Assuming that the package is coded to
296 check the value of the option, you still need to arrange for the package
297 to be loaded. You can do that with @code{:require}. @xref{Common
298 Keywords}. Here is an example, from the library @file{paren.el}:
301 (defcustom show-paren-mode nil
302 "Toggle Show Paren mode..."
303 :set (lambda (symbol value)
304 (show-paren-mode (or value 0)))
305 :initialize 'custom-initialize-default
307 :group 'paren-showing
311 If a customization item has a type such as @code{hook} or @code{alist},
312 which supports @code{:options}, you can add additional options to the
313 item, outside the @code{defcustom} declaration, by calling
314 @code{custom-add-option}. For example, if you define a function
315 @code{my-lisp-mode-initialization} intended to be called from
316 @code{emacs-lisp-mode-hook}, you might want to add that to the list of
317 options for @code{emacs-lisp-mode-hook}, but not by editing its
318 definition. You can do it thus:
321 (custom-add-option 'emacs-lisp-mode-hook
322 'my-lisp-mode-initialization)
325 @defun custom-add-option symbol option
326 To the customization @var{symbol}, add @var{option}.
328 The precise effect of adding @var{option} depends on the customization
329 type of @var{symbol}.
332 Internally, @code{defcustom} uses the symbol property
333 @code{standard-value} to record the expression for the default value,
334 and @code{saved-value} to record the value saved by the user with the
335 customization buffer. The @code{saved-value} property is actually a
336 list whose car is an expression which evaluates to the value.
338 @node Customization Types
339 @section Customization Types
341 When you define a user option with @code{defcustom}, you must specify
342 its @dfn{customization type}. That is a Lisp object which describes (1)
343 which values are legitimate and (2) how to display the value in the
344 customization buffer for editing.
346 You specify the customization type in @code{defcustom} with the
347 @code{:type} keyword. The argument of @code{:type} is evaluated, but
348 only once when the @code{defcustom} is executed, so it isn't useful
349 for the value to vary. Normally we use a quoted constant. For
353 (defcustom diff-command "diff"
354 "*The command to use to run diff."
359 In general, a customization type is a list whose first element is a
360 symbol, one of the customization type names defined in the following
361 sections. After this symbol come a number of arguments, depending on
362 the symbol. Between the type symbol and its arguments, you can
363 optionally write keyword-value pairs (@pxref{Type Keywords}).
365 Some of the type symbols do not use any arguments; those are called
366 @dfn{simple types}. For a simple type, if you do not use any
367 keyword-value pairs, you can omit the parentheses around the type
368 symbol. For example just @code{string} as a customization type is
369 equivalent to @code{(string)}.
374 * Splicing into Lists::
378 All customization types are implemented as widgets; see @ref{Top, ,
379 Introduction, widget, The Emacs Widget Library} for details.
382 @subsection Simple Types
384 This section describes all the simple customization types.
388 The value may be any Lisp object that can be printed and read back. You
389 can use @code{sexp} as a fall-back for any option, if you don't want to
390 take the time to work out a more specific type to use.
393 The value must be an integer, and is represented textually
394 in the customization buffer.
397 The value must be a number, and is represented textually in the
398 customization buffer.
401 The value must be a string, and the customization buffer shows just the
402 contents, with no delimiting @samp{"} characters and no quoting with
406 Like @code{string} except that the string must be a valid regular
410 The value must be a character code. A character code is actually an
411 integer, but this type shows the value by inserting the character in the
412 buffer, rather than by showing the number.
415 The value must be a file name, and you can do completion with
418 @item (file :must-match t)
419 The value must be a file name for an existing file, and you can do
420 completion with @kbd{M-@key{TAB}}.
423 The value must be a directory name, and you can do completion with
427 The value must be a list of functions (or a single function, but that is
428 obsolete usage). This customization type is used for hook variables.
429 You can use the @code{:options} keyword in a hook variable's
430 @code{defcustom} to specify a list of functions recommended for use in
431 the hook; see @ref{Variable Definitions}.
434 The value must be a list of cons-cells, the @sc{car} of each cell
435 representing a key, and the @sc{cdr} of the same cell representing an
436 associated value. The user can add and delete key/value pairs, and
437 edit both the key and the value of each pair.
439 You can specify the key and value types like this:
442 (alist :key-type @var{key-type} :value-type @var{value-type})
446 where @var{key-type} and @var{value-type} are customization type
447 specifications. The default key type is @code{sexp}, and the default
448 value type is @code{sexp}.
450 The user can add any key matching the specified key type, but you can
451 give some keys a preferential treatment by specifying them with the
452 @code{:options} (see @ref{Variable Definitions}). The specified keys
453 will always be shown in the customize buffer (together with a suitable
454 value), with a checkbox to include or exclude or disable the key/value
455 pair from the alist. The user will not be able to edit the keys
456 specified by the @code{:options} keyword argument.
458 The argument to the @code{:options} keywords should be a list of option
459 specifications. Ordinarily, the options are simply atoms, which are the
460 specified keys. For example:
463 :options '("foo" "bar" "baz")
467 specifies that there are three ``known'' keys, namely @code{"foo"},
468 @code{"bar"} and @code{"baz"}, which will always be shown first.
470 You may want to restrict the value type for specific keys, for example,
471 the value associated with the @code{"bar"} key can only be an integer.
472 You can specify this by using a list instead of an atom in the option
473 specification. The first element will specify the key, like before,
474 while the second element will specify the value type.
477 :options '("foo" ("bar" integer) "baz")
480 Finally, you may want to change how the key is presented. By default,
481 the key is simply shown as a @code{const}, since the user cannot change
482 the special keys specified with the @code{:options} keyword. However,
483 you may want to use a more specialized type for presenting the key, like
484 @code{function-item} if you know it is a symbol with a function binding.
485 This is done by using a customization type specification instead of a
489 :options '("foo" ((function-item some-function) integer) "baz")
492 Many alists use lists with two elements, instead of cons cells. For
496 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
497 "Each element is a list of the form (KEY VALUE).")
504 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
505 "Each element is a cons-cell (KEY . VALUE).")
508 Because of the way lists are implemented on top of cons cells, you can
509 treat @code{list-alist} in the example above as a cons cell alist, where
510 the value type is a list with a single element containing the real
514 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
515 "Each element is a list of the form (KEY VALUE)."
516 :type '(alist :value-type (group integer)))
519 The @code{group} widget is used here instead of @code{list} only because
520 the formatting is better suited for the purpose.
522 Similarily, you can have alists with more values associated with each
523 key, using variations of this trick:
526 (defcustom person-data '(("brian" 50 t)
529 "Alist of basic info about people.
530 Each element has the form (NAME AGE MALE-FLAG)."
531 :type '(alist :value-type (group age boolean)))
533 (defcustom pets '(("brian")
534 ("dorith" "dog" "guppy")
536 "Alist of people's pets.
537 In an element (KEY . VALUE), KEY is the person's name,
538 and the VALUE is a list of that person's pets."
539 :type '(alist :value-type (repeat string)))
543 The @code{plist} custom type is similar to the @code{alist} (see above),
544 except that the information is stored as a property list, i.e. a list of
548 (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
551 The default @code{:key-type} for @code{plist} is @code{symbol},
552 rather than @code{sexp}.
555 The value must be a symbol. It appears in the customization buffer as
556 the name of the symbol.
559 The value must be either a lambda expression or a function name. When
560 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
563 The value must be a variable name, and you can do completion with
567 The value must be a symbol which is a face name, and you can do
568 completion with @kbd{M-@key{TAB}}.
571 The value is boolean---either @code{nil} or @code{t}. Note that by
572 using @code{choice} and @code{const} together (see the next section),
573 you can specify that the value must be @code{nil} or @code{t}, but also
574 specify the text to describe each value in a way that fits the specific
575 meaning of the alternative.
578 The value must be a coding-system name, and you can do completion with
582 The value must be a valid color name, and you can do completion with
583 @kbd{M-@key{TAB}}. A sample is provided,
586 @node Composite Types
587 @subsection Composite Types
588 @cindex arguments (of composite type)
590 When none of the simple types is appropriate, you can use composite
591 types, which build new types from other types or from specified data.
592 The specified types or data are called the @dfn{arguments} of the
593 composite type. The composite type normally looks like this:
596 (@var{constructor} @var{arguments}@dots{})
600 but you can also add keyword-value pairs before the arguments, like
604 (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
607 Here is a table of constructors and how to use them to write
611 @item (cons @var{car-type} @var{cdr-type})
612 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
613 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
614 symbol)} is a customization type which matches values such as
615 @code{("foo" . foo)}.
617 In the customization buffer, the @sc{car} and the @sc{cdr} are
618 displayed and edited separately, each according to the type
619 that you specify for it.
621 @item (list @var{element-types}@dots{})
622 The value must be a list with exactly as many elements as the
623 @var{element-types} you have specified; and each element must fit the
624 corresponding @var{element-type}.
626 For example, @code{(list integer string function)} describes a list of
627 three elements; the first element must be an integer, the second a
628 string, and the third a function.
630 In the customization buffer, each element is displayed and edited
631 separately, according to the type specified for it.
633 @item (vector @var{element-types}@dots{})
634 Like @code{list} except that the value must be a vector instead of a
635 list. The elements work the same as in @code{list}.
637 @item (choice @var{alternative-types}@dots{})
638 The value must fit at least one of @var{alternative-types}.
639 For example, @code{(choice integer string)} allows either an
642 In the customization buffer, the user selects one of the alternatives
643 using a menu, and can then edit the value in the usual way for that
646 Normally the strings in this menu are determined automatically from the
647 choices; however, you can specify different strings for the menu by
648 including the @code{:tag} keyword in the alternatives. For example, if
649 an integer stands for a number of spaces, while a string is text to use
650 verbatim, you might write the customization type this way,
653 (choice (integer :tag "Number of spaces")
654 (string :tag "Literal text"))
658 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
660 In any alternative for which @code{nil} is not a valid value, other than
661 a @code{const}, you should specify a valid default for that alternative
662 using the @code{:value} keyword. @xref{Type Keywords}.
664 @item (radio @var{element-types}@dots{})
665 This is similar to @code{choice}, except that the choices are displayed
666 using `radio buttons' rather than a menu. This has the advantage of
667 displaying documentation for the choices when applicable and so is often
668 a good choice for a choice between constant functions
669 (@code{function-item} customization types).
671 @item (const @var{value})
672 The value must be @var{value}---nothing else is allowed.
674 The main use of @code{const} is inside of @code{choice}. For example,
675 @code{(choice integer (const nil))} allows either an integer or
678 @code{:tag} is often used with @code{const}, inside of @code{choice}.
682 (choice (const :tag "Yes" t)
683 (const :tag "No" nil)
684 (const :tag "Ask" foo))
688 describes a variable for which @code{t} means yes, @code{nil} means no,
689 and @code{foo} means ``ask.''
691 @item (other @var{value})
692 This alternative can match any Lisp value, but if the user chooses this
693 alternative, that selects the value @var{value}.
695 The main use of @code{other} is as the last element of @code{choice}.
699 (choice (const :tag "Yes" t)
700 (const :tag "No" nil)
701 (other :tag "Ask" foo))
705 describes a variable for which @code{t} means yes, @code{nil} means no,
706 and anything else means ``ask.'' If the user chooses @samp{Ask} from
707 the menu of alternatives, that specifies the value @code{foo}; but any
708 other value (not @code{t}, @code{nil} or @code{foo}) displays as
709 @samp{Ask}, just like @code{foo}.
711 @item (function-item @var{function})
712 Like @code{const}, but used for values which are functions. This
713 displays the documentation string as well as the function name.
714 The documentation string is either the one you specify with
715 @code{:doc}, or @var{function}'s own documentation string.
717 @item (variable-item @var{variable})
718 Like @code{const}, but used for values which are variable names. This
719 displays the documentation string as well as the variable name. The
720 documentation string is either the one you specify with @code{:doc}, or
721 @var{variable}'s own documentation string.
723 @item (set @var{types}@dots{})
724 The value must be a list, and each element of the list must match one of
725 the @var{types} specified.
727 This appears in the customization buffer as a checklist, so that each of
728 @var{types} may have either one corresponding element or none. It is
729 not possible to specify two different elements that match the same one
730 of @var{types}. For example, @code{(set integer symbol)} allows one
731 integer and/or one symbol in the list; it does not allow multiple
732 integers or multiple symbols. As a result, it is rare to use
733 nonspecific types such as @code{integer} in a @code{set}.
735 Most often, the @var{types} in a @code{set} are @code{const} types, as
739 (set (const :bold) (const :italic))
742 Sometimes they describe possible elements in an alist:
745 (set (cons :tag "Height" (const height) integer)
746 (cons :tag "Width" (const width) integer))
750 That lets the user specify a height value optionally
751 and a width value optionally.
753 @item (repeat @var{element-type})
754 The value must be a list and each element of the list must fit the type
755 @var{element-type}. This appears in the customization buffer as a
756 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
757 more elements or removing elements.
759 @item (restricted-sexp :match-alternatives @var{criteria})
760 This is the most general composite type construct. The value may be
761 any Lisp object that satisfies one of @var{criteria}. @var{criteria}
762 should be a list, and each element should be one of these
767 A predicate---that is, a function of one argument that has no side
768 effects, and returns either @code{nil} or non-@code{nil} according to
769 the argument. Using a predicate in the list says that objects for which
770 the predicate returns non-@code{nil} are acceptable.
773 A quoted constant---that is, @code{'@var{object}}. This sort of element
774 in the list says that @var{object} itself is an acceptable value.
780 (restricted-sexp :match-alternatives
785 allows integers, @code{t} and @code{nil} as legitimate values.
787 The customization buffer shows all legitimate values using their read
788 syntax, and the user edits them textually.
791 Here is a table of the keywords you can use in keyword-value pairs
796 Use @var{tag} as the name of this alternative, for user communication
797 purposes. This is useful for a type that appears inside of a
800 @item :match-alternatives @var{criteria}
801 Use @var{criteria} to match possible values. This is used only in
802 @code{restricted-sexp}.
804 @item :args @var{argumentlist}
805 Use the elements of @var{argumentlist} as the arguments of the type
806 construct. For instance, @code{(const :args (foo))} is equivalent to
807 @code{(const foo)}. You rarely need to write @code{:args} explicitly,
808 because normally the arguments are recognized automatically as
809 whatever follows the last keyword-value pair.
812 @node Splicing into Lists
813 @subsection Splicing into Lists
815 The @code{:inline} feature lets you splice a variable number of
816 elements into the middle of a list or vector. You use it in a
817 @code{set}, @code{choice} or @code{repeat} type which appears among the
818 element-types of a @code{list} or @code{vector}.
820 Normally, each of the element-types in a @code{list} or @code{vector}
821 describes one and only one element of the list or vector. Thus, if an
822 element-type is a @code{repeat}, that specifies a list of unspecified
823 length which appears as one element.
825 But when the element-type uses @code{:inline}, the value it matches is
826 merged directly into the containing sequence. For example, if it
827 matches a list with three elements, those become three elements of the
828 overall sequence. This is analogous to using @samp{,@@} in the backquote
831 For example, to specify a list whose first element must be @code{baz}
832 and whose remaining arguments should be zero or more of @code{foo} and
833 @code{bar}, use this customization type:
836 (list (const baz) (set :inline t (const foo) (const bar)))
840 This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
841 and @code{(baz foo bar)}.
843 When the element-type is a @code{choice}, you use @code{:inline} not
844 in the @code{choice} itself, but in (some of) the alternatives of the
845 @code{choice}. For example, to match a list which must start with a
846 file name, followed either by the symbol @code{t} or two strings, use
847 this customization type:
852 (list :inline t string string)))
856 If the user chooses the first alternative in the choice, then the
857 overall list has two elements and the second element is @code{t}. If
858 the user chooses the second alternative, then the overall list has three
859 elements and the second and third must be strings.
862 @subsection Type Keywords
864 You can specify keyword-argument pairs in a customization type after the
865 type name symbol. Here are the keywords you can use, and their
869 @item :value @var{default}
870 This is used for a type that appears as an alternative inside of
871 @code{choice}; it specifies the default value to use, at first, if and
872 when the user selects this alternative with the menu in the
873 customization buffer.
875 Of course, if the actual value of the option fits this alternative, it
876 will appear showing the actual value, not @var{default}.
878 If @code{nil} is not a valid value for the alternative, then it is
879 essential to specify a valid default with @code{:value}.
881 @item :format @var{format-string}
882 This string will be inserted in the buffer to represent the value
883 corresponding to the type. The following @samp{%} escapes are available
884 for use in @var{format-string}:
887 @item %[@var{button}%]
888 Display the text @var{button} marked as a button. The @code{:action}
889 attribute specifies what the button will do if the user invokes it;
890 its value is a function which takes two arguments---the widget which
891 the button appears in, and the event.
893 There is no way to specify two different buttons with different
896 @item %@{@var{sample}%@}
897 Show @var{sample} in a special face specified by @code{:sample-face}.
900 Substitute the item's value. How the value is represented depends on
901 the kind of item, and (for variables) on the customization type.
904 Substitute the item's documentation string.
907 Like @samp{%d}, but if the documentation string is more than one line,
908 add an active field to control whether to show all of it or just the
912 Substitute the tag here. You specify the tag with the @code{:tag}
916 Display a literal @samp{%}.
919 @item :action @var{action}
920 Perform @var{action} if the user clicks on a button.
922 @item :button-face @var{face}
923 Use the face @var{face} (a face name or a list of face names) for button
924 text displayed with @samp{%[@dots{}%]}.
926 @item :button-prefix @var{prefix}
927 @itemx :button-suffix @var{suffix}
928 These specify the text to display before and after a button.
936 The string is inserted literally.
939 The symbol's value is used.
943 Use @var{tag} (a string) as the tag for the value (or part of the value)
944 that corresponds to this type.
947 Use @var{doc} as the documentation string for this value (or part of the
948 value) that corresponds to this type. In order for this to work, you
949 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
952 The usual reason to specify a documentation string for a type is to
953 provide more information about the meanings of alternatives inside a
954 @code{:choice} type or the parts of some other composite type.
956 @item :help-echo @var{motion-doc}
957 When you move to this item with @code{widget-forward} or
958 @code{widget-backward}, it will display the string @var{motion-doc} in
959 the echo area. In addition, @var{motion-doc} is used as the mouse
960 @code{help-echo} string and may actually be a function or form evaluated
961 to yield a help string as for @code{help-echo} text properties.
962 @c @xref{Text help-echo}.
964 @item :match @var{function}
965 Specify how to decide whether a value matches the type. The
966 corresponding value, @var{function}, should be a function that accepts
967 two arguments, a widget and a value; it should return non-@code{nil} if
968 the value is acceptable.
971 @item :indent @var{columns}
972 Indent this item by @var{columns} columns. The indentation is used for
973 @samp{%n}, and automatically for group names, for checklists and radio
974 buttons, and for editable lists. It affects the whole of the
975 item except for the first line.
977 @item :offset @var{columns}
978 An integer indicating how many extra spaces to indent the subitems of
979 this item. By default, subitems are indented the same as their parent.
982 An integer indicating how many extra spaces to add to this item's
983 indentation, compared to its parent.
986 A function called each time the item or a subitem is changed. The
987 function is called with two or three arguments. The first argument is
988 the item itself, the second argument is the item that was changed, and
989 the third argument is the event leading to the change, if any.
992 A tag used in the menu when the widget is used as an option in a
993 @code{menu-choice} widget.
996 A function used for finding the tag when the widget is used as an option
997 in a @code{menu-choice} widget. By default, the tag used will be either the
998 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
999 representation of the @code{:value} property if not.
1002 A function which takes a widget as an argument, and return @code{nil}
1003 if the widget's current value is valid for the widget. Otherwise, it
1004 should return the widget containing the invalid data, and set that
1005 widget's @code{:error} property to a string explaining the error.
1007 You can use the function @code{widget-children-validate} for this job;
1008 it tests that all children of @var{widget} are valid.
1011 Specify the order in which widgets are traversed with
1012 @code{widget-forward} or @code{widget-backward}. This is only partially
1017 Widgets with tabbing order @code{-1} are ignored.
1020 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
1021 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
1022 whichever comes first.
1025 When on a widget with no tabbing order specified, go to the next widget
1026 in the buffer with a positive tabbing order, or @code{nil}
1030 The parent of a nested widget (e.g., a @code{menu-choice} item or an
1031 element of a @code{editable-list} widget).
1034 This keyword is only used for members of a @code{radio-button-choice} or
1035 @code{checklist}. The value should be a list of extra keyword
1036 arguments, which will be used when creating the @code{radio-button} or
1037 @code{checkbox} associated with this item.