|
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::
|
|
775
|
19 * Enabling Behavior::
|
|
318
|
20 @end menu
|
|
|
21
|
|
|
22 @node Common Keywords
|
|
|
23 @section Common Keywords for All Kinds of Items
|
|
|
24
|
|
|
25 All kinds of customization declarations (for variables and groups, and
|
|
|
26 for faces) accept keyword arguments for specifying various information.
|
|
|
27 This section describes some keywords that apply to all kinds.
|
|
|
28
|
|
|
29 All of these keywords, except @code{:tag}, can be used more than once
|
|
|
30 in a given item. Each use of the keyword has an independent effect.
|
|
|
31 The keyword @code{:tag} is an exception because any given item can only
|
|
|
32 display one name.
|
|
|
33
|
|
|
34 @table @code
|
|
|
35 @item :tag @var{name}
|
|
|
36 Use @var{name}, a string, instead of the item's name, to label the item
|
|
|
37 in customization menus and buffers.
|
|
|
38
|
|
|
39 @item :group @var{group}
|
|
|
40 Put this customization item in group @var{group}. When you use
|
|
|
41 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
|
|
|
42 @var{group}.
|
|
|
43
|
|
|
44 If you use this keyword more than once, you can put a single item into
|
|
|
45 more than one group. Displaying any of those groups will show this
|
|
|
46 item. Be careful not to overdo this!
|
|
|
47
|
|
|
48 @item :link @var{link-data}
|
|
|
49 Include an external link after the documentation string for this item.
|
|
|
50 This is a sentence containing an active field which references some
|
|
|
51 other documentation.
|
|
|
52
|
|
|
53 There are three alternatives you can use for @var{link-data}:
|
|
|
54
|
|
|
55 @table @code
|
|
|
56 @item (custom-manual @var{info-node})
|
|
|
57 Link to an Info node; @var{info-node} is a string which specifies the
|
|
|
58 node name, as in @code{"(emacs)Top"}. The link appears as
|
|
|
59 @samp{[manual]} in the customization buffer.
|
|
|
60
|
|
|
61 @item (info-link @var{info-node})
|
|
|
62 Like @code{custom-manual} except that the link appears
|
|
|
63 in the customization buffer with the Info node name.
|
|
|
64
|
|
|
65 @item (url-link @var{url})
|
|
|
66 Link to a web page; @var{url} is a string which specifies the @sc{url}.
|
|
|
67 The link appears in the customization buffer as @var{url}.
|
|
|
68 @end table
|
|
|
69
|
|
|
70 You can specify the text to use in the customization buffer by adding
|
|
|
71 @code{:tag @var{name}} after the first element of the @var{link-data};
|
|
|
72 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
|
|
|
73 the Emacs manual which appears in the buffer as @samp{foo}.
|
|
|
74
|
|
|
75 An item can have more than one external link; however, most items have
|
|
|
76 none at all.
|
|
|
77
|
|
|
78 @item :load @var{file}
|
|
|
79 Load file @var{file} (a string) before displaying this customization
|
|
|
80 item. Loading is done with @code{load-library}, and only if the file is
|
|
|
81 not already loaded.
|
|
|
82
|
|
|
83 @item :require @var{feature}
|
|
|
84 Require feature @var{feature} (a symbol) when installing a value for
|
|
|
85 this item (an option or a face) that was saved using the customization
|
|
|
86 feature. This is done by calling @code{require}.
|
|
|
87
|
|
|
88 The most common reason to use @code{:require} is when a variable enables
|
|
|
89 a feature such as a minor mode, and just setting the variable won't have
|
|
|
90 any effect unless the code which implements the mode is loaded.
|
|
|
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 put 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. (To display the full list of them,
|
|
|
107 use @kbd{M-x customize}.) Choose one or more of them (but not too
|
|
|
108 many), and add your group to each of them using the @code{:group}
|
|
|
109 keyword.
|
|
|
110
|
|
|
111 The way to declare new customization groups is with @code{defgroup}.
|
|
|
112
|
|
|
113 @tindex defgroup
|
|
|
114 @defmac defgroup group members doc [keyword value]...
|
|
|
115 Declare @var{group} as a customization group containing @var{members}.
|
|
|
116 Do not quote the symbol @var{group}. The argument @var{doc} specifies
|
|
|
117 the documentation string for the group.
|
|
|
118
|
|
|
119 The argument @var{members} is a list specifying an initial set of
|
|
|
120 customization items to be members of the group. However, most often
|
|
|
121 @var{members} is @code{nil}, and you specify the group's members by
|
|
|
122 using the @code{:group} keyword when defining those members.
|
|
|
123
|
|
|
124 If you want to specify group members through @var{members}, each element
|
|
|
125 should have the form @code{(@var{name} @var{widget})}. Here @var{name}
|
|
|
126 is a symbol, and @var{widget} is a widget type for editing that symbol.
|
|
|
127 Useful widgets are @code{custom-variable} for a variable,
|
|
|
128 @code{custom-face} for a face, and @code{custom-group} for a group.
|
|
|
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 @c Doesn't apply to XEmacs
|
|
|
143 @c
|
|
|
144 @c The prefix-discarding feature is currently turned off, which means
|
|
|
145 @c that @code{:prefix} currently has no effect. We did this because we
|
|
|
146 @c found that discarding the specified prefixes often led to confusing
|
|
|
147 @c names for options. This happened because the people who wrote the
|
|
|
148 @c @code{defgroup} definitions for various groups added @code{:prefix}
|
|
|
149 @c keywords whenever they make logical sense---that is, whenever the
|
|
|
150 @c variables in the library have a common prefix.
|
|
|
151
|
|
|
152 @c In order to obtain good results with @code{:prefix}, it would be
|
|
|
153 @c necessary to check the specific effects of discarding a particular
|
|
|
154 @c prefix, given the specific items in a group and their names and
|
|
|
155 @c documentation. If the resulting text is not clear, then @code{:prefix}
|
|
|
156 @c should not be used in that case.
|
|
|
157
|
|
|
158 @c It should be possible to recheck all the customization groups, delete
|
|
|
159 @c the @code{:prefix} specifications which give unclear results, and then
|
|
|
160 @c turn this feature back on, if someone would like to do the work.
|
|
|
161
|
|
|
162 @node Variable Definitions
|
|
|
163 @section Defining Customization Variables
|
|
|
164
|
|
|
165 Use @code{defcustom} to declare user-editable variables.
|
|
|
166
|
|
|
167 @tindex defcustom
|
|
|
168 @defmac defcustom option default doc [keyword value]...
|
|
|
169 Declare @var{option} as a customizable user option variable. Do not
|
|
|
170 quote @var{option}. The argument @var{doc} specifies the documentation
|
|
|
171 string for the variable.
|
|
|
172
|
|
|
173 If @var{option} is void, @code{defcustom} initializes it to
|
|
|
174 @var{default}. @var{default} should be an expression to compute the
|
|
|
175 value; be careful in writing it, because it can be evaluated on more
|
|
|
176 than one occasion.
|
|
|
177
|
|
|
178 The following additional keywords are defined:
|
|
|
179
|
|
|
180 @table @code
|
|
|
181 @item :type @var{type}
|
|
|
182 Use @var{type} as the data type for this option. It specifies which
|
|
|
183 values are legitimate, and how to display the value.
|
|
|
184 @xref{Customization Types}, for more information.
|
|
|
185
|
|
|
186 @item :options @var{list}
|
|
|
187 Specify @var{list} as the list of reasonable values for use in this
|
|
|
188 option.
|
|
|
189
|
|
|
190 Currently this is meaningful only when the type is @code{hook}. In that
|
|
|
191 case, the elements of @var{list} should be functions that are useful as
|
|
|
192 elements of the hook value. The user is not restricted to using only
|
|
|
193 these functions, but they are offered as convenient alternatives.
|
|
|
194
|
|
|
195 @item :version @var{version}
|
|
|
196 This option specifies that the variable was first introduced, or its
|
|
|
197 default value was changed, in Emacs version @var{version}. The value
|
|
|
198 @var{version} must be a string. For example,
|
|
|
199
|
|
|
200 @example
|
|
|
201 (defcustom foo-max 34
|
|
|
202 "*Maximum number of foo's allowed."
|
|
|
203 :type 'integer
|
|
|
204 :group 'foo
|
|
|
205 :version "20.3")
|
|
|
206 @end example
|
|
|
207
|
|
|
208 @item :set @var{setfunction}
|
|
|
209 Specify @var{setfunction} as the way to change the value of this option.
|
|
|
210 The function @var{setfunction} should take two arguments, a symbol and
|
|
|
211 the new value, and should do whatever is necessary to update the value
|
|
|
212 properly for this option (which may not mean simply setting the option
|
|
|
213 as a Lisp variable). The default for @var{setfunction} is
|
|
|
214 @code{set-default}.
|
|
|
215
|
|
|
216 @item :get @var{getfunction}
|
|
|
217 Specify @var{getfunction} as the way to extract the value of this
|
|
|
218 option. The function @var{getfunction} should take one argument, a
|
|
|
219 symbol, and should return the ``current value'' for that symbol (which
|
|
|
220 need not be the symbol's Lisp value). The default is
|
|
|
221 @code{default-value}.
|
|
|
222
|
|
|
223 @item :initialize @var{function}
|
|
|
224 @var{function} should be a function used to initialize the variable when
|
|
|
225 the @code{defcustom} is evaluated. It should take two arguments, the
|
|
|
226 symbol and value. Here are some predefined functions meant for use in
|
|
|
227 this way:
|
|
|
228
|
|
|
229 @table @code
|
|
|
230 @item custom-initialize-set
|
|
|
231 Use the variable's @code{:set} function to initialize the variable, but
|
|
|
232 do not reinitialize it if it is already non-void. This is the default
|
|
|
233 @code{:initialize} function.
|
|
|
234
|
|
|
235 @item custom-initialize-default
|
|
|
236 Like @code{custom-initialize-set}, but use the function
|
|
|
237 @code{set-default} to set the variable, instead of the variable's
|
|
|
238 @code{:set} function. This is the usual choice for a variable whose
|
|
|
239 @code{:set} function enables or disables a minor mode; with this choice,
|
|
|
240 defining the variable will not call the minor mode function, but
|
|
|
241 customizing the variable will do so.
|
|
|
242
|
|
|
243 @item custom-initialize-reset
|
|
|
244 Always use the @code{:set} function to initialize the variable. If the
|
|
|
245 variable is already non-void, reset it by calling the @code{:set}
|
|
|
246 function using the current value (returned by the @code{:get} method).
|
|
|
247
|
|
|
248 @item custom-initialize-changed
|
|
|
249 Use the @code{:set} function to initialize the variable, if it is
|
|
|
250 already set or has been customized; otherwise, just use
|
|
|
251 @code{set-default}.
|
|
|
252 @end table
|
|
|
253 @end table
|
|
|
254 @end defmac
|
|
|
255
|
|
|
256 The @code{:require} option is useful for an option that turns on the
|
|
|
257 operation of a certain feature. Assuming that the package is coded to
|
|
|
258 check the value of the option, you still need to arrange for the package
|
|
|
259 to be loaded. You can do that with @code{:require}. @xref{Common
|
|
|
260 Keywords}. Here is an example, from the library @file{paren.el}:
|
|
|
261
|
|
|
262 @example
|
|
|
263 (defcustom show-paren-mode nil
|
|
|
264 "Toggle Show Paren mode@enddots{}"
|
|
|
265 :set (lambda (symbol value)
|
|
398
|
266 (show-paren-mode (or value 0)))
|
|
318
|
267 :initialize 'custom-initialize-default
|
|
|
268 :type 'boolean
|
|
|
269 :group 'paren-showing
|
|
|
270 :require 'paren)
|
|
|
271 @end example
|
|
|
272
|
|
|
273 @ignore
|
|
|
274 Use @code{custom-add-option} to specify that a specific function is
|
|
|
275 useful as an member of a hook.
|
|
|
276
|
|
|
277 @defun custom-add-option symbol option
|
|
|
278 To the variable @var{symbol} add @var{option}.
|
|
|
279
|
|
|
280 If @var{symbol} is a hook variable, @var{option} should be a hook
|
|
|
281 member. For other types variables, the effect is undefined."
|
|
|
282 @end defun
|
|
|
283 @end ignore
|
|
|
284
|
|
|
285 Internally, @code{defcustom} uses the symbol property
|
|
|
286 @code{standard-value} to record the expression for the default value,
|
|
|
287 and @code{saved-value} to record the value saved by the user with the
|
|
|
288 customization buffer. The @code{saved-value} property is actually a
|
|
|
289 list whose car is an expression which evaluates to the value.
|
|
|
290
|
|
775
|
291 @node Customization Types, Enabling Behavior, Variable Definitions, Customization
|
|
318
|
292 @section Customization Types
|
|
|
293
|
|
|
294 When you define a user option with @code{defcustom}, you must specify
|
|
|
295 its @dfn{customization type}. That is a Lisp object which describes (1)
|
|
|
296 which values are legitimate and (2) how to display the value in the
|
|
|
297 customization buffer for editing.
|
|
|
298
|
|
|
299 You specify the customization type in @code{defcustom} with the
|
|
|
300 @code{:type} keyword. The argument of @code{:type} is evaluated; since
|
|
|
301 types that vary at run time are rarely useful, normally you use a quoted
|
|
|
302 constant. For example:
|
|
|
303
|
|
|
304 @example
|
|
|
305 (defcustom diff-command "diff"
|
|
|
306 "*The command to use to run diff."
|
|
|
307 :type '(string)
|
|
|
308 :group 'diff)
|
|
|
309 @end example
|
|
|
310
|
|
|
311 In general, a customization type is a list whose first element is a
|
|
|
312 symbol, one of the customization type names defined in the following
|
|
|
313 sections. After this symbol come a number of arguments, depending on
|
|
|
314 the symbol. Between the type symbol and its arguments, you can
|
|
|
315 optionally write keyword-value pairs (@pxref{Type Keywords}).
|
|
|
316
|
|
|
317 Some of the type symbols do not use any arguments; those are called
|
|
|
318 @dfn{simple types}. For a simple type, if you do not use any
|
|
|
319 keyword-value pairs, you can omit the parentheses around the type
|
|
|
320 symbol. For example just @code{string} as a customization type is
|
|
|
321 equivalent to @code{(string)}.
|
|
|
322
|
|
|
323 @menu
|
|
|
324 * Simple Types::
|
|
|
325 * Composite Types::
|
|
|
326 * Splicing into Lists::
|
|
|
327 * Type Keywords::
|
|
1833
|
328 * Defining New Types::
|
|
318
|
329 @end menu
|
|
|
330
|
|
|
331 @node Simple Types
|
|
|
332 @subsection Simple Types
|
|
|
333
|
|
|
334 This section describes all the simple customization types.
|
|
|
335
|
|
|
336 @table @code
|
|
|
337 @item sexp
|
|
|
338 The value may be any Lisp object that can be printed and read back. You
|
|
|
339 can use @code{sexp} as a fall-back for any option, if you don't want to
|
|
|
340 take the time to work out a more specific type to use.
|
|
|
341
|
|
|
342 @item integer
|
|
|
343 The value must be an integer, and is represented textually
|
|
|
344 in the customization buffer.
|
|
|
345
|
|
|
346 @item number
|
|
|
347 The value must be a number, and is represented textually in the
|
|
|
348 customization buffer.
|
|
|
349
|
|
|
350 @item string
|
|
|
351 The value must be a string, and the customization buffer shows just the
|
|
|
352 contents, with no delimiting @samp{"} characters and no quoting with
|
|
|
353 @samp{\}.
|
|
|
354
|
|
|
355 @item regexp
|
|
|
356 Like @code{string} except that the string must be a valid regular
|
|
|
357 expression.
|
|
|
358
|
|
|
359 @item character
|
|
|
360 The value must be a character code. A character code is actually an
|
|
|
361 integer, but this type shows the value by inserting the character in the
|
|
|
362 buffer, rather than by showing the number.
|
|
|
363
|
|
|
364 @item file
|
|
|
365 The value must be a file name, and you can do completion with
|
|
|
366 @kbd{M-@key{TAB}}.
|
|
|
367
|
|
|
368 @item (file :must-match t)
|
|
|
369 The value must be a file name for an existing file, and you can do
|
|
|
370 completion with @kbd{M-@key{TAB}}.
|
|
|
371
|
|
|
372 @item directory
|
|
|
373 The value must be a directory name, and you can do completion with
|
|
|
374 @kbd{M-@key{TAB}}.
|
|
|
375
|
|
|
376 @item symbol
|
|
|
377 The value must be a symbol. It appears in the customization buffer as
|
|
|
378 the name of the symbol.
|
|
|
379
|
|
|
380 @item function
|
|
|
381 The value must be either a lambda expression or a function name. When
|
|
|
382 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
|
|
|
383
|
|
|
384 @item variable
|
|
|
385 The value must be a variable name, and you can do completion with
|
|
|
386 @kbd{M-@key{TAB}}.
|
|
|
387
|
|
|
388 @item face
|
|
|
389 The value must be a symbol which is a face name.
|
|
|
390
|
|
|
391 @item boolean
|
|
|
392 The value is boolean---either @code{nil} or @code{t}. Note that by
|
|
|
393 using @code{choice} and @code{const} together (see the next section),
|
|
|
394 you can specify that the value must be @code{nil} or @code{t}, but also
|
|
|
395 specify the text to describe each value in a way that fits the specific
|
|
|
396 meaning of the alternative.
|
|
|
397 @end table
|
|
|
398
|
|
|
399 @node Composite Types
|
|
|
400 @subsection Composite Types
|
|
|
401
|
|
|
402 When none of the simple types is appropriate, you can use composite
|
|
|
403 types, which build new types from other types. Here are several ways of
|
|
|
404 doing that:
|
|
|
405
|
|
|
406 @table @code
|
|
|
407 @item (restricted-sexp :match-alternatives @var{criteria})
|
|
|
408 The value may be any Lisp object that satisfies one of @var{criteria}.
|
|
|
409 @var{criteria} should be a list, and each elements should be
|
|
|
410 one of these possibilities:
|
|
|
411
|
|
|
412 @itemize @bullet
|
|
|
413 @item
|
|
|
414 A predicate---that is, a function of one argument that returns non-@code{nil}
|
|
|
415 if the argument fits a certain type. This means that objects of that type
|
|
|
416 are acceptable.
|
|
|
417
|
|
|
418 @item
|
|
|
419 A quoted constant---that is, @code{'@var{object}}. This means that
|
|
|
420 @var{object} itself is an acceptable value.
|
|
|
421 @end itemize
|
|
|
422
|
|
|
423 For example,
|
|
|
424
|
|
|
425 @example
|
|
|
426 (restricted-sexp :match-alternatives (integerp 't 'nil))
|
|
|
427 @end example
|
|
|
428
|
|
|
429 @noindent
|
|
|
430 allows integers, @code{t} and @code{nil} as legitimate values.
|
|
|
431
|
|
|
432 The customization buffer shows all legitimate values using their read
|
|
|
433 syntax, and the user edits them textually.
|
|
|
434
|
|
|
435 @item (cons @var{car-type} @var{cdr-type})
|
|
|
436 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
|
|
|
437 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
|
|
|
438 symbol)} is a customization type which matches values such as
|
|
|
439 @code{("foo" . foo)}.
|
|
|
440
|
|
|
441 In the customization buffer, the @sc{car} and the @sc{cdr} are
|
|
|
442 displayed and edited separately, each according to the type
|
|
|
443 that you specify for it.
|
|
|
444
|
|
|
445 @item (list @var{element-types}@dots{})
|
|
|
446 The value must be a list with exactly as many elements as the
|
|
|
447 @var{element-types} you have specified; and each element must fit the
|
|
|
448 corresponding @var{element-type}.
|
|
|
449
|
|
|
450 For example, @code{(list integer string function)} describes a list of
|
|
|
451 three elements; the first element must be an integer, the second a
|
|
|
452 string, and the third a function.
|
|
|
453
|
|
|
454 In the customization buffer, the each element is displayed and edited
|
|
|
455 separately, according to the type specified for it.
|
|
|
456
|
|
|
457 @item (vector @var{element-types}@dots{})
|
|
|
458 Like @code{list} except that the value must be a vector instead of a
|
|
|
459 list. The elements work the same as in @code{list}.
|
|
|
460
|
|
|
461 @item (choice @var{alternative-types}...)
|
|
|
462 The value must fit at least one of @var{alternative-types}.
|
|
|
463 For example, @code{(choice integer string)} allows either an
|
|
|
464 integer or a string.
|
|
|
465
|
|
|
466 In the customization buffer, the user selects one of the alternatives
|
|
|
467 using a menu, and can then edit the value in the usual way for that
|
|
|
468 alternative.
|
|
|
469
|
|
|
470 Normally the strings in this menu are determined automatically from the
|
|
|
471 choices; however, you can specify different strings for the menu by
|
|
|
472 including the @code{:tag} keyword in the alternatives. For example, if
|
|
|
473 an integer stands for a number of spaces, while a string is text to use
|
|
|
474 verbatim, you might write the customization type this way,
|
|
|
475
|
|
|
476 @smallexample
|
|
|
477 (choice (integer :tag "Number of spaces")
|
|
|
478 (string :tag "Literal text"))
|
|
|
479 @end smallexample
|
|
|
480
|
|
|
481 @noindent
|
|
|
482 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
|
|
|
483
|
|
|
484 In any alternative for which @code{nil} is not a valid value, other than
|
|
|
485 a @code{const}, you should specify a valid default for that alternative
|
|
|
486 using the @code{:value} keyword. @xref{Type Keywords}.
|
|
|
487
|
|
|
488 @item (const @var{value})
|
|
|
489 The value must be @var{value}---nothing else is allowed.
|
|
|
490
|
|
|
491 The main use of @code{const} is inside of @code{choice}. For example,
|
|
|
492 @code{(choice integer (const nil))} allows either an integer or
|
|
|
493 @code{nil}.
|
|
|
494
|
|
|
495 @code{:tag} is often used with @code{const}, inside of @code{choice}.
|
|
|
496 For example,
|
|
|
497
|
|
|
498 @smallexample
|
|
|
499 (choice (const :tag "Yes" t)
|
|
|
500 (const :tag "No" nil)
|
|
|
501 (const :tag "Ask" foo))
|
|
|
502 @end smallexample
|
|
|
503
|
|
|
504 @item (function-item @var{function})
|
|
|
505 Like @code{const}, but used for values which are functions. This
|
|
|
506 displays the documentation string as well as the function name.
|
|
|
507 The documentation string is either the one you specify with
|
|
|
508 @code{:doc}, or @var{function}'s own documentation string.
|
|
|
509
|
|
|
510 @item (variable-item @var{variable})
|
|
|
511 Like @code{const}, but used for values which are variable names. This
|
|
|
512 displays the documentation string as well as the variable name. The
|
|
|
513 documentation string is either the one you specify with @code{:doc}, or
|
|
|
514 @var{variable}'s own documentation string.
|
|
|
515
|
|
|
516 @item (set @var{elements}@dots{})
|
|
|
517 The value must be a list and each element of the list must be one of the
|
|
|
518 @var{elements} specified. This appears in the customization buffer as a
|
|
|
519 checklist.
|
|
|
520
|
|
|
521 @item (repeat @var{element-type})
|
|
|
522 The value must be a list and each element of the list must fit the type
|
|
|
523 @var{element-type}. This appears in the customization buffer as a
|
|
|
524 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
|
|
|
525 more elements or removing elements.
|
|
|
526 @end table
|
|
|
527
|
|
|
528 @node Splicing into Lists
|
|
|
529 @subsection Splicing into Lists
|
|
|
530
|
|
|
531 The @code{:inline} feature lets you splice a variable number of
|
|
|
532 elements into the middle of a list or vector. You use it in a
|
|
|
533 @code{set}, @code{choice} or @code{repeat} type which appears among the
|
|
|
534 element-types of a @code{list} or @code{vector}.
|
|
|
535
|
|
|
536 Normally, each of the element-types in a @code{list} or @code{vector}
|
|
|
537 describes one and only one element of the list or vector. Thus, if an
|
|
|
538 element-type is a @code{repeat}, that specifies a list of unspecified
|
|
|
539 length which appears as one element.
|
|
|
540
|
|
|
541 But when the element-type uses @code{:inline}, the value it matches is
|
|
|
542 merged directly into the containing sequence. For example, if it
|
|
|
543 matches a list with three elements, those become three elements of the
|
|
|
544 overall sequence. This is analogous to using @samp{,@@} in the backquote
|
|
|
545 construct.
|
|
|
546
|
|
|
547 For example, to specify a list whose first element must be @code{t}
|
|
|
548 and whose remaining arguments should be zero or more of @code{foo} and
|
|
|
549 @code{bar}, use this customization type:
|
|
|
550
|
|
|
551 @example
|
|
|
552 (list (const t) (set :inline t foo bar))
|
|
|
553 @end example
|
|
|
554
|
|
|
555 @noindent
|
|
|
556 This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
|
|
|
557 and @code{(t foo bar)}.
|
|
|
558
|
|
|
559 When the element-type is a @code{choice}, you use @code{:inline} not
|
|
|
560 in the @code{choice} itself, but in (some of) the alternatives of the
|
|
|
561 @code{choice}. For example, to match a list which must start with a
|
|
|
562 file name, followed either by the symbol @code{t} or two strings, use
|
|
|
563 this customization type:
|
|
|
564
|
|
|
565 @example
|
|
|
566 (list file
|
|
|
567 (choice (const t)
|
|
|
568 (list :inline t string string)))
|
|
|
569 @end example
|
|
|
570
|
|
|
571 @noindent
|
|
|
572 If the user chooses the first alternative in the choice, then the
|
|
|
573 overall list has two elements and the second element is @code{t}. If
|
|
|
574 the user chooses the second alternative, then the overall list has three
|
|
|
575 elements and the second and third must be strings.
|
|
|
576
|
|
|
577 @node Type Keywords
|
|
|
578 @subsection Type Keywords
|
|
|
579
|
|
|
580 You can specify keyword-argument pairs in a customization type after the
|
|
|
581 type name symbol. Here are the keywords you can use, and their
|
|
|
582 meanings:
|
|
|
583
|
|
|
584 @table @code
|
|
|
585 @item :value @var{default}
|
|
|
586 This is used for a type that appears as an alternative inside of
|
|
|
587 @code{choice}; it specifies the default value to use, at first, if and
|
|
|
588 when the user selects this alternative with the menu in the
|
|
|
589 customization buffer.
|
|
|
590
|
|
|
591 Of course, if the actual value of the option fits this alternative, it
|
|
|
592 will appear showing the actual value, not @var{default}.
|
|
|
593
|
|
|
594 If @code{nil} is not a valid value for the alternative, then it is
|
|
|
595 essential to specify a valid default with @code{:value}.
|
|
|
596
|
|
|
597 @item :format @var{format-string}
|
|
|
598 This string will be inserted in the buffer to represent the value
|
|
|
599 corresponding to the type. The following @samp{%} escapes are available
|
|
|
600 for use in @var{format-string}:
|
|
|
601
|
|
|
602 @table @samp
|
|
|
603 @item %[@var{button}%]
|
|
|
604 Display the text @var{button} marked as a button. The @code{:action}
|
|
|
605 attribute specifies what the button will do if the user invokes it;
|
|
|
606 its value is a function which takes two arguments---the widget which
|
|
|
607 the button appears in, and the event.
|
|
|
608
|
|
|
609 There is no way to specify two different buttons with different
|
|
|
610 actions.
|
|
|
611
|
|
|
612 @item %@{@var{sample}%@}
|
|
|
613 Show @var{sample} in a special face specified by @code{:sample-face}.
|
|
|
614
|
|
|
615 @item %v
|
|
|
616 Substitute the item's value. How the value is represented depends on
|
|
|
617 the kind of item, and (for variables) on the customization type.
|
|
|
618
|
|
|
619 @item %d
|
|
|
620 Substitute the item's documentation string.
|
|
|
621
|
|
|
622 @item %h
|
|
|
623 Like @samp{%d}, but if the documentation string is more than one line,
|
|
|
624 add an active field to control whether to show all of it or just the
|
|
|
625 first line.
|
|
|
626
|
|
|
627 @item %t
|
|
|
628 Substitute the tag here. You specify the tag with the @code{:tag}
|
|
|
629 keyword.
|
|
|
630
|
|
|
631 @item %%
|
|
444
|
632 Display a literal @samp{%}.
|
|
318
|
633 @end table
|
|
|
634
|
|
|
635 @item :action @var{action}
|
|
|
636 Perform @var{action} if the user clicks on a button.
|
|
|
637
|
|
|
638 @item :button-face @var{face}
|
|
|
639 Use the face @var{face} (a face name or a list of face names) for button
|
|
|
640 text displayed with @samp{%[@dots{}%]}.
|
|
|
641
|
|
|
642 @item :button-prefix @var{prefix}
|
|
|
643 @itemx :button-suffix @var{suffix}
|
|
|
644 These specify the text to display before and after a button.
|
|
|
645 Each can be:
|
|
|
646
|
|
|
647 @table @asis
|
|
|
648 @item @code{nil}
|
|
|
649 No text is inserted.
|
|
|
650
|
|
|
651 @item a string
|
|
|
652 The string is inserted literally.
|
|
|
653
|
|
|
654 @item a symbol
|
|
|
655 The symbol's value is used.
|
|
|
656 @end table
|
|
|
657
|
|
|
658 @item :tag @var{tag}
|
|
|
659 Use @var{tag} (a string) as the tag for the value (or part of the value)
|
|
|
660 that corresponds to this type.
|
|
|
661
|
|
|
662 @item :doc @var{doc}
|
|
|
663 Use @var{doc} as the documentation string for this value (or part of the
|
|
|
664 value) that corresponds to this type. In order for this to work, you
|
|
|
665 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
|
|
|
666 in that value.
|
|
|
667
|
|
|
668 The usual reason to specify a documentation string for a type is to
|
|
|
669 provide more information about the meanings of alternatives inside a
|
|
|
670 @code{:choice} type or the parts of some other composite type.
|
|
|
671
|
|
|
672 @item :help-echo @var{motion-doc}
|
|
|
673 When you move to this item with @code{widget-forward} or
|
|
|
674 @code{widget-backward}, it will display the string @var{motion-doc}
|
|
|
675 in the echo area.
|
|
|
676
|
|
|
677 @item :match @var{function}
|
|
|
678 Specify how to decide whether a value matches the type. The
|
|
|
679 corresponding value, @var{function}, should be a function that accepts
|
|
|
680 two arguments, a widget and a value; it should return non-@code{nil} if
|
|
|
681 the value is acceptable.
|
|
|
682
|
|
|
683 @ignore
|
|
|
684 @item :indent @var{columns}
|
|
|
685 Indent this item by @var{columns} columns. The indentation is used for
|
|
|
686 @samp{%n}, and automatically for group names, for checklists and radio
|
|
|
687 buttons, and for editable lists. It affects the whole of the
|
|
|
688 item except for the first line.
|
|
|
689
|
|
|
690 @item :offset @var{columns}
|
|
|
691 An integer indicating how many extra spaces to indent the subitems of
|
|
|
692 this item. By default, subitems are indented the same as their parent.
|
|
|
693
|
|
|
694 @item :extra-offset
|
|
|
695 An integer indicating how many extra spaces to add to this item's
|
|
|
696 indentation, compared to its parent.
|
|
|
697
|
|
|
698 @item :notify
|
|
|
699 A function called each time the item or a subitem is changed. The
|
|
|
700 function is called with two or three arguments. The first argument is
|
|
|
701 the item itself, the second argument is the item that was changed, and
|
|
|
702 the third argument is the event leading to the change, if any.
|
|
|
703
|
|
|
704 @item :menu-tag
|
|
|
705 Tag used in the menu when the widget is used as an option in a
|
|
|
706 @code{menu-choice} widget.
|
|
|
707
|
|
|
708 @item :menu-tag-get
|
|
|
709 Function used for finding the tag when the widget is used as an option
|
|
|
710 in a @code{menu-choice} widget. By default, the tag used will be either the
|
|
|
711 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
|
|
|
712 representation of the @code{:value} property if not.
|
|
|
713
|
|
|
714 @item :validate
|
|
444
|
715 A function which takes a widget as an argument, and returns @code{nil} if the
|
|
318
|
716 widgets current value is valid for the widget. Otherwise, it should
|
|
|
717 return the widget containing the invalid data, and set that widgets
|
|
|
718 @code{:error} property to a string explaining the error.
|
|
|
719
|
|
|
720 You can use the function @code{widget-children-validate} for this job;
|
|
|
721 it tests that all children of @var{widget} are valid.
|
|
|
722
|
|
|
723 @item :tab-order
|
|
|
724 Specify the order in which widgets are traversed with
|
|
|
725 @code{widget-forward} or @code{widget-backward}. This is only partially
|
|
|
726 implemented.
|
|
|
727
|
|
|
728 @enumerate a
|
|
|
729 @item
|
|
|
730 Widgets with tabbing order @code{-1} are ignored.
|
|
|
731
|
|
444
|
732 @item
|
|
318
|
733 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
|
|
|
734 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
|
|
|
735 whichever comes first.
|
|
|
736
|
|
|
737 @item
|
|
|
738 When on a widget with no tabbing order specified, go to the next widget
|
|
|
739 in the buffer with a positive tabbing order, or @code{nil}
|
|
|
740 @end enumerate
|
|
|
741
|
|
|
742 @item :parent
|
|
|
743 The parent of a nested widget (e.g. a @code{menu-choice} item or an
|
|
904
|
744 element of an @code{editable-list} widget).
|
|
318
|
745
|
|
|
746 @item :sibling-args
|
|
|
747 This keyword is only used for members of a @code{radio-button-choice} or
|
|
|
748 @code{checklist}. The value should be a list of extra keyword
|
|
|
749 arguments, which will be used when creating the @code{radio-button} or
|
|
|
750 @code{checkbox} associated with this item.
|
|
|
751 @end ignore
|
|
|
752 @end table
|
|
775
|
753
|
|
|
754
|
|
|
755 @node Enabling Behavior, , Customization Types, Customization
|
|
|
756 @subsection Enabling Behavior
|
|
|
757 @cindex behavior
|
|
|
758
|
|
|
759 @c #### Does this belong here?
|
|
|
760
|
|
|
761 Some functionality requires a fair amount of effort to enable globally
|
|
|
762 in a session. For example, someone who discovers filladapt and really
|
|
|
763 likes it must toggle it separately in each buffer. On the other hand,
|
|
|
764 after trying it for a while she might like to disable it everywhere,
|
|
|
765 having decided it doesn't work very well for her. Such a functionality
|
|
|
766 is called a @dfn{behavior}.
|
|
|
767
|
|
|
768 @code{define-behavior} allows the programmer to register functions to
|
|
|
769 enable or disable a package globally in a session. The user sees a
|
|
|
770 consistent interface through the @code{enable-behavior} and
|
|
|
771 @code{disable-behavior} functions. These functions were introduced in
|
|
|
772 XEmacs 21.5.6.
|
|
|
773
|
|
|
774 @defvar behavior-hash-table
|
|
|
775
|
|
|
776 Internal table of registered behaviors.
|
|
|
777 @end defvar
|
|
|
778
|
|
|
779 @defvar behavior-history
|
|
|
780
|
|
|
781 History of entered behaviors.
|
|
|
782 @end defvar
|
|
|
783
|
|
|
784 @defun define-behavior name doc-string [cl-keys ...]
|
|
|
785
|
|
|
786 Define a behavior named @var{name}.
|
|
|
787
|
|
|
788 @var{doc-string} must be specified. It is a description of what the
|
|
|
789 behavior does when it's enabled and how to further control it (typically
|
|
|
790 through custom variables). Accepted keywords are
|
|
|
791
|
|
|
792 @table @code
|
|
|
793 @item :title
|
|
|
794 A "pretty" version of the name, for use in menus. If omitted
|
|
|
795 a prettified name will be generated.
|
|
|
796
|
|
|
797 @item :require
|
|
|
798 A single symbol or a list of such symbols, which need to be
|
|
|
799 present at enable time, or will be loaded using @code{require}.
|
|
|
800
|
|
|
801 @item :enable
|
|
|
802 A function of no variables, which turns the behavior on.
|
|
|
803
|
|
|
804 @item :disable
|
|
|
805 A function of no variables, which turns the behavior off.
|
|
|
806 @end table
|
|
|
807
|
|
|
808 Behaviors are assumed to be global, and to take effect immediately; if
|
|
|
809 the underlying package is per-buffer, the enabler may have to scan all
|
|
|
810 existing buffers and frob them. When a behavior is disabled, it should
|
|
|
811 completely go away @strong{everywhere}, as if it were never invoked at
|
|
|
812 all.
|
|
|
813
|
|
|
814 The @code{:disable} keyword can be missing. This is bad practice. In
|
|
|
815 such a case, attempting to disable the behavior will signal an error
|
|
|
816 unless you use the @code{force} option.
|
|
|
817 @end defun
|
|
|
818
|
|
|
819 @defun read-behavior prompt [require-match [initial-contents [history [default]]]]
|
|
|
820
|
|
|
821 Return a behavior symbol from the minibuffer, prompting with string
|
|
|
822 @var{prompt}.
|
|
|
823
|
|
|
824 The optional arguments @var{require-match}, @var{initial-contents},
|
|
|
825 @var{history}, and @var{default} are passed to @code{completing-read},
|
|
|
826 and have semantics derived from that function. @ref{Minibuffer
|
|
|
827 Completion}. The default value of @var{history} is
|
|
|
828 @code{behavior-history}.
|
|
|
829 @end defun
|
|
|
830
|
|
|
831 @defun behavior-enabled-p name
|
|
|
832
|
|
|
833 Return non-nil if the behavior registered under @var{name} is enabled.
|
|
|
834
|
|
|
835 Unimplemented in 21.5.6.
|
|
|
836 @end defun
|
|
|
837
|
|
|
838 @defun enable-behavior behavior [force]
|
|
|
839 Enable the behavior registered under the symbol @var{behavior}.
|
|
|
840
|
|
|
841 The optional argument @var{force} is unimplemented in 21.5.6.
|
|
|
842
|
|
|
843 Called interactively, prompt the user for @var{behavior}, and take
|
|
|
844 @var{force} from the prefix argument.
|
|
|
845 @end defun
|
|
|
846
|
|
|
847 @defun disable-behavior (behavior &optional force)
|
|
|
848 Disable the behavior registered under the symbol @var{behavior}.
|
|
|
849
|
|
|
850 The optional argument @var{force} is unimplemented in 21.5.6.
|
|
|
851
|
|
|
852 Called interactively, prompt the user for @var{behavior}, and take
|
|
|
853 @var{force} from the prefix argument.
|
|
|
854 @end defun
|
|
|
855
|
|
1833
|
856 @node Defining New Types
|
|
|
857 @subsection Defining New Types
|
|
|
858
|
|
|
859 In the previous sections we have described how to construct elaborate
|
|
|
860 type specifications for @code{defcustom}. In some cases you may want to
|
|
|
861 give such a type specification a name. The obvious case is when you are
|
|
|
862 using the same type for many user options, rather than repeat the
|
|
|
863 specification for each option, you can give the type specification a
|
|
|
864 name once, and use that name each @code{defcustom}. The other case is
|
|
|
865 when a user option accept a recursive datastructure. To make it
|
|
|
866 possible for a datatype to refer to itself, it needs to have a name.
|
|
|
867
|
|
|
868 Since custom types are implemented as widgets, the way to define a new
|
|
|
869 customize type is to define a new widget. We are not going to describe
|
|
|
870 the widget interface here in details, see @ref{Top, , Introduction,
|
|
|
871 widget, The Emacs Widget Library}, for that. Instead we are going to
|
|
|
872 demonstrate the minimal functionality needed for defining new customize
|
|
|
873 types by a simple example.
|
|
|
874
|
|
|
875 @example
|
|
|
876 (define-widget 'binary-tree-of-string 'lazy
|
|
|
877 "A binary tree made of cons-cells and strings."
|
|
|
878 :offset 4
|
|
|
879 :tag "Node"
|
|
|
880 :type '(choice (string :tag "Leaf" :value "")
|
|
|
881 (cons :tag "Interior"
|
|
|
882 :value ("" . "")
|
|
|
883 binary-tree-of-string
|
|
|
884 binary-tree-of-string)))
|
|
|
885
|
|
|
886 (defcustom foo-bar ""
|
|
|
887 "Sample variable holding a binary tree of strings."
|
|
|
888 :type 'binary-tree-of-string)
|
|
|
889 @end example
|
|
|
890
|
|
|
891 The function to define a new widget is name @code{define-widget}. The
|
|
|
892 first argument is the symbol we want to make a new widget type. The
|
|
|
893 second argument is a symbol representing an existing widget, the new
|
|
|
894 widget is going to be defined in terms of difference from the existing
|
|
|
895 widget. For the purpose of defining new customization types, the
|
|
|
896 @code{lazy} widget is perfect, because it accept a @code{:type} keyword
|
|
|
897 argument with the same syntax as the keyword argument to
|
|
|
898 @code{defcustom} with the same name. The third argument is a
|
|
|
899 documentation string for the new widget. You will be able to see that
|
|
|
900 string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string
|
|
|
901 @key{ret}} command.
|
|
|
902
|
|
|
903 After these mandatory arguments follows the keyword arguments. The most
|
|
|
904 important is @code{:type}, which describes the datatype we want to match
|
|
|
905 with this widget. Here a @code{binary-tree-of-string} is described as
|
|
|
906 being either a string, or a cons-cell whose car and cdr are themselves
|
|
|
907 both @code{binary-tree-of-string}. Note the reference to the widget
|
|
|
908 type we are currently in the process of defining. The @code{:tag}
|
|
|
909 attribute is a string to name the widget in the user interface, and the
|
|
|
910 @code{:offset} argument are there to ensure that child nodes are
|
|
|
911 indented four spaces relatively to the parent node, making the tree
|
|
|
912 structure apparent in the customization buffer.
|
|
|
913
|
|
|
914 The @code{defcustom} shows how the new widget can be used as an ordinary
|
|
|
915 customization type.
|
