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