Commit | Line | Data |
---|---|---|
cc6d0d2c RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
fd897522 | 3 | @c Copyright (C) 1997, 1998, 1999 Free Software Foundation, Inc. |
cc6d0d2c RS |
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 | |
8 | ||
969fe9b5 RS |
9 | This chapter describes how to declare user options for customization, |
10 | and also customization groups for classifying them. We use the term | |
11 | @dfn{customization item} to include both kinds of customization | |
12 | definitions---as well as face definitions (@pxref{Defining Faces}). | |
cc6d0d2c RS |
13 | |
14 | @menu | |
15 | * Common Keywords:: | |
16 | * Group Definitions:: | |
17 | * Variable Definitions:: | |
cc6d0d2c RS |
18 | * Customization Types:: |
19 | @end menu | |
20 | ||
21 | @node Common Keywords | |
8241495d | 22 | @section Common Item Keywords |
cc6d0d2c | 23 | |
969fe9b5 RS |
24 | All kinds of customization declarations (for variables and groups, and |
25 | for faces) accept keyword arguments for specifying various information. | |
26 | This section describes some keywords that apply to all kinds. | |
cc6d0d2c | 27 | |
969fe9b5 RS |
28 | All of these keywords, except @code{:tag}, can be used more than once |
29 | in a given item. Each use of the keyword has an independent effect. | |
30 | The keyword @code{:tag} is an exception because any given item can only | |
31 | display one name. | |
cc6d0d2c RS |
32 | |
33 | @table @code | |
8241495d RS |
34 | @item :tag @var{label} |
35 | Use @var{label}, a string, instead of the item's name, to label the item | |
a9f0a989 RS |
36 | in customization menus and buffers. |
37 | ||
cc6d0d2c RS |
38 | @item :group @var{group} |
39 | Put this customization item in group @var{group}. When you use | |
40 | @code{:group} in a @code{defgroup}, it makes the new group a subgroup of | |
41 | @var{group}. | |
42 | ||
43 | If you use this keyword more than once, you can put a single item into | |
44 | more than one group. Displaying any of those groups will show this | |
8241495d | 45 | item. Please don't overdo this, since the result would be annoying. |
cc6d0d2c RS |
46 | |
47 | @item :link @var{link-data} | |
48 | Include an external link after the documentation string for this item. | |
49 | This is a sentence containing an active field which references some | |
50 | other documentation. | |
51 | ||
52 | There are three alternatives you can use for @var{link-data}: | |
53 | ||
54 | @table @code | |
55 | @item (custom-manual @var{info-node}) | |
56 | Link to an Info node; @var{info-node} is a string which specifies the | |
57 | node name, as in @code{"(emacs)Top"}. The link appears as | |
58 | @samp{[manual]} in the customization buffer. | |
59 | ||
60 | @item (info-link @var{info-node}) | |
61 | Like @code{custom-manual} except that the link appears | |
62 | in the customization buffer with the Info node name. | |
63 | ||
64 | @item (url-link @var{url}) | |
969fe9b5 RS |
65 | Link to a web page; @var{url} is a string which specifies the @sc{url}. |
66 | The link appears in the customization buffer as @var{url}. | |
cc6d0d2c RS |
67 | @end table |
68 | ||
69 | You can specify the text to use in the customization buffer by adding | |
70 | @code{:tag @var{name}} after the first element of the @var{link-data}; | |
71 | for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to | |
72 | the Emacs manual which appears in the buffer as @samp{foo}. | |
73 | ||
74 | An item can have more than one external link; however, most items have | |
75 | none at all. | |
76 | ||
77 | @item :load @var{file} | |
78 | Load file @var{file} (a string) before displaying this customization | |
79 | item. Loading is done with @code{load-library}, and only if the file is | |
80 | not already loaded. | |
81 | ||
82 | @item :require @var{feature} | |
83 | Require feature @var{feature} (a symbol) when installing a value for | |
84 | this item (an option or a face) that was saved using the customization | |
85 | feature. This is done by calling @code{require}. | |
86 | ||
87 | The most common reason to use @code{:require} is when a variable enables | |
88 | a feature such as a minor mode, and just setting the variable won't have | |
89 | any effect unless the code which implements the mode is loaded. | |
cc6d0d2c RS |
90 | @end table |
91 | ||
92 | @node Group Definitions | |
93 | @section Defining Custom Groups | |
94 | ||
969fe9b5 | 95 | Each Emacs Lisp package should have one main customization group which |
cc6d0d2c RS |
96 | contains all the options, faces and other groups in the package. If the |
97 | package has a small number of options and faces, use just one group and | |
98 | put everything in it. When there are more than twelve or so options and | |
99 | faces, then you should structure them into subgroups, and put the | |
969fe9b5 RS |
100 | subgroups under the package's main customization group. It is OK to |
101 | put some of the options and faces in the package's main group alongside | |
cc6d0d2c RS |
102 | the subgroups. |
103 | ||
969fe9b5 RS |
104 | The package's main or only group should be a member of one or more of |
105 | the standard customization groups. (To display the full list of them, | |
106 | use @kbd{M-x customize}.) Choose one or more of them (but not too | |
107 | many), and add your group to each of them using the @code{:group} | |
108 | keyword. | |
cc6d0d2c | 109 | |
969fe9b5 | 110 | The way to declare new customization groups is with @code{defgroup}. |
cc6d0d2c | 111 | |
cc6d0d2c RS |
112 | @defmac defgroup group members doc [keyword value]... |
113 | Declare @var{group} as a customization group containing @var{members}. | |
114 | Do not quote the symbol @var{group}. The argument @var{doc} specifies | |
8241495d RS |
115 | the documentation string for the group. It should not start with a |
116 | @samp{*} as in @code{defcustom}; that convention is for variables only. | |
cc6d0d2c | 117 | |
a9f0a989 RS |
118 | The argument @var{members} is a list specifying an initial set of |
119 | customization items to be members of the group. However, most often | |
969fe9b5 RS |
120 | @var{members} is @code{nil}, and you specify the group's members by |
121 | using the @code{:group} keyword when defining those members. | |
cc6d0d2c | 122 | |
a9f0a989 RS |
123 | If you want to specify group members through @var{members}, each element |
124 | should have the form @code{(@var{name} @var{widget})}. Here @var{name} | |
125 | is a symbol, and @var{widget} is a widget type for editing that symbol. | |
126 | Useful widgets are @code{custom-variable} for a variable, | |
127 | @code{custom-face} for a face, and @code{custom-group} for a group. | |
cc6d0d2c RS |
128 | |
129 | In addition to the common keywords (@pxref{Common Keywords}), you can | |
130 | use this keyword in @code{defgroup}: | |
131 | ||
132 | @table @code | |
133 | @item :prefix @var{prefix} | |
134 | If the name of an item in the group starts with @var{prefix}, then the | |
135 | tag for that item is constructed (by default) by omitting @var{prefix}. | |
136 | ||
137 | One group can have any number of prefixes. | |
138 | @end table | |
139 | @end defmac | |
140 | ||
969fe9b5 RS |
141 | The prefix-discarding feature is currently turned off, which means |
142 | that @code{:prefix} currently has no effect. We did this because we | |
143 | found that discarding the specified prefixes often led to confusing | |
144 | names for options. This happened because the people who wrote the | |
145 | @code{defgroup} definitions for various groups added @code{:prefix} | |
146 | keywords whenever they make logical sense---that is, whenever the | |
147 | variables in the library have a common prefix. | |
148 | ||
149 | In order to obtain good results with @code{:prefix}, it would be | |
150 | necessary to check the specific effects of discarding a particular | |
151 | prefix, given the specific items in a group and their names and | |
152 | documentation. If the resulting text is not clear, then @code{:prefix} | |
153 | should not be used in that case. | |
154 | ||
155 | It should be possible to recheck all the customization groups, delete | |
cc6d0d2c RS |
156 | the @code{:prefix} specifications which give unclear results, and then |
157 | turn this feature back on, if someone would like to do the work. | |
158 | ||
159 | @node Variable Definitions | |
160 | @section Defining Customization Variables | |
161 | ||
969fe9b5 | 162 | Use @code{defcustom} to declare user-editable variables. |
cc6d0d2c | 163 | |
969fe9b5 RS |
164 | @defmac defcustom option default doc [keyword value]... |
165 | Declare @var{option} as a customizable user option variable. Do not | |
166 | quote @var{option}. The argument @var{doc} specifies the documentation | |
8241495d RS |
167 | string for the variable; it should normally start with a @samp{*}. This |
168 | marks the variable, for other purposes, as one that users may want to | |
169 | customize. | |
969fe9b5 RS |
170 | |
171 | If @var{option} is void, @code{defcustom} initializes it to | |
172 | @var{default}. @var{default} should be an expression to compute the | |
a9f0a989 | 173 | value; be careful in writing it, because it can be evaluated on more |
cc6d0d2c | 174 | than one occasion. |
8241495d RS |
175 | |
176 | When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp | |
177 | mode (@code{eval-defun}), a special feature of @code{eval-defun} | |
178 | arranges to set the variable unconditionally, without testing whether | |
179 | its value is void. (The same feature applies to @code{defvar}.) | |
180 | @xref{Defining Variables}. | |
7dd3d99f | 181 | @end defmac |
cc6d0d2c | 182 | |
7dd3d99f | 183 | @code{defcustom} accepts the following additional keywords: |
cc6d0d2c RS |
184 | |
185 | @table @code | |
186 | @item :type @var{type} | |
187 | Use @var{type} as the data type for this option. It specifies which | |
188 | values are legitimate, and how to display the value. | |
189 | @xref{Customization Types}, for more information. | |
190 | ||
191 | @item :options @var{list} | |
192 | Specify @var{list} as the list of reasonable values for use in this | |
b6954afd RS |
193 | option. The user is not restricted to using only these values, but they |
194 | are offered as convenient alternatives. | |
cc6d0d2c | 195 | |
b6954afd RS |
196 | This is meaningful only for certain types, currently including |
197 | @code{hook}, @code{plist} and @code{alist}. See the definition of the | |
198 | individual types for a description of how to use @code{:options}. | |
cc6d0d2c RS |
199 | |
200 | @item :version @var{version} | |
a9f0a989 RS |
201 | This option specifies that the variable was first introduced, or its |
202 | default value was changed, in Emacs version @var{version}. The value | |
203 | @var{version} must be a string. For example, | |
cc6d0d2c RS |
204 | |
205 | @example | |
206 | (defcustom foo-max 34 | |
207 | "*Maximum number of foo's allowed." | |
208 | :type 'integer | |
209 | :group 'foo | |
210 | :version "20.3") | |
211 | @end example | |
212 | ||
213 | @item :set @var{setfunction} | |
214 | Specify @var{setfunction} as the way to change the value of this option. | |
215 | The function @var{setfunction} should take two arguments, a symbol and | |
216 | the new value, and should do whatever is necessary to update the value | |
217 | properly for this option (which may not mean simply setting the option | |
218 | as a Lisp variable). The default for @var{setfunction} is | |
219 | @code{set-default}. | |
220 | ||
221 | @item :get @var{getfunction} | |
222 | Specify @var{getfunction} as the way to extract the value of this | |
223 | option. The function @var{getfunction} should take one argument, a | |
224 | symbol, and should return the ``current value'' for that symbol (which | |
225 | need not be the symbol's Lisp value). The default is | |
226 | @code{default-value}. | |
227 | ||
228 | @item :initialize @var{function} | |
229 | @var{function} should be a function used to initialize the variable when | |
230 | the @code{defcustom} is evaluated. It should take two arguments, the | |
231 | symbol and value. Here are some predefined functions meant for use in | |
232 | this way: | |
233 | ||
234 | @table @code | |
235 | @item custom-initialize-set | |
969fe9b5 RS |
236 | Use the variable's @code{:set} function to initialize the variable, but |
237 | do not reinitialize it if it is already non-void. This is the default | |
cc6d0d2c RS |
238 | @code{:initialize} function. |
239 | ||
240 | @item custom-initialize-default | |
969fe9b5 RS |
241 | Like @code{custom-initialize-set}, but use the function |
242 | @code{set-default} to set the variable, instead of the variable's | |
243 | @code{:set} function. This is the usual choice for a variable whose | |
244 | @code{:set} function enables or disables a minor mode; with this choice, | |
245 | defining the variable will not call the minor mode function, but | |
246 | customizing the variable will do so. | |
cc6d0d2c RS |
247 | |
248 | @item custom-initialize-reset | |
969fe9b5 RS |
249 | Always use the @code{:set} function to initialize the variable. If the |
250 | variable is already non-void, reset it by calling the @code{:set} | |
251 | function using the current value (returned by the @code{:get} method). | |
cc6d0d2c RS |
252 | |
253 | @item custom-initialize-changed | |
969fe9b5 RS |
254 | Use the @code{:set} function to initialize the variable, if it is |
255 | already set or has been customized; otherwise, just use | |
256 | @code{set-default}. | |
cc6d0d2c | 257 | @end table |
390538c3 RS |
258 | |
259 | @item :set-after @var{variables} | |
260 | When setting variables according to saved customizations, make sure to | |
261 | set the variables @var{variables} before this one; in other words, delay | |
262 | setting this variable until after those others have been handled. Use | |
263 | @code{:set-after} if setting this variable won't work properly unless | |
264 | those other variables already have their intended values. | |
969fe9b5 | 265 | @end table |
cc6d0d2c | 266 | |
969fe9b5 | 267 | The @code{:require} option is useful for an option that turns on the |
cc6d0d2c RS |
268 | operation of a certain feature. Assuming that the package is coded to |
269 | check the value of the option, you still need to arrange for the package | |
969fe9b5 RS |
270 | to be loaded. You can do that with @code{:require}. @xref{Common |
271 | Keywords}. Here is an example, from the library @file{paren.el}: | |
272 | ||
273 | @example | |
274 | (defcustom show-paren-mode nil | |
29b677db | 275 | "Toggle Show Paren mode..." |
969fe9b5 | 276 | :set (lambda (symbol value) |
a9f0a989 | 277 | (show-paren-mode (or value 0))) |
969fe9b5 RS |
278 | :initialize 'custom-initialize-default |
279 | :type 'boolean | |
280 | :group 'paren-showing | |
281 | :require 'paren) | |
282 | @end example | |
cc6d0d2c | 283 | |
b6954afd RS |
284 | If a customization item has a type such as @code{hook} or @code{alist}, |
285 | which supports @code{:options}, you can add additional options to the | |
286 | item, outside the @code{defcustom} declaration, by calling | |
287 | @code{custom-add-option}. For example, if you define a function | |
288 | @code{my-lisp-mode-initialization} intended to be called from | |
289 | @code{emacs-lisp-mode-hook}, you might want to add that to the list of | |
290 | options for @code{emacs-lisp-mode-hook}, but not by editing its | |
291 | definition. You can do it thus: | |
292 | ||
293 | @example | |
8241495d RS |
294 | (custom-add-option 'emacs-lisp-mode-hook |
295 | 'my-lisp-mode-initialization) | |
b6954afd | 296 | @end example |
cc6d0d2c RS |
297 | |
298 | @defun custom-add-option symbol option | |
b6954afd | 299 | To the customization @var{symbol}, add @var{option}. |
cc6d0d2c | 300 | |
b6954afd RS |
301 | The precise effect of adding @var{option} depends on the customization |
302 | type of @var{symbol}. | |
cc6d0d2c | 303 | @end defun |
cc6d0d2c RS |
304 | |
305 | Internally, @code{defcustom} uses the symbol property | |
306 | @code{standard-value} to record the expression for the default value, | |
307 | and @code{saved-value} to record the value saved by the user with the | |
308 | customization buffer. The @code{saved-value} property is actually a | |
309 | list whose car is an expression which evaluates to the value. | |
310 | ||
cc6d0d2c RS |
311 | @node Customization Types |
312 | @section Customization Types | |
313 | ||
314 | When you define a user option with @code{defcustom}, you must specify | |
969fe9b5 | 315 | its @dfn{customization type}. That is a Lisp object which describes (1) |
cc6d0d2c RS |
316 | which values are legitimate and (2) how to display the value in the |
317 | customization buffer for editing. | |
318 | ||
319 | You specify the customization type in @code{defcustom} with the | |
320 | @code{:type} keyword. The argument of @code{:type} is evaluated; since | |
969fe9b5 | 321 | types that vary at run time are rarely useful, normally you use a quoted |
cc6d0d2c RS |
322 | constant. For example: |
323 | ||
324 | @example | |
325 | (defcustom diff-command "diff" | |
326 | "*The command to use to run diff." | |
969fe9b5 | 327 | :type '(string) |
cc6d0d2c RS |
328 | :group 'diff) |
329 | @end example | |
330 | ||
969fe9b5 RS |
331 | In general, a customization type is a list whose first element is a |
332 | symbol, one of the customization type names defined in the following | |
333 | sections. After this symbol come a number of arguments, depending on | |
334 | the symbol. Between the type symbol and its arguments, you can | |
335 | optionally write keyword-value pairs (@pxref{Type Keywords}). | |
cc6d0d2c | 336 | |
969fe9b5 RS |
337 | Some of the type symbols do not use any arguments; those are called |
338 | @dfn{simple types}. For a simple type, if you do not use any | |
339 | keyword-value pairs, you can omit the parentheses around the type | |
340 | symbol. For example just @code{string} as a customization type is | |
341 | equivalent to @code{(string)}. | |
cc6d0d2c RS |
342 | |
343 | @menu | |
344 | * Simple Types:: | |
345 | * Composite Types:: | |
346 | * Splicing into Lists:: | |
347 | * Type Keywords:: | |
348 | @end menu | |
349 | ||
350 | @node Simple Types | |
351 | @subsection Simple Types | |
352 | ||
353 | This section describes all the simple customization types. | |
354 | ||
355 | @table @code | |
356 | @item sexp | |
357 | The value may be any Lisp object that can be printed and read back. You | |
358 | can use @code{sexp} as a fall-back for any option, if you don't want to | |
359 | take the time to work out a more specific type to use. | |
360 | ||
361 | @item integer | |
362 | The value must be an integer, and is represented textually | |
363 | in the customization buffer. | |
364 | ||
365 | @item number | |
366 | The value must be a number, and is represented textually in the | |
367 | customization buffer. | |
368 | ||
369 | @item string | |
370 | The value must be a string, and the customization buffer shows just the | |
969fe9b5 RS |
371 | contents, with no delimiting @samp{"} characters and no quoting with |
372 | @samp{\}. | |
cc6d0d2c RS |
373 | |
374 | @item regexp | |
969fe9b5 RS |
375 | Like @code{string} except that the string must be a valid regular |
376 | expression. | |
cc6d0d2c RS |
377 | |
378 | @item character | |
379 | The value must be a character code. A character code is actually an | |
380 | integer, but this type shows the value by inserting the character in the | |
381 | buffer, rather than by showing the number. | |
382 | ||
383 | @item file | |
384 | The value must be a file name, and you can do completion with | |
385 | @kbd{M-@key{TAB}}. | |
386 | ||
387 | @item (file :must-match t) | |
388 | The value must be a file name for an existing file, and you can do | |
389 | completion with @kbd{M-@key{TAB}}. | |
390 | ||
391 | @item directory | |
392 | The value must be a directory name, and you can do completion with | |
393 | @kbd{M-@key{TAB}}. | |
394 | ||
a9f0a989 RS |
395 | @item hook |
396 | The value must be a list of functions (or a single function, but that is | |
397 | obsolete usage). This customization type is used for hook variables. | |
1911e6e5 RS |
398 | You can use the @code{:options} keyword in a hook variable's |
399 | @code{defcustom} to specify a list of functions recommended for use in | |
400 | the hook; see @ref{Variable Definitions}. | |
a9f0a989 | 401 | |
b6954afd | 402 | @item alist |
08f0f5e9 KH |
403 | The value must be a list of cons-cells, the @sc{car} of each cell |
404 | representing a key, and the @sc{cdr} of the same cell representing an | |
405 | associated value. The user can add and delete key/value pairs, and | |
b6954afd RS |
406 | edit both the key and the value of each pair. |
407 | ||
408 | You can specify the key and value types like this: | |
409 | ||
8241495d RS |
410 | @smallexample |
411 | (alist :key-type @var{key-type} :value-type @var{value-type}) | |
412 | @end smallexample | |
b6954afd RS |
413 | |
414 | @noindent | |
415 | where @var{key-type} and @var{value-type} are customization type | |
416 | specifications. The default key type is @code{sexp}, and the default | |
417 | value type is @code{sexp}. | |
418 | ||
419 | The user can add any key matching the specified key type, but you can | |
420 | give some keys a preferential treatment by specifying them with the | |
421 | @code{:options} (see @ref{Variable Definitions}). The specified keys | |
422 | will always be shown in the customize buffer (together with a suitable | |
423 | value), with a checkbox to include or exclude or disable the key/value | |
424 | pair from the alist. The user will not be able to edit the keys | |
425 | specified by the @code{:options} keyword argument. | |
426 | ||
427 | The argument to the @code{:options} keywords should be a list of option | |
428 | specifications. Ordinarily, the options are simply atoms, which are the | |
429 | specified keys. For example: | |
430 | ||
8241495d | 431 | @smallexample |
b6954afd | 432 | :options '("foo" "bar" "baz") |
8241495d | 433 | @end smallexample |
b6954afd RS |
434 | |
435 | @noindent | |
436 | specifies that there are three ``known'' keys, namely @code{"foo"}, | |
437 | @code{"bar"} and @code{"baz"}, which will always be shown first. | |
438 | ||
439 | You may want to restrict the value type for specific keys, for example, | |
440 | the value associated with the @code{"bar"} key can only be an integer. | |
441 | You can specify this by using a list instead of an atom in the option | |
442 | specification. The first element will specify the key, like before, | |
443 | while the second element will specify the value type. | |
444 | ||
8241495d | 445 | @smallexample |
b6954afd | 446 | :options '("foo" ("bar" integer) "baz") |
8241495d | 447 | @end smallexample |
b6954afd RS |
448 | |
449 | Finally, you may want to change how the key is presented. By default, | |
450 | the key is simply shown as a @code{const}, since the user cannot change | |
451 | the special keys specified with the @code{:options} keyword. However, | |
452 | you may want to use a more specialized type for presenting the key, like | |
453 | @code{function-item} if you know it is a symbol with a function binding. | |
454 | This is done by using a customization type specification instead of a | |
455 | symbol for the key. | |
456 | ||
8241495d | 457 | @smallexample |
b6954afd | 458 | :options '("foo" ((function-item some-function) integer) "baz") |
8241495d | 459 | @end smallexample |
b6954afd | 460 | |
08f0f5e9 | 461 | Many alists use lists with two elements, instead of cons cells. For |
b6954afd RS |
462 | example, |
463 | ||
8241495d | 464 | @smallexample |
b6954afd RS |
465 | (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) |
466 | "Each element is a list of the form (KEY VALUE).") | |
8241495d | 467 | @end smallexample |
b6954afd RS |
468 | |
469 | @noindent | |
470 | instead of | |
471 | ||
8241495d | 472 | @smallexample |
b6954afd RS |
473 | (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) |
474 | "Each element is a cons-cell (KEY . VALUE).") | |
8241495d | 475 | @end smallexample |
b6954afd RS |
476 | |
477 | Because of the way lists are implemented on top of cons cells, you can | |
478 | treat @code{list-alist} in the example above as a cons cell alist, where | |
479 | the value type is a list with a single element containing the real | |
480 | value. | |
481 | ||
8241495d | 482 | @smallexample |
b6954afd RS |
483 | (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) |
484 | "Each element is a list of the form (KEY VALUE)." | |
485 | :type '(alist :value-type (group integer))) | |
8241495d | 486 | @end smallexample |
b6954afd RS |
487 | |
488 | The @code{group} widget is used here instead of @code{list} only because | |
489 | the formatting is better suited for the purpose. | |
490 | ||
491 | Similarily, you can have alists with more values associated with each | |
492 | key, using variations of this trick: | |
493 | ||
8241495d | 494 | @smallexample |
b6954afd RS |
495 | (defcustom person-data '(("brian" 50 t) |
496 | ("dorith" 55 nil) | |
497 | ("ken" 52 t)) | |
3d3df9e1 RS |
498 | "Alist of basic info about people. |
499 | Each element has the form (NAME AGE MALE-FLAG)." | |
b6954afd RS |
500 | :type '(alist :value-type (group age boolean))) |
501 | ||
502 | (defcustom pets '(("brian") | |
503 | ("dorith" "dog" "guppy") | |
504 | ("ken" "cat")) | |
3d3df9e1 RS |
505 | "Alist of people's pets. |
506 | In an element (KEY . VALUE), KEY is the person's name, | |
507 | and the VALUE is a list of that person's pets." | |
b6954afd | 508 | :type '(alist :value-type (repeat string))) |
8241495d | 509 | @end smallexample |
b6954afd RS |
510 | |
511 | @item plist | |
512 | The @code{plist} custom type is similar to the @code{alist} (see above), | |
513 | except that the information is stored as a property list, i.e. a list of | |
514 | this form: | |
515 | ||
8241495d | 516 | @smallexample |
b6954afd | 517 | (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{}) |
8241495d | 518 | @end smallexample |
b6954afd RS |
519 | |
520 | The default @code{:key-type} for @code{plist} is @code{symbol}, | |
521 | rather than @code{sexp}. | |
522 | ||
cc6d0d2c RS |
523 | @item symbol |
524 | The value must be a symbol. It appears in the customization buffer as | |
525 | the name of the symbol. | |
526 | ||
527 | @item function | |
528 | The value must be either a lambda expression or a function name. When | |
529 | it is a function name, you can do completion with @kbd{M-@key{TAB}}. | |
530 | ||
531 | @item variable | |
532 | The value must be a variable name, and you can do completion with | |
533 | @kbd{M-@key{TAB}}. | |
534 | ||
a9f0a989 RS |
535 | @item face |
536 | The value must be a symbol which is a face name, and you can do | |
537 | completion with @kbd{M-@key{TAB}}. | |
538 | ||
cc6d0d2c | 539 | @item boolean |
969fe9b5 RS |
540 | The value is boolean---either @code{nil} or @code{t}. Note that by |
541 | using @code{choice} and @code{const} together (see the next section), | |
542 | you can specify that the value must be @code{nil} or @code{t}, but also | |
543 | specify the text to describe each value in a way that fits the specific | |
544 | meaning of the alternative. | |
cc6d0d2c RS |
545 | @end table |
546 | ||
547 | @node Composite Types | |
548 | @subsection Composite Types | |
549 | ||
550 | When none of the simple types is appropriate, you can use composite | |
969fe9b5 RS |
551 | types, which build new types from other types. Here are several ways of |
552 | doing that: | |
cc6d0d2c RS |
553 | |
554 | @table @code | |
555 | @item (restricted-sexp :match-alternatives @var{criteria}) | |
556 | The value may be any Lisp object that satisfies one of @var{criteria}. | |
a9f0a989 | 557 | @var{criteria} should be a list, and each element should be |
cc6d0d2c RS |
558 | one of these possibilities: |
559 | ||
560 | @itemize @bullet | |
561 | @item | |
a9f0a989 RS |
562 | A predicate---that is, a function of one argument that has no side |
563 | effects, and returns either @code{nil} or non-@code{nil} according to | |
564 | the argument. Using a predicate in the list says that objects for which | |
565 | the predicate returns non-@code{nil} are acceptable. | |
cc6d0d2c RS |
566 | |
567 | @item | |
a9f0a989 RS |
568 | A quoted constant---that is, @code{'@var{object}}. This sort of element |
569 | in the list says that @var{object} itself is an acceptable value. | |
cc6d0d2c RS |
570 | @end itemize |
571 | ||
572 | For example, | |
573 | ||
574 | @example | |
a9f0a989 RS |
575 | (restricted-sexp :match-alternatives |
576 | (integerp 't 'nil)) | |
cc6d0d2c RS |
577 | @end example |
578 | ||
579 | @noindent | |
580 | allows integers, @code{t} and @code{nil} as legitimate values. | |
581 | ||
582 | The customization buffer shows all legitimate values using their read | |
583 | syntax, and the user edits them textually. | |
584 | ||
585 | @item (cons @var{car-type} @var{cdr-type}) | |
586 | The value must be a cons cell, its @sc{car} must fit @var{car-type}, and | |
a9f0a989 | 587 | its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string |
cc6d0d2c RS |
588 | symbol)} is a customization type which matches values such as |
589 | @code{("foo" . foo)}. | |
590 | ||
969fe9b5 | 591 | In the customization buffer, the @sc{car} and the @sc{cdr} are |
cc6d0d2c RS |
592 | displayed and edited separately, each according to the type |
593 | that you specify for it. | |
594 | ||
595 | @item (list @var{element-types}@dots{}) | |
596 | The value must be a list with exactly as many elements as the | |
597 | @var{element-types} you have specified; and each element must fit the | |
598 | corresponding @var{element-type}. | |
599 | ||
600 | For example, @code{(list integer string function)} describes a list of | |
601 | three elements; the first element must be an integer, the second a | |
602 | string, and the third a function. | |
603 | ||
a9f0a989 | 604 | In the customization buffer, each element is displayed and edited |
cc6d0d2c RS |
605 | separately, according to the type specified for it. |
606 | ||
607 | @item (vector @var{element-types}@dots{}) | |
608 | Like @code{list} except that the value must be a vector instead of a | |
609 | list. The elements work the same as in @code{list}. | |
610 | ||
611 | @item (choice @var{alternative-types}...) | |
612 | The value must fit at least one of @var{alternative-types}. | |
613 | For example, @code{(choice integer string)} allows either an | |
614 | integer or a string. | |
615 | ||
616 | In the customization buffer, the user selects one of the alternatives | |
617 | using a menu, and can then edit the value in the usual way for that | |
618 | alternative. | |
619 | ||
620 | Normally the strings in this menu are determined automatically from the | |
621 | choices; however, you can specify different strings for the menu by | |
622 | including the @code{:tag} keyword in the alternatives. For example, if | |
623 | an integer stands for a number of spaces, while a string is text to use | |
624 | verbatim, you might write the customization type this way, | |
625 | ||
a9f0a989 | 626 | @example |
cc6d0d2c RS |
627 | (choice (integer :tag "Number of spaces") |
628 | (string :tag "Literal text")) | |
a9f0a989 | 629 | @end example |
cc6d0d2c RS |
630 | |
631 | @noindent | |
632 | so that the menu offers @samp{Number of spaces} and @samp{Literal Text}. | |
633 | ||
969fe9b5 RS |
634 | In any alternative for which @code{nil} is not a valid value, other than |
635 | a @code{const}, you should specify a valid default for that alternative | |
636 | using the @code{:value} keyword. @xref{Type Keywords}. | |
637 | ||
cc6d0d2c RS |
638 | @item (const @var{value}) |
639 | The value must be @var{value}---nothing else is allowed. | |
640 | ||
641 | The main use of @code{const} is inside of @code{choice}. For example, | |
642 | @code{(choice integer (const nil))} allows either an integer or | |
969fe9b5 RS |
643 | @code{nil}. |
644 | ||
645 | @code{:tag} is often used with @code{const}, inside of @code{choice}. | |
646 | For example, | |
647 | ||
a9f0a989 | 648 | @example |
969fe9b5 RS |
649 | (choice (const :tag "Yes" t) |
650 | (const :tag "No" nil) | |
651 | (const :tag "Ask" foo)) | |
a9f0a989 | 652 | @end example |
cc6d0d2c | 653 | |
da03dc1d RS |
654 | @noindent |
655 | describes a variable for which @code{t} means yes, @code{nil} means no, | |
656 | and @code{foo} means ``ask.'' | |
657 | ||
658 | @item (other @var{value}) | |
659 | This alternative can match any Lisp value, but if the user chooses this | |
660 | alternative, that selects the value @var{value}. | |
661 | ||
662 | The main use of @code{other} is as the last element of @code{choice}. | |
663 | For example, | |
664 | ||
665 | @example | |
666 | (choice (const :tag "Yes" t) | |
667 | (const :tag "No" nil) | |
668 | (other :tag "Ask" foo)) | |
669 | @end example | |
670 | ||
671 | @noindent | |
672 | describes a variable for which @code{t} means yes, @code{nil} means no, | |
673 | and anything else means ``ask.'' If the user chooses @samp{Ask} from | |
674 | the menu of alternatives, that specifies the value @code{foo}; but any | |
675 | other value (not @code{t}, @code{nil} or @code{foo}) displays as | |
676 | @samp{Ask}, just like @code{foo}. | |
677 | ||
cc6d0d2c RS |
678 | @item (function-item @var{function}) |
679 | Like @code{const}, but used for values which are functions. This | |
969fe9b5 RS |
680 | displays the documentation string as well as the function name. |
681 | The documentation string is either the one you specify with | |
682 | @code{:doc}, or @var{function}'s own documentation string. | |
cc6d0d2c RS |
683 | |
684 | @item (variable-item @var{variable}) | |
685 | Like @code{const}, but used for values which are variable names. This | |
969fe9b5 RS |
686 | displays the documentation string as well as the variable name. The |
687 | documentation string is either the one you specify with @code{:doc}, or | |
688 | @var{variable}'s own documentation string. | |
cc6d0d2c | 689 | |
1f447a50 KH |
690 | @item (set @var{types}@dots{}) |
691 | The value must be a list, and each element of the list must match one of | |
692 | the @var{types} specified. | |
693 | ||
694 | This appears in the customization buffer as a checklist, so that each of | |
695 | @var{types} may have either one corresponding element or none. It is | |
696 | not possible to specify two different elements that match the same one | |
697 | of @var{types}. For example, @code{(set integer symbol)} allows one | |
698 | integer and/or one symbol in the list; it does not allow multiple | |
699 | integers or multiple symbols. As a result, it is rare to use | |
700 | nonspecific types such as @code{integer} in a @code{set}. | |
701 | ||
702 | Most often, the @var{types} in a @code{set} are @code{const} types, as | |
703 | shown here: | |
704 | ||
705 | @example | |
706 | (set (const :bold) (const :italic)) | |
707 | @end example | |
708 | ||
709 | Sometimes they describe possible elements in an alist: | |
710 | ||
711 | @example | |
712 | (set (cons :tag "Height" (const height) integer) | |
713 | (cons :tag "Width" (const width) integer)) | |
714 | @end example | |
715 | ||
716 | @noindent | |
717 | That lets the user specify a height value optionally | |
718 | and a width value optionally. | |
cc6d0d2c RS |
719 | |
720 | @item (repeat @var{element-type}) | |
721 | The value must be a list and each element of the list must fit the type | |
722 | @var{element-type}. This appears in the customization buffer as a | |
723 | list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding | |
724 | more elements or removing elements. | |
725 | @end table | |
726 | ||
727 | @node Splicing into Lists | |
728 | @subsection Splicing into Lists | |
729 | ||
730 | The @code{:inline} feature lets you splice a variable number of | |
731 | elements into the middle of a list or vector. You use it in a | |
732 | @code{set}, @code{choice} or @code{repeat} type which appears among the | |
733 | element-types of a @code{list} or @code{vector}. | |
734 | ||
735 | Normally, each of the element-types in a @code{list} or @code{vector} | |
736 | describes one and only one element of the list or vector. Thus, if an | |
737 | element-type is a @code{repeat}, that specifies a list of unspecified | |
738 | length which appears as one element. | |
739 | ||
740 | But when the element-type uses @code{:inline}, the value it matches is | |
741 | merged directly into the containing sequence. For example, if it | |
742 | matches a list with three elements, those become three elements of the | |
743 | overall sequence. This is analogous to using @samp{,@@} in the backquote | |
744 | construct. | |
745 | ||
746 | For example, to specify a list whose first element must be @code{t} | |
747 | and whose remaining arguments should be zero or more of @code{foo} and | |
748 | @code{bar}, use this customization type: | |
749 | ||
750 | @example | |
751 | (list (const t) (set :inline t foo bar)) | |
752 | @end example | |
753 | ||
754 | @noindent | |
755 | This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)} | |
756 | and @code{(t foo bar)}. | |
757 | ||
758 | When the element-type is a @code{choice}, you use @code{:inline} not | |
759 | in the @code{choice} itself, but in (some of) the alternatives of the | |
760 | @code{choice}. For example, to match a list which must start with a | |
761 | file name, followed either by the symbol @code{t} or two strings, use | |
762 | this customization type: | |
763 | ||
764 | @example | |
765 | (list file | |
766 | (choice (const t) | |
767 | (list :inline t string string))) | |
768 | @end example | |
769 | ||
770 | @noindent | |
771 | If the user chooses the first alternative in the choice, then the | |
772 | overall list has two elements and the second element is @code{t}. If | |
773 | the user chooses the second alternative, then the overall list has three | |
774 | elements and the second and third must be strings. | |
775 | ||
776 | @node Type Keywords | |
777 | @subsection Type Keywords | |
778 | ||
779 | You can specify keyword-argument pairs in a customization type after the | |
780 | type name symbol. Here are the keywords you can use, and their | |
781 | meanings: | |
782 | ||
783 | @table @code | |
784 | @item :value @var{default} | |
785 | This is used for a type that appears as an alternative inside of | |
969fe9b5 | 786 | @code{choice}; it specifies the default value to use, at first, if and |
cc6d0d2c RS |
787 | when the user selects this alternative with the menu in the |
788 | customization buffer. | |
789 | ||
790 | Of course, if the actual value of the option fits this alternative, it | |
791 | will appear showing the actual value, not @var{default}. | |
792 | ||
969fe9b5 RS |
793 | If @code{nil} is not a valid value for the alternative, then it is |
794 | essential to specify a valid default with @code{:value}. | |
795 | ||
cc6d0d2c RS |
796 | @item :format @var{format-string} |
797 | This string will be inserted in the buffer to represent the value | |
798 | corresponding to the type. The following @samp{%} escapes are available | |
799 | for use in @var{format-string}: | |
800 | ||
801 | @table @samp | |
cc6d0d2c RS |
802 | @item %[@var{button}%] |
803 | Display the text @var{button} marked as a button. The @code{:action} | |
804 | attribute specifies what the button will do if the user invokes it; | |
805 | its value is a function which takes two arguments---the widget which | |
806 | the button appears in, and the event. | |
807 | ||
808 | There is no way to specify two different buttons with different | |
969fe9b5 | 809 | actions. |
cc6d0d2c RS |
810 | |
811 | @item %@{@var{sample}%@} | |
812 | Show @var{sample} in a special face specified by @code{:sample-face}. | |
813 | ||
814 | @item %v | |
815 | Substitute the item's value. How the value is represented depends on | |
816 | the kind of item, and (for variables) on the customization type. | |
817 | ||
818 | @item %d | |
819 | Substitute the item's documentation string. | |
820 | ||
821 | @item %h | |
822 | Like @samp{%d}, but if the documentation string is more than one line, | |
823 | add an active field to control whether to show all of it or just the | |
824 | first line. | |
825 | ||
826 | @item %t | |
827 | Substitute the tag here. You specify the tag with the @code{:tag} | |
828 | keyword. | |
829 | ||
830 | @item %% | |
831 | Display a literal @samp{%}. | |
832 | @end table | |
833 | ||
969fe9b5 RS |
834 | @item :action @var{action} |
835 | Perform @var{action} if the user clicks on a button. | |
836 | ||
cc6d0d2c | 837 | @item :button-face @var{face} |
969fe9b5 RS |
838 | Use the face @var{face} (a face name or a list of face names) for button |
839 | text displayed with @samp{%[@dots{}%]}. | |
cc6d0d2c | 840 | |
969fe9b5 RS |
841 | @item :button-prefix @var{prefix} |
842 | @itemx :button-suffix @var{suffix} | |
cc6d0d2c RS |
843 | These specify the text to display before and after a button. |
844 | Each can be: | |
845 | ||
846 | @table @asis | |
847 | @item @code{nil} | |
848 | No text is inserted. | |
849 | ||
850 | @item a string | |
851 | The string is inserted literally. | |
852 | ||
853 | @item a symbol | |
854 | The symbol's value is used. | |
855 | @end table | |
856 | ||
969fe9b5 RS |
857 | @item :tag @var{tag} |
858 | Use @var{tag} (a string) as the tag for the value (or part of the value) | |
859 | that corresponds to this type. | |
860 | ||
cc6d0d2c | 861 | @item :doc @var{doc} |
969fe9b5 RS |
862 | Use @var{doc} as the documentation string for this value (or part of the |
863 | value) that corresponds to this type. In order for this to work, you | |
864 | must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} | |
865 | in that value. | |
cc6d0d2c | 866 | |
969fe9b5 RS |
867 | The usual reason to specify a documentation string for a type is to |
868 | provide more information about the meanings of alternatives inside a | |
869 | @code{:choice} type or the parts of some other composite type. | |
cc6d0d2c RS |
870 | |
871 | @item :help-echo @var{motion-doc} | |
872 | When you move to this item with @code{widget-forward} or | |
873 | @code{widget-backward}, it will display the string @var{motion-doc} | |
874 | in the echo area. | |
875 | ||
876 | @item :match @var{function} | |
969fe9b5 RS |
877 | Specify how to decide whether a value matches the type. The |
878 | corresponding value, @var{function}, should be a function that accepts | |
879 | two arguments, a widget and a value; it should return non-@code{nil} if | |
880 | the value is acceptable. | |
cc6d0d2c RS |
881 | |
882 | @ignore | |
883 | @item :indent @var{columns} | |
884 | Indent this item by @var{columns} columns. The indentation is used for | |
885 | @samp{%n}, and automatically for group names, for checklists and radio | |
886 | buttons, and for editable lists. It affects the whole of the | |
887 | item except for the first line. | |
888 | ||
889 | @item :offset @var{columns} | |
890 | An integer indicating how many extra spaces to indent the subitems of | |
891 | this item. By default, subitems are indented the same as their parent. | |
892 | ||
893 | @item :extra-offset | |
894 | An integer indicating how many extra spaces to add to this item's | |
895 | indentation, compared to its parent. | |
896 | ||
897 | @item :notify | |
898 | A function called each time the item or a subitem is changed. The | |
899 | function is called with two or three arguments. The first argument is | |
900 | the item itself, the second argument is the item that was changed, and | |
901 | the third argument is the event leading to the change, if any. | |
902 | ||
903 | @item :menu-tag | |
904 | Tag used in the menu when the widget is used as an option in a | |
905 | @code{menu-choice} widget. | |
906 | ||
907 | @item :menu-tag-get | |
908 | Function used for finding the tag when the widget is used as an option | |
909 | in a @code{menu-choice} widget. By default, the tag used will be either the | |
910 | @code{:menu-tag} or @code{:tag} property if present, or the @code{princ} | |
911 | representation of the @code{:value} property if not. | |
912 | ||
913 | @item :validate | |
914 | A function which takes a widget as an argument, and return nil if the | |
915 | widgets current value is valid for the widget. Otherwise, it should | |
916 | return the widget containing the invalid data, and set that widgets | |
917 | @code{:error} property to a string explaining the error. | |
918 | ||
919 | You can use the function @code{widget-children-validate} for this job; | |
920 | it tests that all children of @var{widget} are valid. | |
921 | ||
922 | @item :tab-order | |
923 | Specify the order in which widgets are traversed with | |
924 | @code{widget-forward} or @code{widget-backward}. This is only partially | |
925 | implemented. | |
926 | ||
927 | @enumerate a | |
928 | @item | |
929 | Widgets with tabbing order @code{-1} are ignored. | |
930 | ||
931 | @item | |
932 | (Unimplemented) When on a widget with tabbing order @var{n}, go to the | |
933 | next widget in the buffer with tabbing order @var{n+1} or @code{nil}, | |
934 | whichever comes first. | |
935 | ||
936 | @item | |
937 | When on a widget with no tabbing order specified, go to the next widget | |
938 | in the buffer with a positive tabbing order, or @code{nil} | |
939 | @end enumerate | |
940 | ||
941 | @item :parent | |
a9f0a989 | 942 | The parent of a nested widget (e.g., a @code{menu-choice} item or an |
cc6d0d2c RS |
943 | element of a @code{editable-list} widget). |
944 | ||
945 | @item :sibling-args | |
946 | This keyword is only used for members of a @code{radio-button-choice} or | |
947 | @code{checklist}. The value should be a list of extra keyword | |
948 | arguments, which will be used when creating the @code{radio-button} or | |
949 | @code{checkbox} associated with this item. | |
950 | @end ignore | |
951 | @end table |