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