2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1997, 1998 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 customization groups, variables,
10 and faces. We use the term @dfn{customization item} to include all
11 three of those. This has few examples, but please look at the file
12 @file{cus-edit.el}, which contains many declarations you can learn from.
17 * Variable Definitions::
19 * Customization Types::
23 @section Common Keywords for All Kinds of Items
25 All three kinds of customization declarations (for groups, variables,
26 and faces) accept keyword arguments for specifying various information.
27 This section describes some keywords that apply to all three.
29 All of these keywords, except @code{:tag}, can be used more than once in
30 a given item. Each use of the keyword has an independent effect. The
31 keyword @code{:tag} is an exception because any given item can only
32 display one name item.
35 @item :group @var{group}
36 Put this customization item in group @var{group}. When you use
37 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
40 If you use this keyword more than once, you can put a single item into
41 more than one group. Displaying any of those groups will show this
42 item. Be careful not to overdo this!
44 @item :link @var{link-data}
45 Include an external link after the documentation string for this item.
46 This is a sentence containing an active field which references some
49 There are three alternatives you can use for @var{link-data}:
52 @item (custom-manual @var{info-node})
53 Link to an Info node; @var{info-node} is a string which specifies the
54 node name, as in @code{"(emacs)Top"}. The link appears as
55 @samp{[manual]} in the customization buffer.
57 @item (info-link @var{info-node})
58 Like @code{custom-manual} except that the link appears
59 in the customization buffer with the Info node name.
61 @item (url-link @var{url})
62 Link to a web page; @var{url} is a string which specifies the URL. The
63 link appears in the customization buffer as @var{url}.
66 You can specify the text to use in the customization buffer by adding
67 @code{:tag @var{name}} after the first element of the @var{link-data};
68 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
69 the Emacs manual which appears in the buffer as @samp{foo}.
71 An item can have more than one external link; however, most items have
74 @item :load @var{file}
75 Load file @var{file} (a string) before displaying this customization
76 item. Loading is done with @code{load-library}, and only if the file is
79 @item :require @var{feature}
80 Require feature @var{feature} (a symbol) when installing a value for
81 this item (an option or a face) that was saved using the customization
82 feature. This is done by calling @code{require}.
84 The most common reason to use @code{:require} is when a variable enables
85 a feature such as a minor mode, and just setting the variable won't have
86 any effect unless the code which implements the mode is loaded.
89 Use @var{name}, a string, instead of the item's name, to label the item
90 in customization menus and buffers.
93 @node Group Definitions
94 @section Defining Custom Groups
96 Each Emacs Lisp package should have one main customization group which
97 contains all the options, faces and other groups in the package. If the
98 package has a small number of options and faces, use just one group and
99 put everything in it. When there are more than twelve or so options and
100 faces, then you should structure them into subgroups, and put the
101 subgroups under the package's main customization group. It is ok to
102 have some of the options and faces in the package's main group alongside
105 The package's main or only group should be a member of one or more of
106 the standard customization groups. Type press @kbd{C-h p} to display a
107 list of finder keywords; them choose some of them add your group to each
108 of them, using the @code{:group} keyword.
110 The way to declare new customization groups is with @code{defgroup}.
113 @defmac defgroup group members doc [keyword value]...
114 Declare @var{group} as a customization group containing @var{members}.
115 Do not quote the symbol @var{group}. The argument @var{doc} specifies
116 the documentation string for the group.
118 The arguments @var{members} can be an alist whose elements specify
119 members of the group; however, normally @var{members} is @code{nil}, and
120 you specify the group's members by using the @code{:group} keyword when
121 defining those members.
124 @code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and
125 @var{widget} is a widget for editing that symbol. Useful widgets are
126 @code{custom-variable} for editing variables, @code{custom-face} for
127 editing faces, and @code{custom-group} for editing groups.
130 In addition to the common keywords (@pxref{Common Keywords}), you can
131 use this keyword in @code{defgroup}:
134 @item :prefix @var{prefix}
135 If the name of an item in the group starts with @var{prefix}, then the
136 tag for that item is constructed (by default) by omitting @var{prefix}.
138 One group can have any number of prefixes.
142 The @code{:prefix} feature is currently turned off, which means that
143 @code{:prefix} currently has no effect. We did this because we found
144 that discarding the specified prefixes often led to confusing names for
145 options. This happened because the people who wrote the @code{defgroup}
146 definitions for various groups added @code{:prefix} keywords whenever
147 they make logical sense---that is, whenever they say that there was a
148 common prefix for the option names in a library.
150 In order to obtain good results with @code{:prefix}, it is necessary to
151 check the specific effects of discarding a particular prefix, given the
152 specific items in a group and their names and documentation. If the
153 resulting text is not clear, then @code{:prefix} should not be used in
156 It should be possible to recheck all the customization groups, delete
157 the @code{:prefix} specifications which give unclear results, and then
158 turn this feature back on, if someone would like to do the work.
160 @node Variable Definitions
161 @section Defining Customization Variables
163 Use @code{defcustom} to declare user editable variables.
166 @defmac defcustom option value doc [keyword value]...
167 Declare @var{option} as a customizable user option variable that
168 defaults to @var{value}. Do not quote @var{option}. @var{value} should
169 be an expression to compute the value; it will be be evaluated on more
172 If @var{option} is void, @code{defcustom} initializes it to @var{value}.
174 The argument @var{doc} specifies the documentation string for the variable.
176 The following additional keywords are defined:
179 @item :type @var{type}
180 Use @var{type} as the data type for this option. It specifies which
181 values are legitimate, and how to display the value.
182 @xref{Customization Types}, for more information.
184 @item :options @var{list}
185 Specify @var{list} as the list of reasonable values for use in this
188 Currently this is meaningful only when type is @code{hook}. The
189 elements of @var{list} are functions that you might likely want to use
190 as elements of the hook value. The user is not actually restricted to
191 using only these functions, but they are offered as convenient
194 @item :version @var{version}
195 This option specifies that the variable's default value was changed in
196 Emacs version @var{version}. For example,
199 (defcustom foo-max 34
200 "*Maximum number of foo's allowed."
206 @item :set @var{setfunction}
207 Specify @var{setfunction} as the way to change the value of this option.
208 The function @var{setfunction} should take two arguments, a symbol and
209 the new value, and should do whatever is necessary to update the value
210 properly for this option (which may not mean simply setting the option
211 as a Lisp variable). The default for @var{setfunction} is
214 @item :get @var{getfunction}
215 Specify @var{getfunction} as the way to extract the value of this
216 option. The function @var{getfunction} should take one argument, a
217 symbol, and should return the ``current value'' for that symbol (which
218 need not be the symbol's Lisp value). The default is
219 @code{default-value}.
221 @item :initialize @var{function}
222 @var{function} should be a function used to initialize the variable when
223 the @code{defcustom} is evaluated. It should take two arguments, the
224 symbol and value. Here are some predefined functions meant for use in
228 @item custom-initialize-set
229 Use the variable's @code{:set} function to initialize the variable. Do
230 not reinitialize it if it is already non-void. This is the default
231 @code{:initialize} function.
233 @item custom-initialize-default
234 Always use @code{set-default} to initialize the variable, even if some
235 other @code{:set} function has been specified.
237 @item custom-initialize-reset
238 Even if the variable is already non-void, reset it by calling the
239 @code{:set} function using the current value (returned by the
242 @item custom-initialize-changed
243 Like @code{custom-initialize-reset}, except use @code{set-default}
244 (rather than the @code{:set} function) to initialize the variable if it
245 is not bound and has not been set already.
248 @item :require @var{feature}
249 If the user saves a customized value for this item, them Emacs should do
250 @code{(require @var{feature})} after installing the saved value.
252 The place to use this feature is for an option that turns on the
253 operation of a certain feature. Assuming that the package is coded to
254 check the value of the option, you still need to arrange for the package
255 to be loaded. That is what @code{:require} is for.
260 Use @code{custom-add-option} to specify that a specific function is
261 useful as an member of a hook.
263 @defun custom-add-option symbol option
264 To the variable @var{symbol} add @var{option}.
266 If @var{symbol} is a hook variable, @var{option} should be a hook
267 member. For other types variables, the effect is undefined."
271 Internally, @code{defcustom} uses the symbol property
272 @code{standard-value} to record the expression for the default value,
273 and @code{saved-value} to record the value saved by the user with the
274 customization buffer. The @code{saved-value} property is actually a
275 list whose car is an expression which evaluates to the value.
277 @node Face Definitions
278 @section Defining Faces
280 Faces are declared with @code{defface}.
283 @defmac defface face spec doc [keyword value]...
284 Declare @var{face} as a customizable face that defaults according to
285 @var{spec}. Do not quote the symbol @var{face}.
287 @var{doc} is the face documentation.
289 @var{spec} should be an alist whose elements have the form
290 @code{(@var{display} @var{atts})} (see below). When @code{defface}
291 executes, it defines the face according to @var{spec}, then uses any
292 customizations saved in the @file{.emacs} file to override that
295 In each element of @var{spec}, @var{atts} is a list of face attributes
296 and their values. The possible attributes are defined in the variable
297 @code{custom-face-attributes}.
299 The @var{display} part of an element of @var{spec} determines which
300 frames the element applies to. If more than one element of @var{spec}
301 matches a given frame, the first matching element is the only one used
304 If @var{display} is @code{t} in a @var{spec} element, that element
305 matches all frames. (This means that any subsequent elements of
306 @var{spec} are never used.)
308 Alternatively, @var{display} can be an alist whose elements have the
309 form @code{(@var{characteristic} @var{value}@dots{})}. Here
310 @var{characteristic} specifies a way of classifying frames, and the
311 @var{value}s are possible classifications which @var{display} should
312 apply to. Here are the possible values of @var{characteristic}:
316 The kind of window system the frame uses---either @code{x}, @code{pc}
317 (for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
321 What kinds of colors the frame supports---either @code{color},
322 @code{grayscale}, or @code{mono}.
325 The kind of background--- either @code{light} or @code{dark}.
328 If an element of @var{display} specifies more than one
329 @var{value} for a given @var{characteristic}, any of those values
330 is acceptable. If an element of @var{display} has elements for
331 more than one @var{characteristic}, then @var{each} characteristic
332 of the frame must match one of the values specified for it.
335 Internally, @code{defface} uses the symbol property
336 @code{face-defface-spec} to record the face attributes specified in
337 @code{defface}, @code{saved-face} for the attributes saved by the user
338 with the customization buffer, and @code{face-documentation} for the
339 documentation string.
341 @node Customization Types
342 @section Customization Types
344 When you define a user option with @code{defcustom}, you must specify
345 its @dfn{customization type}. That is a Lisp object which indictaes (1)
346 which values are legitimate and (2) how to display the value in the
347 customization buffer for editing.
349 You specify the customization type in @code{defcustom} with the
350 @code{:type} keyword. The argument of @code{:type} is evaluated; since
351 types that vary at run time are rarely useful, normally it is a quoted
352 constant. For example:
355 (defcustom diff-command "diff"
356 "*The command to use to run diff."
361 In general, a customization type appears is a list whose first element
362 is a symbol, one of the customization type names defined in the
363 following sections. After this symbol come a number of arguments,
364 depending on the symbol. Some of the type symbols do not use any
365 arguments; those are called @dfn{simple types}.
367 In between the type symbol and its arguments, you can optionally
368 write keyword-value pairs. @xref{Type Keywords}.
370 For a simple type, if you do not use any keyword-value pairs, you can
371 omit the parentheses around the type symbol. The above example does
372 this, using just @code{string} as the customization type.
373 But @code{(string)} would mean the same thing.
378 * Splicing into Lists::
383 @subsection Simple Types
385 This section describes all the simple customization types.
389 The value may be any Lisp object that can be printed and read back. You
390 can use @code{sexp} as a fall-back for any option, if you don't want to
391 take the time to work out a more specific type to use.
394 The value must be an integer, and is represented textually
395 in the customization buffer.
398 The value must be a number, and is represented textually in the
399 customization buffer.
402 The value must be a string, and the customization buffer shows just the
403 contents, with no @samp{"} characters or quoting with @samp{\}.
406 The value must be a string which is a valid regular expression.
409 The value must be a character code. A character code is actually an
410 integer, but this type shows the value by inserting the character in the
411 buffer, rather than by showing the number.
414 The value must be a file name, and you can do completion with
417 @item (file :must-match t)
418 The value must be a file name for an existing file, and you can do
419 completion with @kbd{M-@key{TAB}}.
422 The value must be a directory name, and you can do completion with
426 The value must be a symbol. It appears in the customization buffer as
427 the name of the symbol.
430 The value must be either a lambda expression or a function name. When
431 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
434 The value must be a variable name, and you can do completion with
438 The value is boolean---either @code{nil} or @code{t}.
441 @node Composite Types
442 @subsection Composite Types
444 When none of the simple types is appropriate, you can use composite
445 types, which build from simple types. Here are several ways of doing
449 @item (restricted-sexp :match-alternatives @var{criteria})
450 The value may be any Lisp object that satisfies one of @var{criteria}.
451 @var{criteria} should be a list, and each elements should be
452 one of these possibilities:
456 A predicate---that is, a function of one argument that returns non-@code{nil}
457 if the argument fits a certain type. This means that objects of that type
461 A quoted constant---that is, @code{'@var{object}}. This means that
462 @var{object} is an acceptable value.
468 (restricted-sexp :match-alternatives (integerp 't 'nil))
472 allows integers, @code{t} and @code{nil} as legitimate values.
474 The customization buffer shows all legitimate values using their read
475 syntax, and the user edits them textually.
477 @item (cons @var{car-type} @var{cdr-type})
478 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
479 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(const string
480 symbol)} is a customization type which matches values such as
481 @code{("foo" . foo)}.
483 In the customization buffeer, the @sc{car} and the @sc{cdr} are
484 displayed and edited separately, each according to the type
485 that you specify for it.
487 @item (list @var{element-types}@dots{})
488 The value must be a list with exactly as many elements as the
489 @var{element-types} you have specified; and each element must fit the
490 corresponding @var{element-type}.
492 For example, @code{(list integer string function)} describes a list of
493 three elements; the first element must be an integer, the second a
494 string, and the third a function.
496 In the customization buffeer, the each element is displayed and edited
497 separately, according to the type specified for it.
499 @item (vector @var{element-types}@dots{})
500 Like @code{list} except that the value must be a vector instead of a
501 list. The elements work the same as in @code{list}.
503 @item (choice @var{alternative-types}...)
504 The value must fit at least one of @var{alternative-types}.
505 For example, @code{(choice integer string)} allows either an
508 In the customization buffer, the user selects one of the alternatives
509 using a menu, and can then edit the value in the usual way for that
512 Normally the strings in this menu are determined automatically from the
513 choices; however, you can specify different strings for the menu by
514 including the @code{:tag} keyword in the alternatives. For example, if
515 an integer stands for a number of spaces, while a string is text to use
516 verbatim, you might write the customization type this way,
519 (choice (integer :tag "Number of spaces")
520 (string :tag "Literal text"))
524 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
526 @item (const @var{value})
527 The value must be @var{value}---nothing else is allowed.
529 The main use of @code{const} is inside of @code{choice}. For example,
530 @code{(choice integer (const nil))} allows either an integer or
531 @code{nil}. @code{:tag} is often used with @code{const}.
533 @item (function-item @var{function})
534 Like @code{const}, but used for values which are functions. This
535 displays the documentation string of the function @var{function}
538 @item (variable-item @var{variable})
539 Like @code{const}, but used for values which are variable names. This
540 displays the documentation string of the variable @var{variable} as well
543 @item (set @var{elements}@dots{})
544 The value must be a list and each element of the list must be one of the
545 @var{elements} specified. This appears in the customization buffer as a
548 @item (repeat @var{element-type})
549 The value must be a list and each element of the list must fit the type
550 @var{element-type}. This appears in the customization buffer as a
551 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
552 more elements or removing elements.
555 @node Splicing into Lists
556 @subsection Splicing into Lists
558 The @code{:inline} feature lets you splice a variable number of
559 elements into the middle of a list or vector. You use it in a
560 @code{set}, @code{choice} or @code{repeat} type which appears among the
561 element-types of a @code{list} or @code{vector}.
563 Normally, each of the element-types in a @code{list} or @code{vector}
564 describes one and only one element of the list or vector. Thus, if an
565 element-type is a @code{repeat}, that specifies a list of unspecified
566 length which appears as one element.
568 But when the element-type uses @code{:inline}, the value it matches is
569 merged directly into the containing sequence. For example, if it
570 matches a list with three elements, those become three elements of the
571 overall sequence. This is analogous to using @samp{,@@} in the backquote
574 For example, to specify a list whose first element must be @code{t}
575 and whose remaining arguments should be zero or more of @code{foo} and
576 @code{bar}, use this customization type:
579 (list (const t) (set :inline t foo bar))
583 This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
584 and @code{(t foo bar)}.
586 When the element-type is a @code{choice}, you use @code{:inline} not
587 in the @code{choice} itself, but in (some of) the alternatives of the
588 @code{choice}. For example, to match a list which must start with a
589 file name, followed either by the symbol @code{t} or two strings, use
590 this customization type:
595 (list :inline t string string)))
599 If the user chooses the first alternative in the choice, then the
600 overall list has two elements and the second element is @code{t}. If
601 the user chooses the second alternative, then the overall list has three
602 elements and the second and third must be strings.
605 @subsection Type Keywords
607 You can specify keyword-argument pairs in a customization type after the
608 type name symbol. Here are the keywords you can use, and their
612 @item :value @var{default}
613 This is used for a type that appears as an alternative inside of
614 @code{:choice}; it specifies the default value to use, at first, if and
615 when the user selects this alternative with the menu in the
616 customization buffer.
618 Of course, if the actual value of the option fits this alternative, it
619 will appear showing the actual value, not @var{default}.
621 @item :format @var{format-string}
622 This string will be inserted in the buffer to represent the value
623 corresponding to the type. The following @samp{%} escapes are available
624 for use in @var{format-string}:
628 @item %[@var{button}%]
629 Display the text @var{button} marked as a button. The @code{:action}
630 attribute specifies what the button will do if the user invokes it;
631 its value is a function which takes two arguments---the widget which
632 the button appears in, and the event.
634 There is no way to specify two different buttons with different
635 actions; but perhaps there is no need for one.
638 @item %@{@var{sample}%@}
639 Show @var{sample} in a special face specified by @code{:sample-face}.
642 Substitute the item's value. How the value is represented depends on
643 the kind of item, and (for variables) on the customization type.
646 Substitute the item's documentation string.
649 Like @samp{%d}, but if the documentation string is more than one line,
650 add an active field to control whether to show all of it or just the
654 Substitute the tag here. You specify the tag with the @code{:tag}
658 Display a literal @samp{%}.
661 @item :button-face @var{face}
662 Use face @var{face} for text displayed with @samp{%[@dots{}%]}.
665 @itemx :button-suffix
666 These specify the text to display before and after a button.
674 The string is inserted literally.
677 The symbol's value is used.
681 Use @var{doc} as the documentation string for this item.
684 Use @var{tag} (a string) as the tag for this item.
686 @item :help-echo @var{motion-doc}
687 When you move to this item with @code{widget-forward} or
688 @code{widget-backward}, it will display the string @var{motion-doc}
691 @item :match @var{function}
692 Specify how to decide whether a value matches the type. @var{function}
693 should be a function that accepts two arguments, a widget and a value;
694 it should return non-@code{nil} if the value is acceptable.
697 @item :indent @var{columns}
698 Indent this item by @var{columns} columns. The indentation is used for
699 @samp{%n}, and automatically for group names, for checklists and radio
700 buttons, and for editable lists. It affects the whole of the
701 item except for the first line.
703 @item :offset @var{columns}
704 An integer indicating how many extra spaces to indent the subitems of
705 this item. By default, subitems are indented the same as their parent.
708 An integer indicating how many extra spaces to add to this item's
709 indentation, compared to its parent.
712 A function called each time the item or a subitem is changed. The
713 function is called with two or three arguments. The first argument is
714 the item itself, the second argument is the item that was changed, and
715 the third argument is the event leading to the change, if any.
718 Tag used in the menu when the widget is used as an option in a
719 @code{menu-choice} widget.
722 Function used for finding the tag when the widget is used as an option
723 in a @code{menu-choice} widget. By default, the tag used will be either the
724 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
725 representation of the @code{:value} property if not.
728 A function which takes a widget as an argument, and return nil if the
729 widgets current value is valid for the widget. Otherwise, it should
730 return the widget containing the invalid data, and set that widgets
731 @code{:error} property to a string explaining the error.
733 You can use the function @code{widget-children-validate} for this job;
734 it tests that all children of @var{widget} are valid.
737 Specify the order in which widgets are traversed with
738 @code{widget-forward} or @code{widget-backward}. This is only partially
743 Widgets with tabbing order @code{-1} are ignored.
746 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
747 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
748 whichever comes first.
751 When on a widget with no tabbing order specified, go to the next widget
752 in the buffer with a positive tabbing order, or @code{nil}
756 The parent of a nested widget (e.g. a @code{menu-choice} item or an
757 element of a @code{editable-list} widget).
760 This keyword is only used for members of a @code{radio-button-choice} or
761 @code{checklist}. The value should be a list of extra keyword
762 arguments, which will be used when creating the @code{radio-button} or
763 @code{checkbox} associated with this item.