21006
|
1 @c -*-texinfo-*-
|
|
2 @c This is part of the GNU Emacs Lisp Reference Manual.
|
|
3 @c Copyright (C) 1997, 1998 Free Software Foundation, Inc.
|
|
4 @c See the file elisp.texi for copying conditions.
|
|
5 @setfilename ../info/customize
|
|
6 @node Customization, Loading, Macros, Top
|
|
7 @chapter Writing Customization Definitions
|
|
8
|
|
9 This chapter describes how to declare customization groups, variables,
|
|
10 and faces. We use the term @dfn{customization item} to include all
|
|
11 three of those. This has few examples, but please look at the file
|
|
12 @file{cus-edit.el}, which contains many declarations you can learn from.
|
|
13
|
|
14 @menu
|
|
15 * Common Keywords::
|
|
16 * Group Definitions::
|
|
17 * Variable Definitions::
|
|
18 * Face Definitions::
|
|
19 * Customization Types::
|
|
20 @end menu
|
|
21
|
|
22 @node Common Keywords
|
|
23 @section Common Keywords for All Kinds of Items
|
|
24
|
|
25 All three kinds of customization declarations (for groups, variables,
|
|
26 and faces) accept keyword arguments for specifying various information.
|
|
27 This section describes some keywords that apply to all three.
|
|
28
|
|
29 All of these keywords, except @code{:tag}, can be used more than once in
|
|
30 a given item. Each use of the keyword has an independent effect. The
|
|
31 keyword @code{:tag} is an exception because any given item can only
|
|
32 display one name item.
|
|
33
|
|
34 @table @code
|
|
35 @item :group @var{group}
|
|
36 Put this customization item in group @var{group}. When you use
|
|
37 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
|
|
38 @var{group}.
|
|
39
|
|
40 If you use this keyword more than once, you can put a single item into
|
|
41 more than one group. Displaying any of those groups will show this
|
|
42 item. Be careful not to overdo this!
|
|
43
|
|
44 @item :link @var{link-data}
|
|
45 Include an external link after the documentation string for this item.
|
|
46 This is a sentence containing an active field which references some
|
|
47 other documentation.
|
|
48
|
|
49 There are three alternatives you can use for @var{link-data}:
|
|
50
|
|
51 @table @code
|
|
52 @item (custom-manual @var{info-node})
|
|
53 Link to an Info node; @var{info-node} is a string which specifies the
|
|
54 node name, as in @code{"(emacs)Top"}. The link appears as
|
|
55 @samp{[manual]} in the customization buffer.
|
|
56
|
|
57 @item (info-link @var{info-node})
|
|
58 Like @code{custom-manual} except that the link appears
|
|
59 in the customization buffer with the Info node name.
|
|
60
|
|
61 @item (url-link @var{url})
|
|
62 Link to a web page; @var{url} is a string which specifies the URL. The
|
|
63 link appears in the customization buffer as @var{url}.
|
|
64 @end table
|
|
65
|
|
66 You can specify the text to use in the customization buffer by adding
|
|
67 @code{:tag @var{name}} after the first element of the @var{link-data};
|
|
68 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
|
|
69 the Emacs manual which appears in the buffer as @samp{foo}.
|
|
70
|
|
71 An item can have more than one external link; however, most items have
|
|
72 none at all.
|
|
73
|
|
74 @item :load @var{file}
|
|
75 Load file @var{file} (a string) before displaying this customization
|
|
76 item. Loading is done with @code{load-library}, and only if the file is
|
|
77 not already loaded.
|
|
78
|
|
79 @item :require @var{feature}
|
|
80 Require feature @var{feature} (a symbol) when installing a value for
|
|
81 this item (an option or a face) that was saved using the customization
|
|
82 feature. This is done by calling @code{require}.
|
|
83
|
|
84 The most common reason to use @code{:require} is when a variable enables
|
|
85 a feature such as a minor mode, and just setting the variable won't have
|
|
86 any effect unless the code which implements the mode is loaded.
|
|
87
|
|
88 @item :tag @var{name}
|
|
89 Use @var{name}, a string, instead of the item's name, to label the item
|
|
90 in customization menus and buffers.
|
|
91 @end table
|
|
92
|
|
93 @node Group Definitions
|
|
94 @section Defining Custom Groups
|
|
95
|
|
96 Each Emacs Lisp package should have one main customization group which
|
|
97 contains all the options, faces and other groups in the package. If the
|
|
98 package has a small number of options and faces, use just one group and
|
|
99 put everything in it. When there are more than twelve or so options and
|
|
100 faces, then you should structure them into subgroups, and put the
|
|
101 subgroups under the package's main customization group. It is ok to
|
|
102 have some of the options and faces in the package's main group alongside
|
|
103 the subgroups.
|
|
104
|
|
105 The package's main or only group should be a member of one or more of
|
|
106 the standard customization groups. Type press @kbd{C-h p} to display a
|
|
107 list of finder keywords; them choose some of them add your group to each
|
|
108 of them, using the @code{:group} keyword.
|
|
109
|
|
110 The way to declare new customization groups is with @code{defgroup}.
|
|
111
|
|
112 @tindex defgroup
|
|
113 @defmac defgroup group members doc [keyword value]...
|
|
114 Declare @var{group} as a customization group containing @var{members}.
|
|
115 Do not quote the symbol @var{group}. The argument @var{doc} specifies
|
|
116 the documentation string for the group.
|
|
117
|
|
118 The arguments @var{members} can be an alist whose elements specify
|
|
119 members of the group; however, normally @var{members} is @code{nil}, and
|
|
120 you specify the group's members by using the @code{:group} keyword when
|
|
121 defining those members.
|
|
122
|
|
123 @ignore
|
|
124 @code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and
|
|
125 @var{widget} is a widget for editing that symbol. Useful widgets are
|
|
126 @code{custom-variable} for editing variables, @code{custom-face} for
|
|
127 editing faces, and @code{custom-group} for editing groups.
|
|
128 @end ignore
|
|
129
|
|
130 In addition to the common keywords (@pxref{Common Keywords}), you can
|
|
131 use this keyword in @code{defgroup}:
|
|
132
|
|
133 @table @code
|
|
134 @item :prefix @var{prefix}
|
|
135 If the name of an item in the group starts with @var{prefix}, then the
|
|
136 tag for that item is constructed (by default) by omitting @var{prefix}.
|
|
137
|
|
138 One group can have any number of prefixes.
|
|
139 @end table
|
|
140 @end defmac
|
|
141
|
|
142 The @code{:prefix} feature is currently turned off, which means that
|
|
143 @code{:prefix} currently has no effect. We did this because we found
|
|
144 that discarding the specified prefixes often led to confusing names for
|
|
145 options. This happened because the people who wrote the @code{defgroup}
|
|
146 definitions for various groups added @code{:prefix} keywords whenever
|
|
147 they make logical sense---that is, whenever they say that there was a
|
|
148 common prefix for the option names in a library.
|
|
149
|
|
150 In order to obtain good results with @code{:prefix}, it is necessary to
|
|
151 check the specific effects of discarding a particular prefix, given the
|
|
152 specific items in a group and their names and documentation. If the
|
|
153 resulting text is not clear, then @code{:prefix} should not be used in
|
|
154 that case.
|
|
155
|
|
156 It should be possible to recheck all the customization groups, delete
|
|
157 the @code{:prefix} specifications which give unclear results, and then
|
|
158 turn this feature back on, if someone would like to do the work.
|
|
159
|
|
160 @node Variable Definitions
|
|
161 @section Defining Customization Variables
|
|
162
|
|
163 Use @code{defcustom} to declare user editable variables.
|
|
164
|
|
165 @tindex defcustom
|
|
166 @defmac defcustom option value doc [keyword value]...
|
|
167 Declare @var{option} as a customizable user option variable that
|
|
168 defaults to @var{value}. Do not quote @var{option}. @var{value} should
|
|
169 be an expression to compute the value; it will be be evaluated on more
|
|
170 than one occasion.
|
|
171
|
|
172 If @var{option} is void, @code{defcustom} initializes it to @var{value}.
|
|
173
|
|
174 The argument @var{doc} specifies the documentation string for the variable.
|
|
175
|
|
176 The following additional keywords are defined:
|
|
177
|
|
178 @table @code
|
|
179 @item :type @var{type}
|
|
180 Use @var{type} as the data type for this option. It specifies which
|
|
181 values are legitimate, and how to display the value.
|
|
182 @xref{Customization Types}, for more information.
|
|
183
|
|
184 @item :options @var{list}
|
|
185 Specify @var{list} as the list of reasonable values for use in this
|
|
186 option.
|
|
187
|
|
188 Currently this is meaningful only when type is @code{hook}. The
|
|
189 elements of @var{list} are functions that you might likely want to use
|
|
190 as elements of the hook value. The user is not actually restricted to
|
|
191 using only these functions, but they are offered as convenient
|
|
192 alternatives.
|
|
193
|
|
194 @item :version @var{version}
|
|
195 This option specifies that the variable's default value was changed in
|
|
196 Emacs version @var{version}. For example,
|
|
197
|
|
198 @example
|
|
199 (defcustom foo-max 34
|
|
200 "*Maximum number of foo's allowed."
|
|
201 :type 'integer
|
|
202 :group 'foo
|
|
203 :version "20.3")
|
|
204 @end example
|
|
205
|
|
206 @item :set @var{setfunction}
|
|
207 Specify @var{setfunction} as the way to change the value of this option.
|
|
208 The function @var{setfunction} should take two arguments, a symbol and
|
|
209 the new value, and should do whatever is necessary to update the value
|
|
210 properly for this option (which may not mean simply setting the option
|
|
211 as a Lisp variable). The default for @var{setfunction} is
|
|
212 @code{set-default}.
|
|
213
|
|
214 @item :get @var{getfunction}
|
|
215 Specify @var{getfunction} as the way to extract the value of this
|
|
216 option. The function @var{getfunction} should take one argument, a
|
|
217 symbol, and should return the ``current value'' for that symbol (which
|
|
218 need not be the symbol's Lisp value). The default is
|
|
219 @code{default-value}.
|
|
220
|
|
221 @item :initialize @var{function}
|
|
222 @var{function} should be a function used to initialize the variable when
|
|
223 the @code{defcustom} is evaluated. It should take two arguments, the
|
|
224 symbol and value. Here are some predefined functions meant for use in
|
|
225 this way:
|
|
226
|
|
227 @table @code
|
|
228 @item custom-initialize-set
|
|
229 Use the variable's @code{:set} function to initialize the variable. Do
|
|
230 not reinitialize it if it is already non-void. This is the default
|
|
231 @code{:initialize} function.
|
|
232
|
|
233 @item custom-initialize-default
|
|
234 Always use @code{set-default} to initialize the variable, even if some
|
|
235 other @code{:set} function has been specified.
|
|
236
|
|
237 @item custom-initialize-reset
|
|
238 Even if the variable is already non-void, reset it by calling the
|
|
239 @code{:set} function using the current value (returned by the
|
|
240 @code{:get} method).
|
|
241
|
|
242 @item custom-initialize-changed
|
|
243 Like @code{custom-initialize-reset}, except use @code{set-default}
|
|
244 (rather than the @code{:set} function) to initialize the variable if it
|
|
245 is not bound and has not been set already.
|
|
246 @end table
|
|
247
|
|
248 @item :require @var{feature}
|
|
249 If the user saves a customized value for this item, them Emacs should do
|
|
250 @code{(require @var{feature})} after installing the saved value.
|
|
251
|
|
252 The place to use this feature is for an option that turns on the
|
|
253 operation of a certain feature. Assuming that the package is coded to
|
|
254 check the value of the option, you still need to arrange for the package
|
|
255 to be loaded. That is what @code{:require} is for.
|
|
256 @end table
|
|
257 @end defmac
|
|
258
|
|
259 @ignore
|
|
260 Use @code{custom-add-option} to specify that a specific function is
|
|
261 useful as an member of a hook.
|
|
262
|
|
263 @defun custom-add-option symbol option
|
|
264 To the variable @var{symbol} add @var{option}.
|
|
265
|
|
266 If @var{symbol} is a hook variable, @var{option} should be a hook
|
|
267 member. For other types variables, the effect is undefined."
|
|
268 @end defun
|
|
269 @end ignore
|
|
270
|
|
271 Internally, @code{defcustom} uses the symbol property
|
|
272 @code{standard-value} to record the expression for the default value,
|
|
273 and @code{saved-value} to record the value saved by the user with the
|
|
274 customization buffer. The @code{saved-value} property is actually a
|
|
275 list whose car is an expression which evaluates to the value.
|
|
276
|
|
277 @node Face Definitions
|
|
278 @section Defining Faces
|
|
279
|
|
280 Faces are declared with @code{defface}.
|
|
281
|
|
282 @tindex defface
|
|
283 @defmac defface face spec doc [keyword value]...
|
|
284 Declare @var{face} as a customizable face that defaults according to
|
|
285 @var{spec}. Do not quote the symbol @var{face}.
|
|
286
|
|
287 @var{doc} is the face documentation.
|
|
288
|
|
289 @var{spec} should be an alist whose elements have the form
|
|
290 @code{(@var{display} @var{atts})} (see below). When @code{defface}
|
|
291 executes, it defines the face according to @var{spec}, then uses any
|
|
292 customizations saved in the @file{.emacs} file to override that
|
|
293 specification.
|
|
294
|
|
295 In each element of @var{spec}, @var{atts} is a list of face attributes
|
|
296 and their values. The possible attributes are defined in the variable
|
|
297 @code{custom-face-attributes}.
|
|
298
|
|
299 The @var{display} part of an element of @var{spec} determines which
|
|
300 frames the element applies to. If more than one element of @var{spec}
|
|
301 matches a given frame, the first matching element is the only one used
|
|
302 for that frame.
|
|
303
|
|
304 If @var{display} is @code{t} in a @var{spec} element, that element
|
|
305 matches all frames. (This means that any subsequent elements of
|
|
306 @var{spec} are never used.)
|
|
307
|
|
308 Alternatively, @var{display} can be an alist whose elements have the
|
|
309 form @code{(@var{characteristic} @var{value}@dots{})}. Here
|
|
310 @var{characteristic} specifies a way of classifying frames, and the
|
|
311 @var{value}s are possible classifications which @var{display} should
|
|
312 apply to. Here are the possible values of @var{characteristic}:
|
|
313
|
|
314 @table @code
|
|
315 @item type
|
|
316 The kind of window system the frame uses---either @code{x}, @code{pc}
|
|
317 (for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
|
|
318 @code{tty}.
|
|
319
|
|
320 @item class
|
|
321 What kinds of colors the frame supports---either @code{color},
|
|
322 @code{grayscale}, or @code{mono}.
|
|
323
|
|
324 @item background
|
|
325 The kind of background--- either @code{light} or @code{dark}.
|
|
326 @end table
|
|
327
|
|
328 If an element of @var{display} specifies more than one
|
|
329 @var{value} for a given @var{characteristic}, any of those values
|
|
330 is acceptable. If an element of @var{display} has elements for
|
|
331 more than one @var{characteristic}, then @var{each} characteristic
|
|
332 of the frame must match one of the values specified for it.
|
|
333 @end defmac
|
|
334
|
|
335 Internally, @code{defface} uses the symbol property
|
|
336 @code{face-defface-spec} to record the face attributes specified in
|
|
337 @code{defface}, @code{saved-face} for the attributes saved by the user
|
|
338 with the customization buffer, and @code{face-documentation} for the
|
|
339 documentation string.
|
|
340
|
|
341 @node Customization Types
|
|
342 @section Customization Types
|
|
343
|
|
344 When you define a user option with @code{defcustom}, you must specify
|
|
345 its @dfn{customization type}. That is a Lisp object which indictaes (1)
|
|
346 which values are legitimate and (2) how to display the value in the
|
|
347 customization buffer for editing.
|
|
348
|
|
349 You specify the customization type in @code{defcustom} with the
|
|
350 @code{:type} keyword. The argument of @code{:type} is evaluated; since
|
|
351 types that vary at run time are rarely useful, normally it is a quoted
|
|
352 constant. For example:
|
|
353
|
|
354 @example
|
|
355 (defcustom diff-command "diff"
|
|
356 "*The command to use to run diff."
|
|
357 :type 'string
|
|
358 :group 'diff)
|
|
359 @end example
|
|
360
|
|
361 In general, a customization type appears is a list whose first element
|
|
362 is a symbol, one of the customization type names defined in the
|
|
363 following sections. After this symbol come a number of arguments,
|
|
364 depending on the symbol. Some of the type symbols do not use any
|
|
365 arguments; those are called @dfn{simple types}.
|
|
366
|
|
367 In between the type symbol and its arguments, you can optionally
|
|
368 write keyword-value pairs. @xref{Type Keywords}.
|
|
369
|
|
370 For a simple type, if you do not use any keyword-value pairs, you can
|
|
371 omit the parentheses around the type symbol. The above example does
|
|
372 this, using just @code{string} as the customization type.
|
|
373 But @code{(string)} would mean the same thing.
|
|
374
|
|
375 @menu
|
|
376 * Simple Types::
|
|
377 * Composite Types::
|
|
378 * Splicing into Lists::
|
|
379 * Type Keywords::
|
|
380 @end menu
|
|
381
|
|
382 @node Simple Types
|
|
383 @subsection Simple Types
|
|
384
|
|
385 This section describes all the simple customization types.
|
|
386
|
|
387 @table @code
|
|
388 @item sexp
|
|
389 The value may be any Lisp object that can be printed and read back. You
|
|
390 can use @code{sexp} as a fall-back for any option, if you don't want to
|
|
391 take the time to work out a more specific type to use.
|
|
392
|
|
393 @item integer
|
|
394 The value must be an integer, and is represented textually
|
|
395 in the customization buffer.
|
|
396
|
|
397 @item number
|
|
398 The value must be a number, and is represented textually in the
|
|
399 customization buffer.
|
|
400
|
|
401 @item string
|
|
402 The value must be a string, and the customization buffer shows just the
|
|
403 contents, with no @samp{"} characters or quoting with @samp{\}.
|
|
404
|
|
405 @item regexp
|
|
406 The value must be a string which is a valid regular expression.
|
|
407
|
|
408 @item character
|
|
409 The value must be a character code. A character code is actually an
|
|
410 integer, but this type shows the value by inserting the character in the
|
|
411 buffer, rather than by showing the number.
|
|
412
|
|
413 @item file
|
|
414 The value must be a file name, and you can do completion with
|
|
415 @kbd{M-@key{TAB}}.
|
|
416
|
|
417 @item (file :must-match t)
|
|
418 The value must be a file name for an existing file, and you can do
|
|
419 completion with @kbd{M-@key{TAB}}.
|
|
420
|
|
421 @item directory
|
|
422 The value must be a directory name, and you can do completion with
|
|
423 @kbd{M-@key{TAB}}.
|
|
424
|
|
425 @item symbol
|
|
426 The value must be a symbol. It appears in the customization buffer as
|
|
427 the name of the symbol.
|
|
428
|
|
429 @item function
|
|
430 The value must be either a lambda expression or a function name. When
|
|
431 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
|
|
432
|
|
433 @item variable
|
|
434 The value must be a variable name, and you can do completion with
|
|
435 @kbd{M-@key{TAB}}.
|
|
436
|
|
437 @item boolean
|
|
438 The value is boolean---either @code{nil} or @code{t}.
|
|
439 @end table
|
|
440
|
|
441 @node Composite Types
|
|
442 @subsection Composite Types
|
|
443
|
|
444 When none of the simple types is appropriate, you can use composite
|
|
445 types, which build from simple types. Here are several ways of doing
|
|
446 that:
|
|
447
|
|
448 @table @code
|
|
449 @item (restricted-sexp :match-alternatives @var{criteria})
|
|
450 The value may be any Lisp object that satisfies one of @var{criteria}.
|
|
451 @var{criteria} should be a list, and each elements should be
|
|
452 one of these possibilities:
|
|
453
|
|
454 @itemize @bullet
|
|
455 @item
|
|
456 A predicate---that is, a function of one argument that returns non-@code{nil}
|
|
457 if the argument fits a certain type. This means that objects of that type
|
|
458 are acceptable.
|
|
459
|
|
460 @item
|
|
461 A quoted constant---that is, @code{'@var{object}}. This means that
|
|
462 @var{object} is an acceptable value.
|
|
463 @end itemize
|
|
464
|
|
465 For example,
|
|
466
|
|
467 @example
|
|
468 (restricted-sexp :match-alternatives (integerp 't 'nil))
|
|
469 @end example
|
|
470
|
|
471 @noindent
|
|
472 allows integers, @code{t} and @code{nil} as legitimate values.
|
|
473
|
|
474 The customization buffer shows all legitimate values using their read
|
|
475 syntax, and the user edits them textually.
|
|
476
|
|
477 @item (cons @var{car-type} @var{cdr-type})
|
|
478 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
|
|
479 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(const string
|
|
480 symbol)} is a customization type which matches values such as
|
|
481 @code{("foo" . foo)}.
|
|
482
|
|
483 In the customization buffeer, the @sc{car} and the @sc{cdr} are
|
|
484 displayed and edited separately, each according to the type
|
|
485 that you specify for it.
|
|
486
|
|
487 @item (list @var{element-types}@dots{})
|
|
488 The value must be a list with exactly as many elements as the
|
|
489 @var{element-types} you have specified; and each element must fit the
|
|
490 corresponding @var{element-type}.
|
|
491
|
|
492 For example, @code{(list integer string function)} describes a list of
|
|
493 three elements; the first element must be an integer, the second a
|
|
494 string, and the third a function.
|
|
495
|
|
496 In the customization buffeer, the each element is displayed and edited
|
|
497 separately, according to the type specified for it.
|
|
498
|
|
499 @item (vector @var{element-types}@dots{})
|
|
500 Like @code{list} except that the value must be a vector instead of a
|
|
501 list. The elements work the same as in @code{list}.
|
|
502
|
|
503 @item (choice @var{alternative-types}...)
|
|
504 The value must fit at least one of @var{alternative-types}.
|
|
505 For example, @code{(choice integer string)} allows either an
|
|
506 integer or a string.
|
|
507
|
|
508 In the customization buffer, the user selects one of the alternatives
|
|
509 using a menu, and can then edit the value in the usual way for that
|
|
510 alternative.
|
|
511
|
|
512 Normally the strings in this menu are determined automatically from the
|
|
513 choices; however, you can specify different strings for the menu by
|
|
514 including the @code{:tag} keyword in the alternatives. For example, if
|
|
515 an integer stands for a number of spaces, while a string is text to use
|
|
516 verbatim, you might write the customization type this way,
|
|
517
|
|
518 @smallexample
|
|
519 (choice (integer :tag "Number of spaces")
|
|
520 (string :tag "Literal text"))
|
|
521 @end smallexample
|
|
522
|
|
523 @noindent
|
|
524 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
|
|
525
|
|
526 @item (const @var{value})
|
|
527 The value must be @var{value}---nothing else is allowed.
|
|
528
|
|
529 The main use of @code{const} is inside of @code{choice}. For example,
|
|
530 @code{(choice integer (const nil))} allows either an integer or
|
|
531 @code{nil}. @code{:tag} is often used with @code{const}.
|
|
532
|
|
533 @item (function-item @var{function})
|
|
534 Like @code{const}, but used for values which are functions. This
|
|
535 displays the documentation string of the function @var{function}
|
|
536 as well as its name.
|
|
537
|
|
538 @item (variable-item @var{variable})
|
|
539 Like @code{const}, but used for values which are variable names. This
|
|
540 displays the documentation string of the variable @var{variable} as well
|
|
541 as its name.
|
|
542
|
|
543 @item (set @var{elements}@dots{})
|
|
544 The value must be a list and each element of the list must be one of the
|
|
545 @var{elements} specified. This appears in the customization buffer as a
|
|
546 checklist.
|
|
547
|
|
548 @item (repeat @var{element-type})
|
|
549 The value must be a list and each element of the list must fit the type
|
|
550 @var{element-type}. This appears in the customization buffer as a
|
|
551 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
|
|
552 more elements or removing elements.
|
|
553 @end table
|
|
554
|
|
555 @node Splicing into Lists
|
|
556 @subsection Splicing into Lists
|
|
557
|
|
558 The @code{:inline} feature lets you splice a variable number of
|
|
559 elements into the middle of a list or vector. You use it in a
|
|
560 @code{set}, @code{choice} or @code{repeat} type which appears among the
|
|
561 element-types of a @code{list} or @code{vector}.
|
|
562
|
|
563 Normally, each of the element-types in a @code{list} or @code{vector}
|
|
564 describes one and only one element of the list or vector. Thus, if an
|
|
565 element-type is a @code{repeat}, that specifies a list of unspecified
|
|
566 length which appears as one element.
|
|
567
|
|
568 But when the element-type uses @code{:inline}, the value it matches is
|
|
569 merged directly into the containing sequence. For example, if it
|
|
570 matches a list with three elements, those become three elements of the
|
|
571 overall sequence. This is analogous to using @samp{,@@} in the backquote
|
|
572 construct.
|
|
573
|
|
574 For example, to specify a list whose first element must be @code{t}
|
|
575 and whose remaining arguments should be zero or more of @code{foo} and
|
|
576 @code{bar}, use this customization type:
|
|
577
|
|
578 @example
|
|
579 (list (const t) (set :inline t foo bar))
|
|
580 @end example
|
|
581
|
|
582 @noindent
|
|
583 This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
|
|
584 and @code{(t foo bar)}.
|
|
585
|
|
586 When the element-type is a @code{choice}, you use @code{:inline} not
|
|
587 in the @code{choice} itself, but in (some of) the alternatives of the
|
|
588 @code{choice}. For example, to match a list which must start with a
|
|
589 file name, followed either by the symbol @code{t} or two strings, use
|
|
590 this customization type:
|
|
591
|
|
592 @example
|
|
593 (list file
|
|
594 (choice (const t)
|
|
595 (list :inline t string string)))
|
|
596 @end example
|
|
597
|
|
598 @noindent
|
|
599 If the user chooses the first alternative in the choice, then the
|
|
600 overall list has two elements and the second element is @code{t}. If
|
|
601 the user chooses the second alternative, then the overall list has three
|
|
602 elements and the second and third must be strings.
|
|
603
|
|
604 @node Type Keywords
|
|
605 @subsection Type Keywords
|
|
606
|
|
607 You can specify keyword-argument pairs in a customization type after the
|
|
608 type name symbol. Here are the keywords you can use, and their
|
|
609 meanings:
|
|
610
|
|
611 @table @code
|
|
612 @item :value @var{default}
|
|
613 This is used for a type that appears as an alternative inside of
|
|
614 @code{:choice}; it specifies the default value to use, at first, if and
|
|
615 when the user selects this alternative with the menu in the
|
|
616 customization buffer.
|
|
617
|
|
618 Of course, if the actual value of the option fits this alternative, it
|
|
619 will appear showing the actual value, not @var{default}.
|
|
620
|
|
621 @item :format @var{format-string}
|
|
622 This string will be inserted in the buffer to represent the value
|
|
623 corresponding to the type. The following @samp{%} escapes are available
|
|
624 for use in @var{format-string}:
|
|
625
|
|
626 @table @samp
|
|
627 @ignore
|
|
628 @item %[@var{button}%]
|
|
629 Display the text @var{button} marked as a button. The @code{:action}
|
|
630 attribute specifies what the button will do if the user invokes it;
|
|
631 its value is a function which takes two arguments---the widget which
|
|
632 the button appears in, and the event.
|
|
633
|
|
634 There is no way to specify two different buttons with different
|
|
635 actions; but perhaps there is no need for one.
|
|
636 @end ignore
|
|
637
|
|
638 @item %@{@var{sample}%@}
|
|
639 Show @var{sample} in a special face specified by @code{:sample-face}.
|
|
640
|
|
641 @item %v
|
|
642 Substitute the item's value. How the value is represented depends on
|
|
643 the kind of item, and (for variables) on the customization type.
|
|
644
|
|
645 @item %d
|
|
646 Substitute the item's documentation string.
|
|
647
|
|
648 @item %h
|
|
649 Like @samp{%d}, but if the documentation string is more than one line,
|
|
650 add an active field to control whether to show all of it or just the
|
|
651 first line.
|
|
652
|
|
653 @item %t
|
|
654 Substitute the tag here. You specify the tag with the @code{:tag}
|
|
655 keyword.
|
|
656
|
|
657 @item %%
|
|
658 Display a literal @samp{%}.
|
|
659 @end table
|
|
660
|
|
661 @item :button-face @var{face}
|
|
662 Use face @var{face} for text displayed with @samp{%[@dots{}%]}.
|
|
663
|
|
664 @item :button-prefix
|
|
665 @itemx :button-suffix
|
|
666 These specify the text to display before and after a button.
|
|
667 Each can be:
|
|
668
|
|
669 @table @asis
|
|
670 @item @code{nil}
|
|
671 No text is inserted.
|
|
672
|
|
673 @item a string
|
|
674 The string is inserted literally.
|
|
675
|
|
676 @item a symbol
|
|
677 The symbol's value is used.
|
|
678 @end table
|
|
679
|
|
680 @item :doc @var{doc}
|
|
681 Use @var{doc} as the documentation string for this item.
|
|
682
|
|
683 @item :tag @var{tag}
|
|
684 Use @var{tag} (a string) as the tag for this item.
|
|
685
|
|
686 @item :help-echo @var{motion-doc}
|
|
687 When you move to this item with @code{widget-forward} or
|
|
688 @code{widget-backward}, it will display the string @var{motion-doc}
|
|
689 in the echo area.
|
|
690
|
|
691 @item :match @var{function}
|
|
692 Specify how to decide whether a value matches the type. @var{function}
|
|
693 should be a function that accepts two arguments, a widget and a value;
|
|
694 it should return non-@code{nil} if the value is acceptable.
|
|
695
|
|
696 @ignore
|
|
697 @item :indent @var{columns}
|
|
698 Indent this item by @var{columns} columns. The indentation is used for
|
|
699 @samp{%n}, and automatically for group names, for checklists and radio
|
|
700 buttons, and for editable lists. It affects the whole of the
|
|
701 item except for the first line.
|
|
702
|
|
703 @item :offset @var{columns}
|
|
704 An integer indicating how many extra spaces to indent the subitems of
|
|
705 this item. By default, subitems are indented the same as their parent.
|
|
706
|
|
707 @item :extra-offset
|
|
708 An integer indicating how many extra spaces to add to this item's
|
|
709 indentation, compared to its parent.
|
|
710
|
|
711 @item :notify
|
|
712 A function called each time the item or a subitem is changed. The
|
|
713 function is called with two or three arguments. The first argument is
|
|
714 the item itself, the second argument is the item that was changed, and
|
|
715 the third argument is the event leading to the change, if any.
|
|
716
|
|
717 @item :menu-tag
|
|
718 Tag used in the menu when the widget is used as an option in a
|
|
719 @code{menu-choice} widget.
|
|
720
|
|
721 @item :menu-tag-get
|
|
722 Function used for finding the tag when the widget is used as an option
|
|
723 in a @code{menu-choice} widget. By default, the tag used will be either the
|
|
724 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
|
|
725 representation of the @code{:value} property if not.
|
|
726
|
|
727 @item :validate
|
|
728 A function which takes a widget as an argument, and return nil if the
|
|
729 widgets current value is valid for the widget. Otherwise, it should
|
|
730 return the widget containing the invalid data, and set that widgets
|
|
731 @code{:error} property to a string explaining the error.
|
|
732
|
|
733 You can use the function @code{widget-children-validate} for this job;
|
|
734 it tests that all children of @var{widget} are valid.
|
|
735
|
|
736 @item :tab-order
|
|
737 Specify the order in which widgets are traversed with
|
|
738 @code{widget-forward} or @code{widget-backward}. This is only partially
|
|
739 implemented.
|
|
740
|
|
741 @enumerate a
|
|
742 @item
|
|
743 Widgets with tabbing order @code{-1} are ignored.
|
|
744
|
|
745 @item
|
|
746 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
|
|
747 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
|
|
748 whichever comes first.
|
|
749
|
|
750 @item
|
|
751 When on a widget with no tabbing order specified, go to the next widget
|
|
752 in the buffer with a positive tabbing order, or @code{nil}
|
|
753 @end enumerate
|
|
754
|
|
755 @item :parent
|
|
756 The parent of a nested widget (e.g. a @code{menu-choice} item or an
|
|
757 element of a @code{editable-list} widget).
|
|
758
|
|
759 @item :sibling-args
|
|
760 This keyword is only used for members of a @code{radio-button-choice} or
|
|
761 @code{checklist}. The value should be a list of extra keyword
|
|
762 arguments, which will be used when creating the @code{radio-button} or
|
|
763 @code{checkbox} associated with this item.
|
|
764 @end ignore
|
|
765 @end table
|