2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003, 2004,
4 @c 2005, 2006 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/customize
7 @node Customization, Loading, Macros, Top
8 @chapter Writing 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 All kinds of customization declarations (for variables and groups, and
27 for faces) accept keyword arguments for specifying various information.
28 This section describes some keywords that apply to all kinds.
30 All of these keywords, except @code{:tag}, can be used more than once
31 in a given item. Each use of the keyword has an independent effect.
32 The keyword @code{:tag} is an exception because any given item can only
36 @item :tag @var{label}
37 Use @var{label}, a string, instead of the item's name, to label the
38 item in customization menus and buffers. @strong{Don't use a tag
39 which is substantially different from the item's real name; that would
40 cause confusion.} One legitimate case for use of @code{:tag} is to
41 specify a dash where normally a hyphen would be converted to a space:
44 (defcustom cursor-in-non-selected-windows @dots{}
45 :tag "Cursor In Non-selected Windows"
48 @item :group @var{group}
49 Put this customization item in group @var{group}. When you use
50 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
53 If you use this keyword more than once, you can put a single item into
54 more than one group. Displaying any of those groups will show this
55 item. Please don't overdo this, since the result would be annoying.
57 @item :link @var{link-data}
58 Include an external link after the documentation string for this item.
59 This is a sentence containing an active field which references some
62 There are several alternatives you can use for @var{link-data}:
65 @item (custom-manual @var{info-node})
66 Link to an Info node; @var{info-node} is a string which specifies the
67 node name, as in @code{"(emacs)Top"}. The link appears as
68 @samp{[Manual]} in the customization buffer and enters the built-in
69 Info reader on @var{info-node}.
71 @item (info-link @var{info-node})
72 Like @code{custom-manual} except that the link appears
73 in the customization buffer with the Info node name.
75 @item (url-link @var{url})
76 Link to a web page; @var{url} is a string which specifies the
77 @acronym{URL}. The link appears in the customization buffer as
78 @var{url} and invokes the WWW browser specified by
79 @code{browse-url-browser-function}.
81 @item (emacs-commentary-link @var{library})
82 Link to the commentary section of a library; @var{library} is a string
83 which specifies the library name.
85 @item (emacs-library-link @var{library})
86 Link to an Emacs Lisp library file; @var{library} is a string which
87 specifies the library name.
89 @item (file-link @var{file})
90 Link to a file; @var{file} is a string which specifies the name of the
91 file to visit with @code{find-file} when the user invokes this link.
93 @item (function-link @var{function})
94 Link to the documentation of a function; @var{function} is a string
95 which specifies the name of the function to describe with
96 @code{describe-function} when the user invokes this link.
98 @item (variable-link @var{variable})
99 Link to the documentation of a variable; @var{variable} is a string
100 which specifies the name of the variable to describe with
101 @code{describe-variable} when the user invokes this link.
103 @item (custom-group-link @var{group})
104 Link to another customization group. Invoking it creates a new
105 customization buffer for @var{group}.
108 You can specify the text to use in the customization buffer by adding
109 @code{:tag @var{name}} after the first element of the @var{link-data};
110 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
111 the Emacs manual which appears in the buffer as @samp{foo}.
113 An item can have more than one external link; however, most items have
116 @item :load @var{file}
117 Load file @var{file} (a string) before displaying this customization
118 item. Loading is done with @code{load-library}, and only if the file is
121 @item :require @var{feature}
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 This option specifies that the item was first introduced in Emacs
131 version @var{version}, or that its default value was changed in that
132 version. The value @var{version} must be a string.
134 @item :package-version '(@var{package} . @var{version})
135 This option specifies that the item was first introduced in
136 @var{package} version @var{version}, or that its meaning or default
137 value was changed in that version. The value of @var{package} is a
138 symbol and @var{version} is a string.
140 This keyword takes priority over @code{:version}.
142 @var{package} should be the official name of the package, such as MH-E
143 or Gnus. If the package @var{package} is released as part of Emacs,
144 @var{package} and @var{version} should appear in the value of
145 @code{customize-package-emacs-version-alist}.
148 Packages distributed as part of Emacs that use the
149 @code{:package-version} keyword must also update the
150 @code{customize-package-emacs-version-alist} variable.
152 @defvar customize-package-emacs-version-alist
153 This alist provides a mapping for the versions of Emacs that are
154 associated with versions of a package listed in the
155 @code{:package-version} keyword. Its elements look like this:
158 (@var{package} (@var{pversion} . @var{eversion})@dots{})
161 For each @var{package}, which is a symbol, there are one or more
162 elements that contain a package version @var{pversion} with an
163 associated Emacs version @var{eversion}. These versions are strings.
164 For example, the MH-E package updates this alist with the following:
167 (add-to-list 'customize-package-emacs-version-alist
168 '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
169 ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
170 ("7.4" . "22.1") ("8.0" . "22.1")))
173 The value of @var{package} needs to be unique and it needs to match
174 the @var{package} value appearing in the @code{:package-version}
175 keyword. Since the user might see the value in a error message, a good
176 choice is the official name of the package, such as MH-E or Gnus.
179 @node Group Definitions
180 @section Defining Custom Groups
182 Each Emacs Lisp package should have one main customization group which
183 contains all the options, faces and other groups in the package. If the
184 package has a small number of options and faces, use just one group and
185 put everything in it. When there are more than twelve or so options and
186 faces, then you should structure them into subgroups, and put the
187 subgroups under the package's main customization group. It is OK to
188 put some of the options and faces in the package's main group alongside
191 The package's main or only group should be a member of one or more of
192 the standard customization groups. (To display the full list of them,
193 use @kbd{M-x customize}.) Choose one or more of them (but not too
194 many), and add your group to each of them using the @code{:group}
197 The way to declare new customization groups is with @code{defgroup}.
199 @defmac defgroup group members doc [keyword value]@dots{}
200 Declare @var{group} as a customization group containing @var{members}.
201 Do not quote the symbol @var{group}. The argument @var{doc} specifies
202 the documentation string for the group.
204 The argument @var{members} is a list specifying an initial set of
205 customization items to be members of the group. However, most often
206 @var{members} is @code{nil}, and you specify the group's members by
207 using the @code{:group} keyword when defining those members.
209 If you want to specify group members through @var{members}, each element
210 should have the form @code{(@var{name} @var{widget})}. Here @var{name}
211 is a symbol, and @var{widget} is a widget type for editing that symbol.
212 Useful widgets are @code{custom-variable} for a variable,
213 @code{custom-face} for a face, and @code{custom-group} for a group.
215 When you introduce a new group into Emacs, use the @code{:version}
216 keyword in the @code{defgroup}; then you need not use it for
217 the individual members of the group.
219 In addition to the common keywords (@pxref{Common Keywords}), you can
220 also use this keyword in @code{defgroup}:
223 @item :prefix @var{prefix}
224 If the name of an item in the group starts with @var{prefix}, then the
225 tag for that item is constructed (by default) by omitting @var{prefix}.
227 One group can have any number of prefixes.
231 The prefix-discarding feature is currently turned off, which means
232 that @code{:prefix} currently has no effect. We did this because we
233 found that discarding the specified prefixes often led to confusing
234 names for options. This happened because the people who wrote the
235 @code{defgroup} definitions for various groups added @code{:prefix}
236 keywords whenever they make logical sense---that is, whenever the
237 variables in the library have a common prefix.
239 In order to obtain good results with @code{:prefix}, it would be
240 necessary to check the specific effects of discarding a particular
241 prefix, given the specific items in a group and their names and
242 documentation. If the resulting text is not clear, then @code{:prefix}
243 should not be used in that case.
245 It should be possible to recheck all the customization groups, delete
246 the @code{:prefix} specifications which give unclear results, and then
247 turn this feature back on, if someone would like to do the work.
249 @node Variable Definitions
250 @section Defining Customization Variables
252 Use @code{defcustom} to declare user-editable variables.
254 @defmac defcustom option default doc [keyword value]@dots{}
255 Declare @var{option} as a customizable user option variable. Do not
256 quote @var{option}. The argument @var{doc} specifies the documentation
257 string for the variable. There is no need to start it with a @samp{*}
258 because @code{defcustom} automatically marks @var{option} as a
259 @dfn{user option} (@pxref{Defining Variables}).
261 If @var{option} is void, @code{defcustom} initializes it to
262 @var{default}. @var{default} should be an expression to compute the
263 value; be careful in writing it, because it can be evaluated on more
264 than one occasion. You should normally avoid using backquotes in
265 @var{default} because they are not expanded when editing the value,
266 causing list values to appear to have the wrong structure.
268 If you specify the @code{:set} option, to make the variable take other
269 special actions when set through the customization buffer, the
270 variable's documentation string should tell the user specifically how
271 to do the same job in hand-written Lisp code.
273 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
274 mode (@code{eval-defun}), a special feature of @code{eval-defun}
275 arranges to set the variable unconditionally, without testing whether
276 its value is void. (The same feature applies to @code{defvar}.)
277 @xref{Defining Variables}.
280 @code{defcustom} accepts the following additional keywords:
283 @item :type @var{type}
284 Use @var{type} as the data type for this option. It specifies which
285 values are legitimate, and how to display the value.
286 @xref{Customization Types}, for more information.
288 @item :options @var{list}
289 Specify @var{list} as the list of reasonable values for use in this
290 option. The user is not restricted to using only these values, but they
291 are offered as convenient alternatives.
293 This is meaningful only for certain types, currently including
294 @code{hook}, @code{plist} and @code{alist}. See the definition of the
295 individual types for a description of how to use @code{:options}.
297 @item :set @var{setfunction}
298 Specify @var{setfunction} as the way to change the value of this
299 option. The function @var{setfunction} should take two arguments, a
300 symbol (the option name) and the new value, and should do whatever is
301 necessary to update the value properly for this option (which may not
302 mean simply setting the option as a Lisp variable). The default for
303 @var{setfunction} is @code{set-default}.
305 @item :get @var{getfunction}
306 Specify @var{getfunction} as the way to extract the value of this
307 option. The function @var{getfunction} should take one argument, a
308 symbol, and should return whatever customize should use as the
309 ``current value'' for that symbol (which need not be the symbol's Lisp
310 value). The default is @code{default-value}.
312 You have to really understand the workings of Custom to use
313 @code{:get} correctly. It is meant for values that are treated in
314 Custom as variables but are not actually stored in Lisp variables. It
315 is almost surely a mistake to specify @code{getfunction} for a value
316 that really is stored in a Lisp variable.
318 @item :initialize @var{function}
319 @var{function} should be a function used to initialize the variable
320 when the @code{defcustom} is evaluated. It should take two arguments,
321 the option name (a symbol) and the value. Here are some predefined
322 functions meant for use in this way:
325 @item custom-initialize-set
326 Use the variable's @code{:set} function to initialize the variable, but
327 do not reinitialize it if it is already non-void.
329 @item custom-initialize-default
330 Like @code{custom-initialize-set}, but use the function
331 @code{set-default} to set the variable, instead of the variable's
332 @code{:set} function. This is the usual choice for a variable whose
333 @code{:set} function enables or disables a minor mode; with this choice,
334 defining the variable will not call the minor mode function, but
335 customizing the variable will do so.
337 @item custom-initialize-reset
338 Always use the @code{:set} function to initialize the variable. If
339 the variable is already non-void, reset it by calling the @code{:set}
340 function using the current value (returned by the @code{:get} method).
341 This is the default @code{:initialize} function.
343 @item custom-initialize-changed
344 Use the @code{:set} function to initialize the variable, if it is
345 already set or has been customized; otherwise, just use
348 @item custom-initialize-safe-set
349 @itemx custom-initialize-safe-default
350 These functions behave like @code{custom-initialize-set}
351 (@code{custom-initialize-default}, respectively), but catch errors.
352 If an error occurs during initialization, they set the variable to
353 @code{nil} using @code{set-default}, and throw no error.
355 These two functions are only meant for options defined in pre-loaded
356 files, where some variables or functions used to compute the option's
357 value may not yet be defined. The option normally gets updated in
358 @file{startup.el}, ignoring the previously computed value. Because of
359 this typical usage, the value which these two functions compute
360 normally only matters when, after startup, one unsets the option's
361 value and then reevaluates the defcustom. By that time, the necessary
362 variables and functions will be defined, so there will not be an error.
365 @item :set-after @var{variables}
366 When setting variables according to saved customizations, make sure to
367 set the variables @var{variables} before this one; in other words, delay
368 setting this variable until after those others have been handled. Use
369 @code{:set-after} if setting this variable won't work properly unless
370 those other variables already have their intended values.
373 The @code{:require} option is useful for an option that turns on the
374 operation of a certain feature. Assuming that the package is coded to
375 check the value of the option, you still need to arrange for the package
376 to be loaded. You can do that with @code{:require}. @xref{Common
377 Keywords}. Here is an example, from the library @file{saveplace.el}:
380 (defcustom save-place nil
381 "*Non-nil means automatically save place in each file..."
387 If a customization item has a type such as @code{hook} or @code{alist},
388 which supports @code{:options}, you can add additional options to the
389 item, outside the @code{defcustom} declaration, by calling
390 @code{custom-add-option}. For example, if you define a function
391 @code{my-lisp-mode-initialization} intended to be called from
392 @code{emacs-lisp-mode-hook}, you might want to add that to the list of
393 options for @code{emacs-lisp-mode-hook}, but not by editing its
394 definition. You can do it thus:
397 (custom-add-option 'emacs-lisp-mode-hook
398 'my-lisp-mode-initialization)
401 @defun custom-add-option symbol option
402 To the customization @var{symbol}, add @var{option}.
404 The precise effect of adding @var{option} depends on the customization
405 type of @var{symbol}.
408 Internally, @code{defcustom} uses the symbol property
409 @code{standard-value} to record the expression for the default value,
410 and @code{saved-value} to record the value saved by the user with the
411 customization buffer. Both properties are actually lists whose car is
412 an expression which evaluates to the value.
414 @node Customization Types
415 @section Customization Types
417 When you define a user option with @code{defcustom}, you must specify
418 its @dfn{customization type}. That is a Lisp object which describes (1)
419 which values are legitimate and (2) how to display the value in the
420 customization buffer for editing.
422 You specify the customization type in @code{defcustom} with the
423 @code{:type} keyword. The argument of @code{:type} is evaluated, but
424 only once when the @code{defcustom} is executed, so it isn't useful
425 for the value to vary. Normally we use a quoted constant. For
429 (defcustom diff-command "diff"
430 "*The command to use to run diff."
435 In general, a customization type is a list whose first element is a
436 symbol, one of the customization type names defined in the following
437 sections. After this symbol come a number of arguments, depending on
438 the symbol. Between the type symbol and its arguments, you can
439 optionally write keyword-value pairs (@pxref{Type Keywords}).
441 Some of the type symbols do not use any arguments; those are called
442 @dfn{simple types}. For a simple type, if you do not use any
443 keyword-value pairs, you can omit the parentheses around the type
444 symbol. For example just @code{string} as a customization type is
445 equivalent to @code{(string)}.
450 * Splicing into Lists::
452 * Defining New Types::
455 All customization types are implemented as widgets; see @ref{Top, ,
456 Introduction, widget, The Emacs Widget Library}, for details.
459 @subsection Simple Types
461 This section describes all the simple customization types.
465 The value may be any Lisp object that can be printed and read back. You
466 can use @code{sexp} as a fall-back for any option, if you don't want to
467 take the time to work out a more specific type to use.
470 The value must be an integer, and is represented textually
471 in the customization buffer.
474 The value must be a number (floating point or integer), and is
475 represented textually in the customization buffer.
478 The value must be a floating point number, and is represented
479 textually in the customization buffer.
482 The value must be a string, and the customization buffer shows just the
483 contents, with no delimiting @samp{"} characters and no quoting with
487 Like @code{string} except that the string must be a valid regular
491 The value must be a character code. A character code is actually an
492 integer, but this type shows the value by inserting the character in the
493 buffer, rather than by showing the number.
496 The value must be a file name, and you can do completion with
499 @item (file :must-match t)
500 The value must be a file name for an existing file, and you can do
501 completion with @kbd{M-@key{TAB}}.
504 The value must be a directory name, and you can do completion with
508 The value must be a list of functions (or a single function, but that is
509 obsolete usage). This customization type is used for hook variables.
510 You can use the @code{:options} keyword in a hook variable's
511 @code{defcustom} to specify a list of functions recommended for use in
512 the hook; see @ref{Variable Definitions}.
515 The value must be a list of cons-cells, the @sc{car} of each cell
516 representing a key, and the @sc{cdr} of the same cell representing an
517 associated value. The user can add and delete key/value pairs, and
518 edit both the key and the value of each pair.
520 You can specify the key and value types like this:
523 (alist :key-type @var{key-type} :value-type @var{value-type})
527 where @var{key-type} and @var{value-type} are customization type
528 specifications. The default key type is @code{sexp}, and the default
529 value type is @code{sexp}.
531 The user can add any key matching the specified key type, but you can
532 give some keys a preferential treatment by specifying them with the
533 @code{:options} (see @ref{Variable Definitions}). The specified keys
534 will always be shown in the customize buffer (together with a suitable
535 value), with a checkbox to include or exclude or disable the key/value
536 pair from the alist. The user will not be able to edit the keys
537 specified by the @code{:options} keyword argument.
539 The argument to the @code{:options} keywords should be a list of option
540 specifications. Ordinarily, the options are simply atoms, which are the
541 specified keys. For example:
544 :options '("foo" "bar" "baz")
548 specifies that there are three ``known'' keys, namely @code{"foo"},
549 @code{"bar"} and @code{"baz"}, which will always be shown first.
551 You may want to restrict the value type for specific keys, for example,
552 the value associated with the @code{"bar"} key can only be an integer.
553 You can specify this by using a list instead of an atom in the option
554 specification. The first element will specify the key, like before,
555 while the second element will specify the value type.
558 :options '("foo" ("bar" integer) "baz")
561 Finally, you may want to change how the key is presented. By default,
562 the key is simply shown as a @code{const}, since the user cannot change
563 the special keys specified with the @code{:options} keyword. However,
564 you may want to use a more specialized type for presenting the key, like
565 @code{function-item} if you know it is a symbol with a function binding.
566 This is done by using a customization type specification instead of a
570 :options '("foo" ((function-item some-function) integer)
574 Many alists use lists with two elements, instead of cons cells. For
578 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
579 "Each element is a list of the form (KEY VALUE).")
586 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
587 "Each element is a cons-cell (KEY . VALUE).")
590 Because of the way lists are implemented on top of cons cells, you can
591 treat @code{list-alist} in the example above as a cons cell alist, where
592 the value type is a list with a single element containing the real
596 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
597 "Each element is a list of the form (KEY VALUE)."
598 :type '(alist :value-type (group integer)))
601 The @code{group} widget is used here instead of @code{list} only because
602 the formatting is better suited for the purpose.
604 Similarly, you can have alists with more values associated with each
605 key, using variations of this trick:
608 (defcustom person-data '(("brian" 50 t)
611 "Alist of basic info about people.
612 Each element has the form (NAME AGE MALE-FLAG)."
613 :type '(alist :value-type (group integer boolean)))
615 (defcustom pets '(("brian")
616 ("dorith" "dog" "guppy")
618 "Alist of people's pets.
619 In an element (KEY . VALUE), KEY is the person's name,
620 and the VALUE is a list of that person's pets."
621 :type '(alist :value-type (repeat string)))
625 The @code{plist} custom type is similar to the @code{alist} (see above),
626 except that the information is stored as a property list, i.e. a list of
630 (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
633 The default @code{:key-type} for @code{plist} is @code{symbol},
634 rather than @code{sexp}.
637 The value must be a symbol. It appears in the customization buffer as
638 the name of the symbol.
641 The value must be either a lambda expression or a function name. When
642 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
645 The value must be a variable name, and you can do completion with
649 The value must be a symbol which is a face name, and you can do
650 completion with @kbd{M-@key{TAB}}.
653 The value is boolean---either @code{nil} or @code{t}. Note that by
654 using @code{choice} and @code{const} together (see the next section),
655 you can specify that the value must be @code{nil} or @code{t}, but also
656 specify the text to describe each value in a way that fits the specific
657 meaning of the alternative.
660 The value must be a coding-system name, and you can do completion with
664 The value must be a valid color name, and you can do completion with
665 @kbd{M-@key{TAB}}. A sample is provided.
668 @node Composite Types
669 @subsection Composite Types
670 @cindex arguments (of composite type)
672 When none of the simple types is appropriate, you can use composite
673 types, which build new types from other types or from specified data.
674 The specified types or data are called the @dfn{arguments} of the
675 composite type. The composite type normally looks like this:
678 (@var{constructor} @var{arguments}@dots{})
682 but you can also add keyword-value pairs before the arguments, like
686 (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
689 Here is a table of constructors and how to use them to write
693 @item (cons @var{car-type} @var{cdr-type})
694 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
695 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
696 symbol)} is a customization type which matches values such as
697 @code{("foo" . foo)}.
699 In the customization buffer, the @sc{car} and the @sc{cdr} are
700 displayed and edited separately, each according to the type
701 that you specify for it.
703 @item (list @var{element-types}@dots{})
704 The value must be a list with exactly as many elements as the
705 @var{element-types} given; and each element must fit the
706 corresponding @var{element-type}.
708 For example, @code{(list integer string function)} describes a list of
709 three elements; the first element must be an integer, the second a
710 string, and the third a function.
712 In the customization buffer, each element is displayed and edited
713 separately, according to the type specified for it.
715 @item (vector @var{element-types}@dots{})
716 Like @code{list} except that the value must be a vector instead of a
717 list. The elements work the same as in @code{list}.
719 @item (choice @var{alternative-types}@dots{})
720 The value must fit at least one of @var{alternative-types}.
721 For example, @code{(choice integer string)} allows either an
724 In the customization buffer, the user selects an alternative
725 using a menu, and can then edit the value in the usual way for that
728 Normally the strings in this menu are determined automatically from the
729 choices; however, you can specify different strings for the menu by
730 including the @code{:tag} keyword in the alternatives. For example, if
731 an integer stands for a number of spaces, while a string is text to use
732 verbatim, you might write the customization type this way,
735 (choice (integer :tag "Number of spaces")
736 (string :tag "Literal text"))
740 so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
742 In any alternative for which @code{nil} is not a valid value, other than
743 a @code{const}, you should specify a valid default for that alternative
744 using the @code{:value} keyword. @xref{Type Keywords}.
746 If some values are covered by more than one of the alternatives,
747 customize will choose the first alternative that the value fits. This
748 means you should always list the most specific types first, and the
749 most general last. Here's an example of proper usage:
752 (choice (const :tag "Off" nil)
753 symbol (sexp :tag "Other"))
757 This way, the special value @code{nil} is not treated like other
758 symbols, and symbols are not treated like other Lisp expressions.
760 @item (radio @var{element-types}@dots{})
761 This is similar to @code{choice}, except that the choices are displayed
762 using `radio buttons' rather than a menu. This has the advantage of
763 displaying documentation for the choices when applicable and so is often
764 a good choice for a choice between constant functions
765 (@code{function-item} customization types).
767 @item (const @var{value})
768 The value must be @var{value}---nothing else is allowed.
770 The main use of @code{const} is inside of @code{choice}. For example,
771 @code{(choice integer (const nil))} allows either an integer or
774 @code{:tag} is often used with @code{const}, inside of @code{choice}.
778 (choice (const :tag "Yes" t)
779 (const :tag "No" nil)
780 (const :tag "Ask" foo))
784 describes a variable for which @code{t} means yes, @code{nil} means no,
785 and @code{foo} means ``ask.''
787 @item (other @var{value})
788 This alternative can match any Lisp value, but if the user chooses this
789 alternative, that selects the value @var{value}.
791 The main use of @code{other} is as the last element of @code{choice}.
795 (choice (const :tag "Yes" t)
796 (const :tag "No" nil)
797 (other :tag "Ask" foo))
801 describes a variable for which @code{t} means yes, @code{nil} means no,
802 and anything else means ``ask.'' If the user chooses @samp{Ask} from
803 the menu of alternatives, that specifies the value @code{foo}; but any
804 other value (not @code{t}, @code{nil} or @code{foo}) displays as
805 @samp{Ask}, just like @code{foo}.
807 @item (function-item @var{function})
808 Like @code{const}, but used for values which are functions. This
809 displays the documentation string as well as the function name.
810 The documentation string is either the one you specify with
811 @code{:doc}, or @var{function}'s own documentation string.
813 @item (variable-item @var{variable})
814 Like @code{const}, but used for values which are variable names. This
815 displays the documentation string as well as the variable name. The
816 documentation string is either the one you specify with @code{:doc}, or
817 @var{variable}'s own documentation string.
819 @item (set @var{types}@dots{})
820 The value must be a list, and each element of the list must match one of
821 the @var{types} specified.
823 This appears in the customization buffer as a checklist, so that each of
824 @var{types} may have either one corresponding element or none. It is
825 not possible to specify two different elements that match the same one
826 of @var{types}. For example, @code{(set integer symbol)} allows one
827 integer and/or one symbol in the list; it does not allow multiple
828 integers or multiple symbols. As a result, it is rare to use
829 nonspecific types such as @code{integer} in a @code{set}.
831 Most often, the @var{types} in a @code{set} are @code{const} types, as
835 (set (const :bold) (const :italic))
838 Sometimes they describe possible elements in an alist:
841 (set (cons :tag "Height" (const height) integer)
842 (cons :tag "Width" (const width) integer))
846 That lets the user specify a height value optionally
847 and a width value optionally.
849 @item (repeat @var{element-type})
850 The value must be a list and each element of the list must fit the type
851 @var{element-type}. This appears in the customization buffer as a
852 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
853 more elements or removing elements.
855 @item (restricted-sexp :match-alternatives @var{criteria})
856 This is the most general composite type construct. The value may be
857 any Lisp object that satisfies one of @var{criteria}. @var{criteria}
858 should be a list, and each element should be one of these
863 A predicate---that is, a function of one argument that has no side
864 effects, and returns either @code{nil} or non-@code{nil} according to
865 the argument. Using a predicate in the list says that objects for which
866 the predicate returns non-@code{nil} are acceptable.
869 A quoted constant---that is, @code{'@var{object}}. This sort of element
870 in the list says that @var{object} itself is an acceptable value.
876 (restricted-sexp :match-alternatives
881 allows integers, @code{t} and @code{nil} as legitimate values.
883 The customization buffer shows all legitimate values using their read
884 syntax, and the user edits them textually.
887 Here is a table of the keywords you can use in keyword-value pairs
892 Use @var{tag} as the name of this alternative, for user communication
893 purposes. This is useful for a type that appears inside of a
896 @item :match-alternatives @var{criteria}
897 Use @var{criteria} to match possible values. This is used only in
898 @code{restricted-sexp}.
900 @item :args @var{argument-list}
901 Use the elements of @var{argument-list} as the arguments of the type
902 construct. For instance, @code{(const :args (foo))} is equivalent to
903 @code{(const foo)}. You rarely need to write @code{:args} explicitly,
904 because normally the arguments are recognized automatically as
905 whatever follows the last keyword-value pair.
908 @node Splicing into Lists
909 @subsection Splicing into Lists
911 The @code{:inline} feature lets you splice a variable number of
912 elements into the middle of a list or vector. You use it in a
913 @code{set}, @code{choice} or @code{repeat} type which appears among the
914 element-types of a @code{list} or @code{vector}.
916 Normally, each of the element-types in a @code{list} or @code{vector}
917 describes one and only one element of the list or vector. Thus, if an
918 element-type is a @code{repeat}, that specifies a list of unspecified
919 length which appears as one element.
921 But when the element-type uses @code{:inline}, the value it matches is
922 merged directly into the containing sequence. For example, if it
923 matches a list with three elements, those become three elements of the
924 overall sequence. This is analogous to using @samp{,@@} in the backquote
927 For example, to specify a list whose first element must be @code{baz}
928 and whose remaining arguments should be zero or more of @code{foo} and
929 @code{bar}, use this customization type:
932 (list (const baz) (set :inline t (const foo) (const bar)))
936 This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
937 and @code{(baz foo bar)}.
939 When the element-type is a @code{choice}, you use @code{:inline} not
940 in the @code{choice} itself, but in (some of) the alternatives of the
941 @code{choice}. For example, to match a list which must start with a
942 file name, followed either by the symbol @code{t} or two strings, use
943 this customization type:
948 (list :inline t string string)))
952 If the user chooses the first alternative in the choice, then the
953 overall list has two elements and the second element is @code{t}. If
954 the user chooses the second alternative, then the overall list has three
955 elements and the second and third must be strings.
958 @subsection Type Keywords
960 You can specify keyword-argument pairs in a customization type after the
961 type name symbol. Here are the keywords you can use, and their
965 @item :value @var{default}
966 This is used for a type that appears as an alternative inside of
967 @code{choice}; it specifies the default value to use, at first, if and
968 when the user selects this alternative with the menu in the
969 customization buffer.
971 Of course, if the actual value of the option fits this alternative, it
972 will appear showing the actual value, not @var{default}.
974 If @code{nil} is not a valid value for the alternative, then it is
975 essential to specify a valid default with @code{:value}.
977 @item :format @var{format-string}
978 This string will be inserted in the buffer to represent the value
979 corresponding to the type. The following @samp{%} escapes are available
980 for use in @var{format-string}:
983 @item %[@var{button}%]
984 Display the text @var{button} marked as a button. The @code{:action}
985 attribute specifies what the button will do if the user invokes it;
986 its value is a function which takes two arguments---the widget which
987 the button appears in, and the event.
989 There is no way to specify two different buttons with different
992 @item %@{@var{sample}%@}
993 Show @var{sample} in a special face specified by @code{:sample-face}.
996 Substitute the item's value. How the value is represented depends on
997 the kind of item, and (for variables) on the customization type.
1000 Substitute the item's documentation string.
1003 Like @samp{%d}, but if the documentation string is more than one line,
1004 add an active field to control whether to show all of it or just the
1008 Substitute the tag here. You specify the tag with the @code{:tag}
1012 Display a literal @samp{%}.
1015 @item :action @var{action}
1016 Perform @var{action} if the user clicks on a button.
1018 @item :button-face @var{face}
1019 Use the face @var{face} (a face name or a list of face names) for button
1020 text displayed with @samp{%[@dots{}%]}.
1022 @item :button-prefix @var{prefix}
1023 @itemx :button-suffix @var{suffix}
1024 These specify the text to display before and after a button.
1029 No text is inserted.
1032 The string is inserted literally.
1035 The symbol's value is used.
1038 @item :tag @var{tag}
1039 Use @var{tag} (a string) as the tag for the value (or part of the value)
1040 that corresponds to this type.
1042 @item :doc @var{doc}
1043 Use @var{doc} as the documentation string for this value (or part of the
1044 value) that corresponds to this type. In order for this to work, you
1045 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
1048 The usual reason to specify a documentation string for a type is to
1049 provide more information about the meanings of alternatives inside a
1050 @code{:choice} type or the parts of some other composite type.
1052 @item :help-echo @var{motion-doc}
1053 When you move to this item with @code{widget-forward} or
1054 @code{widget-backward}, it will display the string @var{motion-doc} in
1055 the echo area. In addition, @var{motion-doc} is used as the mouse
1056 @code{help-echo} string and may actually be a function or form evaluated
1057 to yield a help string. If it is a function, it is called with one
1058 argument, the widget.
1060 @item :match @var{function}
1061 Specify how to decide whether a value matches the type. The
1062 corresponding value, @var{function}, should be a function that accepts
1063 two arguments, a widget and a value; it should return non-@code{nil} if
1064 the value is acceptable.
1067 @item :indent @var{columns}
1068 Indent this item by @var{columns} columns. The indentation is used for
1069 @samp{%n}, and automatically for group names, for checklists and radio
1070 buttons, and for editable lists. It affects the whole of the
1071 item except for the first line.
1073 @item :offset @var{columns}
1074 An integer indicating how many extra spaces to indent the subitems of
1075 this item. By default, subitems are indented the same as their parent.
1078 An integer indicating how many extra spaces to add to this item's
1079 indentation, compared to its parent.
1082 A function called each time the item or a subitem is changed. The
1083 function is called with two or three arguments. The first argument is
1084 the item itself, the second argument is the item that was changed, and
1085 the third argument is the event leading to the change, if any.
1088 A tag used in the menu when the widget is used as an option in a
1089 @code{menu-choice} widget.
1092 A function used for finding the tag when the widget is used as an option
1093 in a @code{menu-choice} widget. By default, the tag used will be either the
1094 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
1095 representation of the @code{:value} property if not.
1098 A function which takes a widget as an argument, and return @code{nil}
1099 if the widget's current value is valid for the widget. Otherwise, it
1100 should return the widget containing the invalid data, and set that
1101 widget's @code{:error} property to a string explaining the error.
1103 You can use the function @code{widget-children-validate} for this job;
1104 it tests that all children of @var{widget} are valid.
1107 Specify the order in which widgets are traversed with
1108 @code{widget-forward} or @code{widget-backward}. This is only partially
1113 Widgets with tabbing order @code{-1} are ignored.
1116 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
1117 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
1118 whichever comes first.
1121 When on a widget with no tabbing order specified, go to the next widget
1122 in the buffer with a positive tabbing order, or @code{nil}
1126 The parent of a nested widget (e.g., a @code{menu-choice} item or an
1127 element of a @code{editable-list} widget).
1130 This keyword is only used for members of a @code{radio-button-choice} or
1131 @code{checklist}. The value should be a list of extra keyword
1132 arguments, which will be used when creating the @code{radio-button} or
1133 @code{checkbox} associated with this item.
1137 @node Defining New Types
1138 @subsection Defining New Types
1140 In the previous sections we have described how to construct elaborate
1141 type specifications for @code{defcustom}. In some cases you may want
1142 to give such a type specification a name. The obvious case is when
1143 you are using the same type for many user options: rather than repeat
1144 the specification for each option, you can give the type specification
1145 a name, and use that name each @code{defcustom}. The other case is
1146 when a user option's value is a recursive data structure. To make it
1147 possible for a datatype to refer to itself, it needs to have a name.
1149 Since custom types are implemented as widgets, the way to define a new
1150 customize type is to define a new widget. We are not going to describe
1151 the widget interface here in details, see @ref{Top, , Introduction,
1152 widget, The Emacs Widget Library}, for that. Instead we are going to
1153 demonstrate the minimal functionality needed for defining new customize
1154 types by a simple example.
1157 (define-widget 'binary-tree-of-string 'lazy
1158 "A binary tree made of cons-cells and strings."
1161 :type '(choice (string :tag "Leaf" :value "")
1162 (cons :tag "Interior"
1164 binary-tree-of-string
1165 binary-tree-of-string)))
1167 (defcustom foo-bar ""
1168 "Sample variable holding a binary tree of strings."
1169 :type 'binary-tree-of-string)
1172 The function to define a new widget is called @code{define-widget}. The
1173 first argument is the symbol we want to make a new widget type. The
1174 second argument is a symbol representing an existing widget, the new
1175 widget is going to be defined in terms of difference from the existing
1176 widget. For the purpose of defining new customization types, the
1177 @code{lazy} widget is perfect, because it accepts a @code{:type} keyword
1178 argument with the same syntax as the keyword argument to
1179 @code{defcustom} with the same name. The third argument is a
1180 documentation string for the new widget. You will be able to see that
1181 string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
1184 After these mandatory arguments follow the keyword arguments. The most
1185 important is @code{:type}, which describes the data type we want to match
1186 with this widget. Here a @code{binary-tree-of-string} is described as
1187 being either a string, or a cons-cell whose car and cdr are themselves
1188 both @code{binary-tree-of-string}. Note the reference to the widget
1189 type we are currently in the process of defining. The @code{:tag}
1190 attribute is a string to name the widget in the user interface, and the
1191 @code{:offset} argument is there to ensure that child nodes are
1192 indented four spaces relative to the parent node, making the tree
1193 structure apparent in the customization buffer.
1195 The @code{defcustom} shows how the new widget can be used as an ordinary
1198 The reason for the name @code{lazy} is that the other composite
1199 widgets convert their inferior widgets to internal form when the
1200 widget is instantiated in a buffer. This conversion is recursive, so
1201 the inferior widgets will convert @emph{their} inferior widgets. If
1202 the data structure is itself recursive, this conversion is an infinite
1203 recursion. The @code{lazy} widget prevents the recursion: it convert
1204 its @code{:type} argument only when needed.
1207 arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2