Commit | Line | Data |
---|---|---|
b8d4c8d0 GM |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
ba318903 | 3 | @c Copyright (C) 1997-2014 Free Software Foundation, Inc. |
b8d4c8d0 | 4 | @c See the file elisp.texi for copying conditions. |
ecc6530d | 5 | @node Customization |
81927dd2 | 6 | @chapter Customization Settings |
b8d4c8d0 | 7 | |
81927dd2 | 8 | @cindex customization item |
ed1f0bd3 CY |
9 | Users of Emacs can customize variables and faces without writing |
10 | Lisp code, by using the Customize interface. @xref{Easy | |
11 | Customization,,, emacs, The GNU Emacs Manual}. This chapter describes | |
12 | how to define @dfn{customization items} that users can interact with | |
13 | through the Customize interface. | |
14 | ||
15 | Customization items include customizable variables, which are | |
16 | defined with the | |
17 | @ifinfo | |
18 | @code{defcustom} macro (@pxref{Variable Definitions}); | |
19 | @end ifinfo | |
20 | @ifnotinfo | |
21 | @code{defcustom} macro; | |
22 | @end ifnotinfo | |
23 | customizable faces, which are defined with @code{defface} (described | |
24 | separately in @ref{Defining Faces}); and @dfn{customization groups}, | |
25 | defined with | |
26 | @ifinfo | |
27 | @code{defgroup} (@pxref{Group Definitions}), | |
28 | @end ifinfo | |
29 | @ifnotinfo | |
30 | @code{defgroup}, | |
31 | @end ifnotinfo | |
32 | which act as containers for groups of related customization items. | |
b8d4c8d0 GM |
33 | |
34 | @menu | |
81927dd2 CY |
35 | * Common Keywords:: Common keyword arguments for all kinds of |
36 | customization declarations. | |
37 | * Group Definitions:: Writing customization group definitions. | |
38 | * Variable Definitions:: Declaring user options. | |
39 | * Customization Types:: Specifying the type of a user option. | |
40 | * Applying Customizations:: Functions to apply customization settings. | |
41 | * Custom Themes:: Writing Custom themes. | |
b8d4c8d0 GM |
42 | @end menu |
43 | ||
44 | @node Common Keywords | |
45 | @section Common Item Keywords | |
46 | ||
47 | @cindex customization keywords | |
03988c98 | 48 | The customization declarations that we will describe in the next few |
ed1f0bd3 CY |
49 | sections---@code{defcustom}, @code{defgroup}, etc.---all accept |
50 | keyword arguments (@pxref{Constant Variables}) for specifying various | |
51 | information. This section describes keywords that apply to all types | |
52 | of customization declarations. | |
b8d4c8d0 GM |
53 | |
54 | All of these keywords, except @code{:tag}, can be used more than once | |
55 | in a given item. Each use of the keyword has an independent effect. | |
56 | The keyword @code{:tag} is an exception because any given item can only | |
57 | display one name. | |
58 | ||
59 | @table @code | |
60 | @item :tag @var{label} | |
61 | @kindex tag@r{, customization keyword} | |
62 | Use @var{label}, a string, instead of the item's name, to label the | |
63 | item in customization menus and buffers. @strong{Don't use a tag | |
64 | which is substantially different from the item's real name; that would | |
0f631634 | 65 | cause confusion.} |
b8d4c8d0 GM |
66 | |
67 | @kindex group@r{, customization keyword} | |
68 | @item :group @var{group} | |
69 | Put this customization item in group @var{group}. When you use | |
70 | @code{:group} in a @code{defgroup}, it makes the new group a subgroup of | |
71 | @var{group}. | |
72 | ||
73 | If you use this keyword more than once, you can put a single item into | |
74 | more than one group. Displaying any of those groups will show this | |
75 | item. Please don't overdo this, since the result would be annoying. | |
76 | ||
77 | @item :link @var{link-data} | |
78 | @kindex link@r{, customization keyword} | |
79 | Include an external link after the documentation string for this item. | |
22ff2cb8 | 80 | This is a sentence containing a button that references some |
b8d4c8d0 GM |
81 | other documentation. |
82 | ||
83 | There are several alternatives you can use for @var{link-data}: | |
84 | ||
85 | @table @code | |
86 | @item (custom-manual @var{info-node}) | |
87 | Link to an Info node; @var{info-node} is a string which specifies the | |
88 | node name, as in @code{"(emacs)Top"}. The link appears as | |
89 | @samp{[Manual]} in the customization buffer and enters the built-in | |
90 | Info reader on @var{info-node}. | |
91 | ||
92 | @item (info-link @var{info-node}) | |
93 | Like @code{custom-manual} except that the link appears | |
94 | in the customization buffer with the Info node name. | |
95 | ||
96 | @item (url-link @var{url}) | |
97 | Link to a web page; @var{url} is a string which specifies the | |
98 | @acronym{URL}. The link appears in the customization buffer as | |
99 | @var{url} and invokes the WWW browser specified by | |
100 | @code{browse-url-browser-function}. | |
101 | ||
102 | @item (emacs-commentary-link @var{library}) | |
103 | Link to the commentary section of a library; @var{library} is a string | |
9800c5b0 | 104 | which specifies the library name. @xref{Library Headers}. |
b8d4c8d0 GM |
105 | |
106 | @item (emacs-library-link @var{library}) | |
107 | Link to an Emacs Lisp library file; @var{library} is a string which | |
108 | specifies the library name. | |
109 | ||
110 | @item (file-link @var{file}) | |
111 | Link to a file; @var{file} is a string which specifies the name of the | |
112 | file to visit with @code{find-file} when the user invokes this link. | |
113 | ||
114 | @item (function-link @var{function}) | |
115 | Link to the documentation of a function; @var{function} is a string | |
116 | which specifies the name of the function to describe with | |
117 | @code{describe-function} when the user invokes this link. | |
118 | ||
119 | @item (variable-link @var{variable}) | |
120 | Link to the documentation of a variable; @var{variable} is a string | |
121 | which specifies the name of the variable to describe with | |
122 | @code{describe-variable} when the user invokes this link. | |
123 | ||
124 | @item (custom-group-link @var{group}) | |
125 | Link to another customization group. Invoking it creates a new | |
126 | customization buffer for @var{group}. | |
127 | @end table | |
128 | ||
129 | You can specify the text to use in the customization buffer by adding | |
130 | @code{:tag @var{name}} after the first element of the @var{link-data}; | |
131 | for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to | |
132 | the Emacs manual which appears in the buffer as @samp{foo}. | |
133 | ||
03988c98 | 134 | You can use this keyword more than once, to add multiple links. |
b8d4c8d0 GM |
135 | |
136 | @item :load @var{file} | |
137 | @kindex load@r{, customization keyword} | |
138 | Load file @var{file} (a string) before displaying this customization | |
f6de8a37 CY |
139 | item (@pxref{Loading}). Loading is done with @code{load}, and only if |
140 | the file is not already loaded. | |
b8d4c8d0 GM |
141 | |
142 | @item :require @var{feature} | |
143 | @kindex require@r{, customization keyword} | |
144 | Execute @code{(require '@var{feature})} when your saved customizations | |
145 | set the value of this item. @var{feature} should be a symbol. | |
146 | ||
147 | The most common reason to use @code{:require} is when a variable enables | |
148 | a feature such as a minor mode, and just setting the variable won't have | |
149 | any effect unless the code which implements the mode is loaded. | |
150 | ||
151 | @item :version @var{version} | |
152 | @kindex version@r{, customization keyword} | |
153 | This keyword specifies that the item was first introduced in Emacs | |
154 | version @var{version}, or that its default value was changed in that | |
155 | version. The value @var{version} must be a string. | |
156 | ||
157 | @item :package-version '(@var{package} . @var{version}) | |
158 | @kindex package-version@r{, customization keyword} | |
159 | This keyword specifies that the item was first introduced in | |
160 | @var{package} version @var{version}, or that its meaning or default | |
03988c98 CY |
161 | value was changed in that version. This keyword takes priority over |
162 | @code{:version}. | |
b8d4c8d0 | 163 | |
03988c98 | 164 | @var{package} should be the official name of the package, as a symbol |
1df7defd | 165 | (e.g., @code{MH-E}). @var{version} should be a string. If the |
03988c98 CY |
166 | package @var{package} is released as part of Emacs, @var{package} and |
167 | @var{version} should appear in the value of | |
b8d4c8d0 GM |
168 | @code{customize-package-emacs-version-alist}. |
169 | @end table | |
170 | ||
171 | Packages distributed as part of Emacs that use the | |
172 | @code{:package-version} keyword must also update the | |
173 | @code{customize-package-emacs-version-alist} variable. | |
174 | ||
175 | @defvar customize-package-emacs-version-alist | |
176 | This alist provides a mapping for the versions of Emacs that are | |
177 | associated with versions of a package listed in the | |
ddff3351 | 178 | @code{:package-version} keyword. Its elements are: |
b8d4c8d0 GM |
179 | |
180 | @example | |
181 | (@var{package} (@var{pversion} . @var{eversion})@dots{}) | |
182 | @end example | |
183 | ||
184 | For each @var{package}, which is a symbol, there are one or more | |
185 | elements that contain a package version @var{pversion} with an | |
186 | associated Emacs version @var{eversion}. These versions are strings. | |
187 | For example, the MH-E package updates this alist with the following: | |
188 | ||
ddff3351 GM |
189 | @c Must be small else too wide. |
190 | @c FIXME obviously this is out of date (in the code). | |
b8d4c8d0 GM |
191 | @smallexample |
192 | (add-to-list 'customize-package-emacs-version-alist | |
193 | '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1") | |
194 | ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1") | |
195 | ("7.4" . "22.1") ("8.0" . "22.1"))) | |
196 | @end smallexample | |
197 | ||
198 | The value of @var{package} needs to be unique and it needs to match | |
199 | the @var{package} value appearing in the @code{:package-version} | |
35a30759 | 200 | keyword. Since the user might see the value in an error message, a good |
b8d4c8d0 GM |
201 | choice is the official name of the package, such as MH-E or Gnus. |
202 | @end defvar | |
203 | ||
204 | @node Group Definitions | |
205 | @section Defining Customization Groups | |
206 | @cindex define customization group | |
207 | @cindex customization groups, defining | |
208 | ||
ed1f0bd3 CY |
209 | Each Emacs Lisp package should have one main customization group |
210 | which contains all the options, faces and other groups in the package. | |
211 | If the package has a small number of options and faces, use just one | |
212 | group and put everything in it. When there are more than twenty or so | |
213 | options and faces, then you should structure them into subgroups, and | |
214 | put the subgroups under the package's main customization group. It is | |
215 | OK to put some of the options and faces in the package's main group | |
216 | alongside the subgroups. | |
b8d4c8d0 GM |
217 | |
218 | The package's main or only group should be a member of one or more of | |
219 | the standard customization groups. (To display the full list of them, | |
220 | use @kbd{M-x customize}.) Choose one or more of them (but not too | |
221 | many), and add your group to each of them using the @code{:group} | |
222 | keyword. | |
223 | ||
224 | The way to declare new customization groups is with @code{defgroup}. | |
225 | ||
226 | @defmac defgroup group members doc [keyword value]@dots{} | |
227 | Declare @var{group} as a customization group containing @var{members}. | |
228 | Do not quote the symbol @var{group}. The argument @var{doc} specifies | |
229 | the documentation string for the group. | |
230 | ||
231 | The argument @var{members} is a list specifying an initial set of | |
232 | customization items to be members of the group. However, most often | |
233 | @var{members} is @code{nil}, and you specify the group's members by | |
234 | using the @code{:group} keyword when defining those members. | |
235 | ||
236 | If you want to specify group members through @var{members}, each element | |
237 | should have the form @code{(@var{name} @var{widget})}. Here @var{name} | |
238 | is a symbol, and @var{widget} is a widget type for editing that symbol. | |
239 | Useful widgets are @code{custom-variable} for a variable, | |
240 | @code{custom-face} for a face, and @code{custom-group} for a group. | |
241 | ||
242 | When you introduce a new group into Emacs, use the @code{:version} | |
243 | keyword in the @code{defgroup}; then you need not use it for | |
244 | the individual members of the group. | |
245 | ||
246 | In addition to the common keywords (@pxref{Common Keywords}), you can | |
247 | also use this keyword in @code{defgroup}: | |
248 | ||
249 | @table @code | |
250 | @item :prefix @var{prefix} | |
251 | @kindex prefix@r{, @code{defgroup} keyword} | |
03988c98 CY |
252 | If the name of an item in the group starts with @var{prefix}, and the |
253 | customizable variable @code{custom-unlispify-remove-prefixes} is | |
254 | non-@code{nil}, the item's tag will omit @var{prefix}. A group can | |
255 | have any number of prefixes. | |
b8d4c8d0 GM |
256 | @end table |
257 | @end defmac | |
258 | ||
03988c98 CY |
259 | @defopt custom-unlispify-remove-prefixes |
260 | If this variable is non-@code{nil}, the prefixes specified by a | |
261 | group's @code{:prefix} keyword are omitted from tag names, whenever | |
262 | the user customizes the group. | |
b8d4c8d0 | 263 | |
1df7defd | 264 | The default value is @code{nil}, i.e., the prefix-discarding feature |
03988c98 CY |
265 | is disabled. This is because discarding prefixes often leads to |
266 | confusing names for options and faces. | |
267 | @end defopt | |
b8d4c8d0 GM |
268 | |
269 | @node Variable Definitions | |
270 | @section Defining Customization Variables | |
271 | @cindex define customization options | |
ed1f0bd3 CY |
272 | @cindex customizable variables, how to define |
273 | @cindex user options, how to define | |
274 | ||
275 | @dfn{Customizable variables}, also called @dfn{user options}, are | |
276 | global Lisp variables whose values can be set through the Customize | |
277 | interface. Unlike other global variables, which are defined with | |
278 | @code{defvar} (@pxref{Defining Variables}), customizable variables are | |
279 | defined using the @code{defcustom} macro. In addition to calling | |
280 | @code{defvar} as a subroutine, @code{defcustom} states how the | |
281 | variable should be displayed in the Customize interface, the values it | |
282 | is allowed to take, etc. | |
b8d4c8d0 | 283 | |
b8d4c8d0 | 284 | @defmac defcustom option standard doc [keyword value]@dots{} |
1df7defd | 285 | This macro declares @var{option} as a user option (i.e., a |
03988c98 | 286 | customizable variable). You should not quote @var{option}. |
0f631634 | 287 | |
b8d4c8d0 GM |
288 | The argument @var{standard} is an expression that specifies the |
289 | standard value for @var{option}. Evaluating the @code{defcustom} form | |
81c7d631 CY |
290 | evaluates @var{standard}, but does not necessarily bind the option to |
291 | that value. If @var{option} already has a default value, it is left | |
292 | unchanged. If the user has already saved a customization for | |
293 | @var{option}, the user's customized value is installed as the default | |
294 | value. Otherwise, the result of evaluating @var{standard} is | |
295 | installed as the default value. | |
296 | ||
297 | Like @code{defvar}, this macro marks @code{option} as a special | |
298 | variable, meaning that it should always be dynamically bound. If | |
299 | @var{option} is already lexically bound, that lexical binding remains | |
300 | in effect until the binding construct exits. @xref{Variable Scoping}. | |
b8d4c8d0 GM |
301 | |
302 | The expression @var{standard} can be evaluated at various other times, | |
303 | too---whenever the customization facility needs to know @var{option}'s | |
304 | standard value. So be sure to use an expression which is harmless to | |
03988c98 | 305 | evaluate at any time. |
b8d4c8d0 | 306 | |
1021c761 CY |
307 | The argument @var{doc} specifies the documentation string for the |
308 | variable. | |
309 | ||
1cbae532 SM |
310 | If a @code{defcustom} does not specify any @code{:group}, the last group |
311 | defined with @code{defgroup} in the same file will be used. This way, most | |
312 | @code{defcustom} do not need an explicit @code{:group}. | |
b8d4c8d0 | 313 | |
b8d4c8d0 GM |
314 | When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp |
315 | mode (@code{eval-defun}), a special feature of @code{eval-defun} | |
316 | arranges to set the variable unconditionally, without testing whether | |
c6c08d3f GM |
317 | its value is void. (The same feature applies to @code{defvar}, |
318 | @pxref{Defining Variables}.) Using @code{eval-defun} on a defcustom | |
319 | that is already defined calls the @code{:set} function (see below), | |
320 | if there is one. | |
437706cd | 321 | |
03988c98 CY |
322 | If you put a @code{defcustom} in a pre-loaded Emacs Lisp file |
323 | (@pxref{Building Emacs}), the standard value installed at dump time | |
1df7defd | 324 | might be incorrect, e.g., because another variable that it depends on |
03988c98 | 325 | has not been assigned the right value yet. In that case, use |
437706cd | 326 | @code{custom-reevaluate-setting}, described below, to re-evaluate the |
03988c98 | 327 | standard value after Emacs starts up. |
b8d4c8d0 GM |
328 | @end defmac |
329 | ||
ed1f0bd3 CY |
330 | In addition to the keywords listed in @ref{Common Keywords}, this |
331 | macro accepts the following keywords: | |
b8d4c8d0 GM |
332 | |
333 | @table @code | |
334 | @item :type @var{type} | |
335 | Use @var{type} as the data type for this option. It specifies which | |
ed1f0bd3 CY |
336 | values are legitimate, and how to display the value |
337 | (@pxref{Customization Types}). | |
b8d4c8d0 GM |
338 | |
339 | @item :options @var{value-list} | |
340 | @kindex options@r{, @code{defcustom} keyword} | |
341 | Specify the list of reasonable values for use in this | |
342 | option. The user is not restricted to using only these values, but they | |
343 | are offered as convenient alternatives. | |
344 | ||
345 | This is meaningful only for certain types, currently including | |
346 | @code{hook}, @code{plist} and @code{alist}. See the definition of the | |
347 | individual types for a description of how to use @code{:options}. | |
348 | ||
349 | @item :set @var{setfunction} | |
350 | @kindex set@r{, @code{defcustom} keyword} | |
351 | Specify @var{setfunction} as the way to change the value of this | |
81927dd2 | 352 | option when using the Customize interface. The function |
8a20ca4c LMI |
353 | @var{setfunction} should take two arguments, a symbol (the option |
354 | name) and the new value, and should do whatever is necessary to update | |
355 | the value properly for this option (which may not mean simply setting | |
356 | the option as a Lisp variable). The default for @var{setfunction} is | |
357 | @code{set-default}. | |
b8d4c8d0 | 358 | |
03988c98 CY |
359 | If you specify this keyword, the variable's documentation string |
360 | should describe how to do the same job in hand-written Lisp code. | |
361 | ||
b8d4c8d0 GM |
362 | @item :get @var{getfunction} |
363 | @kindex get@r{, @code{defcustom} keyword} | |
364 | Specify @var{getfunction} as the way to extract the value of this | |
365 | option. The function @var{getfunction} should take one argument, a | |
366 | symbol, and should return whatever customize should use as the | |
367 | ``current value'' for that symbol (which need not be the symbol's Lisp | |
368 | value). The default is @code{default-value}. | |
369 | ||
370 | You have to really understand the workings of Custom to use | |
371 | @code{:get} correctly. It is meant for values that are treated in | |
372 | Custom as variables but are not actually stored in Lisp variables. It | |
03988c98 | 373 | is almost surely a mistake to specify @var{getfunction} for a value |
b8d4c8d0 GM |
374 | that really is stored in a Lisp variable. |
375 | ||
376 | @item :initialize @var{function} | |
377 | @kindex initialize@r{, @code{defcustom} keyword} | |
378 | @var{function} should be a function used to initialize the variable | |
379 | when the @code{defcustom} is evaluated. It should take two arguments, | |
380 | the option name (a symbol) and the value. Here are some predefined | |
381 | functions meant for use in this way: | |
382 | ||
383 | @table @code | |
384 | @item custom-initialize-set | |
385 | Use the variable's @code{:set} function to initialize the variable, but | |
386 | do not reinitialize it if it is already non-void. | |
387 | ||
388 | @item custom-initialize-default | |
389 | Like @code{custom-initialize-set}, but use the function | |
390 | @code{set-default} to set the variable, instead of the variable's | |
391 | @code{:set} function. This is the usual choice for a variable whose | |
392 | @code{:set} function enables or disables a minor mode; with this choice, | |
393 | defining the variable will not call the minor mode function, but | |
394 | customizing the variable will do so. | |
395 | ||
396 | @item custom-initialize-reset | |
397 | Always use the @code{:set} function to initialize the variable. If | |
398 | the variable is already non-void, reset it by calling the @code{:set} | |
399 | function using the current value (returned by the @code{:get} method). | |
400 | This is the default @code{:initialize} function. | |
401 | ||
402 | @item custom-initialize-changed | |
403 | Use the @code{:set} function to initialize the variable, if it is | |
404 | already set or has been customized; otherwise, just use | |
405 | @code{set-default}. | |
406 | ||
407 | @item custom-initialize-safe-set | |
408 | @itemx custom-initialize-safe-default | |
409 | These functions behave like @code{custom-initialize-set} | |
410 | (@code{custom-initialize-default}, respectively), but catch errors. | |
411 | If an error occurs during initialization, they set the variable to | |
03988c98 CY |
412 | @code{nil} using @code{set-default}, and signal no error. |
413 | ||
414 | These functions are meant for options defined in pre-loaded files, | |
415 | where the @var{standard} expression may signal an error because some | |
416 | required variable or function is not yet defined. The value normally | |
417 | gets updated in @file{startup.el}, ignoring the value computed by | |
418 | @code{defcustom}. After startup, if one unsets the value and | |
419 | reevaluates the @code{defcustom}, the @var{standard} expression can be | |
420 | evaluated without error. | |
b8d4c8d0 GM |
421 | @end table |
422 | ||
db21122c GM |
423 | @item :risky @var{value} |
424 | @kindex risky@r{, @code{defcustom} keyword} | |
95ddd36f | 425 | Set the variable's @code{risky-local-variable} property to |
0f631634 | 426 | @var{value} (@pxref{File Local Variables}). |
db21122c GM |
427 | |
428 | @item :safe @var{function} | |
429 | @kindex safe@r{, @code{defcustom} keyword} | |
95ddd36f | 430 | Set the variable's @code{safe-local-variable} property to |
0f631634 | 431 | @var{function} (@pxref{File Local Variables}). |
db21122c | 432 | |
b8d4c8d0 GM |
433 | @item :set-after @var{variables} |
434 | @kindex set-after@r{, @code{defcustom} keyword} | |
435 | When setting variables according to saved customizations, make sure to | |
ddff3351 | 436 | set the variables @var{variables} before this one; i.e., delay |
b8d4c8d0 GM |
437 | setting this variable until after those others have been handled. Use |
438 | @code{:set-after} if setting this variable won't work properly unless | |
439 | those other variables already have their intended values. | |
440 | @end table | |
441 | ||
0f631634 CY |
442 | It is useful to specify the @code{:require} keyword for an option |
443 | that ``turns on'' a certain feature. This causes Emacs to load the | |
444 | feature, if it is not already loaded, whenever the option is set. | |
445 | @xref{Common Keywords}. Here is an example, from the library | |
446 | @file{saveplace.el}: | |
b8d4c8d0 GM |
447 | |
448 | @example | |
449 | (defcustom save-place nil | |
450 | "Non-nil means automatically save place in each file..." | |
451 | :type 'boolean | |
452 | :require 'saveplace | |
453 | :group 'save-place) | |
454 | @end example | |
455 | ||
456 | If a customization item has a type such as @code{hook} or | |
457 | @code{alist}, which supports @code{:options}, you can add additional | |
458 | values to the list from outside the @code{defcustom} declaration by | |
459 | calling @code{custom-add-frequent-value}. For example, if you define a | |
460 | function @code{my-lisp-mode-initialization} intended to be called from | |
461 | @code{emacs-lisp-mode-hook}, you might want to add that to the list of | |
462 | reasonable values for @code{emacs-lisp-mode-hook}, but not by editing | |
463 | its definition. You can do it thus: | |
464 | ||
465 | @example | |
466 | (custom-add-frequent-value 'emacs-lisp-mode-hook | |
467 | 'my-lisp-mode-initialization) | |
468 | @end example | |
469 | ||
470 | @defun custom-add-frequent-value symbol value | |
471 | For the customization option @var{symbol}, add @var{value} to the | |
472 | list of reasonable values. | |
473 | ||
474 | The precise effect of adding a value depends on the customization type | |
475 | of @var{symbol}. | |
476 | @end defun | |
477 | ||
478 | Internally, @code{defcustom} uses the symbol property | |
479 | @code{standard-value} to record the expression for the standard value, | |
0f631634 CY |
480 | @code{saved-value} to record the value saved by the user with the |
481 | customization buffer, and @code{customized-value} to record the value | |
482 | set by the user with the customization buffer, but not saved. | |
f02f19bd CY |
483 | @xref{Symbol Properties}. These properties are lists, the car of |
484 | which is an expression that evaluates to the value. | |
b8d4c8d0 | 485 | |
437706cd | 486 | @defun custom-reevaluate-setting symbol |
0f631634 | 487 | This function re-evaluates the standard value of @var{symbol}, which |
03988c98 | 488 | should be a user option declared via @code{defcustom}. If the |
0f631634 | 489 | variable was customized, this function re-evaluates the saved value |
03988c98 CY |
490 | instead. Then it sets the user option to that value (using the |
491 | option's @code{:set} property if that is defined). | |
492 | ||
493 | This is useful for customizable options that are defined before their | |
494 | value could be computed correctly. For example, during startup Emacs | |
495 | calls this function for some user options that were defined in | |
496 | pre-loaded Emacs Lisp files, but whose initial values depend on | |
497 | information available only at run-time. | |
437706cd EZ |
498 | @end defun |
499 | ||
1021c761 CY |
500 | @defun custom-variable-p arg |
501 | This function returns non-@code{nil} if @var{arg} is a customizable | |
502 | variable. A customizable variable is either a variable that has a | |
503 | @code{standard-value} or @code{custom-autoload} property (usually | |
504 | meaning it was declared with @code{defcustom}), or an alias for | |
505 | another customizable variable. | |
506 | @end defun | |
507 | ||
b8d4c8d0 GM |
508 | @node Customization Types |
509 | @section Customization Types | |
510 | ||
511 | @cindex customization types | |
512 | When you define a user option with @code{defcustom}, you must specify | |
513 | its @dfn{customization type}. That is a Lisp object which describes (1) | |
514 | which values are legitimate and (2) how to display the value in the | |
515 | customization buffer for editing. | |
516 | ||
517 | @kindex type@r{, @code{defcustom} keyword} | |
518 | You specify the customization type in @code{defcustom} with the | |
519 | @code{:type} keyword. The argument of @code{:type} is evaluated, but | |
520 | only once when the @code{defcustom} is executed, so it isn't useful | |
521 | for the value to vary. Normally we use a quoted constant. For | |
522 | example: | |
523 | ||
524 | @example | |
525 | (defcustom diff-command "diff" | |
526 | "The command to use to run diff." | |
527 | :type '(string) | |
528 | :group 'diff) | |
529 | @end example | |
530 | ||
531 | In general, a customization type is a list whose first element is a | |
532 | symbol, one of the customization type names defined in the following | |
533 | sections. After this symbol come a number of arguments, depending on | |
534 | the symbol. Between the type symbol and its arguments, you can | |
535 | optionally write keyword-value pairs (@pxref{Type Keywords}). | |
536 | ||
0f631634 | 537 | Some type symbols do not use any arguments; those are called |
b8d4c8d0 GM |
538 | @dfn{simple types}. For a simple type, if you do not use any |
539 | keyword-value pairs, you can omit the parentheses around the type | |
540 | symbol. For example just @code{string} as a customization type is | |
541 | equivalent to @code{(string)}. | |
542 | ||
0f631634 CY |
543 | All customization types are implemented as widgets; see @ref{Top, , |
544 | Introduction, widget, The Emacs Widget Library}, for details. | |
545 | ||
b8d4c8d0 | 546 | @menu |
3deead93 | 547 | * Simple Types:: Simple customization types: sexp, integer, etc. |
51d9979c GM |
548 | * Composite Types:: Build new types from other types or data. |
549 | * Splicing into Lists:: Splice elements into list with @code{:inline}. | |
550 | * Type Keywords:: Keyword-argument pairs in a customization type. | |
551 | * Defining New Types:: Give your type a name. | |
b8d4c8d0 GM |
552 | @end menu |
553 | ||
b8d4c8d0 GM |
554 | @node Simple Types |
555 | @subsection Simple Types | |
556 | ||
e1161b06 CY |
557 | This section describes all the simple customization types. For |
558 | several of these customization types, the customization widget | |
559 | provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}. | |
b8d4c8d0 GM |
560 | |
561 | @table @code | |
562 | @item sexp | |
e1161b06 CY |
563 | The value may be any Lisp object that can be printed and read back. |
564 | You can use @code{sexp} as a fall-back for any option, if you don't | |
565 | want to take the time to work out a more specific type to use. | |
b8d4c8d0 GM |
566 | |
567 | @item integer | |
e1161b06 | 568 | The value must be an integer. |
b8d4c8d0 GM |
569 | |
570 | @item number | |
e1161b06 | 571 | The value must be a number (floating point or integer). |
b8d4c8d0 GM |
572 | |
573 | @item float | |
e1161b06 | 574 | The value must be a floating point number. |
b8d4c8d0 GM |
575 | |
576 | @item string | |
e1161b06 CY |
577 | The value must be a string. The customization buffer shows the string |
578 | without delimiting @samp{"} characters or @samp{\} quotes. | |
b8d4c8d0 GM |
579 | |
580 | @item regexp | |
581 | Like @code{string} except that the string must be a valid regular | |
582 | expression. | |
583 | ||
584 | @item character | |
585 | The value must be a character code. A character code is actually an | |
586 | integer, but this type shows the value by inserting the character in the | |
587 | buffer, rather than by showing the number. | |
588 | ||
589 | @item file | |
e1161b06 | 590 | The value must be a file name. The widget provides completion. |
b8d4c8d0 GM |
591 | |
592 | @item (file :must-match t) | |
e1161b06 CY |
593 | The value must be a file name for an existing file. The widget |
594 | provides completion. | |
b8d4c8d0 GM |
595 | |
596 | @item directory | |
e1161b06 | 597 | The value must be a directory name. The widget provides completion. |
b8d4c8d0 GM |
598 | |
599 | @item hook | |
e1161b06 CY |
600 | The value must be a list of functions. This customization type is |
601 | used for hook variables. You can use the @code{:options} keyword in a | |
602 | hook variable's @code{defcustom} to specify a list of functions | |
603 | recommended for use in the hook; @xref{Variable Definitions}. | |
b8d4c8d0 | 604 | |
3deead93 CY |
605 | @item symbol |
606 | The value must be a symbol. It appears in the customization buffer as | |
e1161b06 | 607 | the symbol name. The widget provides completion. |
b8d4c8d0 | 608 | |
3deead93 | 609 | @item function |
e1161b06 CY |
610 | The value must be either a lambda expression or a function name. The |
611 | widget provides completion for function names. | |
b8d4c8d0 | 612 | |
3deead93 | 613 | @item variable |
e1161b06 | 614 | The value must be a variable name. The widget provides completion. |
3deead93 CY |
615 | |
616 | @item face | |
e1161b06 CY |
617 | The value must be a symbol which is a face name. The widget provides |
618 | completion. | |
3deead93 CY |
619 | |
620 | @item boolean | |
621 | The value is boolean---either @code{nil} or @code{t}. Note that by | |
622 | using @code{choice} and @code{const} together (see the next section), | |
623 | you can specify that the value must be @code{nil} or @code{t}, but also | |
624 | specify the text to describe each value in a way that fits the specific | |
625 | meaning of the alternative. | |
626 | ||
6e55f03e CY |
627 | @item key-sequence |
628 | The value is a key sequence. The customization buffer shows the key | |
629 | sequence using the same syntax as the @kbd{kbd} function. @xref{Key | |
630 | Sequences}. | |
631 | ||
3deead93 CY |
632 | @item coding-system |
633 | The value must be a coding-system name, and you can do completion with | |
634 | @kbd{M-@key{TAB}}. | |
635 | ||
636 | @item color | |
e1161b06 CY |
637 | The value must be a valid color name. The widget provides completion |
638 | for color names, as well as a sample and a button for selecting a | |
2bb0eca1 | 639 | color name from a list of color names shown in a @file{*Colors*} |
e1161b06 | 640 | buffer. |
3deead93 CY |
641 | @end table |
642 | ||
643 | @node Composite Types | |
644 | @subsection Composite Types | |
645 | @cindex composite types (customization) | |
646 | ||
647 | When none of the simple types is appropriate, you can use composite | |
648 | types, which build new types from other types or from specified data. | |
649 | The specified types or data are called the @dfn{arguments} of the | |
650 | composite type. The composite type normally looks like this: | |
651 | ||
652 | @example | |
653 | (@var{constructor} @var{arguments}@dots{}) | |
654 | @end example | |
b8d4c8d0 GM |
655 | |
656 | @noindent | |
3deead93 CY |
657 | but you can also add keyword-value pairs before the arguments, like |
658 | this: | |
659 | ||
660 | @example | |
661 | (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{}) | |
662 | @end example | |
663 | ||
664 | Here is a table of constructors and how to use them to write | |
665 | composite types: | |
666 | ||
667 | @table @code | |
668 | @item (cons @var{car-type} @var{cdr-type}) | |
669 | The value must be a cons cell, its @sc{car} must fit @var{car-type}, and | |
670 | its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string | |
671 | symbol)} is a customization type which matches values such as | |
672 | @code{("foo" . foo)}. | |
673 | ||
e1161b06 CY |
674 | In the customization buffer, the @sc{car} and @sc{cdr} are displayed |
675 | and edited separately, each according to their specified type. | |
3deead93 CY |
676 | |
677 | @item (list @var{element-types}@dots{}) | |
678 | The value must be a list with exactly as many elements as the | |
679 | @var{element-types} given; and each element must fit the | |
680 | corresponding @var{element-type}. | |
681 | ||
682 | For example, @code{(list integer string function)} describes a list of | |
683 | three elements; the first element must be an integer, the second a | |
684 | string, and the third a function. | |
685 | ||
686 | In the customization buffer, each element is displayed and edited | |
687 | separately, according to the type specified for it. | |
688 | ||
689 | @item (group @var{element-types}@dots{}) | |
690 | This works like @code{list} except for the formatting | |
691 | of text in the Custom buffer. @code{list} labels each | |
692 | element value with its tag; @code{group} does not. | |
693 | ||
694 | @item (vector @var{element-types}@dots{}) | |
695 | Like @code{list} except that the value must be a vector instead of a | |
696 | list. The elements work the same as in @code{list}. | |
697 | ||
698 | @item (alist :key-type @var{key-type} :value-type @var{value-type}) | |
699 | The value must be a list of cons-cells, the @sc{car} of each cell | |
700 | representing a key of customization type @var{key-type}, and the | |
701 | @sc{cdr} of the same cell representing a value of customization type | |
702 | @var{value-type}. The user can add and delete key/value pairs, and | |
703 | edit both the key and the value of each pair. | |
704 | ||
705 | If omitted, @var{key-type} and @var{value-type} default to | |
706 | @code{sexp}. | |
b8d4c8d0 GM |
707 | |
708 | The user can add any key matching the specified key type, but you can | |
709 | give some keys a preferential treatment by specifying them with the | |
710 | @code{:options} (see @ref{Variable Definitions}). The specified keys | |
711 | will always be shown in the customize buffer (together with a suitable | |
712 | value), with a checkbox to include or exclude or disable the key/value | |
713 | pair from the alist. The user will not be able to edit the keys | |
714 | specified by the @code{:options} keyword argument. | |
715 | ||
716 | The argument to the @code{:options} keywords should be a list of | |
717 | specifications for reasonable keys in the alist. Ordinarily, they are | |
e1161b06 | 718 | simply atoms, which stand for themselves. For example: |
b8d4c8d0 | 719 | |
ddff3351 | 720 | @example |
b8d4c8d0 | 721 | :options '("foo" "bar" "baz") |
ddff3351 | 722 | @end example |
b8d4c8d0 GM |
723 | |
724 | @noindent | |
725 | specifies that there are three ``known'' keys, namely @code{"foo"}, | |
726 | @code{"bar"} and @code{"baz"}, which will always be shown first. | |
727 | ||
728 | You may want to restrict the value type for specific keys, for | |
729 | example, the value associated with the @code{"bar"} key can only be an | |
730 | integer. You can specify this by using a list instead of an atom in | |
731 | the list. The first element will specify the key, like before, while | |
732 | the second element will specify the value type. For example: | |
733 | ||
ddff3351 | 734 | @example |
b8d4c8d0 | 735 | :options '("foo" ("bar" integer) "baz") |
ddff3351 | 736 | @end example |
b8d4c8d0 GM |
737 | |
738 | Finally, you may want to change how the key is presented. By default, | |
739 | the key is simply shown as a @code{const}, since the user cannot change | |
740 | the special keys specified with the @code{:options} keyword. However, | |
741 | you may want to use a more specialized type for presenting the key, like | |
742 | @code{function-item} if you know it is a symbol with a function binding. | |
743 | This is done by using a customization type specification instead of a | |
744 | symbol for the key. | |
745 | ||
ddff3351 | 746 | @example |
84f4a531 CY |
747 | :options '("foo" |
748 | ((function-item some-function) integer) | |
b8d4c8d0 | 749 | "baz") |
ddff3351 | 750 | @end example |
b8d4c8d0 GM |
751 | |
752 | Many alists use lists with two elements, instead of cons cells. For | |
753 | example, | |
754 | ||
ddff3351 | 755 | @example |
84f4a531 CY |
756 | (defcustom list-alist |
757 | '(("foo" 1) ("bar" 2) ("baz" 3)) | |
b8d4c8d0 | 758 | "Each element is a list of the form (KEY VALUE).") |
ddff3351 | 759 | @end example |
b8d4c8d0 GM |
760 | |
761 | @noindent | |
762 | instead of | |
763 | ||
ddff3351 | 764 | @example |
84f4a531 CY |
765 | (defcustom cons-alist |
766 | '(("foo" . 1) ("bar" . 2) ("baz" . 3)) | |
b8d4c8d0 | 767 | "Each element is a cons-cell (KEY . VALUE).") |
ddff3351 | 768 | @end example |
b8d4c8d0 GM |
769 | |
770 | Because of the way lists are implemented on top of cons cells, you can | |
771 | treat @code{list-alist} in the example above as a cons cell alist, where | |
772 | the value type is a list with a single element containing the real | |
773 | value. | |
774 | ||
ddff3351 | 775 | @example |
b8d4c8d0 GM |
776 | (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) |
777 | "Each element is a list of the form (KEY VALUE)." | |
778 | :type '(alist :value-type (group integer))) | |
ddff3351 | 779 | @end example |
b8d4c8d0 GM |
780 | |
781 | The @code{group} widget is used here instead of @code{list} only because | |
782 | the formatting is better suited for the purpose. | |
783 | ||
784 | Similarly, you can have alists with more values associated with each | |
785 | key, using variations of this trick: | |
786 | ||
ddff3351 | 787 | @example |
b8d4c8d0 GM |
788 | (defcustom person-data '(("brian" 50 t) |
789 | ("dorith" 55 nil) | |
790 | ("ken" 52 t)) | |
791 | "Alist of basic info about people. | |
792 | Each element has the form (NAME AGE MALE-FLAG)." | |
793 | :type '(alist :value-type (group integer boolean))) | |
ddff3351 | 794 | @end example |
b8d4c8d0 | 795 | |
3deead93 CY |
796 | @item (plist :key-type @var{key-type} :value-type @var{value-type}) |
797 | This customization type is similar to @code{alist} (see above), except | |
798 | that (i) the information is stored as a property list, | |
799 | (@pxref{Property Lists}), and (ii) @var{key-type}, if omitted, | |
800 | defaults to @code{symbol} rather than @code{sexp}. | |
b8d4c8d0 GM |
801 | |
802 | @item (choice @var{alternative-types}@dots{}) | |
e1161b06 CY |
803 | The value must fit one of @var{alternative-types}. For example, |
804 | @code{(choice integer string)} allows either an integer or a string. | |
b8d4c8d0 GM |
805 | |
806 | In the customization buffer, the user selects an alternative | |
807 | using a menu, and can then edit the value in the usual way for that | |
808 | alternative. | |
809 | ||
810 | Normally the strings in this menu are determined automatically from the | |
811 | choices; however, you can specify different strings for the menu by | |
812 | including the @code{:tag} keyword in the alternatives. For example, if | |
813 | an integer stands for a number of spaces, while a string is text to use | |
814 | verbatim, you might write the customization type this way, | |
815 | ||
816 | @example | |
817 | (choice (integer :tag "Number of spaces") | |
818 | (string :tag "Literal text")) | |
819 | @end example | |
820 | ||
821 | @noindent | |
822 | so that the menu offers @samp{Number of spaces} and @samp{Literal text}. | |
823 | ||
824 | In any alternative for which @code{nil} is not a valid value, other than | |
825 | a @code{const}, you should specify a valid default for that alternative | |
826 | using the @code{:value} keyword. @xref{Type Keywords}. | |
827 | ||
828 | If some values are covered by more than one of the alternatives, | |
829 | customize will choose the first alternative that the value fits. This | |
830 | means you should always list the most specific types first, and the | |
831 | most general last. Here's an example of proper usage: | |
832 | ||
833 | @example | |
834 | (choice (const :tag "Off" nil) | |
835 | symbol (sexp :tag "Other")) | |
836 | @end example | |
837 | ||
838 | @noindent | |
839 | This way, the special value @code{nil} is not treated like other | |
840 | symbols, and symbols are not treated like other Lisp expressions. | |
841 | ||
842 | @item (radio @var{element-types}@dots{}) | |
843 | This is similar to @code{choice}, except that the choices are displayed | |
844 | using `radio buttons' rather than a menu. This has the advantage of | |
845 | displaying documentation for the choices when applicable and so is often | |
846 | a good choice for a choice between constant functions | |
847 | (@code{function-item} customization types). | |
848 | ||
849 | @item (const @var{value}) | |
850 | The value must be @var{value}---nothing else is allowed. | |
851 | ||
852 | The main use of @code{const} is inside of @code{choice}. For example, | |
853 | @code{(choice integer (const nil))} allows either an integer or | |
854 | @code{nil}. | |
855 | ||
856 | @code{:tag} is often used with @code{const}, inside of @code{choice}. | |
857 | For example, | |
858 | ||
859 | @example | |
860 | (choice (const :tag "Yes" t) | |
861 | (const :tag "No" nil) | |
862 | (const :tag "Ask" foo)) | |
863 | @end example | |
864 | ||
865 | @noindent | |
866 | describes a variable for which @code{t} means yes, @code{nil} means no, | |
16152b76 | 867 | and @code{foo} means ``ask''. |
b8d4c8d0 GM |
868 | |
869 | @item (other @var{value}) | |
870 | This alternative can match any Lisp value, but if the user chooses this | |
871 | alternative, that selects the value @var{value}. | |
872 | ||
873 | The main use of @code{other} is as the last element of @code{choice}. | |
874 | For example, | |
875 | ||
876 | @example | |
877 | (choice (const :tag "Yes" t) | |
878 | (const :tag "No" nil) | |
879 | (other :tag "Ask" foo)) | |
880 | @end example | |
881 | ||
882 | @noindent | |
883 | describes a variable for which @code{t} means yes, @code{nil} means no, | |
16152b76 | 884 | and anything else means ``ask''. If the user chooses @samp{Ask} from |
b8d4c8d0 GM |
885 | the menu of alternatives, that specifies the value @code{foo}; but any |
886 | other value (not @code{t}, @code{nil} or @code{foo}) displays as | |
887 | @samp{Ask}, just like @code{foo}. | |
888 | ||
889 | @item (function-item @var{function}) | |
890 | Like @code{const}, but used for values which are functions. This | |
891 | displays the documentation string as well as the function name. | |
892 | The documentation string is either the one you specify with | |
893 | @code{:doc}, or @var{function}'s own documentation string. | |
894 | ||
895 | @item (variable-item @var{variable}) | |
896 | Like @code{const}, but used for values which are variable names. This | |
897 | displays the documentation string as well as the variable name. The | |
898 | documentation string is either the one you specify with @code{:doc}, or | |
899 | @var{variable}'s own documentation string. | |
900 | ||
901 | @item (set @var{types}@dots{}) | |
902 | The value must be a list, and each element of the list must match one of | |
903 | the @var{types} specified. | |
904 | ||
905 | This appears in the customization buffer as a checklist, so that each of | |
906 | @var{types} may have either one corresponding element or none. It is | |
907 | not possible to specify two different elements that match the same one | |
908 | of @var{types}. For example, @code{(set integer symbol)} allows one | |
909 | integer and/or one symbol in the list; it does not allow multiple | |
910 | integers or multiple symbols. As a result, it is rare to use | |
911 | nonspecific types such as @code{integer} in a @code{set}. | |
912 | ||
913 | Most often, the @var{types} in a @code{set} are @code{const} types, as | |
914 | shown here: | |
915 | ||
916 | @example | |
917 | (set (const :bold) (const :italic)) | |
918 | @end example | |
919 | ||
920 | Sometimes they describe possible elements in an alist: | |
921 | ||
922 | @example | |
923 | (set (cons :tag "Height" (const height) integer) | |
924 | (cons :tag "Width" (const width) integer)) | |
925 | @end example | |
926 | ||
927 | @noindent | |
928 | That lets the user specify a height value optionally | |
929 | and a width value optionally. | |
930 | ||
931 | @item (repeat @var{element-type}) | |
932 | The value must be a list and each element of the list must fit the type | |
933 | @var{element-type}. This appears in the customization buffer as a | |
934 | list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding | |
935 | more elements or removing elements. | |
936 | ||
937 | @item (restricted-sexp :match-alternatives @var{criteria}) | |
938 | This is the most general composite type construct. The value may be | |
939 | any Lisp object that satisfies one of @var{criteria}. @var{criteria} | |
940 | should be a list, and each element should be one of these | |
941 | possibilities: | |
942 | ||
943 | @itemize @bullet | |
944 | @item | |
945 | A predicate---that is, a function of one argument that has no side | |
946 | effects, and returns either @code{nil} or non-@code{nil} according to | |
947 | the argument. Using a predicate in the list says that objects for which | |
948 | the predicate returns non-@code{nil} are acceptable. | |
949 | ||
950 | @item | |
951 | A quoted constant---that is, @code{'@var{object}}. This sort of element | |
952 | in the list says that @var{object} itself is an acceptable value. | |
953 | @end itemize | |
954 | ||
955 | For example, | |
956 | ||
957 | @example | |
958 | (restricted-sexp :match-alternatives | |
959 | (integerp 't 'nil)) | |
960 | @end example | |
961 | ||
962 | @noindent | |
963 | allows integers, @code{t} and @code{nil} as legitimate values. | |
964 | ||
965 | The customization buffer shows all legitimate values using their read | |
966 | syntax, and the user edits them textually. | |
967 | @end table | |
968 | ||
969 | Here is a table of the keywords you can use in keyword-value pairs | |
970 | in a composite type: | |
971 | ||
972 | @table @code | |
973 | @item :tag @var{tag} | |
974 | Use @var{tag} as the name of this alternative, for user communication | |
975 | purposes. This is useful for a type that appears inside of a | |
976 | @code{choice}. | |
977 | ||
978 | @item :match-alternatives @var{criteria} | |
979 | @kindex match-alternatives@r{, customization keyword} | |
980 | Use @var{criteria} to match possible values. This is used only in | |
981 | @code{restricted-sexp}. | |
982 | ||
983 | @item :args @var{argument-list} | |
984 | @kindex args@r{, customization keyword} | |
985 | Use the elements of @var{argument-list} as the arguments of the type | |
986 | construct. For instance, @code{(const :args (foo))} is equivalent to | |
987 | @code{(const foo)}. You rarely need to write @code{:args} explicitly, | |
988 | because normally the arguments are recognized automatically as | |
989 | whatever follows the last keyword-value pair. | |
990 | @end table | |
991 | ||
992 | @node Splicing into Lists | |
993 | @subsection Splicing into Lists | |
994 | ||
995 | The @code{:inline} feature lets you splice a variable number of | |
e1161b06 CY |
996 | elements into the middle of a @code{list} or @code{vector} |
997 | customization type. You use it by adding @code{:inline t} to a type | |
998 | specification which is contained in a @code{list} or @code{vector} | |
999 | specification. | |
1000 | ||
1001 | Normally, each entry in a @code{list} or @code{vector} type | |
1002 | specification describes a single element type. But when an entry | |
1003 | contains @code{:inline t}, the value it matches is merged directly | |
1004 | into the containing sequence. For example, if the entry matches a | |
1005 | list with three elements, those become three elements of the overall | |
1006 | sequence. This is analogous to @samp{,@@} in a backquote construct | |
1007 | (@pxref{Backquote}). | |
b8d4c8d0 GM |
1008 | |
1009 | For example, to specify a list whose first element must be @code{baz} | |
1010 | and whose remaining arguments should be zero or more of @code{foo} and | |
1011 | @code{bar}, use this customization type: | |
1012 | ||
1013 | @example | |
1014 | (list (const baz) (set :inline t (const foo) (const bar))) | |
1015 | @end example | |
1016 | ||
1017 | @noindent | |
1018 | This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)} | |
1019 | and @code{(baz foo bar)}. | |
1020 | ||
1021 | When the element-type is a @code{choice}, you use @code{:inline} not | |
1022 | in the @code{choice} itself, but in (some of) the alternatives of the | |
1023 | @code{choice}. For example, to match a list which must start with a | |
1024 | file name, followed either by the symbol @code{t} or two strings, use | |
1025 | this customization type: | |
1026 | ||
1027 | @example | |
1028 | (list file | |
1029 | (choice (const t) | |
1030 | (list :inline t string string))) | |
1031 | @end example | |
1032 | ||
1033 | @noindent | |
1034 | If the user chooses the first alternative in the choice, then the | |
1035 | overall list has two elements and the second element is @code{t}. If | |
1036 | the user chooses the second alternative, then the overall list has three | |
1037 | elements and the second and third must be strings. | |
1038 | ||
1039 | @node Type Keywords | |
1040 | @subsection Type Keywords | |
1041 | ||
1042 | You can specify keyword-argument pairs in a customization type after the | |
1043 | type name symbol. Here are the keywords you can use, and their | |
1044 | meanings: | |
1045 | ||
1046 | @table @code | |
1047 | @item :value @var{default} | |
0ec389b9 LMI |
1048 | Provide a default value. |
1049 | ||
1050 | If @code{nil} is not a valid value for the alternative, then it is | |
1051 | essential to specify a valid default with @code{:value}. | |
1052 | ||
1053 | If you use this for a type that appears as an alternative inside of | |
b8d4c8d0 GM |
1054 | @code{choice}; it specifies the default value to use, at first, if and |
1055 | when the user selects this alternative with the menu in the | |
1056 | customization buffer. | |
1057 | ||
1058 | Of course, if the actual value of the option fits this alternative, it | |
1059 | will appear showing the actual value, not @var{default}. | |
1060 | ||
b8d4c8d0 GM |
1061 | @item :format @var{format-string} |
1062 | @kindex format@r{, customization keyword} | |
1063 | This string will be inserted in the buffer to represent the value | |
1064 | corresponding to the type. The following @samp{%} escapes are available | |
1065 | for use in @var{format-string}: | |
1066 | ||
1067 | @table @samp | |
1068 | @item %[@var{button}%] | |
1069 | Display the text @var{button} marked as a button. The @code{:action} | |
1070 | attribute specifies what the button will do if the user invokes it; | |
1071 | its value is a function which takes two arguments---the widget which | |
1072 | the button appears in, and the event. | |
1073 | ||
1074 | There is no way to specify two different buttons with different | |
1075 | actions. | |
1076 | ||
1077 | @item %@{@var{sample}%@} | |
1078 | Show @var{sample} in a special face specified by @code{:sample-face}. | |
1079 | ||
1080 | @item %v | |
1081 | Substitute the item's value. How the value is represented depends on | |
1082 | the kind of item, and (for variables) on the customization type. | |
1083 | ||
1084 | @item %d | |
1085 | Substitute the item's documentation string. | |
1086 | ||
1087 | @item %h | |
1088 | Like @samp{%d}, but if the documentation string is more than one line, | |
22ff2cb8 | 1089 | add a button to control whether to show all of it or just the first line. |
b8d4c8d0 GM |
1090 | |
1091 | @item %t | |
1092 | Substitute the tag here. You specify the tag with the @code{:tag} | |
1093 | keyword. | |
1094 | ||
1095 | @item %% | |
1096 | Display a literal @samp{%}. | |
1097 | @end table | |
1098 | ||
1099 | @item :action @var{action} | |
1100 | @kindex action@r{, customization keyword} | |
1101 | Perform @var{action} if the user clicks on a button. | |
1102 | ||
1103 | @item :button-face @var{face} | |
1104 | @kindex button-face@r{, customization keyword} | |
1105 | Use the face @var{face} (a face name or a list of face names) for button | |
1106 | text displayed with @samp{%[@dots{}%]}. | |
1107 | ||
1108 | @item :button-prefix @var{prefix} | |
1109 | @itemx :button-suffix @var{suffix} | |
1110 | @kindex button-prefix@r{, customization keyword} | |
1111 | @kindex button-suffix@r{, customization keyword} | |
1112 | These specify the text to display before and after a button. | |
1113 | Each can be: | |
1114 | ||
1115 | @table @asis | |
1116 | @item @code{nil} | |
1117 | No text is inserted. | |
1118 | ||
1119 | @item a string | |
1120 | The string is inserted literally. | |
1121 | ||
1122 | @item a symbol | |
1123 | The symbol's value is used. | |
1124 | @end table | |
1125 | ||
1126 | @item :tag @var{tag} | |
1127 | Use @var{tag} (a string) as the tag for the value (or part of the value) | |
1128 | that corresponds to this type. | |
1129 | ||
1130 | @item :doc @var{doc} | |
1131 | @kindex doc@r{, customization keyword} | |
1132 | Use @var{doc} as the documentation string for this value (or part of the | |
1133 | value) that corresponds to this type. In order for this to work, you | |
1134 | must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} | |
1135 | in that value. | |
1136 | ||
1137 | The usual reason to specify a documentation string for a type is to | |
1138 | provide more information about the meanings of alternatives inside a | |
1139 | @code{:choice} type or the parts of some other composite type. | |
1140 | ||
1141 | @item :help-echo @var{motion-doc} | |
1142 | @kindex help-echo@r{, customization keyword} | |
1143 | When you move to this item with @code{widget-forward} or | |
1144 | @code{widget-backward}, it will display the string @var{motion-doc} in | |
1145 | the echo area. In addition, @var{motion-doc} is used as the mouse | |
1146 | @code{help-echo} string and may actually be a function or form evaluated | |
1147 | to yield a help string. If it is a function, it is called with one | |
1148 | argument, the widget. | |
1149 | ||
1150 | @item :match @var{function} | |
1151 | @kindex match@r{, customization keyword} | |
1152 | Specify how to decide whether a value matches the type. The | |
1153 | corresponding value, @var{function}, should be a function that accepts | |
1154 | two arguments, a widget and a value; it should return non-@code{nil} if | |
1155 | the value is acceptable. | |
1156 | ||
72b7e664 RS |
1157 | @item :validate @var{function} |
1158 | Specify a validation function for input. @var{function} takes a | |
1159 | widget as an argument, and should return @code{nil} if the widget's | |
1160 | current value is valid for the widget. Otherwise, it should return | |
1161 | the widget containing the invalid data, and set that widget's | |
1162 | @code{:error} property to a string explaining the error. | |
1163 | ||
b8d4c8d0 GM |
1164 | @ignore |
1165 | @item :indent @var{columns} | |
1166 | Indent this item by @var{columns} columns. The indentation is used for | |
1167 | @samp{%n}, and automatically for group names, for checklists and radio | |
1168 | buttons, and for editable lists. It affects the whole of the | |
1169 | item except for the first line. | |
1170 | ||
72b7e664 RS |
1171 | @item :offset @var{extra} |
1172 | Indent the subitems of this item @var{extra} columns more than this | |
1173 | item itself. By default, subitems are indented the same as their | |
1174 | parent. | |
b8d4c8d0 | 1175 | |
72b7e664 RS |
1176 | @item :extra-offset @var{n} |
1177 | Add @var{n} extra spaces to this item's indentation, compared to its | |
1178 | parent's indentation. | |
b8d4c8d0 | 1179 | |
72b7e664 RS |
1180 | @item :notify @var{function} |
1181 | Call @var{function} each time the item or a subitem is changed. The | |
1182 | function gets two or three arguments. The first argument is the item | |
1183 | itself, the second argument is the item that was changed, and the | |
1184 | third argument is the event leading to the change, if any. | |
b8d4c8d0 | 1185 | |
72b7e664 RS |
1186 | @item :menu-tag @var{tag-string} |
1187 | Use @var{tag-string} in the menu when the widget is used as an option | |
1188 | in a @code{menu-choice} widget. | |
b8d4c8d0 GM |
1189 | |
1190 | @item :menu-tag-get | |
1191 | A function used for finding the tag when the widget is used as an option | |
1192 | in a @code{menu-choice} widget. By default, the tag used will be either the | |
1193 | @code{:menu-tag} or @code{:tag} property if present, or the @code{princ} | |
1194 | representation of the @code{:value} property if not. | |
1195 | ||
b8d4c8d0 GM |
1196 | @item :tab-order |
1197 | Specify the order in which widgets are traversed with | |
1198 | @code{widget-forward} or @code{widget-backward}. This is only partially | |
1199 | implemented. | |
1200 | ||
1201 | @enumerate a | |
1202 | @item | |
1203 | Widgets with tabbing order @code{-1} are ignored. | |
1204 | ||
1205 | @item | |
1206 | (Unimplemented) When on a widget with tabbing order @var{n}, go to the | |
1207 | next widget in the buffer with tabbing order @var{n+1} or @code{nil}, | |
1208 | whichever comes first. | |
1209 | ||
1210 | @item | |
1211 | When on a widget with no tabbing order specified, go to the next widget | |
1212 | in the buffer with a positive tabbing order, or @code{nil} | |
1213 | @end enumerate | |
1214 | ||
1215 | @item :parent | |
1216 | The parent of a nested widget (e.g., a @code{menu-choice} item or an | |
1217 | element of a @code{editable-list} widget). | |
1218 | ||
1219 | @item :sibling-args | |
1220 | This keyword is only used for members of a @code{radio-button-choice} or | |
1221 | @code{checklist}. The value should be a list of extra keyword | |
1222 | arguments, which will be used when creating the @code{radio-button} or | |
1223 | @code{checkbox} associated with this item. | |
1224 | @end ignore | |
1225 | @end table | |
1226 | ||
1227 | @node Defining New Types | |
1228 | @subsection Defining New Types | |
1229 | ||
1230 | In the previous sections we have described how to construct elaborate | |
1231 | type specifications for @code{defcustom}. In some cases you may want | |
1232 | to give such a type specification a name. The obvious case is when | |
1233 | you are using the same type for many user options: rather than repeat | |
1234 | the specification for each option, you can give the type specification | |
1235 | a name, and use that name each @code{defcustom}. The other case is | |
1236 | when a user option's value is a recursive data structure. To make it | |
1237 | possible for a datatype to refer to itself, it needs to have a name. | |
1238 | ||
1239 | Since custom types are implemented as widgets, the way to define a new | |
1240 | customize type is to define a new widget. We are not going to describe | |
1241 | the widget interface here in details, see @ref{Top, , Introduction, | |
1242 | widget, The Emacs Widget Library}, for that. Instead we are going to | |
1243 | demonstrate the minimal functionality needed for defining new customize | |
1244 | types by a simple example. | |
1245 | ||
1246 | @example | |
1247 | (define-widget 'binary-tree-of-string 'lazy | |
1248 | "A binary tree made of cons-cells and strings." | |
1249 | :offset 4 | |
1250 | :tag "Node" | |
1251 | :type '(choice (string :tag "Leaf" :value "") | |
1252 | (cons :tag "Interior" | |
1253 | :value ("" . "") | |
1254 | binary-tree-of-string | |
1255 | binary-tree-of-string))) | |
1256 | ||
1257 | (defcustom foo-bar "" | |
1258 | "Sample variable holding a binary tree of strings." | |
1259 | :type 'binary-tree-of-string) | |
1260 | @end example | |
1261 | ||
1262 | The function to define a new widget is called @code{define-widget}. The | |
1263 | first argument is the symbol we want to make a new widget type. The | |
1264 | second argument is a symbol representing an existing widget, the new | |
1265 | widget is going to be defined in terms of difference from the existing | |
1266 | widget. For the purpose of defining new customization types, the | |
1267 | @code{lazy} widget is perfect, because it accepts a @code{:type} keyword | |
1268 | argument with the same syntax as the keyword argument to | |
1269 | @code{defcustom} with the same name. The third argument is a | |
1270 | documentation string for the new widget. You will be able to see that | |
1271 | string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string | |
1272 | @key{RET}} command. | |
1273 | ||
1274 | After these mandatory arguments follow the keyword arguments. The most | |
1275 | important is @code{:type}, which describes the data type we want to match | |
1276 | with this widget. Here a @code{binary-tree-of-string} is described as | |
1277 | being either a string, or a cons-cell whose car and cdr are themselves | |
1278 | both @code{binary-tree-of-string}. Note the reference to the widget | |
1279 | type we are currently in the process of defining. The @code{:tag} | |
1280 | attribute is a string to name the widget in the user interface, and the | |
1281 | @code{:offset} argument is there to ensure that child nodes are | |
1282 | indented four spaces relative to the parent node, making the tree | |
1283 | structure apparent in the customization buffer. | |
1284 | ||
1285 | The @code{defcustom} shows how the new widget can be used as an ordinary | |
1286 | customization type. | |
1287 | ||
1288 | The reason for the name @code{lazy} is that the other composite | |
1289 | widgets convert their inferior widgets to internal form when the | |
1290 | widget is instantiated in a buffer. This conversion is recursive, so | |
1291 | the inferior widgets will convert @emph{their} inferior widgets. If | |
1292 | the data structure is itself recursive, this conversion is an infinite | |
1293 | recursion. The @code{lazy} widget prevents the recursion: it convert | |
1294 | its @code{:type} argument only when needed. | |
81927dd2 CY |
1295 | |
1296 | @node Applying Customizations | |
1297 | @section Applying Customizations | |
1298 | ||
1299 | The following functions are responsible for installing the user's | |
1300 | customization settings for variables and faces, respectively. When | |
1301 | the user invokes @samp{Save for future sessions} in the Customize | |
1302 | interface, that takes effect by writing a @code{custom-set-variables} | |
1303 | and/or a @code{custom-set-faces} form into the custom file, to be | |
ddff3351 | 1304 | evaluated the next time Emacs starts. |
81927dd2 CY |
1305 | |
1306 | @defun custom-set-variables &rest args | |
1307 | This function installs the variable customizations specified by | |
1308 | @var{args}. Each argument in @var{args} should have the form | |
1309 | ||
1310 | @example | |
1311 | (@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]]) | |
1312 | @end example | |
1313 | ||
1314 | @noindent | |
1315 | @var{var} is a variable name (a symbol), and @var{expression} is an | |
1316 | expression which evaluates to the desired customized value. | |
1317 | ||
1318 | If the @code{defcustom} form for @var{var} has been evaluated prior to | |
1319 | this @code{custom-set-variables} call, @var{expression} is immediately | |
1320 | evaluated, and the variable's value is set to the result. Otherwise, | |
1321 | @var{expression} is stored into the variable's @code{saved-value} | |
1322 | property, to be evaluated when the relevant @code{defcustom} is called | |
1323 | (usually when the library defining that variable is loaded into | |
1324 | Emacs). | |
1325 | ||
1326 | The @var{now}, @var{request}, and @var{comment} entries are for | |
1327 | internal use only, and may be omitted. @var{now}, if non-@code{nil}, | |
1328 | means to set the variable's value now, even if the variable's | |
1329 | @code{defcustom} form has not been evaluated. @var{request} is a list | |
1330 | of features to be loaded immediately (@pxref{Named Features}). | |
1331 | @var{comment} is a string describing the customization. | |
1332 | @end defun | |
1333 | ||
1334 | @defun custom-set-faces &rest args | |
1335 | This function installs the face customizations specified by | |
1336 | @var{args}. Each argument in @var{args} should have the form | |
1337 | ||
1338 | @example | |
1339 | (@var{face} @var{spec} [@var{now} [@var{comment}]]) | |
1340 | @end example | |
1341 | ||
1342 | @noindent | |
1343 | @var{face} is a face name (a symbol), and @var{spec} is the customized | |
1344 | face specification for that face (@pxref{Defining Faces}). | |
1345 | ||
1346 | The @var{now} and @var{comment} entries are for internal use only, and | |
1347 | may be omitted. @var{now}, if non-@code{nil}, means to install the | |
1348 | face specification now, even if the @code{defface} form has not been | |
1349 | evaluated. @var{comment} is a string describing the customization. | |
1350 | @end defun | |
1351 | ||
1352 | @node Custom Themes | |
1353 | @section Custom Themes | |
1354 | ||
1355 | @dfn{Custom themes} are collections of settings that can be enabled | |
1356 | or disabled as a unit. @xref{Custom Themes,,, emacs, The GNU Emacs | |
1357 | Manual}. Each Custom theme is defined by an Emacs Lisp source file, | |
1358 | which should follow the conventions described in this section. | |
1359 | (Instead of writing a Custom theme by hand, you can also create one | |
1360 | using a Customize-like interface; @pxref{Creating Custom Themes,,, | |
1361 | emacs, The GNU Emacs Manual}.) | |
1362 | ||
1363 | A Custom theme file should be named @file{@var{foo}-theme.el}, where | |
1364 | @var{foo} is the theme name. The first Lisp form in the file should | |
1365 | be a call to @code{deftheme}, and the last form should be a call to | |
1366 | @code{provide-theme}. | |
1367 | ||
1368 | @defmac deftheme theme &optional doc | |
1369 | This macro declares @var{theme} (a symbol) as the name of a Custom | |
03ed9e82 | 1370 | theme. The optional argument @var{doc} should be a string describing |
81927dd2 | 1371 | the theme; this is the description shown when the user invokes the |
03ed9e82 CY |
1372 | @code{describe-theme} command or types @kbd{?} in the @samp{*Custom |
1373 | Themes*} buffer. | |
81927dd2 | 1374 | |
ddff3351 GM |
1375 | Two special theme names are disallowed (using them causes an error): |
1376 | @code{user} is a ``dummy'' theme that stores the user's direct | |
1377 | customization settings, and @code{changed} is a ``dummy'' theme that | |
1378 | stores changes made outside of the Customize system. | |
81927dd2 CY |
1379 | @end defmac |
1380 | ||
1381 | @defmac provide-theme theme | |
1382 | This macro declares that the theme named @var{theme} has been fully | |
1383 | specified. | |
1384 | @end defmac | |
1385 | ||
03ed9e82 CY |
1386 | In between @code{deftheme} and @code{provide-theme} are Lisp forms |
1387 | specifying the theme settings: usually a call to | |
81927dd2 | 1388 | @code{custom-theme-set-variables} and/or a call to |
03ed9e82 | 1389 | @code{custom-theme-set-faces}. |
81927dd2 CY |
1390 | |
1391 | @defun custom-theme-set-variables theme &rest args | |
03ed9e82 CY |
1392 | This function specifies the Custom theme @var{theme}'s variable |
1393 | settings. @var{theme} should be a symbol. Each argument in | |
1394 | @var{args} should be a list of the form | |
81927dd2 CY |
1395 | |
1396 | @example | |
1397 | (@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]]) | |
1398 | @end example | |
1399 | ||
1400 | @noindent | |
1401 | where the list entries have the same meanings as in | |
1402 | @code{custom-set-variables}. @xref{Applying Customizations}. | |
1403 | @end defun | |
1404 | ||
1405 | @defun custom-theme-set-faces theme &rest args | |
03ed9e82 CY |
1406 | This function specifies the Custom theme @var{theme}'s face settings. |
1407 | @var{theme} should be a symbol. Each argument in @var{args} should be | |
1408 | a list of the form | |
81927dd2 CY |
1409 | |
1410 | @example | |
1411 | (@var{face} @var{spec} [@var{now} [@var{comment}]]) | |
1412 | @end example | |
1413 | ||
1414 | @noindent | |
1415 | where the list entries have the same meanings as in | |
1416 | @code{custom-set-faces}. @xref{Applying Customizations}. | |
1417 | @end defun | |
1418 | ||
03ed9e82 CY |
1419 | In theory, a theme file can also contain other Lisp forms, which |
1420 | would be evaluated when loading the theme, but that is ``bad form''. | |
1421 | To protect against loading themes containing malicious code, Emacs | |
1422 | displays the source file and asks for confirmation from the user | |
1423 | before loading any non-built-in theme for the first time. | |
1424 | ||
1425 | The following functions are useful for programmatically enabling and | |
ddff3351 | 1426 | disabling themes: |
03ed9e82 CY |
1427 | |
1428 | @defun custom-theme-p theme | |
1429 | This function return a non-@code{nil} value if @var{theme} (a symbol) | |
1df7defd | 1430 | is the name of a Custom theme (i.e., a Custom theme which has been |
03ed9e82 CY |
1431 | loaded into Emacs, whether or not the theme is enabled). Otherwise, |
1432 | it returns @code{nil}. | |
1433 | @end defun | |
1434 | ||
18874304 CY |
1435 | @defvar custom-known-themes |
1436 | The value of this variable is a list of themes loaded into Emacs. | |
1437 | Each theme is represented by a Lisp symbol (the theme name). The | |
1438 | default value of this variable is a list containing two ``dummy'' | |
1439 | themes: @code{(user changed)}. The @code{changed} theme stores | |
1440 | settings made before any Custom themes are applied (e.g., variables | |
1441 | set outside of Customize). The @code{user} theme stores settings the | |
1442 | user has customized and saved. Any additional themes declared with | |
1443 | the @code{deftheme} macro are added to the front of this list. | |
1444 | @end defvar | |
1445 | ||
03ed9e82 CY |
1446 | @deffn Command load-theme theme &optional no-confirm no-enable |
1447 | This function loads the Custom theme named @var{theme} from its source | |
1448 | file, looking for the source file in the directories specified by the | |
1449 | variable @code{custom-theme-load-path}. @xref{Custom Themes,,, emacs, | |
ddff3351 GM |
1450 | The GNU Emacs Manual}. It also @dfn{enables} the theme (unless the |
1451 | optional argument @var{no-enable} is non-@code{nil}), causing its | |
1452 | variable and face settings to take effect. It prompts the user for | |
1453 | confirmation before loading the theme, unless the optional argument | |
1454 | @var{no-confirm} is non-@code{nil}. | |
03ed9e82 CY |
1455 | @end deffn |
1456 | ||
1457 | @deffn Command enable-theme theme | |
1458 | This function enables the Custom theme named @var{theme}. It signals | |
1459 | an error if no such theme has been loaded. | |
1460 | @end deffn | |
1461 | ||
1462 | @deffn Command disable-theme theme | |
1463 | This function disables the Custom theme named @var{theme}. The theme | |
1464 | remains loaded, so that a subsequent call to @code{enable-theme} will | |
1465 | re-enable it. | |
1466 | @end deffn |