Commit | Line | Data |
---|---|---|
cc6d0d2c RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
b3d90e46 GM |
3 | @c Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, |
4 | @c 2005, 2006, 2007 Free Software Foundation, Inc. | |
cc6d0d2c RS |
5 | @c See the file elisp.texi for copying conditions. |
6 | @setfilename ../info/customize | |
7 | @node Customization, Loading, Macros, Top | |
8 | @chapter Writing Customization Definitions | |
1db203ff | 9 | @cindex customize |
cc6d0d2c | 10 | |
83b97379 | 11 | @cindex customization definitions |
969fe9b5 RS |
12 | This chapter describes how to declare user options for customization, |
13 | and also customization groups for classifying them. We use the term | |
14 | @dfn{customization item} to include both kinds of customization | |
15 | definitions---as well as face definitions (@pxref{Defining Faces}). | |
cc6d0d2c RS |
16 | |
17 | @menu | |
d5b3141d | 18 | * Common Keywords:: Common keyword arguments for all kinds of |
5f43de89 LK |
19 | customization declarations. |
20 | * Group Definitions:: Writing customization group definitions. | |
21 | * Variable Definitions:: Declaring user options. | |
22 | * Customization Types:: Specifying the type of a user option. | |
cc6d0d2c RS |
23 | @end menu |
24 | ||
25 | @node Common Keywords | |
8241495d | 26 | @section Common Item Keywords |
cc6d0d2c | 27 | |
83b97379 | 28 | @cindex customization keywords |
969fe9b5 RS |
29 | All kinds of customization declarations (for variables and groups, and |
30 | for faces) accept keyword arguments for specifying various information. | |
31 | This section describes some keywords that apply to all kinds. | |
cc6d0d2c | 32 | |
969fe9b5 RS |
33 | All of these keywords, except @code{:tag}, can be used more than once |
34 | in a given item. Each use of the keyword has an independent effect. | |
35 | The keyword @code{:tag} is an exception because any given item can only | |
36 | display one name. | |
cc6d0d2c RS |
37 | |
38 | @table @code | |
8241495d | 39 | @item :tag @var{label} |
83b97379 | 40 | @kindex tag@r{, customization keyword} |
912ea554 RS |
41 | Use @var{label}, a string, instead of the item's name, to label the |
42 | item in customization menus and buffers. @strong{Don't use a tag | |
43 | which is substantially different from the item's real name; that would | |
44 | cause confusion.} One legitimate case for use of @code{:tag} is to | |
45 | specify a dash where normally a hyphen would be converted to a space: | |
46 | ||
47 | @example | |
48 | (defcustom cursor-in-non-selected-windows @dots{} | |
49 | :tag "Cursor In Non-selected Windows" | |
50 | @end example | |
a9f0a989 | 51 | |
83b97379 | 52 | @kindex group@r{, customization keyword} |
cc6d0d2c RS |
53 | @item :group @var{group} |
54 | Put this customization item in group @var{group}. When you use | |
55 | @code{:group} in a @code{defgroup}, it makes the new group a subgroup of | |
56 | @var{group}. | |
57 | ||
58 | If you use this keyword more than once, you can put a single item into | |
59 | more than one group. Displaying any of those groups will show this | |
8241495d | 60 | item. Please don't overdo this, since the result would be annoying. |
cc6d0d2c RS |
61 | |
62 | @item :link @var{link-data} | |
83b97379 | 63 | @kindex link@r{, customization keyword} |
cc6d0d2c RS |
64 | Include an external link after the documentation string for this item. |
65 | This is a sentence containing an active field which references some | |
66 | other documentation. | |
67 | ||
27a0fffe | 68 | There are several alternatives you can use for @var{link-data}: |
cc6d0d2c RS |
69 | |
70 | @table @code | |
71 | @item (custom-manual @var{info-node}) | |
72 | Link to an Info node; @var{info-node} is a string which specifies the | |
73 | node name, as in @code{"(emacs)Top"}. The link appears as | |
27a0fffe JL |
74 | @samp{[Manual]} in the customization buffer and enters the built-in |
75 | Info reader on @var{info-node}. | |
cc6d0d2c RS |
76 | |
77 | @item (info-link @var{info-node}) | |
78 | Like @code{custom-manual} except that the link appears | |
79 | in the customization buffer with the Info node name. | |
80 | ||
81 | @item (url-link @var{url}) | |
27a0fffe JL |
82 | Link to a web page; @var{url} is a string which specifies the |
83 | @acronym{URL}. The link appears in the customization buffer as | |
84 | @var{url} and invokes the WWW browser specified by | |
3c9af438 | 85 | @code{browse-url-browser-function}. |
5e0c8a23 DL |
86 | |
87 | @item (emacs-commentary-link @var{library}) | |
88 | Link to the commentary section of a library; @var{library} is a string | |
89 | which specifies the library name. | |
27a0fffe JL |
90 | |
91 | @item (emacs-library-link @var{library}) | |
92 | Link to an Emacs Lisp library file; @var{library} is a string which | |
93 | specifies the library name. | |
94 | ||
95 | @item (file-link @var{file}) | |
96 | Link to a file; @var{file} is a string which specifies the name of the | |
97 | file to visit with @code{find-file} when the user invokes this link. | |
98 | ||
99 | @item (function-link @var{function}) | |
100 | Link to the documentation of a function; @var{function} is a string | |
101 | which specifies the name of the function to describe with | |
102 | @code{describe-function} when the user invokes this link. | |
103 | ||
104 | @item (variable-link @var{variable}) | |
105 | Link to the documentation of a variable; @var{variable} is a string | |
106 | which specifies the name of the variable to describe with | |
107 | @code{describe-variable} when the user invokes this link. | |
108 | ||
109 | @item (custom-group-link @var{group}) | |
110 | Link to another customization group. Invoking it creates a new | |
111 | customization buffer for @var{group}. | |
cc6d0d2c RS |
112 | @end table |
113 | ||
114 | You can specify the text to use in the customization buffer by adding | |
115 | @code{:tag @var{name}} after the first element of the @var{link-data}; | |
116 | for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to | |
117 | the Emacs manual which appears in the buffer as @samp{foo}. | |
118 | ||
119 | An item can have more than one external link; however, most items have | |
120 | none at all. | |
121 | ||
122 | @item :load @var{file} | |
83b97379 | 123 | @kindex load@r{, customization keyword} |
cc6d0d2c RS |
124 | Load file @var{file} (a string) before displaying this customization |
125 | item. Loading is done with @code{load-library}, and only if the file is | |
126 | not already loaded. | |
127 | ||
128 | @item :require @var{feature} | |
83b97379 | 129 | @kindex require@r{, customization keyword} |
937dbf8c RS |
130 | Execute @code{(require '@var{feature})} when your saved customizations |
131 | set the value of this item. @var{feature} should be a symbol. | |
cc6d0d2c RS |
132 | |
133 | The most common reason to use @code{:require} is when a variable enables | |
134 | a feature such as a minor mode, and just setting the variable won't have | |
135 | any effect unless the code which implements the mode is loaded. | |
937dbf8c RS |
136 | |
137 | @item :version @var{version} | |
83b97379 | 138 | @kindex version@r{, customization keyword} |
e1f2af9c | 139 | This keyword specifies that the item was first introduced in Emacs |
937dbf8c RS |
140 | version @var{version}, or that its default value was changed in that |
141 | version. The value @var{version} must be a string. | |
e5e864ab | 142 | |
61f32d39 | 143 | @item :package-version '(@var{package} . @var{version}) |
83b97379 | 144 | @kindex package-version@r{, customization keyword} |
e1f2af9c | 145 | This keyword specifies that the item was first introduced in |
eb107d09 RS |
146 | @var{package} version @var{version}, or that its meaning or default |
147 | value was changed in that version. The value of @var{package} is a | |
148 | symbol and @var{version} is a string. | |
4f8ed159 | 149 | |
eb107d09 RS |
150 | This keyword takes priority over @code{:version}. |
151 | ||
152 | @var{package} should be the official name of the package, such as MH-E | |
153 | or Gnus. If the package @var{package} is released as part of Emacs, | |
154 | @var{package} and @var{version} should appear in the value of | |
155 | @code{customize-package-emacs-version-alist}. | |
4f8ed159 BW |
156 | @end table |
157 | ||
eb107d09 RS |
158 | Packages distributed as part of Emacs that use the |
159 | @code{:package-version} keyword must also update the | |
160 | @code{customize-package-emacs-version-alist} variable. | |
4f8ed159 BW |
161 | |
162 | @defvar customize-package-emacs-version-alist | |
61f32d39 BW |
163 | This alist provides a mapping for the versions of Emacs that are |
164 | associated with versions of a package listed in the | |
165 | @code{:package-version} keyword. Its elements look like this: | |
166 | ||
167 | @example | |
168 | (@var{package} (@var{pversion} . @var{eversion})@dots{}) | |
169 | @end example | |
170 | ||
171 | For each @var{package}, which is a symbol, there are one or more | |
172 | elements that contain a package version @var{pversion} with an | |
173 | associated Emacs version @var{eversion}. These versions are strings. | |
174 | For example, the MH-E package updates this alist with the following: | |
e5e864ab BW |
175 | |
176 | @smallexample | |
177 | (add-to-list 'customize-package-emacs-version-alist | |
61f32d39 BW |
178 | '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1") |
179 | ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1") | |
180 | ("7.4" . "22.1") ("8.0" . "22.1"))) | |
e5e864ab | 181 | @end smallexample |
61f32d39 BW |
182 | |
183 | The value of @var{package} needs to be unique and it needs to match | |
184 | the @var{package} value appearing in the @code{:package-version} | |
185 | keyword. Since the user might see the value in a error message, a good | |
186 | choice is the official name of the package, such as MH-E or Gnus. | |
4f8ed159 | 187 | @end defvar |
cc6d0d2c RS |
188 | |
189 | @node Group Definitions | |
190 | @section Defining Custom Groups | |
c115a463 | 191 | @cindex define custom group |
cc6d0d2c | 192 | |
83b97379 | 193 | @cindex custom groups, how to define |
969fe9b5 | 194 | Each Emacs Lisp package should have one main customization group which |
cc6d0d2c RS |
195 | contains all the options, faces and other groups in the package. If the |
196 | package has a small number of options and faces, use just one group and | |
197 | put everything in it. When there are more than twelve or so options and | |
198 | faces, then you should structure them into subgroups, and put the | |
969fe9b5 RS |
199 | subgroups under the package's main customization group. It is OK to |
200 | put some of the options and faces in the package's main group alongside | |
cc6d0d2c RS |
201 | the subgroups. |
202 | ||
969fe9b5 RS |
203 | The package's main or only group should be a member of one or more of |
204 | the standard customization groups. (To display the full list of them, | |
205 | use @kbd{M-x customize}.) Choose one or more of them (but not too | |
206 | many), and add your group to each of them using the @code{:group} | |
207 | keyword. | |
cc6d0d2c | 208 | |
969fe9b5 | 209 | The way to declare new customization groups is with @code{defgroup}. |
cc6d0d2c | 210 | |
3e14f3da | 211 | @defmac defgroup group members doc [keyword value]@dots{} |
cc6d0d2c RS |
212 | Declare @var{group} as a customization group containing @var{members}. |
213 | Do not quote the symbol @var{group}. The argument @var{doc} specifies | |
3c9af438 | 214 | the documentation string for the group. |
cc6d0d2c | 215 | |
a9f0a989 RS |
216 | The argument @var{members} is a list specifying an initial set of |
217 | customization items to be members of the group. However, most often | |
969fe9b5 RS |
218 | @var{members} is @code{nil}, and you specify the group's members by |
219 | using the @code{:group} keyword when defining those members. | |
cc6d0d2c | 220 | |
a9f0a989 RS |
221 | If you want to specify group members through @var{members}, each element |
222 | should have the form @code{(@var{name} @var{widget})}. Here @var{name} | |
223 | is a symbol, and @var{widget} is a widget type for editing that symbol. | |
224 | Useful widgets are @code{custom-variable} for a variable, | |
225 | @code{custom-face} for a face, and @code{custom-group} for a group. | |
cc6d0d2c | 226 | |
937dbf8c RS |
227 | When you introduce a new group into Emacs, use the @code{:version} |
228 | keyword in the @code{defgroup}; then you need not use it for | |
229 | the individual members of the group. | |
3d66f910 | 230 | |
cc6d0d2c | 231 | In addition to the common keywords (@pxref{Common Keywords}), you can |
3d66f910 | 232 | also use this keyword in @code{defgroup}: |
cc6d0d2c RS |
233 | |
234 | @table @code | |
235 | @item :prefix @var{prefix} | |
83b97379 | 236 | @kindex prefix@r{, @code{defgroup} keyword} |
cc6d0d2c RS |
237 | If the name of an item in the group starts with @var{prefix}, then the |
238 | tag for that item is constructed (by default) by omitting @var{prefix}. | |
239 | ||
240 | One group can have any number of prefixes. | |
241 | @end table | |
242 | @end defmac | |
243 | ||
969fe9b5 RS |
244 | The prefix-discarding feature is currently turned off, which means |
245 | that @code{:prefix} currently has no effect. We did this because we | |
246 | found that discarding the specified prefixes often led to confusing | |
247 | names for options. This happened because the people who wrote the | |
248 | @code{defgroup} definitions for various groups added @code{:prefix} | |
249 | keywords whenever they make logical sense---that is, whenever the | |
250 | variables in the library have a common prefix. | |
251 | ||
252 | In order to obtain good results with @code{:prefix}, it would be | |
253 | necessary to check the specific effects of discarding a particular | |
254 | prefix, given the specific items in a group and their names and | |
255 | documentation. If the resulting text is not clear, then @code{:prefix} | |
256 | should not be used in that case. | |
257 | ||
258 | It should be possible to recheck all the customization groups, delete | |
cc6d0d2c RS |
259 | the @code{:prefix} specifications which give unclear results, and then |
260 | turn this feature back on, if someone would like to do the work. | |
261 | ||
262 | @node Variable Definitions | |
263 | @section Defining Customization Variables | |
c115a463 | 264 | @cindex define customization options |
cc6d0d2c | 265 | |
83b97379 EZ |
266 | @cindex customization variables, how to define |
267 | @cindex declare user-editable variables | |
969fe9b5 | 268 | Use @code{defcustom} to declare user-editable variables. |
cc6d0d2c | 269 | |
81b4d9ab RS |
270 | @defmac defcustom option standard doc [keyword value]@dots{} |
271 | This construct declares @var{option} as a customizable user option | |
272 | variable. You should not quote @var{option}. The argument @var{doc} | |
273 | specifies the documentation string for the variable. There is no need | |
274 | to start it with a @samp{*}, because @code{defcustom} automatically | |
275 | marks @var{option} as a @dfn{user option} (@pxref{Defining | |
276 | Variables}). | |
277 | ||
278 | The argument @var{standard} is an expression that specifies the | |
279 | standard value for @var{option}. Evaluating the @code{defcustom} form | |
280 | evaluates @var{standard}, but does not necessarily install the | |
281 | standard value. If @var{option} already has a default value, | |
282 | @code{defcustom} does not change it. If the user has saved a | |
283 | customization for @var{option}, @code{defcustom} installs the user's | |
284 | customized value as @var{option}'s default value. If neither of those | |
285 | cases applies, @code{defcustom} installs the result of evaluating | |
286 | @var{standard} as the default value. | |
287 | ||
288 | The expression @var{standard} can be evaluated at various other times, | |
289 | too---whenever the customization facility needs to know @var{option}'s | |
290 | standard value. So be sure to use an expression which is harmless to | |
291 | evaluate at any time. We recommend avoiding backquotes in | |
292 | @var{standard}, because they are not expanded when editing the value, | |
293 | so list values will appear to have the wrong structure. | |
8241495d | 294 | |
e1f2af9c RS |
295 | Every @code{defcustom} should specify @code{:group} at least once. |
296 | ||
297 | If you specify the @code{:set} keyword, to make the variable take other | |
379031d1 RS |
298 | special actions when set through the customization buffer, the |
299 | variable's documentation string should tell the user specifically how | |
300 | to do the same job in hand-written Lisp code. | |
301 | ||
8241495d RS |
302 | When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp |
303 | mode (@code{eval-defun}), a special feature of @code{eval-defun} | |
304 | arranges to set the variable unconditionally, without testing whether | |
305 | its value is void. (The same feature applies to @code{defvar}.) | |
306 | @xref{Defining Variables}. | |
7dd3d99f | 307 | @end defmac |
cc6d0d2c | 308 | |
7dd3d99f | 309 | @code{defcustom} accepts the following additional keywords: |
cc6d0d2c RS |
310 | |
311 | @table @code | |
312 | @item :type @var{type} | |
313 | Use @var{type} as the data type for this option. It specifies which | |
314 | values are legitimate, and how to display the value. | |
315 | @xref{Customization Types}, for more information. | |
316 | ||
e1f2af9c | 317 | @item :options @var{value-list} |
83b97379 | 318 | @kindex options@r{, @code{defcustom} keyword} |
e1f2af9c | 319 | Specify the list of reasonable values for use in this |
b6954afd RS |
320 | option. The user is not restricted to using only these values, but they |
321 | are offered as convenient alternatives. | |
cc6d0d2c | 322 | |
b6954afd RS |
323 | This is meaningful only for certain types, currently including |
324 | @code{hook}, @code{plist} and @code{alist}. See the definition of the | |
325 | individual types for a description of how to use @code{:options}. | |
cc6d0d2c | 326 | |
cc6d0d2c | 327 | @item :set @var{setfunction} |
83b97379 | 328 | @kindex set@r{, @code{defcustom} keyword} |
937dbf8c RS |
329 | Specify @var{setfunction} as the way to change the value of this |
330 | option. The function @var{setfunction} should take two arguments, a | |
331 | symbol (the option name) and the new value, and should do whatever is | |
332 | necessary to update the value properly for this option (which may not | |
333 | mean simply setting the option as a Lisp variable). The default for | |
334 | @var{setfunction} is @code{set-default}. | |
cc6d0d2c RS |
335 | |
336 | @item :get @var{getfunction} | |
83b97379 | 337 | @kindex get@r{, @code{defcustom} keyword} |
cc6d0d2c RS |
338 | Specify @var{getfunction} as the way to extract the value of this |
339 | option. The function @var{getfunction} should take one argument, a | |
7db0894f RS |
340 | symbol, and should return whatever customize should use as the |
341 | ``current value'' for that symbol (which need not be the symbol's Lisp | |
342 | value). The default is @code{default-value}. | |
343 | ||
344 | You have to really understand the workings of Custom to use | |
345 | @code{:get} correctly. It is meant for values that are treated in | |
346 | Custom as variables but are not actually stored in Lisp variables. It | |
347 | is almost surely a mistake to specify @code{getfunction} for a value | |
348 | that really is stored in a Lisp variable. | |
cc6d0d2c RS |
349 | |
350 | @item :initialize @var{function} | |
83b97379 | 351 | @kindex initialize@r{, @code{defcustom} keyword} |
937dbf8c RS |
352 | @var{function} should be a function used to initialize the variable |
353 | when the @code{defcustom} is evaluated. It should take two arguments, | |
354 | the option name (a symbol) and the value. Here are some predefined | |
355 | functions meant for use in this way: | |
cc6d0d2c RS |
356 | |
357 | @table @code | |
358 | @item custom-initialize-set | |
969fe9b5 | 359 | Use the variable's @code{:set} function to initialize the variable, but |
7db0894f | 360 | do not reinitialize it if it is already non-void. |
cc6d0d2c RS |
361 | |
362 | @item custom-initialize-default | |
969fe9b5 RS |
363 | Like @code{custom-initialize-set}, but use the function |
364 | @code{set-default} to set the variable, instead of the variable's | |
365 | @code{:set} function. This is the usual choice for a variable whose | |
366 | @code{:set} function enables or disables a minor mode; with this choice, | |
367 | defining the variable will not call the minor mode function, but | |
368 | customizing the variable will do so. | |
cc6d0d2c RS |
369 | |
370 | @item custom-initialize-reset | |
7db0894f RS |
371 | Always use the @code{:set} function to initialize the variable. If |
372 | the variable is already non-void, reset it by calling the @code{:set} | |
969fe9b5 | 373 | function using the current value (returned by the @code{:get} method). |
7db0894f | 374 | This is the default @code{:initialize} function. |
cc6d0d2c RS |
375 | |
376 | @item custom-initialize-changed | |
969fe9b5 RS |
377 | Use the @code{:set} function to initialize the variable, if it is |
378 | already set or has been customized; otherwise, just use | |
379 | @code{set-default}. | |
d5b3141d LT |
380 | |
381 | @item custom-initialize-safe-set | |
382 | @itemx custom-initialize-safe-default | |
383 | These functions behave like @code{custom-initialize-set} | |
384 | (@code{custom-initialize-default}, respectively), but catch errors. | |
385 | If an error occurs during initialization, they set the variable to | |
386 | @code{nil} using @code{set-default}, and throw no error. | |
387 | ||
388 | These two functions are only meant for options defined in pre-loaded | |
389 | files, where some variables or functions used to compute the option's | |
390 | value may not yet be defined. The option normally gets updated in | |
391 | @file{startup.el}, ignoring the previously computed value. Because of | |
392 | this typical usage, the value which these two functions compute | |
393 | normally only matters when, after startup, one unsets the option's | |
394 | value and then reevaluates the defcustom. By that time, the necessary | |
395 | variables and functions will be defined, so there will not be an error. | |
cc6d0d2c | 396 | @end table |
390538c3 RS |
397 | |
398 | @item :set-after @var{variables} | |
83b97379 | 399 | @kindex set-after@r{, @code{defcustom} keyword} |
390538c3 RS |
400 | When setting variables according to saved customizations, make sure to |
401 | set the variables @var{variables} before this one; in other words, delay | |
402 | setting this variable until after those others have been handled. Use | |
403 | @code{:set-after} if setting this variable won't work properly unless | |
404 | those other variables already have their intended values. | |
969fe9b5 | 405 | @end table |
cc6d0d2c | 406 | |
e1f2af9c | 407 | The @code{:require} keyword is useful for an option that turns on the |
cc6d0d2c RS |
408 | operation of a certain feature. Assuming that the package is coded to |
409 | check the value of the option, you still need to arrange for the package | |
969fe9b5 | 410 | to be loaded. You can do that with @code{:require}. @xref{Common |
1a60ceae | 411 | Keywords}. Here is an example, from the library @file{saveplace.el}: |
969fe9b5 RS |
412 | |
413 | @example | |
1a60ceae | 414 | (defcustom save-place nil |
cd35741d | 415 | "Non-nil means automatically save place in each file..." |
969fe9b5 | 416 | :type 'boolean |
1a60ceae NR |
417 | :require 'saveplace |
418 | :group 'save-place) | |
969fe9b5 | 419 | @end example |
cc6d0d2c | 420 | |
e1f2af9c RS |
421 | If a customization item has a type such as @code{hook} or |
422 | @code{alist}, which supports @code{:options}, you can add additional | |
423 | values to the list from outside the @code{defcustom} declaration by | |
d78b75dd | 424 | calling @code{custom-add-frequent-value}. For example, if you define a |
e1f2af9c | 425 | function @code{my-lisp-mode-initialization} intended to be called from |
b6954afd | 426 | @code{emacs-lisp-mode-hook}, you might want to add that to the list of |
e1f2af9c RS |
427 | reasonable values for @code{emacs-lisp-mode-hook}, but not by editing |
428 | its definition. You can do it thus: | |
b6954afd RS |
429 | |
430 | @example | |
d78b75dd RS |
431 | (custom-add-frequent-value 'emacs-lisp-mode-hook |
432 | 'my-lisp-mode-initialization) | |
b6954afd | 433 | @end example |
cc6d0d2c | 434 | |
d78b75dd | 435 | @defun custom-add-frequent-value symbol value |
e1f2af9c RS |
436 | For the customization option @var{symbol}, add @var{value} to the |
437 | list of reasonable values. | |
cc6d0d2c | 438 | |
e1f2af9c RS |
439 | The precise effect of adding a value depends on the customization type |
440 | of @var{symbol}. | |
cc6d0d2c | 441 | @end defun |
cc6d0d2c RS |
442 | |
443 | Internally, @code{defcustom} uses the symbol property | |
81b4d9ab | 444 | @code{standard-value} to record the expression for the standard value, |
cc6d0d2c | 445 | and @code{saved-value} to record the value saved by the user with the |
d5b3141d LT |
446 | customization buffer. Both properties are actually lists whose car is |
447 | an expression which evaluates to the value. | |
cc6d0d2c | 448 | |
cc6d0d2c RS |
449 | @node Customization Types |
450 | @section Customization Types | |
451 | ||
83b97379 | 452 | @cindex customization types |
cc6d0d2c | 453 | When you define a user option with @code{defcustom}, you must specify |
969fe9b5 | 454 | its @dfn{customization type}. That is a Lisp object which describes (1) |
cc6d0d2c RS |
455 | which values are legitimate and (2) how to display the value in the |
456 | customization buffer for editing. | |
457 | ||
83b97379 | 458 | @kindex type@r{, @code{defcustom} keyword} |
cc6d0d2c | 459 | You specify the customization type in @code{defcustom} with the |
5a65439e RS |
460 | @code{:type} keyword. The argument of @code{:type} is evaluated, but |
461 | only once when the @code{defcustom} is executed, so it isn't useful | |
462 | for the value to vary. Normally we use a quoted constant. For | |
463 | example: | |
cc6d0d2c RS |
464 | |
465 | @example | |
466 | (defcustom diff-command "diff" | |
cd35741d | 467 | "The command to use to run diff." |
969fe9b5 | 468 | :type '(string) |
cc6d0d2c RS |
469 | :group 'diff) |
470 | @end example | |
471 | ||
969fe9b5 RS |
472 | In general, a customization type is a list whose first element is a |
473 | symbol, one of the customization type names defined in the following | |
474 | sections. After this symbol come a number of arguments, depending on | |
475 | the symbol. Between the type symbol and its arguments, you can | |
476 | optionally write keyword-value pairs (@pxref{Type Keywords}). | |
cc6d0d2c | 477 | |
969fe9b5 RS |
478 | Some of the type symbols do not use any arguments; those are called |
479 | @dfn{simple types}. For a simple type, if you do not use any | |
480 | keyword-value pairs, you can omit the parentheses around the type | |
481 | symbol. For example just @code{string} as a customization type is | |
482 | equivalent to @code{(string)}. | |
cc6d0d2c RS |
483 | |
484 | @menu | |
485 | * Simple Types:: | |
486 | * Composite Types:: | |
487 | * Splicing into Lists:: | |
488 | * Type Keywords:: | |
cfa921fd | 489 | * Defining New Types:: |
cc6d0d2c RS |
490 | @end menu |
491 | ||
c5c36e02 | 492 | All customization types are implemented as widgets; see @ref{Top, , |
333c5fc5 | 493 | Introduction, widget, The Emacs Widget Library}, for details. |
c5c36e02 | 494 | |
cc6d0d2c RS |
495 | @node Simple Types |
496 | @subsection Simple Types | |
497 | ||
498 | This section describes all the simple customization types. | |
499 | ||
500 | @table @code | |
501 | @item sexp | |
502 | The value may be any Lisp object that can be printed and read back. You | |
503 | can use @code{sexp} as a fall-back for any option, if you don't want to | |
504 | take the time to work out a more specific type to use. | |
505 | ||
506 | @item integer | |
507 | The value must be an integer, and is represented textually | |
508 | in the customization buffer. | |
509 | ||
510 | @item number | |
177f790c MR |
511 | The value must be a number (floating point or integer), and is |
512 | represented textually in the customization buffer. | |
513 | ||
514 | @item float | |
515 | The value must be a floating point number, and is represented | |
516 | textually in the customization buffer. | |
cc6d0d2c RS |
517 | |
518 | @item string | |
519 | The value must be a string, and the customization buffer shows just the | |
969fe9b5 RS |
520 | contents, with no delimiting @samp{"} characters and no quoting with |
521 | @samp{\}. | |
cc6d0d2c RS |
522 | |
523 | @item regexp | |
969fe9b5 RS |
524 | Like @code{string} except that the string must be a valid regular |
525 | expression. | |
cc6d0d2c RS |
526 | |
527 | @item character | |
528 | The value must be a character code. A character code is actually an | |
529 | integer, but this type shows the value by inserting the character in the | |
530 | buffer, rather than by showing the number. | |
531 | ||
532 | @item file | |
533 | The value must be a file name, and you can do completion with | |
534 | @kbd{M-@key{TAB}}. | |
535 | ||
536 | @item (file :must-match t) | |
537 | The value must be a file name for an existing file, and you can do | |
538 | completion with @kbd{M-@key{TAB}}. | |
539 | ||
540 | @item directory | |
541 | The value must be a directory name, and you can do completion with | |
542 | @kbd{M-@key{TAB}}. | |
543 | ||
a9f0a989 RS |
544 | @item hook |
545 | The value must be a list of functions (or a single function, but that is | |
546 | obsolete usage). This customization type is used for hook variables. | |
1911e6e5 RS |
547 | You can use the @code{:options} keyword in a hook variable's |
548 | @code{defcustom} to specify a list of functions recommended for use in | |
549 | the hook; see @ref{Variable Definitions}. | |
a9f0a989 | 550 | |
b6954afd | 551 | @item alist |
08f0f5e9 KH |
552 | The value must be a list of cons-cells, the @sc{car} of each cell |
553 | representing a key, and the @sc{cdr} of the same cell representing an | |
554 | associated value. The user can add and delete key/value pairs, and | |
b6954afd RS |
555 | edit both the key and the value of each pair. |
556 | ||
557 | You can specify the key and value types like this: | |
558 | ||
8241495d RS |
559 | @smallexample |
560 | (alist :key-type @var{key-type} :value-type @var{value-type}) | |
561 | @end smallexample | |
b6954afd RS |
562 | |
563 | @noindent | |
564 | where @var{key-type} and @var{value-type} are customization type | |
565 | specifications. The default key type is @code{sexp}, and the default | |
566 | value type is @code{sexp}. | |
567 | ||
568 | The user can add any key matching the specified key type, but you can | |
569 | give some keys a preferential treatment by specifying them with the | |
570 | @code{:options} (see @ref{Variable Definitions}). The specified keys | |
571 | will always be shown in the customize buffer (together with a suitable | |
572 | value), with a checkbox to include or exclude or disable the key/value | |
573 | pair from the alist. The user will not be able to edit the keys | |
574 | specified by the @code{:options} keyword argument. | |
575 | ||
e1f2af9c RS |
576 | The argument to the @code{:options} keywords should be a list of |
577 | specifications for reasonable keys in the alist. Ordinarily, they are | |
578 | simply atoms, which stand for themselves as. For example: | |
b6954afd | 579 | |
8241495d | 580 | @smallexample |
b6954afd | 581 | :options '("foo" "bar" "baz") |
8241495d | 582 | @end smallexample |
b6954afd RS |
583 | |
584 | @noindent | |
585 | specifies that there are three ``known'' keys, namely @code{"foo"}, | |
586 | @code{"bar"} and @code{"baz"}, which will always be shown first. | |
587 | ||
e1f2af9c RS |
588 | You may want to restrict the value type for specific keys, for |
589 | example, the value associated with the @code{"bar"} key can only be an | |
590 | integer. You can specify this by using a list instead of an atom in | |
591 | the list. The first element will specify the key, like before, while | |
592 | the second element will specify the value type. For example: | |
b6954afd | 593 | |
8241495d | 594 | @smallexample |
b6954afd | 595 | :options '("foo" ("bar" integer) "baz") |
8241495d | 596 | @end smallexample |
b6954afd RS |
597 | |
598 | Finally, you may want to change how the key is presented. By default, | |
599 | the key is simply shown as a @code{const}, since the user cannot change | |
600 | the special keys specified with the @code{:options} keyword. However, | |
601 | you may want to use a more specialized type for presenting the key, like | |
602 | @code{function-item} if you know it is a symbol with a function binding. | |
603 | This is done by using a customization type specification instead of a | |
604 | symbol for the key. | |
605 | ||
8241495d | 606 | @smallexample |
42b50684 KB |
607 | :options '("foo" ((function-item some-function) integer) |
608 | "baz") | |
8241495d | 609 | @end smallexample |
b6954afd | 610 | |
08f0f5e9 | 611 | Many alists use lists with two elements, instead of cons cells. For |
b6954afd RS |
612 | example, |
613 | ||
8241495d | 614 | @smallexample |
b6954afd RS |
615 | (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) |
616 | "Each element is a list of the form (KEY VALUE).") | |
8241495d | 617 | @end smallexample |
b6954afd RS |
618 | |
619 | @noindent | |
177c0ea7 | 620 | instead of |
b6954afd | 621 | |
8241495d | 622 | @smallexample |
b6954afd RS |
623 | (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) |
624 | "Each element is a cons-cell (KEY . VALUE).") | |
8241495d | 625 | @end smallexample |
b6954afd RS |
626 | |
627 | Because of the way lists are implemented on top of cons cells, you can | |
628 | treat @code{list-alist} in the example above as a cons cell alist, where | |
629 | the value type is a list with a single element containing the real | |
630 | value. | |
631 | ||
8241495d | 632 | @smallexample |
b6954afd RS |
633 | (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) |
634 | "Each element is a list of the form (KEY VALUE)." | |
635 | :type '(alist :value-type (group integer))) | |
8241495d | 636 | @end smallexample |
b6954afd RS |
637 | |
638 | The @code{group} widget is used here instead of @code{list} only because | |
639 | the formatting is better suited for the purpose. | |
640 | ||
38c7d6d5 | 641 | Similarly, you can have alists with more values associated with each |
b6954afd RS |
642 | key, using variations of this trick: |
643 | ||
8241495d | 644 | @smallexample |
177c0ea7 | 645 | (defcustom person-data '(("brian" 50 t) |
b6954afd RS |
646 | ("dorith" 55 nil) |
647 | ("ken" 52 t)) | |
3d3df9e1 RS |
648 | "Alist of basic info about people. |
649 | Each element has the form (NAME AGE MALE-FLAG)." | |
38c7d6d5 | 650 | :type '(alist :value-type (group integer boolean))) |
b6954afd | 651 | |
177c0ea7 | 652 | (defcustom pets '(("brian") |
b6954afd RS |
653 | ("dorith" "dog" "guppy") |
654 | ("ken" "cat")) | |
3d3df9e1 RS |
655 | "Alist of people's pets. |
656 | In an element (KEY . VALUE), KEY is the person's name, | |
657 | and the VALUE is a list of that person's pets." | |
b6954afd | 658 | :type '(alist :value-type (repeat string))) |
8241495d | 659 | @end smallexample |
b6954afd RS |
660 | |
661 | @item plist | |
662 | The @code{plist} custom type is similar to the @code{alist} (see above), | |
663 | except that the information is stored as a property list, i.e. a list of | |
664 | this form: | |
665 | ||
8241495d | 666 | @smallexample |
b6954afd | 667 | (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{}) |
8241495d | 668 | @end smallexample |
b6954afd RS |
669 | |
670 | The default @code{:key-type} for @code{plist} is @code{symbol}, | |
671 | rather than @code{sexp}. | |
672 | ||
cc6d0d2c RS |
673 | @item symbol |
674 | The value must be a symbol. It appears in the customization buffer as | |
675 | the name of the symbol. | |
676 | ||
677 | @item function | |
678 | The value must be either a lambda expression or a function name. When | |
679 | it is a function name, you can do completion with @kbd{M-@key{TAB}}. | |
680 | ||
681 | @item variable | |
682 | The value must be a variable name, and you can do completion with | |
683 | @kbd{M-@key{TAB}}. | |
684 | ||
a9f0a989 RS |
685 | @item face |
686 | The value must be a symbol which is a face name, and you can do | |
687 | completion with @kbd{M-@key{TAB}}. | |
688 | ||
cc6d0d2c | 689 | @item boolean |
969fe9b5 RS |
690 | The value is boolean---either @code{nil} or @code{t}. Note that by |
691 | using @code{choice} and @code{const} together (see the next section), | |
692 | you can specify that the value must be @code{nil} or @code{t}, but also | |
693 | specify the text to describe each value in a way that fits the specific | |
694 | meaning of the alternative. | |
5e0c8a23 DL |
695 | |
696 | @item coding-system | |
697 | The value must be a coding-system name, and you can do completion with | |
698 | @kbd{M-@key{TAB}}. | |
699 | ||
700 | @item color | |
701 | The value must be a valid color name, and you can do completion with | |
97073664 | 702 | @kbd{M-@key{TAB}}. A sample is provided. |
cc6d0d2c RS |
703 | @end table |
704 | ||
705 | @node Composite Types | |
706 | @subsection Composite Types | |
608dc417 | 707 | @cindex arguments (of composite type) |
cc6d0d2c RS |
708 | |
709 | When none of the simple types is appropriate, you can use composite | |
608dc417 RS |
710 | types, which build new types from other types or from specified data. |
711 | The specified types or data are called the @dfn{arguments} of the | |
712 | composite type. The composite type normally looks like this: | |
cc6d0d2c RS |
713 | |
714 | @example | |
608dc417 | 715 | (@var{constructor} @var{arguments}@dots{}) |
cc6d0d2c RS |
716 | @end example |
717 | ||
718 | @noindent | |
608dc417 RS |
719 | but you can also add keyword-value pairs before the arguments, like |
720 | this: | |
cc6d0d2c | 721 | |
608dc417 RS |
722 | @example |
723 | (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{}) | |
724 | @end example | |
cc6d0d2c | 725 | |
608dc417 RS |
726 | Here is a table of constructors and how to use them to write |
727 | composite types: | |
728 | ||
729 | @table @code | |
cc6d0d2c RS |
730 | @item (cons @var{car-type} @var{cdr-type}) |
731 | The value must be a cons cell, its @sc{car} must fit @var{car-type}, and | |
a9f0a989 | 732 | its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string |
cc6d0d2c RS |
733 | symbol)} is a customization type which matches values such as |
734 | @code{("foo" . foo)}. | |
735 | ||
969fe9b5 | 736 | In the customization buffer, the @sc{car} and the @sc{cdr} are |
cc6d0d2c RS |
737 | displayed and edited separately, each according to the type |
738 | that you specify for it. | |
739 | ||
740 | @item (list @var{element-types}@dots{}) | |
741 | The value must be a list with exactly as many elements as the | |
42995636 | 742 | @var{element-types} given; and each element must fit the |
cc6d0d2c RS |
743 | corresponding @var{element-type}. |
744 | ||
745 | For example, @code{(list integer string function)} describes a list of | |
746 | three elements; the first element must be an integer, the second a | |
747 | string, and the third a function. | |
748 | ||
a9f0a989 | 749 | In the customization buffer, each element is displayed and edited |
cc6d0d2c RS |
750 | separately, according to the type specified for it. |
751 | ||
752 | @item (vector @var{element-types}@dots{}) | |
753 | Like @code{list} except that the value must be a vector instead of a | |
754 | list. The elements work the same as in @code{list}. | |
755 | ||
4577e8cc | 756 | @item (choice @var{alternative-types}@dots{}) |
cc6d0d2c RS |
757 | The value must fit at least one of @var{alternative-types}. |
758 | For example, @code{(choice integer string)} allows either an | |
759 | integer or a string. | |
760 | ||
42995636 | 761 | In the customization buffer, the user selects an alternative |
cc6d0d2c RS |
762 | using a menu, and can then edit the value in the usual way for that |
763 | alternative. | |
764 | ||
765 | Normally the strings in this menu are determined automatically from the | |
766 | choices; however, you can specify different strings for the menu by | |
767 | including the @code{:tag} keyword in the alternatives. For example, if | |
768 | an integer stands for a number of spaces, while a string is text to use | |
769 | verbatim, you might write the customization type this way, | |
770 | ||
a9f0a989 | 771 | @example |
cc6d0d2c RS |
772 | (choice (integer :tag "Number of spaces") |
773 | (string :tag "Literal text")) | |
a9f0a989 | 774 | @end example |
cc6d0d2c RS |
775 | |
776 | @noindent | |
38c7d6d5 | 777 | so that the menu offers @samp{Number of spaces} and @samp{Literal text}. |
cc6d0d2c | 778 | |
969fe9b5 RS |
779 | In any alternative for which @code{nil} is not a valid value, other than |
780 | a @code{const}, you should specify a valid default for that alternative | |
781 | using the @code{:value} keyword. @xref{Type Keywords}. | |
782 | ||
b56f98ab RS |
783 | If some values are covered by more than one of the alternatives, |
784 | customize will choose the first alternative that the value fits. This | |
785 | means you should always list the most specific types first, and the | |
786 | most general last. Here's an example of proper usage: | |
787 | ||
788 | @example | |
342fd6cd RS |
789 | (choice (const :tag "Off" nil) |
790 | symbol (sexp :tag "Other")) | |
b56f98ab RS |
791 | @end example |
792 | ||
793 | @noindent | |
794 | This way, the special value @code{nil} is not treated like other | |
795 | symbols, and symbols are not treated like other Lisp expressions. | |
796 | ||
4577e8cc DL |
797 | @item (radio @var{element-types}@dots{}) |
798 | This is similar to @code{choice}, except that the choices are displayed | |
799 | using `radio buttons' rather than a menu. This has the advantage of | |
800 | displaying documentation for the choices when applicable and so is often | |
801 | a good choice for a choice between constant functions | |
802 | (@code{function-item} customization types). | |
803 | ||
cc6d0d2c RS |
804 | @item (const @var{value}) |
805 | The value must be @var{value}---nothing else is allowed. | |
806 | ||
807 | The main use of @code{const} is inside of @code{choice}. For example, | |
808 | @code{(choice integer (const nil))} allows either an integer or | |
969fe9b5 RS |
809 | @code{nil}. |
810 | ||
811 | @code{:tag} is often used with @code{const}, inside of @code{choice}. | |
812 | For example, | |
813 | ||
a9f0a989 | 814 | @example |
969fe9b5 RS |
815 | (choice (const :tag "Yes" t) |
816 | (const :tag "No" nil) | |
817 | (const :tag "Ask" foo)) | |
a9f0a989 | 818 | @end example |
cc6d0d2c | 819 | |
da03dc1d RS |
820 | @noindent |
821 | describes a variable for which @code{t} means yes, @code{nil} means no, | |
822 | and @code{foo} means ``ask.'' | |
823 | ||
824 | @item (other @var{value}) | |
825 | This alternative can match any Lisp value, but if the user chooses this | |
826 | alternative, that selects the value @var{value}. | |
827 | ||
828 | The main use of @code{other} is as the last element of @code{choice}. | |
829 | For example, | |
830 | ||
831 | @example | |
832 | (choice (const :tag "Yes" t) | |
833 | (const :tag "No" nil) | |
834 | (other :tag "Ask" foo)) | |
835 | @end example | |
836 | ||
837 | @noindent | |
838 | describes a variable for which @code{t} means yes, @code{nil} means no, | |
839 | and anything else means ``ask.'' If the user chooses @samp{Ask} from | |
840 | the menu of alternatives, that specifies the value @code{foo}; but any | |
841 | other value (not @code{t}, @code{nil} or @code{foo}) displays as | |
842 | @samp{Ask}, just like @code{foo}. | |
843 | ||
cc6d0d2c RS |
844 | @item (function-item @var{function}) |
845 | Like @code{const}, but used for values which are functions. This | |
969fe9b5 RS |
846 | displays the documentation string as well as the function name. |
847 | The documentation string is either the one you specify with | |
848 | @code{:doc}, or @var{function}'s own documentation string. | |
cc6d0d2c RS |
849 | |
850 | @item (variable-item @var{variable}) | |
851 | Like @code{const}, but used for values which are variable names. This | |
969fe9b5 RS |
852 | displays the documentation string as well as the variable name. The |
853 | documentation string is either the one you specify with @code{:doc}, or | |
854 | @var{variable}'s own documentation string. | |
cc6d0d2c | 855 | |
1f447a50 KH |
856 | @item (set @var{types}@dots{}) |
857 | The value must be a list, and each element of the list must match one of | |
858 | the @var{types} specified. | |
859 | ||
860 | This appears in the customization buffer as a checklist, so that each of | |
861 | @var{types} may have either one corresponding element or none. It is | |
862 | not possible to specify two different elements that match the same one | |
863 | of @var{types}. For example, @code{(set integer symbol)} allows one | |
864 | integer and/or one symbol in the list; it does not allow multiple | |
865 | integers or multiple symbols. As a result, it is rare to use | |
866 | nonspecific types such as @code{integer} in a @code{set}. | |
867 | ||
868 | Most often, the @var{types} in a @code{set} are @code{const} types, as | |
869 | shown here: | |
870 | ||
871 | @example | |
872 | (set (const :bold) (const :italic)) | |
873 | @end example | |
874 | ||
875 | Sometimes they describe possible elements in an alist: | |
876 | ||
877 | @example | |
878 | (set (cons :tag "Height" (const height) integer) | |
879 | (cons :tag "Width" (const width) integer)) | |
880 | @end example | |
881 | ||
882 | @noindent | |
883 | That lets the user specify a height value optionally | |
884 | and a width value optionally. | |
cc6d0d2c RS |
885 | |
886 | @item (repeat @var{element-type}) | |
887 | The value must be a list and each element of the list must fit the type | |
888 | @var{element-type}. This appears in the customization buffer as a | |
889 | list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding | |
890 | more elements or removing elements. | |
608dc417 RS |
891 | |
892 | @item (restricted-sexp :match-alternatives @var{criteria}) | |
893 | This is the most general composite type construct. The value may be | |
894 | any Lisp object that satisfies one of @var{criteria}. @var{criteria} | |
895 | should be a list, and each element should be one of these | |
896 | possibilities: | |
897 | ||
898 | @itemize @bullet | |
899 | @item | |
900 | A predicate---that is, a function of one argument that has no side | |
901 | effects, and returns either @code{nil} or non-@code{nil} according to | |
902 | the argument. Using a predicate in the list says that objects for which | |
903 | the predicate returns non-@code{nil} are acceptable. | |
904 | ||
905 | @item | |
906 | A quoted constant---that is, @code{'@var{object}}. This sort of element | |
907 | in the list says that @var{object} itself is an acceptable value. | |
908 | @end itemize | |
909 | ||
910 | For example, | |
911 | ||
912 | @example | |
913 | (restricted-sexp :match-alternatives | |
914 | (integerp 't 'nil)) | |
915 | @end example | |
916 | ||
917 | @noindent | |
918 | allows integers, @code{t} and @code{nil} as legitimate values. | |
919 | ||
920 | The customization buffer shows all legitimate values using their read | |
921 | syntax, and the user edits them textually. | |
922 | @end table | |
923 | ||
924 | Here is a table of the keywords you can use in keyword-value pairs | |
925 | in a composite type: | |
926 | ||
927 | @table @code | |
928 | @item :tag @var{tag} | |
929 | Use @var{tag} as the name of this alternative, for user communication | |
930 | purposes. This is useful for a type that appears inside of a | |
931 | @code{choice}. | |
932 | ||
933 | @item :match-alternatives @var{criteria} | |
83b97379 | 934 | @kindex match-alternatives@r{, customization keyword} |
608dc417 RS |
935 | Use @var{criteria} to match possible values. This is used only in |
936 | @code{restricted-sexp}. | |
937 | ||
38c7d6d5 | 938 | @item :args @var{argument-list} |
83b97379 | 939 | @kindex args@r{, customization keyword} |
38c7d6d5 | 940 | Use the elements of @var{argument-list} as the arguments of the type |
608dc417 RS |
941 | construct. For instance, @code{(const :args (foo))} is equivalent to |
942 | @code{(const foo)}. You rarely need to write @code{:args} explicitly, | |
943 | because normally the arguments are recognized automatically as | |
944 | whatever follows the last keyword-value pair. | |
cc6d0d2c RS |
945 | @end table |
946 | ||
947 | @node Splicing into Lists | |
948 | @subsection Splicing into Lists | |
949 | ||
950 | The @code{:inline} feature lets you splice a variable number of | |
951 | elements into the middle of a list or vector. You use it in a | |
952 | @code{set}, @code{choice} or @code{repeat} type which appears among the | |
953 | element-types of a @code{list} or @code{vector}. | |
954 | ||
955 | Normally, each of the element-types in a @code{list} or @code{vector} | |
956 | describes one and only one element of the list or vector. Thus, if an | |
957 | element-type is a @code{repeat}, that specifies a list of unspecified | |
958 | length which appears as one element. | |
959 | ||
960 | But when the element-type uses @code{:inline}, the value it matches is | |
961 | merged directly into the containing sequence. For example, if it | |
962 | matches a list with three elements, those become three elements of the | |
963 | overall sequence. This is analogous to using @samp{,@@} in the backquote | |
964 | construct. | |
965 | ||
241f79af | 966 | For example, to specify a list whose first element must be @code{baz} |
cc6d0d2c RS |
967 | and whose remaining arguments should be zero or more of @code{foo} and |
968 | @code{bar}, use this customization type: | |
969 | ||
970 | @example | |
241f79af | 971 | (list (const baz) (set :inline t (const foo) (const bar))) |
cc6d0d2c RS |
972 | @end example |
973 | ||
974 | @noindent | |
241f79af PA |
975 | This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)} |
976 | and @code{(baz foo bar)}. | |
cc6d0d2c RS |
977 | |
978 | When the element-type is a @code{choice}, you use @code{:inline} not | |
979 | in the @code{choice} itself, but in (some of) the alternatives of the | |
980 | @code{choice}. For example, to match a list which must start with a | |
981 | file name, followed either by the symbol @code{t} or two strings, use | |
982 | this customization type: | |
983 | ||
984 | @example | |
985 | (list file | |
986 | (choice (const t) | |
987 | (list :inline t string string))) | |
988 | @end example | |
989 | ||
990 | @noindent | |
991 | If the user chooses the first alternative in the choice, then the | |
992 | overall list has two elements and the second element is @code{t}. If | |
993 | the user chooses the second alternative, then the overall list has three | |
994 | elements and the second and third must be strings. | |
995 | ||
996 | @node Type Keywords | |
997 | @subsection Type Keywords | |
998 | ||
999 | You can specify keyword-argument pairs in a customization type after the | |
1000 | type name symbol. Here are the keywords you can use, and their | |
1001 | meanings: | |
1002 | ||
1003 | @table @code | |
1004 | @item :value @var{default} | |
1005 | This is used for a type that appears as an alternative inside of | |
969fe9b5 | 1006 | @code{choice}; it specifies the default value to use, at first, if and |
cc6d0d2c RS |
1007 | when the user selects this alternative with the menu in the |
1008 | customization buffer. | |
1009 | ||
1010 | Of course, if the actual value of the option fits this alternative, it | |
1011 | will appear showing the actual value, not @var{default}. | |
1012 | ||
969fe9b5 RS |
1013 | If @code{nil} is not a valid value for the alternative, then it is |
1014 | essential to specify a valid default with @code{:value}. | |
1015 | ||
cc6d0d2c | 1016 | @item :format @var{format-string} |
83b97379 | 1017 | @kindex format@r{, customization keyword} |
cc6d0d2c RS |
1018 | This string will be inserted in the buffer to represent the value |
1019 | corresponding to the type. The following @samp{%} escapes are available | |
1020 | for use in @var{format-string}: | |
1021 | ||
1022 | @table @samp | |
cc6d0d2c RS |
1023 | @item %[@var{button}%] |
1024 | Display the text @var{button} marked as a button. The @code{:action} | |
1025 | attribute specifies what the button will do if the user invokes it; | |
1026 | its value is a function which takes two arguments---the widget which | |
1027 | the button appears in, and the event. | |
1028 | ||
1029 | There is no way to specify two different buttons with different | |
969fe9b5 | 1030 | actions. |
cc6d0d2c RS |
1031 | |
1032 | @item %@{@var{sample}%@} | |
1033 | Show @var{sample} in a special face specified by @code{:sample-face}. | |
1034 | ||
1035 | @item %v | |
1036 | Substitute the item's value. How the value is represented depends on | |
1037 | the kind of item, and (for variables) on the customization type. | |
1038 | ||
1039 | @item %d | |
1040 | Substitute the item's documentation string. | |
1041 | ||
1042 | @item %h | |
1043 | Like @samp{%d}, but if the documentation string is more than one line, | |
1044 | add an active field to control whether to show all of it or just the | |
1045 | first line. | |
1046 | ||
1047 | @item %t | |
1048 | Substitute the tag here. You specify the tag with the @code{:tag} | |
1049 | keyword. | |
1050 | ||
1051 | @item %% | |
177c0ea7 | 1052 | Display a literal @samp{%}. |
cc6d0d2c RS |
1053 | @end table |
1054 | ||
969fe9b5 | 1055 | @item :action @var{action} |
83b97379 | 1056 | @kindex action@r{, customization keyword} |
969fe9b5 RS |
1057 | Perform @var{action} if the user clicks on a button. |
1058 | ||
cc6d0d2c | 1059 | @item :button-face @var{face} |
83b97379 | 1060 | @kindex button-face@r{, customization keyword} |
969fe9b5 RS |
1061 | Use the face @var{face} (a face name or a list of face names) for button |
1062 | text displayed with @samp{%[@dots{}%]}. | |
cc6d0d2c | 1063 | |
969fe9b5 RS |
1064 | @item :button-prefix @var{prefix} |
1065 | @itemx :button-suffix @var{suffix} | |
83b97379 EZ |
1066 | @kindex button-prefix@r{, customization keyword} |
1067 | @kindex button-suffix@r{, customization keyword} | |
cc6d0d2c RS |
1068 | These specify the text to display before and after a button. |
1069 | Each can be: | |
1070 | ||
1071 | @table @asis | |
1072 | @item @code{nil} | |
1073 | No text is inserted. | |
1074 | ||
1075 | @item a string | |
1076 | The string is inserted literally. | |
1077 | ||
1078 | @item a symbol | |
1079 | The symbol's value is used. | |
1080 | @end table | |
1081 | ||
969fe9b5 RS |
1082 | @item :tag @var{tag} |
1083 | Use @var{tag} (a string) as the tag for the value (or part of the value) | |
1084 | that corresponds to this type. | |
1085 | ||
cc6d0d2c | 1086 | @item :doc @var{doc} |
83b97379 | 1087 | @kindex doc@r{, customization keyword} |
969fe9b5 RS |
1088 | Use @var{doc} as the documentation string for this value (or part of the |
1089 | value) that corresponds to this type. In order for this to work, you | |
1090 | must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} | |
1091 | in that value. | |
cc6d0d2c | 1092 | |
969fe9b5 RS |
1093 | The usual reason to specify a documentation string for a type is to |
1094 | provide more information about the meanings of alternatives inside a | |
1095 | @code{:choice} type or the parts of some other composite type. | |
cc6d0d2c RS |
1096 | |
1097 | @item :help-echo @var{motion-doc} | |
83b97379 | 1098 | @kindex help-echo@r{, customization keyword} |
cc6d0d2c | 1099 | When you move to this item with @code{widget-forward} or |
19182f77 DL |
1100 | @code{widget-backward}, it will display the string @var{motion-doc} in |
1101 | the echo area. In addition, @var{motion-doc} is used as the mouse | |
1102 | @code{help-echo} string and may actually be a function or form evaluated | |
17458c91 LT |
1103 | to yield a help string. If it is a function, it is called with one |
1104 | argument, the widget. | |
cc6d0d2c RS |
1105 | |
1106 | @item :match @var{function} | |
83b97379 | 1107 | @kindex match@r{, customization keyword} |
969fe9b5 RS |
1108 | Specify how to decide whether a value matches the type. The |
1109 | corresponding value, @var{function}, should be a function that accepts | |
1110 | two arguments, a widget and a value; it should return non-@code{nil} if | |
1111 | the value is acceptable. | |
cc6d0d2c RS |
1112 | |
1113 | @ignore | |
1114 | @item :indent @var{columns} | |
1115 | Indent this item by @var{columns} columns. The indentation is used for | |
1116 | @samp{%n}, and automatically for group names, for checklists and radio | |
1117 | buttons, and for editable lists. It affects the whole of the | |
1118 | item except for the first line. | |
1119 | ||
1120 | @item :offset @var{columns} | |
1121 | An integer indicating how many extra spaces to indent the subitems of | |
1122 | this item. By default, subitems are indented the same as their parent. | |
1123 | ||
1124 | @item :extra-offset | |
1125 | An integer indicating how many extra spaces to add to this item's | |
1126 | indentation, compared to its parent. | |
1127 | ||
1128 | @item :notify | |
1129 | A function called each time the item or a subitem is changed. The | |
1130 | function is called with two or three arguments. The first argument is | |
1131 | the item itself, the second argument is the item that was changed, and | |
1132 | the third argument is the event leading to the change, if any. | |
1133 | ||
1134 | @item :menu-tag | |
35208b42 | 1135 | A tag used in the menu when the widget is used as an option in a |
cc6d0d2c RS |
1136 | @code{menu-choice} widget. |
1137 | ||
1138 | @item :menu-tag-get | |
35208b42 | 1139 | A function used for finding the tag when the widget is used as an option |
cc6d0d2c RS |
1140 | in a @code{menu-choice} widget. By default, the tag used will be either the |
1141 | @code{:menu-tag} or @code{:tag} property if present, or the @code{princ} | |
1142 | representation of the @code{:value} property if not. | |
1143 | ||
1144 | @item :validate | |
35208b42 RS |
1145 | A function which takes a widget as an argument, and return @code{nil} |
1146 | if the widget's current value is valid for the widget. Otherwise, it | |
1147 | should return the widget containing the invalid data, and set that | |
1148 | widget's @code{:error} property to a string explaining the error. | |
cc6d0d2c RS |
1149 | |
1150 | You can use the function @code{widget-children-validate} for this job; | |
1151 | it tests that all children of @var{widget} are valid. | |
1152 | ||
1153 | @item :tab-order | |
1154 | Specify the order in which widgets are traversed with | |
1155 | @code{widget-forward} or @code{widget-backward}. This is only partially | |
1156 | implemented. | |
1157 | ||
1158 | @enumerate a | |
1159 | @item | |
1160 | Widgets with tabbing order @code{-1} are ignored. | |
1161 | ||
177c0ea7 | 1162 | @item |
cc6d0d2c RS |
1163 | (Unimplemented) When on a widget with tabbing order @var{n}, go to the |
1164 | next widget in the buffer with tabbing order @var{n+1} or @code{nil}, | |
1165 | whichever comes first. | |
1166 | ||
1167 | @item | |
1168 | When on a widget with no tabbing order specified, go to the next widget | |
1169 | in the buffer with a positive tabbing order, or @code{nil} | |
1170 | @end enumerate | |
1171 | ||
1172 | @item :parent | |
a9f0a989 | 1173 | The parent of a nested widget (e.g., a @code{menu-choice} item or an |
cc6d0d2c RS |
1174 | element of a @code{editable-list} widget). |
1175 | ||
1176 | @item :sibling-args | |
1177 | This keyword is only used for members of a @code{radio-button-choice} or | |
1178 | @code{checklist}. The value should be a list of extra keyword | |
1179 | arguments, which will be used when creating the @code{radio-button} or | |
1180 | @code{checkbox} associated with this item. | |
1181 | @end ignore | |
1182 | @end table | |
ab5796a9 | 1183 | |
cfa921fd PA |
1184 | @node Defining New Types |
1185 | @subsection Defining New Types | |
1186 | ||
1187 | In the previous sections we have described how to construct elaborate | |
38c7d6d5 RS |
1188 | type specifications for @code{defcustom}. In some cases you may want |
1189 | to give such a type specification a name. The obvious case is when | |
1190 | you are using the same type for many user options: rather than repeat | |
1191 | the specification for each option, you can give the type specification | |
1192 | a name, and use that name each @code{defcustom}. The other case is | |
1193 | when a user option's value is a recursive data structure. To make it | |
cfa921fd PA |
1194 | possible for a datatype to refer to itself, it needs to have a name. |
1195 | ||
1196 | Since custom types are implemented as widgets, the way to define a new | |
1197 | customize type is to define a new widget. We are not going to describe | |
1198 | the widget interface here in details, see @ref{Top, , Introduction, | |
1199 | widget, The Emacs Widget Library}, for that. Instead we are going to | |
1200 | demonstrate the minimal functionality needed for defining new customize | |
1201 | types by a simple example. | |
1202 | ||
1203 | @example | |
1204 | (define-widget 'binary-tree-of-string 'lazy | |
1205 | "A binary tree made of cons-cells and strings." | |
1206 | :offset 4 | |
1207 | :tag "Node" | |
1208 | :type '(choice (string :tag "Leaf" :value "") | |
1209 | (cons :tag "Interior" | |
97073664 | 1210 | :value ("" . "") |
cfa921fd PA |
1211 | binary-tree-of-string |
1212 | binary-tree-of-string))) | |
1213 | ||
1214 | (defcustom foo-bar "" | |
1215 | "Sample variable holding a binary tree of strings." | |
1216 | :type 'binary-tree-of-string) | |
1217 | @end example | |
1218 | ||
38c7d6d5 | 1219 | The function to define a new widget is called @code{define-widget}. The |
cfa921fd PA |
1220 | first argument is the symbol we want to make a new widget type. The |
1221 | second argument is a symbol representing an existing widget, the new | |
1222 | widget is going to be defined in terms of difference from the existing | |
1223 | widget. For the purpose of defining new customization types, the | |
38c7d6d5 | 1224 | @code{lazy} widget is perfect, because it accepts a @code{:type} keyword |
cfa921fd PA |
1225 | argument with the same syntax as the keyword argument to |
1226 | @code{defcustom} with the same name. The third argument is a | |
1227 | documentation string for the new widget. You will be able to see that | |
d5b3141d LT |
1228 | string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string |
1229 | @key{RET}} command. | |
cfa921fd | 1230 | |
38c7d6d5 RS |
1231 | After these mandatory arguments follow the keyword arguments. The most |
1232 | important is @code{:type}, which describes the data type we want to match | |
cfa921fd PA |
1233 | with this widget. Here a @code{binary-tree-of-string} is described as |
1234 | being either a string, or a cons-cell whose car and cdr are themselves | |
1235 | both @code{binary-tree-of-string}. Note the reference to the widget | |
1236 | type we are currently in the process of defining. The @code{:tag} | |
1237 | attribute is a string to name the widget in the user interface, and the | |
38c7d6d5 RS |
1238 | @code{:offset} argument is there to ensure that child nodes are |
1239 | indented four spaces relative to the parent node, making the tree | |
cfa921fd PA |
1240 | structure apparent in the customization buffer. |
1241 | ||
1242 | The @code{defcustom} shows how the new widget can be used as an ordinary | |
97073664 | 1243 | customization type. |
cfa921fd | 1244 | |
38c7d6d5 RS |
1245 | The reason for the name @code{lazy} is that the other composite |
1246 | widgets convert their inferior widgets to internal form when the | |
1247 | widget is instantiated in a buffer. This conversion is recursive, so | |
1248 | the inferior widgets will convert @emph{their} inferior widgets. If | |
1249 | the data structure is itself recursive, this conversion is an infinite | |
1250 | recursion. The @code{lazy} widget prevents the recursion: it convert | |
1251 | its @code{:type} argument only when needed. | |
cfa921fd | 1252 | |
ab5796a9 MB |
1253 | @ignore |
1254 | arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2 | |
1255 | @end ignore |