2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1997, 1998 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../info/customize
8 @node Customization, , , Top
9 @chapter Writing Customization Definitions
11 This chapter describes how to declare user options for customization,
12 and also customization groups for classifying them. We use the term
13 @dfn{customization item} to include both kinds of customization
14 definitions---as well as face definitions.
19 * Variable Definitions::
20 * Customization Types::
25 @section Common Keywords for All Kinds of Items
27 All kinds of customization declarations (for variables and groups, and
28 for faces) accept keyword arguments for specifying various information.
29 This section describes some keywords that apply to all kinds.
31 All of these keywords, except @code{:tag}, can be used more than once
32 in a given item. Each use of the keyword has an independent effect.
33 The keyword @code{:tag} is an exception because any given item can only
38 Use @var{name}, a string, instead of the item's name, to label the item
39 in customization menus and buffers.
41 @item :group @var{group}
42 Put this customization item in group @var{group}. When you use
43 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
46 If you use this keyword more than once, you can put a single item into
47 more than one group. Displaying any of those groups will show this
48 item. Be careful not to overdo this!
50 @item :link @var{link-data}
51 Include an external link after the documentation string for this item.
52 This is a sentence containing an active field which references some
55 There are three alternatives you can use for @var{link-data}:
58 @item (custom-manual @var{info-node})
59 Link to an Info node; @var{info-node} is a string which specifies the
60 node name, as in @code{"(emacs)Top"}. The link appears as
61 @samp{[manual]} in the customization buffer.
63 @item (info-link @var{info-node})
64 Like @code{custom-manual} except that the link appears
65 in the customization buffer with the Info node name.
67 @item (url-link @var{url})
68 Link to a web page; @var{url} is a string which specifies the @sc{url}.
69 The link appears in the customization buffer as @var{url}.
72 You can specify the text to use in the customization buffer by adding
73 @code{:tag @var{name}} after the first element of the @var{link-data};
74 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
75 the Emacs manual which appears in the buffer as @samp{foo}.
77 An item can have more than one external link; however, most items have
80 @item :load @var{file}
81 Load file @var{file} (a string) before displaying this customization
82 item. Loading is done with @code{load-library}, and only if the file is
85 @item :require @var{feature}
86 Require feature @var{feature} (a symbol) when installing a value for
87 this item (an option or a face) that was saved using the customization
88 feature. This is done by calling @code{require}.
90 The most common reason to use @code{:require} is when a variable enables
91 a feature such as a minor mode, and just setting the variable won't have
92 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}.
117 @defmac defgroup group members doc [keyword value]...
118 Declare @var{group} as a customization group containing @var{members}.
119 Do not quote the symbol @var{group}. The argument @var{doc} specifies
120 the documentation string for the group.
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 In addition to the common keywords (@pxref{Common Keywords}), you can
134 use this keyword in @code{defgroup}:
137 @item :prefix @var{prefix}
138 If the name of an item in the group starts with @var{prefix}, then the
139 tag for that item is constructed (by default) by omitting @var{prefix}.
141 One group can have any number of prefixes.
145 @c Doesn't apply to XEmacs
147 @c The prefix-discarding feature is currently turned off, which means
148 @c that @code{:prefix} currently has no effect. We did this because we
149 @c found that discarding the specified prefixes often led to confusing
150 @c names for options. This happened because the people who wrote the
151 @c @code{defgroup} definitions for various groups added @code{:prefix}
152 @c keywords whenever they make logical sense---that is, whenever the
153 @c variables in the library have a common prefix.
155 @c In order to obtain good results with @code{:prefix}, it would be
156 @c necessary to check the specific effects of discarding a particular
157 @c prefix, given the specific items in a group and their names and
158 @c documentation. If the resulting text is not clear, then @code{:prefix}
159 @c should not be used in that case.
161 @c It should be possible to recheck all the customization groups, delete
162 @c the @code{:prefix} specifications which give unclear results, and then
163 @c turn this feature back on, if someone would like to do the work.
166 @node Variable Definitions
167 @section Defining Customization Variables
169 Use @code{defcustom} to declare user-editable variables.
172 @defmac defcustom option default doc [keyword value]...
173 Declare @var{option} as a customizable user option variable. Do not
174 quote @var{option}. The argument @var{doc} specifies the documentation
175 string for the variable.
177 If @var{option} is void, @code{defcustom} initializes it to
178 @var{default}. @var{default} should be an expression to compute the
179 value; be careful in writing it, because it can be evaluated on more
182 The following additional keywords are defined:
185 @item :type @var{type}
186 Use @var{type} as the data type for this option. It specifies which
187 values are legitimate, and how to display the value.
188 @xref{Customization Types}, for more information.
190 @item :options @var{list}
191 Specify @var{list} as the list of reasonable values for use in this
194 Currently this is meaningful only when the type is @code{hook}. In that
195 case, the elements of @var{list} should be functions that are useful as
196 elements of the hook value. The user is not restricted to using only
197 these functions, but they are offered as convenient alternatives.
199 @item :version @var{version}
200 This option specifies that the variable was first introduced, or its
201 default value was changed, in Emacs version @var{version}. The value
202 @var{version} must be a string. For example,
205 (defcustom foo-max 34
206 "*Maximum number of foo's allowed."
212 @item :set @var{setfunction}
213 Specify @var{setfunction} as the way to change the value of this option.
214 The function @var{setfunction} should take two arguments, a symbol and
215 the new value, and should do whatever is necessary to update the value
216 properly for this option (which may not mean simply setting the option
217 as a Lisp variable). The default for @var{setfunction} is
220 @item :get @var{getfunction}
221 Specify @var{getfunction} as the way to extract the value of this
222 option. The function @var{getfunction} should take one argument, a
223 symbol, and should return the ``current value'' for that symbol (which
224 need not be the symbol's Lisp value). The default is
225 @code{default-value}.
227 @item :initialize @var{function}
228 @var{function} should be a function used to initialize the variable when
229 the @code{defcustom} is evaluated. It should take two arguments, the
230 symbol and value. Here are some predefined functions meant for use in
234 @item custom-initialize-set
235 Use the variable's @code{:set} function to initialize the variable, but
236 do not reinitialize it if it is already non-void. This is the default
237 @code{:initialize} function.
239 @item custom-initialize-default
240 Like @code{custom-initialize-set}, but use the function
241 @code{set-default} to set the variable, instead of the variable's
242 @code{:set} function. This is the usual choice for a variable whose
243 @code{:set} function enables or disables a minor mode; with this choice,
244 defining the variable will not call the minor mode function, but
245 customizing the variable will do so.
247 @item custom-initialize-reset
248 Always use the @code{:set} function to initialize the variable. If the
249 variable is already non-void, reset it by calling the @code{:set}
250 function using the current value (returned by the @code{:get} method).
252 @item custom-initialize-changed
253 Use the @code{:set} function to initialize the variable, if it is
254 already set or has been customized; otherwise, just use
260 The @code{:require} option is useful for an option that turns on the
261 operation of a certain feature. Assuming that the package is coded to
262 check the value of the option, you still need to arrange for the package
263 to be loaded. You can do that with @code{:require}. @xref{Common
264 Keywords}. Here is an example, from the library @file{paren.el}:
267 (defcustom show-paren-mode nil
268 "Toggle Show Paren mode@enddots{}"
269 :set (lambda (symbol value)
270 (show-paren-mode (or value 0)))
271 :initialize 'custom-initialize-default
273 :group 'paren-showing
278 Use @code{custom-add-option} to specify that a specific function is
279 useful as an member of a hook.
281 @defun custom-add-option symbol option
282 To the variable @var{symbol} add @var{option}.
284 If @var{symbol} is a hook variable, @var{option} should be a hook
285 member. For other types variables, the effect is undefined."
289 Internally, @code{defcustom} uses the symbol property
290 @code{standard-value} to record the expression for the default value,
291 and @code{saved-value} to record the value saved by the user with the
292 customization buffer. The @code{saved-value} property is actually a
293 list whose car is an expression which evaluates to the value.
296 @node Customization Types
297 @section Customization Types
299 When you define a user option with @code{defcustom}, you must specify
300 its @dfn{customization type}. That is a Lisp object which describes (1)
301 which values are legitimate and (2) how to display the value in the
302 customization buffer for editing.
304 You specify the customization type in @code{defcustom} with the
305 @code{:type} keyword. The argument of @code{:type} is evaluated; since
306 types that vary at run time are rarely useful, normally you use a quoted
307 constant. For example:
310 (defcustom diff-command "diff"
311 "*The command to use to run diff."
316 In general, a customization type is a list whose first element is a
317 symbol, one of the customization type names defined in the following
318 sections. After this symbol come a number of arguments, depending on
319 the symbol. Between the type symbol and its arguments, you can
320 optionally write keyword-value pairs (@pxref{Type Keywords}).
322 Some of the type symbols do not use any arguments; those are called
323 @dfn{simple types}. For a simple type, if you do not use any
324 keyword-value pairs, you can omit the parentheses around the type
325 symbol. For example just @code{string} as a customization type is
326 equivalent to @code{(string)}.
331 * Splicing into Lists::
337 @subsection Simple Types
339 This section describes all the simple customization types.
343 The value may be any Lisp object that can be printed and read back. You
344 can use @code{sexp} as a fall-back for any option, if you don't want to
345 take the time to work out a more specific type to use.
348 The value must be an integer, and is represented textually
349 in the customization buffer.
352 The value must be a number, and is represented textually in the
353 customization buffer.
356 The value must be a string, and the customization buffer shows just the
357 contents, with no delimiting @samp{"} characters and no quoting with
361 Like @code{string} except that the string must be a valid regular
365 The value must be a character code. A character code is actually an
366 integer, but this type shows the value by inserting the character in the
367 buffer, rather than by showing the number.
370 The value must be a file name, and you can do completion with
373 @item (file :must-match t)
374 The value must be a file name for an existing file, and you can do
375 completion with @kbd{M-@key{TAB}}.
378 The value must be a directory name, and you can do completion with
382 The value must be a symbol. It appears in the customization buffer as
383 the name of the symbol.
386 The value must be either a lambda expression or a function name. When
387 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
390 The value must be a variable name, and you can do completion with
394 The value must be a symbol which is a face name.
397 The value is boolean---either @code{nil} or @code{t}. Note that by
398 using @code{choice} and @code{const} together (see the next section),
399 you can specify that the value must be @code{nil} or @code{t}, but also
400 specify the text to describe each value in a way that fits the specific
401 meaning of the alternative.
405 @node Composite Types
406 @subsection Composite Types
408 When none of the simple types is appropriate, you can use composite
409 types, which build new types from other types. Here are several ways of
413 @item (restricted-sexp :match-alternatives @var{criteria})
414 The value may be any Lisp object that satisfies one of @var{criteria}.
415 @var{criteria} should be a list, and each elements should be
416 one of these possibilities:
420 A predicate---that is, a function of one argument that returns non-@code{nil}
421 if the argument fits a certain type. This means that objects of that type
425 A quoted constant---that is, @code{'@var{object}}. This means that
426 @var{object} itself is an acceptable value.
432 (restricted-sexp :match-alternatives (integerp 't 'nil))
436 allows integers, @code{t} and @code{nil} as legitimate values.
438 The customization buffer shows all legitimate values using their read
439 syntax, and the user edits them textually.
441 @item (cons @var{car-type} @var{cdr-type})
442 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
443 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
444 symbol)} is a customization type which matches values such as
445 @code{("foo" . foo)}.
447 In the customization buffer, the @sc{car} and the @sc{cdr} are
448 displayed and edited separately, each according to the type
449 that you specify for it.
451 @item (list @var{element-types}@dots{})
452 The value must be a list with exactly as many elements as the
453 @var{element-types} you have specified; and each element must fit the
454 corresponding @var{element-type}.
456 For example, @code{(list integer string function)} describes a list of
457 three elements; the first element must be an integer, the second a
458 string, and the third a function.
460 In the customization buffer, the each element is displayed and edited
461 separately, according to the type specified for it.
463 @item (vector @var{element-types}@dots{})
464 Like @code{list} except that the value must be a vector instead of a
465 list. The elements work the same as in @code{list}.
467 @item (choice @var{alternative-types}...)
468 The value must fit at least one of @var{alternative-types}.
469 For example, @code{(choice integer string)} allows either an
472 In the customization buffer, the user selects one of the alternatives
473 using a menu, and can then edit the value in the usual way for that
476 Normally the strings in this menu are determined automatically from the
477 choices; however, you can specify different strings for the menu by
478 including the @code{:tag} keyword in the alternatives. For example, if
479 an integer stands for a number of spaces, while a string is text to use
480 verbatim, you might write the customization type this way,
483 (choice (integer :tag "Number of spaces")
484 (string :tag "Literal text"))
488 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
490 In any alternative for which @code{nil} is not a valid value, other than
491 a @code{const}, you should specify a valid default for that alternative
492 using the @code{:value} keyword. @xref{Type Keywords}.
494 @item (const @var{value})
495 The value must be @var{value}---nothing else is allowed.
497 The main use of @code{const} is inside of @code{choice}. For example,
498 @code{(choice integer (const nil))} allows either an integer or
501 @code{:tag} is often used with @code{const}, inside of @code{choice}.
505 (choice (const :tag "Yes" t)
506 (const :tag "No" nil)
507 (const :tag "Ask" foo))
510 @item (function-item @var{function})
511 Like @code{const}, but used for values which are functions. This
512 displays the documentation string as well as the function name.
513 The documentation string is either the one you specify with
514 @code{:doc}, or @var{function}'s own documentation string.
516 @item (variable-item @var{variable})
517 Like @code{const}, but used for values which are variable names. This
518 displays the documentation string as well as the variable name. The
519 documentation string is either the one you specify with @code{:doc}, or
520 @var{variable}'s own documentation string.
522 @item (set @var{elements}@dots{})
523 The value must be a list and each element of the list must be one of the
524 @var{elements} specified. This appears in the customization buffer as a
527 @item (repeat @var{element-type})
528 The value must be a list and each element of the list must fit the type
529 @var{element-type}. This appears in the customization buffer as a
530 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
531 more elements or removing elements.
535 @node Splicing into Lists
536 @subsection Splicing into Lists
538 The @code{:inline} feature lets you splice a variable number of
539 elements into the middle of a list or vector. You use it in a
540 @code{set}, @code{choice} or @code{repeat} type which appears among the
541 element-types of a @code{list} or @code{vector}.
543 Normally, each of the element-types in a @code{list} or @code{vector}
544 describes one and only one element of the list or vector. Thus, if an
545 element-type is a @code{repeat}, that specifies a list of unspecified
546 length which appears as one element.
548 But when the element-type uses @code{:inline}, the value it matches is
549 merged directly into the containing sequence. For example, if it
550 matches a list with three elements, those become three elements of the
551 overall sequence. This is analogous to using @samp{,@@} in the backquote
554 For example, to specify a list whose first element must be @code{t}
555 and whose remaining arguments should be zero or more of @code{foo} and
556 @code{bar}, use this customization type:
559 (list (const t) (set :inline t foo bar))
563 This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
564 and @code{(t foo bar)}.
566 When the element-type is a @code{choice}, you use @code{:inline} not
567 in the @code{choice} itself, but in (some of) the alternatives of the
568 @code{choice}. For example, to match a list which must start with a
569 file name, followed either by the symbol @code{t} or two strings, use
570 this customization type:
575 (list :inline t string string)))
579 If the user chooses the first alternative in the choice, then the
580 overall list has two elements and the second element is @code{t}. If
581 the user chooses the second alternative, then the overall list has three
582 elements and the second and third must be strings.
586 @subsection Type Keywords
588 You can specify keyword-argument pairs in a customization type after the
589 type name symbol. Here are the keywords you can use, and their
593 @item :value @var{default}
594 This is used for a type that appears as an alternative inside of
595 @code{choice}; it specifies the default value to use, at first, if and
596 when the user selects this alternative with the menu in the
597 customization buffer.
599 Of course, if the actual value of the option fits this alternative, it
600 will appear showing the actual value, not @var{default}.
602 If @code{nil} is not a valid value for the alternative, then it is
603 essential to specify a valid default with @code{:value}.
605 @item :format @var{format-string}
606 This string will be inserted in the buffer to represent the value
607 corresponding to the type. The following @samp{%} escapes are available
608 for use in @var{format-string}:
611 @item %[@var{button}%]
612 Display the text @var{button} marked as a button. The @code{:action}
613 attribute specifies what the button will do if the user invokes it;
614 its value is a function which takes two arguments---the widget which
615 the button appears in, and the event.
617 There is no way to specify two different buttons with different
620 @item %@{@var{sample}%@}
621 Show @var{sample} in a special face specified by @code{:sample-face}.
624 Substitute the item's value. How the value is represented depends on
625 the kind of item, and (for variables) on the customization type.
628 Substitute the item's documentation string.
631 Like @samp{%d}, but if the documentation string is more than one line,
632 add an active field to control whether to show all of it or just the
636 Substitute the tag here. You specify the tag with the @code{:tag}
640 Display a literal @samp{%}.
643 @item :action @var{action}
644 Perform @var{action} if the user clicks on a button.
646 @item :button-face @var{face}
647 Use the face @var{face} (a face name or a list of face names) for button
648 text displayed with @samp{%[@dots{}%]}.
650 @item :button-prefix @var{prefix}
651 @itemx :button-suffix @var{suffix}
652 These specify the text to display before and after a button.
660 The string is inserted literally.
663 The symbol's value is used.
667 Use @var{tag} (a string) as the tag for the value (or part of the value)
668 that corresponds to this type.
671 Use @var{doc} as the documentation string for this value (or part of the
672 value) that corresponds to this type. In order for this to work, you
673 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
676 The usual reason to specify a documentation string for a type is to
677 provide more information about the meanings of alternatives inside a
678 @code{:choice} type or the parts of some other composite type.
680 @item :help-echo @var{motion-doc}
681 When you move to this item with @code{widget-forward} or
682 @code{widget-backward}, it will display the string @var{motion-doc}
685 @item :match @var{function}
686 Specify how to decide whether a value matches the type. The
687 corresponding value, @var{function}, should be a function that accepts
688 two arguments, a widget and a value; it should return non-@code{nil} if
689 the value is acceptable.
692 @item :indent @var{columns}
693 Indent this item by @var{columns} columns. The indentation is used for
694 @samp{%n}, and automatically for group names, for checklists and radio
695 buttons, and for editable lists. It affects the whole of the
696 item except for the first line.
698 @item :offset @var{columns}
699 An integer indicating how many extra spaces to indent the subitems of
700 this item. By default, subitems are indented the same as their parent.
703 An integer indicating how many extra spaces to add to this item's
704 indentation, compared to its parent.
707 A function called each time the item or a subitem is changed. The
708 function is called with two or three arguments. The first argument is
709 the item itself, the second argument is the item that was changed, and
710 the third argument is the event leading to the change, if any.
713 Tag used in the menu when the widget is used as an option in a
714 @code{menu-choice} widget.
717 Function used for finding the tag when the widget is used as an option
718 in a @code{menu-choice} widget. By default, the tag used will be either the
719 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
720 representation of the @code{:value} property if not.
723 A function which takes a widget as an argument, and returns @code{nil} if the
724 widgets current value is valid for the widget. Otherwise, it should
725 return the widget containing the invalid data, and set that widgets
726 @code{:error} property to a string explaining the error.
728 You can use the function @code{widget-children-validate} for this job;
729 it tests that all children of @var{widget} are valid.
732 Specify the order in which widgets are traversed with
733 @code{widget-forward} or @code{widget-backward}. This is only partially
738 Widgets with tabbing order @code{-1} are ignored.
741 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
742 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
743 whichever comes first.
746 When on a widget with no tabbing order specified, go to the next widget
747 in the buffer with a positive tabbing order, or @code{nil}
751 The parent of a nested widget (e.g. a @code{menu-choice} item or an
752 element of an @code{editable-list} widget).
755 This keyword is only used for members of a @code{radio-button-choice} or
756 @code{checklist}. The value should be a list of extra keyword
757 arguments, which will be used when creating the @code{radio-button} or
758 @code{checkbox} associated with this item.