@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.@c See the file elisp.texi for copying conditions.@setfilename ../info/customize@node Customization, Loading, Macros, Top@chapter Writing Customization Definitions This chapter describes how to declare user options for customization,and also customization groups for classifying them. We use the term@dfn{customization item} to include both kinds of customizationdefinitions---as well as face definitions (@pxref{Defining Faces}).@menu* Common Keywords::* Group Definitions::* Variable Definitions::* Customization Types::@end menu@node Common Keywords@section Common Item Keywords All kinds of customization declarations (for variables and groups, andfor faces) accept keyword arguments for specifying various information.This section describes some keywords that apply to all kinds. All of these keywords, except @code{:tag}, can be used more than oncein a given item. Each use of the keyword has an independent effect.The keyword @code{:tag} is an exception because any given item can onlydisplay one name.@table @code@item :tag @var{label}Use @var{label}, a string, instead of the item's name, to label the itemin customization menus and buffers.@item :group @var{group}Put this customization item in group @var{group}. When you use@code{:group} in a @code{defgroup}, it makes the new group a subgroup of@var{group}.If you use this keyword more than once, you can put a single item intomore than one group. Displaying any of those groups will show thisitem. Please don't overdo this, since the result would be annoying.@item :link @var{link-data}Include an external link after the documentation string for this item.This is a sentence containing an active field which references someother documentation.There are four alternatives you can use for @var{link-data}:@table @code@item (custom-manual @var{info-node})Link to an Info node; @var{info-node} is a string which specifies thenode name, as in @code{"(emacs)Top"}. The link appears as@samp{[manual]} in the customization buffer.@item (info-link @var{info-node})Like @code{custom-manual} except that the link appearsin the customization buffer with the Info node name.@item (url-link @var{url})Link to a web page; @var{url} is a string which specifies the @sc{url}.The link appears in the customization buffer as @var{url}.@item (emacs-commentary-link @var{library})Link to the commentary section of a library; @var{library} is a stringwhich specifies the library name.@end tableYou can specify the text to use in the customization buffer by adding@code{:tag @var{name}} after the first element of the @var{link-data};for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link tothe Emacs manual which appears in the buffer as @samp{foo}.An item can have more than one external link; however, most items havenone at all.@item :load @var{file}Load file @var{file} (a string) before displaying this customizationitem. Loading is done with @code{load-library}, and only if the file isnot already loaded.@item :require @var{feature}Require feature @var{feature} (a symbol) when installing a value forthis item (an option or a face) that was saved using the customizationfeature. This is done by calling @code{require}.The most common reason to use @code{:require} is when a variable enablesa feature such as a minor mode, and just setting the variable won't haveany effect unless the code which implements the mode is loaded.@end table@node Group Definitions@section Defining Custom Groups Each Emacs Lisp package should have one main customization group whichcontains all the options, faces and other groups in the package. If thepackage has a small number of options and faces, use just one group andput everything in it. When there are more than twelve or so options andfaces, then you should structure them into subgroups, and put thesubgroups under the package's main customization group. It is OK toput some of the options and faces in the package's main group alongsidethe subgroups. The package's main or only group should be a member of one or more ofthe standard customization groups. (To display the full list of them,use @kbd{M-x customize}.) Choose one or more of them (but not toomany), and add your group to each of them using the @code{:group}keyword. The way to declare new customization groups is with @code{defgroup}.@defmac defgroup group members doc [keyword value]...Declare @var{group} as a customization group containing @var{members}.Do not quote the symbol @var{group}. The argument @var{doc} specifiesthe documentation string for the group. It should not start with a@samp{*} as in @code{defcustom}; that convention is for variables only.The argument @var{members} is a list specifying an initial set ofcustomization items to be members of the group. However, most often@var{members} is @code{nil}, and you specify the group's members byusing the @code{:group} keyword when defining those members.If you want to specify group members through @var{members}, each elementshould have the form @code{(@var{name} @var{widget})}. Here @var{name}is a symbol, and @var{widget} is a widget type for editing that symbol.Useful widgets are @code{custom-variable} for a variable,@code{custom-face} for a face, and @code{custom-group} for a group.When a new group is introduced into Emacs, use this keyword in@code{defgroup}:@table @code@item :version @var{version}This option specifies that the group was first introduced in Emacsversion @var{version}. The value @var{version} must be a string.@end tableTag the group with a version like this when it is introduced, ratherthan the individual members (@pxref{Variable Definitions}).In addition to the common keywords (@pxref{Common Keywords}), you canalso use this keyword in @code{defgroup}:@table @code@item :prefix @var{prefix}If the name of an item in the group starts with @var{prefix}, then thetag for that item is constructed (by default) by omitting @var{prefix}.One group can have any number of prefixes.@end table@end defmac The prefix-discarding feature is currently turned off, which meansthat @code{:prefix} currently has no effect. We did this because wefound that discarding the specified prefixes often led to confusingnames for options. This happened because the people who wrote the@code{defgroup} definitions for various groups added @code{:prefix}keywords whenever they make logical sense---that is, whenever thevariables in the library have a common prefix. In order to obtain good results with @code{:prefix}, it would benecessary to check the specific effects of discarding a particularprefix, given the specific items in a group and their names anddocumentation. If the resulting text is not clear, then @code{:prefix}should not be used in that case. It should be possible to recheck all the customization groups, deletethe @code{:prefix} specifications which give unclear results, and thenturn this feature back on, if someone would like to do the work.@node Variable Definitions@section Defining Customization Variables Use @code{defcustom} to declare user-editable variables.@defmac defcustom option default doc [keyword value]@dots{}Declare @var{option} as a customizable user option variable. Do notquote @var{option}. The argument @var{doc} specifies the documentationstring for the variable. It should often start with a @samp{*} to markit as a @dfn{user option} (@pxref{Defining Variables}). Do not startthe documentation string with @samp{*} for options which cannot ornormally should not be set with @code{set-variable}; examples of theformer are global minor mode options such as@code{global-font-lock-mode} and examples of the latter are hooks.If @var{option} is void, @code{defcustom} initializes it to@var{default}. @var{default} should be an expression to compute thevalue; be careful in writing it, because it can be evaluated on morethan one occasion. You should normally avoid using backquotes in@var{default} because they are not expanded when editing the value,causing list values to appear to have the wrong structure.When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lispmode (@code{eval-defun}), a special feature of @code{eval-defun}arranges to set the variable unconditionally, without testing whetherits value is void. (The same feature applies to @code{defvar}.)@xref{Defining Variables}.@end defmac @code{defcustom} accepts the following additional keywords:@table @code@item :type @var{type}Use @var{type} as the data type for this option. It specifies whichvalues are legitimate, and how to display the value.@xref{Customization Types}, for more information.@item :options @var{list}Specify @var{list} as the list of reasonable values for use in thisoption. The user is not restricted to using only these values, but theyare offered as convenient alternatives.This is meaningful only for certain types, currently including@code{hook}, @code{plist} and @code{alist}. See the definition of theindividual types for a description of how to use @code{:options}.@item :version @var{version}This option specifies that the variable was first introduced, or itsdefault value was changed, in Emacs version @var{version}. The value@var{version} must be a string. For example,@example(defcustom foo-max 34 "*Maximum number of foo's allowed." :type 'integer :group 'foo :version "20.3")@end example@item :set @var{setfunction}Specify @var{setfunction} as the way to change the value of this option.The function @var{setfunction} should take two arguments, a symbol andthe new value, and should do whatever is necessary to update the valueproperly for this option (which may not mean simply setting the optionas a Lisp variable). The default for @var{setfunction} is@code{set-default}.@item :get @var{getfunction}Specify @var{getfunction} as the way to extract the value of thisoption. The function @var{getfunction} should take one argument, asymbol, and should return whatever customize should use as the``current value'' for that symbol (which need not be the symbol's Lispvalue). The default is @code{default-value}.You have to really understand the workings of Custom to use@code{:get} correctly. It is meant for values that are treated inCustom as variables but are not actually stored in Lisp variables. Itis almost surely a mistake to specify @code{getfunction} for a valuethat really is stored in a Lisp variable.@item :initialize @var{function}@var{function} should be a function used to initialize the variable whenthe @code{defcustom} is evaluated. It should take two arguments, thesymbol and value. Here are some predefined functions meant for use inthis way:@table @code@item custom-initialize-setUse the variable's @code{:set} function to initialize the variable, butdo not reinitialize it if it is already non-void.@item custom-initialize-defaultLike @code{custom-initialize-set}, but use the function@code{set-default} to set the variable, instead of the variable's@code{:set} function. This is the usual choice for a variable whose@code{:set} function enables or disables a minor mode; with this choice,defining the variable will not call the minor mode function, butcustomizing the variable will do so.@item custom-initialize-resetAlways use the @code{:set} function to initialize the variable. Ifthe variable is already non-void, reset it by calling the @code{:set}function using the current value (returned by the @code{:get} method).This is the default @code{:initialize} function.@item custom-initialize-changedUse the @code{:set} function to initialize the variable, if it isalready set or has been customized; otherwise, just use@code{set-default}.@end table@item :set-after @var{variables}When setting variables according to saved customizations, make sure toset the variables @var{variables} before this one; in other words, delaysetting this variable until after those others have been handled. Use@code{:set-after} if setting this variable won't work properly unlessthose other variables already have their intended values.@end table The @code{:require} option is useful for an option that turns on theoperation of a certain feature. Assuming that the package is coded tocheck the value of the option, you still need to arrange for the packageto be loaded. You can do that with @code{:require}. @xref{CommonKeywords}. Here is an example, from the library @file{paren.el}:@example(defcustom show-paren-mode nil "Toggle Show Paren mode..." :set (lambda (symbol value) (show-paren-mode (or value 0))) :initialize 'custom-initialize-default :type 'boolean :group 'paren-showing :require 'paren)@end exampleIf a customization item has a type such as @code{hook} or @code{alist},which supports @code{:options}, you can add additional options to theitem, outside the @code{defcustom} declaration, by calling@code{custom-add-option}. For example, if you define a function@code{my-lisp-mode-initialization} intended to be called from@code{emacs-lisp-mode-hook}, you might want to add that to the list ofoptions for @code{emacs-lisp-mode-hook}, but not by editing itsdefinition. You can do it thus:@example(custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization)@end example@defun custom-add-option symbol optionTo the customization @var{symbol}, add @var{option}.The precise effect of adding @var{option} depends on the customizationtype of @var{symbol}.@end defunInternally, @code{defcustom} uses the symbol property@code{standard-value} to record the expression for the default value,and @code{saved-value} to record the value saved by the user with thecustomization buffer. The @code{saved-value} property is actually alist whose car is an expression which evaluates to the value.@node Customization Types@section Customization Types When you define a user option with @code{defcustom}, you must specifyits @dfn{customization type}. That is a Lisp object which describes (1)which values are legitimate and (2) how to display the value in thecustomization buffer for editing. You specify the customization type in @code{defcustom} with the@code{:type} keyword. The argument of @code{:type} is evaluated, butonly once when the @code{defcustom} is executed, so it isn't usefulfor the value to vary. Normally we use a quoted constant. Forexample:@example(defcustom diff-command "diff" "*The command to use to run diff." :type '(string) :group 'diff)@end example In general, a customization type is a list whose first element is asymbol, one of the customization type names defined in the followingsections. After this symbol come a number of arguments, depending onthe symbol. Between the type symbol and its arguments, you canoptionally write keyword-value pairs (@pxref{Type Keywords}). Some of the type symbols do not use any arguments; those are called@dfn{simple types}. For a simple type, if you do not use anykeyword-value pairs, you can omit the parentheses around the typesymbol. For example just @code{string} as a customization type isequivalent to @code{(string)}.@menu* Simple Types::* Composite Types::* Splicing into Lists::* Type Keywords::@end menuAll customization types are implemented as widgets; see @ref{Top, ,Introduction, widget, The Emacs Widget Library}, for details.@node Simple Types@subsection Simple Types This section describes all the simple customization types.@table @code@item sexpThe value may be any Lisp object that can be printed and read back. Youcan use @code{sexp} as a fall-back for any option, if you don't want totake the time to work out a more specific type to use.@item integerThe value must be an integer, and is represented textuallyin the customization buffer.@item numberThe value must be a number (floating point or integer), and isrepresented textually in the customization buffer.@item floatThe value must be a floating point number, and is representedtextually in the customization buffer.@item stringThe value must be a string, and the customization buffer shows just thecontents, with no delimiting @samp{"} characters and no quoting with@samp{\}.@item regexpLike @code{string} except that the string must be a valid regularexpression.@item characterThe value must be a character code. A character code is actually aninteger, but this type shows the value by inserting the character in thebuffer, rather than by showing the number.@item fileThe value must be a file name, and you can do completion with@kbd{M-@key{TAB}}.@item (file :must-match t)The value must be a file name for an existing file, and you can docompletion with @kbd{M-@key{TAB}}.@item directoryThe value must be a directory name, and you can do completion with@kbd{M-@key{TAB}}.@item hookThe value must be a list of functions (or a single function, but that isobsolete usage). This customization type is used for hook variables.You can use the @code{:options} keyword in a hook variable's@code{defcustom} to specify a list of functions recommended for use inthe hook; see @ref{Variable Definitions}.@item alistThe value must be a list of cons-cells, the @sc{car} of each cellrepresenting a key, and the @sc{cdr} of the same cell representing anassociated value. The user can add and delete key/value pairs, andedit both the key and the value of each pair.You can specify the key and value types like this:@smallexample(alist :key-type @var{key-type} :value-type @var{value-type})@end smallexample@noindentwhere @var{key-type} and @var{value-type} are customization typespecifications. The default key type is @code{sexp}, and the defaultvalue type is @code{sexp}.The user can add any key matching the specified key type, but you cangive some keys a preferential treatment by specifying them with the@code{:options} (see @ref{Variable Definitions}). The specified keyswill always be shown in the customize buffer (together with a suitablevalue), with a checkbox to include or exclude or disable the key/valuepair from the alist. The user will not be able to edit the keysspecified by the @code{:options} keyword argument.The argument to the @code{:options} keywords should be a list of optionspecifications. Ordinarily, the options are simply atoms, which are thespecified keys. For example:@smallexample:options '("foo" "bar" "baz")@end smallexample@noindentspecifies that there are three ``known'' keys, namely @code{"foo"},@code{"bar"} and @code{"baz"}, which will always be shown first.You may want to restrict the value type for specific keys, for example,the value associated with the @code{"bar"} key can only be an integer.You can specify this by using a list instead of an atom in the optionspecification. The first element will specify the key, like before,while the second element will specify the value type.@smallexample:options '("foo" ("bar" integer) "baz")@end smallexampleFinally, you may want to change how the key is presented. By default,the key is simply shown as a @code{const}, since the user cannot changethe special keys specified with the @code{:options} keyword. However,you may want to use a more specialized type for presenting the key, like@code{function-item} if you know it is a symbol with a function binding.This is done by using a customization type specification instead of asymbol for the key.@smallexample:options '("foo" ((function-item some-function) integer) "baz")@end smallexampleMany alists use lists with two elements, instead of cons cells. Forexample,@smallexample(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE).")@end smallexample@noindentinstead of@smallexample(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) "Each element is a cons-cell (KEY . VALUE).")@end smallexampleBecause of the way lists are implemented on top of cons cells, you cantreat @code{list-alist} in the example above as a cons cell alist, wherethe value type is a list with a single element containing the realvalue.@smallexample(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE)." :type '(alist :value-type (group integer)))@end smallexampleThe @code{group} widget is used here instead of @code{list} only becausethe formatting is better suited for the purpose.Similarily, you can have alists with more values associated with eachkey, using variations of this trick:@smallexample(defcustom person-data '(("brian" 50 t) ("dorith" 55 nil) ("ken" 52 t)) "Alist of basic info about people.Each element has the form (NAME AGE MALE-FLAG)." :type '(alist :value-type (group age boolean)))(defcustom pets '(("brian") ("dorith" "dog" "guppy") ("ken" "cat")) "Alist of people's pets.In an element (KEY . VALUE), KEY is the person's name,and the VALUE is a list of that person's pets." :type '(alist :value-type (repeat string)))@end smallexample@item plistThe @code{plist} custom type is similar to the @code{alist} (see above),except that the information is stored as a property list, i.e. a list ofthis form:@smallexample(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})@end smallexampleThe default @code{:key-type} for @code{plist} is @code{symbol},rather than @code{sexp}.@item symbolThe value must be a symbol. It appears in the customization buffer asthe name of the symbol.@item functionThe value must be either a lambda expression or a function name. Whenit is a function name, you can do completion with @kbd{M-@key{TAB}}.@item variableThe value must be a variable name, and you can do completion with@kbd{M-@key{TAB}}.@item faceThe value must be a symbol which is a face name, and you can docompletion with @kbd{M-@key{TAB}}.@item booleanThe value is boolean---either @code{nil} or @code{t}. Note that byusing @code{choice} and @code{const} together (see the next section),you can specify that the value must be @code{nil} or @code{t}, but alsospecify the text to describe each value in a way that fits the specificmeaning of the alternative.@item coding-systemThe value must be a coding-system name, and you can do completion with@kbd{M-@key{TAB}}.@item colorThe value must be a valid color name, and you can do completion with@kbd{M-@key{TAB}}. A sample is provided,@end table@node Composite Types@subsection Composite Types@cindex arguments (of composite type) When none of the simple types is appropriate, you can use compositetypes, which build new types from other types or from specified data.The specified types or data are called the @dfn{arguments} of thecomposite type. The composite type normally looks like this:@example(@var{constructor} @var{arguments}@dots{})@end example@noindentbut you can also add keyword-value pairs before the arguments, likethis:@example(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})@end example Here is a table of constructors and how to use them to writecomposite types:@table @code@item (cons @var{car-type} @var{cdr-type})The value must be a cons cell, its @sc{car} must fit @var{car-type}, andits @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons stringsymbol)} is a customization type which matches values such as@code{("foo" . foo)}.In the customization buffer, the @sc{car} and the @sc{cdr} aredisplayed and edited separately, each according to the typethat you specify for it.@item (list @var{element-types}@dots{})The value must be a list with exactly as many elements as the@var{element-types} you have specified; and each element must fit thecorresponding @var{element-type}.For example, @code{(list integer string function)} describes a list ofthree elements; the first element must be an integer, the second astring, and the third a function.In the customization buffer, each element is displayed and editedseparately, according to the type specified for it.@item (vector @var{element-types}@dots{})Like @code{list} except that the value must be a vector instead of alist. The elements work the same as in @code{list}.@item (choice @var{alternative-types}@dots{})The value must fit at least one of @var{alternative-types}.For example, @code{(choice integer string)} allows either aninteger or a string.In the customization buffer, the user selects one of the alternativesusing a menu, and can then edit the value in the usual way for thatalternative.Normally the strings in this menu are determined automatically from thechoices; however, you can specify different strings for the menu byincluding the @code{:tag} keyword in the alternatives. For example, ifan integer stands for a number of spaces, while a string is text to useverbatim, you might write the customization type this way,@example(choice (integer :tag "Number of spaces") (string :tag "Literal text"))@end example@noindentso that the menu offers @samp{Number of spaces} and @samp{Literal Text}.In any alternative for which @code{nil} is not a valid value, other thana @code{const}, you should specify a valid default for that alternativeusing the @code{:value} keyword. @xref{Type Keywords}.If some values are covered by more than one of the alternatives,customize will choose the first alternative that the value fits. Thismeans you should always list the most specific types first, and themost general last. Here's an example of proper usage:@example(choice (const :tag "Off" nil) symbol (sexp :tag "Other"))@end example@noindentThis way, the special value @code{nil} is not treated like othersymbols, and symbols are not treated like other Lisp expressions.@item (radio @var{element-types}@dots{})This is similar to @code{choice}, except that the choices are displayedusing `radio buttons' rather than a menu. This has the advantage ofdisplaying documentation for the choices when applicable and so is oftena good choice for a choice between constant functions(@code{function-item} customization types).@item (const @var{value})The value must be @var{value}---nothing else is allowed.The main use of @code{const} is inside of @code{choice}. For example,@code{(choice integer (const nil))} allows either an integer or@code{nil}.@code{:tag} is often used with @code{const}, inside of @code{choice}.For example,@example(choice (const :tag "Yes" t) (const :tag "No" nil) (const :tag "Ask" foo))@end example@noindentdescribes a variable for which @code{t} means yes, @code{nil} means no,and @code{foo} means ``ask.''@item (other @var{value})This alternative can match any Lisp value, but if the user chooses thisalternative, that selects the value @var{value}.The main use of @code{other} is as the last element of @code{choice}.For example,@example(choice (const :tag "Yes" t) (const :tag "No" nil) (other :tag "Ask" foo))@end example@noindentdescribes a variable for which @code{t} means yes, @code{nil} means no,and anything else means ``ask.'' If the user chooses @samp{Ask} fromthe menu of alternatives, that specifies the value @code{foo}; but anyother value (not @code{t}, @code{nil} or @code{foo}) displays as@samp{Ask}, just like @code{foo}.@item (function-item @var{function})Like @code{const}, but used for values which are functions. Thisdisplays the documentation string as well as the function name.The documentation string is either the one you specify with@code{:doc}, or @var{function}'s own documentation string.@item (variable-item @var{variable})Like @code{const}, but used for values which are variable names. Thisdisplays the documentation string as well as the variable name. Thedocumentation string is either the one you specify with @code{:doc}, or@var{variable}'s own documentation string.@item (set @var{types}@dots{})The value must be a list, and each element of the list must match one ofthe @var{types} specified.This appears in the customization buffer as a checklist, so that each of@var{types} may have either one corresponding element or none. It isnot possible to specify two different elements that match the same oneof @var{types}. For example, @code{(set integer symbol)} allows oneinteger and/or one symbol in the list; it does not allow multipleintegers or multiple symbols. As a result, it is rare to usenonspecific types such as @code{integer} in a @code{set}.Most often, the @var{types} in a @code{set} are @code{const} types, asshown here:@example(set (const :bold) (const :italic))@end exampleSometimes they describe possible elements in an alist:@example(set (cons :tag "Height" (const height) integer) (cons :tag "Width" (const width) integer))@end example@noindentThat lets the user specify a height value optionallyand a width value optionally.@item (repeat @var{element-type})The value must be a list and each element of the list must fit the type@var{element-type}. This appears in the customization buffer as alist of elements, with @samp{[INS]} and @samp{[DEL]} buttons for addingmore elements or removing elements.@item (restricted-sexp :match-alternatives @var{criteria})This is the most general composite type construct. The value may beany Lisp object that satisfies one of @var{criteria}. @var{criteria}should be a list, and each element should be one of thesepossibilities:@itemize @bullet@itemA predicate---that is, a function of one argument that has no sideeffects, and returns either @code{nil} or non-@code{nil} according tothe argument. Using a predicate in the list says that objects for whichthe predicate returns non-@code{nil} are acceptable.@itemA quoted constant---that is, @code{'@var{object}}. This sort of elementin the list says that @var{object} itself is an acceptable value.@end itemizeFor example,@example(restricted-sexp :match-alternatives (integerp 't 'nil))@end example@noindentallows integers, @code{t} and @code{nil} as legitimate values.The customization buffer shows all legitimate values using their readsyntax, and the user edits them textually.@end table Here is a table of the keywords you can use in keyword-value pairsin a composite type:@table @code@item :tag @var{tag}Use @var{tag} as the name of this alternative, for user communicationpurposes. This is useful for a type that appears inside of a@code{choice}.@item :match-alternatives @var{criteria}Use @var{criteria} to match possible values. This is used only in@code{restricted-sexp}.@item :args @var{argumentlist}Use the elements of @var{argumentlist} as the arguments of the typeconstruct. For instance, @code{(const :args (foo))} is equivalent to@code{(const foo)}. You rarely need to write @code{:args} explicitly,because normally the arguments are recognized automatically aswhatever follows the last keyword-value pair.@end table@node Splicing into Lists@subsection Splicing into Lists The @code{:inline} feature lets you splice a variable number ofelements into the middle of a list or vector. You use it in a@code{set}, @code{choice} or @code{repeat} type which appears among theelement-types of a @code{list} or @code{vector}. Normally, each of the element-types in a @code{list} or @code{vector}describes one and only one element of the list or vector. Thus, if anelement-type is a @code{repeat}, that specifies a list of unspecifiedlength which appears as one element. But when the element-type uses @code{:inline}, the value it matches ismerged directly into the containing sequence. For example, if itmatches a list with three elements, those become three elements of theoverall sequence. This is analogous to using @samp{,@@} in the backquoteconstruct. For example, to specify a list whose first element must be @code{baz}and whose remaining arguments should be zero or more of @code{foo} and@code{bar}, use this customization type:@example(list (const baz) (set :inline t (const foo) (const bar)))@end example@noindentThis matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}and @code{(baz foo bar)}. When the element-type is a @code{choice}, you use @code{:inline} notin the @code{choice} itself, but in (some of) the alternatives of the@code{choice}. For example, to match a list which must start with afile name, followed either by the symbol @code{t} or two strings, usethis customization type:@example(list file (choice (const t) (list :inline t string string)))@end example@noindentIf the user chooses the first alternative in the choice, then theoverall list has two elements and the second element is @code{t}. Ifthe user chooses the second alternative, then the overall list has threeelements and the second and third must be strings.@node Type Keywords@subsection Type KeywordsYou can specify keyword-argument pairs in a customization type after thetype name symbol. Here are the keywords you can use, and theirmeanings:@table @code@item :value @var{default}This is used for a type that appears as an alternative inside of@code{choice}; it specifies the default value to use, at first, if andwhen the user selects this alternative with the menu in thecustomization buffer.Of course, if the actual value of the option fits this alternative, itwill appear showing the actual value, not @var{default}.If @code{nil} is not a valid value for the alternative, then it isessential to specify a valid default with @code{:value}.@item :format @var{format-string}This string will be inserted in the buffer to represent the valuecorresponding to the type. The following @samp{%} escapes are availablefor use in @var{format-string}:@table @samp@item %[@var{button}%]Display the text @var{button} marked as a button. The @code{:action}attribute specifies what the button will do if the user invokes it;its value is a function which takes two arguments---the widget whichthe button appears in, and the event.There is no way to specify two different buttons with differentactions.@item %@{@var{sample}%@}Show @var{sample} in a special face specified by @code{:sample-face}.@item %vSubstitute the item's value. How the value is represented depends onthe kind of item, and (for variables) on the customization type.@item %dSubstitute the item's documentation string.@item %hLike @samp{%d}, but if the documentation string is more than one line,add an active field to control whether to show all of it or just thefirst line.@item %tSubstitute the tag here. You specify the tag with the @code{:tag}keyword.@item %%Display a literal @samp{%}.@end table@item :action @var{action}Perform @var{action} if the user clicks on a button.@item :button-face @var{face}Use the face @var{face} (a face name or a list of face names) for buttontext displayed with @samp{%[@dots{}%]}.@item :button-prefix @var{prefix}@itemx :button-suffix @var{suffix}These specify the text to display before and after a button.Each can be:@table @asis@item @code{nil}No text is inserted.@item a stringThe string is inserted literally.@item a symbolThe symbol's value is used.@end table@item :tag @var{tag}Use @var{tag} (a string) as the tag for the value (or part of the value)that corresponds to this type.@item :doc @var{doc}Use @var{doc} as the documentation string for this value (or part of thevalue) that corresponds to this type. In order for this to work, youmust specify a value for @code{:format}, and use @samp{%d} or @samp{%h}in that value.The usual reason to specify a documentation string for a type is toprovide more information about the meanings of alternatives inside a@code{:choice} type or the parts of some other composite type.@item :help-echo @var{motion-doc}When you move to this item with @code{widget-forward} or@code{widget-backward}, it will display the string @var{motion-doc} inthe echo area. In addition, @var{motion-doc} is used as the mouse@code{help-echo} string and may actually be a function or form evaluatedto yield a help string as for @code{help-echo} text properties.@c @xref{Text help-echo}.@item :match @var{function}Specify how to decide whether a value matches the type. Thecorresponding value, @var{function}, should be a function that acceptstwo arguments, a widget and a value; it should return non-@code{nil} ifthe value is acceptable.@ignore@item :indent @var{columns}Indent this item by @var{columns} columns. The indentation is used for@samp{%n}, and automatically for group names, for checklists and radiobuttons, and for editable lists. It affects the whole of theitem except for the first line.@item :offset @var{columns}An integer indicating how many extra spaces to indent the subitems ofthis item. By default, subitems are indented the same as their parent.@item :extra-offsetAn integer indicating how many extra spaces to add to this item'sindentation, compared to its parent.@item :notifyA function called each time the item or a subitem is changed. Thefunction is called with two or three arguments. The first argument isthe item itself, the second argument is the item that was changed, andthe third argument is the event leading to the change, if any.@item :menu-tagA tag used in the menu when the widget is used as an option in a@code{menu-choice} widget.@item :menu-tag-getA function used for finding the tag when the widget is used as an optionin a @code{menu-choice} widget. By default, the tag used will be either the@code{:menu-tag} or @code{:tag} property if present, or the @code{princ}representation of the @code{:value} property if not.@item :validateA function which takes a widget as an argument, and return @code{nil}if the widget's current value is valid for the widget. Otherwise, itshould return the widget containing the invalid data, and set thatwidget's @code{:error} property to a string explaining the error.You can use the function @code{widget-children-validate} for this job;it tests that all children of @var{widget} are valid.@item :tab-orderSpecify the order in which widgets are traversed with@code{widget-forward} or @code{widget-backward}. This is only partiallyimplemented.@enumerate a@itemWidgets with tabbing order @code{-1} are ignored.@item(Unimplemented) When on a widget with tabbing order @var{n}, go to thenext widget in the buffer with tabbing order @var{n+1} or @code{nil},whichever comes first.@itemWhen on a widget with no tabbing order specified, go to the next widgetin the buffer with a positive tabbing order, or @code{nil}@end enumerate@item :parentThe parent of a nested widget (e.g., a @code{menu-choice} item or anelement of a @code{editable-list} widget).@item :sibling-argsThis keyword is only used for members of a @code{radio-button-choice} or@code{checklist}. The value should be a list of extra keywordarguments, which will be used when creating the @code{radio-button} or@code{checkbox} associated with this item.@end ignore@end table