|
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::
|
|
|
328 @end menu
|
|
|
329
|
|
|
330 @node Simple Types
|
|
|
331 @subsection Simple Types
|
|
|
332
|
|
|
333 This section describes all the simple customization types.
|
|
|
334
|
|
|
335 @table @code
|
|
|
336 @item sexp
|
|
|
337 The value may be any Lisp object that can be printed and read back. You
|
|
|
338 can use @code{sexp} as a fall-back for any option, if you don't want to
|
|
|
339 take the time to work out a more specific type to use.
|
|
|
340
|
|
|
341 @item integer
|
|
|
342 The value must be an integer, and is represented textually
|
|
|
343 in the customization buffer.
|
|
|
344
|
|
|
345 @item number
|
|
|
346 The value must be a number, and is represented textually in the
|
|
|
347 customization buffer.
|
|
|
348
|
|
|
349 @item string
|
|
|
350 The value must be a string, and the customization buffer shows just the
|
|
|
351 contents, with no delimiting @samp{"} characters and no quoting with
|
|
|
352 @samp{\}.
|
|
|
353
|
|
|
354 @item regexp
|
|
|
355 Like @code{string} except that the string must be a valid regular
|
|
|
356 expression.
|
|
|
357
|
|
|
358 @item character
|
|
|
359 The value must be a character code. A character code is actually an
|
|
|
360 integer, but this type shows the value by inserting the character in the
|
|
|
361 buffer, rather than by showing the number.
|
|
|
362
|
|
|
363 @item file
|
|
|
364 The value must be a file name, and you can do completion with
|
|
|
365 @kbd{M-@key{TAB}}.
|
|
|
366
|
|
|
367 @item (file :must-match t)
|
|
|
368 The value must be a file name for an existing file, and you can do
|
|
|
369 completion with @kbd{M-@key{TAB}}.
|
|
|
370
|
|
|
371 @item directory
|
|
|
372 The value must be a directory name, and you can do completion with
|
|
|
373 @kbd{M-@key{TAB}}.
|
|
|
374
|
|
|
375 @item symbol
|
|
|
376 The value must be a symbol. It appears in the customization buffer as
|
|
|
377 the name of the symbol.
|
|
|
378
|
|
|
379 @item function
|
|
|
380 The value must be either a lambda expression or a function name. When
|
|
|
381 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
|
|
|
382
|
|
|
383 @item variable
|
|
|
384 The value must be a variable name, and you can do completion with
|
|
|
385 @kbd{M-@key{TAB}}.
|
|
|
386
|
|
|
387 @item face
|
|
|
388 The value must be a symbol which is a face name.
|
|
|
389
|
|
|
390 @item boolean
|
|
|
391 The value is boolean---either @code{nil} or @code{t}. Note that by
|
|
|
392 using @code{choice} and @code{const} together (see the next section),
|
|
|
393 you can specify that the value must be @code{nil} or @code{t}, but also
|
|
|
394 specify the text to describe each value in a way that fits the specific
|
|
|
395 meaning of the alternative.
|
|
|
396 @end table
|
|
|
397
|
|
|
398 @node Composite Types
|
|
|
399 @subsection Composite Types
|
|
|
400
|
|
|
401 When none of the simple types is appropriate, you can use composite
|
|
|
402 types, which build new types from other types. Here are several ways of
|
|
|
403 doing that:
|
|
|
404
|
|
|
405 @table @code
|
|
|
406 @item (restricted-sexp :match-alternatives @var{criteria})
|
|
|
407 The value may be any Lisp object that satisfies one of @var{criteria}.
|
|
|
408 @var{criteria} should be a list, and each elements should be
|
|
|
409 one of these possibilities:
|
|
|
410
|
|
|
411 @itemize @bullet
|
|
|
412 @item
|
|
|
413 A predicate---that is, a function of one argument that returns non-@code{nil}
|
|
|
414 if the argument fits a certain type. This means that objects of that type
|
|
|
415 are acceptable.
|
|
|
416
|
|
|
417 @item
|
|
|
418 A quoted constant---that is, @code{'@var{object}}. This means that
|
|
|
419 @var{object} itself is an acceptable value.
|
|
|
420 @end itemize
|
|
|
421
|
|
|
422 For example,
|
|
|
423
|
|
|
424 @example
|
|
|
425 (restricted-sexp :match-alternatives (integerp 't 'nil))
|
|
|
426 @end example
|
|
|
427
|
|
|
428 @noindent
|
|
|
429 allows integers, @code{t} and @code{nil} as legitimate values.
|
|
|
430
|
|
|
431 The customization buffer shows all legitimate values using their read
|
|
|
432 syntax, and the user edits them textually.
|
|
|
433
|
|
|
434 @item (cons @var{car-type} @var{cdr-type})
|
|
|
435 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
|
|
|
436 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
|
|
|
437 symbol)} is a customization type which matches values such as
|
|
|
438 @code{("foo" . foo)}.
|
|
|
439
|
|
|
440 In the customization buffer, the @sc{car} and the @sc{cdr} are
|
|
|
441 displayed and edited separately, each according to the type
|
|
|
442 that you specify for it.
|
|
|
443
|
|
|
444 @item (list @var{element-types}@dots{})
|
|
|
445 The value must be a list with exactly as many elements as the
|
|
|
446 @var{element-types} you have specified; and each element must fit the
|
|
|
447 corresponding @var{element-type}.
|
|
|
448
|
|
|
449 For example, @code{(list integer string function)} describes a list of
|
|
|
450 three elements; the first element must be an integer, the second a
|
|
|
451 string, and the third a function.
|
|
|
452
|
|
|
453 In the customization buffer, the each element is displayed and edited
|
|
|
454 separately, according to the type specified for it.
|
|
|
455
|
|
|
456 @item (vector @var{element-types}@dots{})
|
|
|
457 Like @code{list} except that the value must be a vector instead of a
|
|
|
458 list. The elements work the same as in @code{list}.
|
|
|
459
|
|
|
460 @item (choice @var{alternative-types}...)
|
|
|
461 The value must fit at least one of @var{alternative-types}.
|
|
|
462 For example, @code{(choice integer string)} allows either an
|
|
|
463 integer or a string.
|
|
|
464
|
|
|
465 In the customization buffer, the user selects one of the alternatives
|
|
|
466 using a menu, and can then edit the value in the usual way for that
|
|
|
467 alternative.
|
|
|
468
|
|
|
469 Normally the strings in this menu are determined automatically from the
|
|
|
470 choices; however, you can specify different strings for the menu by
|
|
|
471 including the @code{:tag} keyword in the alternatives. For example, if
|
|
|
472 an integer stands for a number of spaces, while a string is text to use
|
|
|
473 verbatim, you might write the customization type this way,
|
|
|
474
|
|
|
475 @smallexample
|
|
|
476 (choice (integer :tag "Number of spaces")
|
|
|
477 (string :tag "Literal text"))
|
|
|
478 @end smallexample
|
|
|
479
|
|
|
480 @noindent
|
|
|
481 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
|
|
|
482
|
|
|
483 In any alternative for which @code{nil} is not a valid value, other than
|
|
|
484 a @code{const}, you should specify a valid default for that alternative
|
|
|
485 using the @code{:value} keyword. @xref{Type Keywords}.
|
|
|
486
|
|
|
487 @item (const @var{value})
|
|
|
488 The value must be @var{value}---nothing else is allowed.
|
|
|
489
|
|
|
490 The main use of @code{const} is inside of @code{choice}. For example,
|
|
|
491 @code{(choice integer (const nil))} allows either an integer or
|
|
|
492 @code{nil}.
|
|
|
493
|
|
|
494 @code{:tag} is often used with @code{const}, inside of @code{choice}.
|
|
|
495 For example,
|
|
|
496
|
|
|
497 @smallexample
|
|
|
498 (choice (const :tag "Yes" t)
|
|
|
499 (const :tag "No" nil)
|
|
|
500 (const :tag "Ask" foo))
|
|
|
501 @end smallexample
|
|
|
502
|
|
|
503 @item (function-item @var{function})
|
|
|
504 Like @code{const}, but used for values which are functions. This
|
|
|
505 displays the documentation string as well as the function name.
|
|
|
506 The documentation string is either the one you specify with
|
|
|
507 @code{:doc}, or @var{function}'s own documentation string.
|
|
|
508
|
|
|
509 @item (variable-item @var{variable})
|
|
|
510 Like @code{const}, but used for values which are variable names. This
|
|
|
511 displays the documentation string as well as the variable name. The
|
|
|
512 documentation string is either the one you specify with @code{:doc}, or
|
|
|
513 @var{variable}'s own documentation string.
|
|
|
514
|
|
|
515 @item (set @var{elements}@dots{})
|
|
|
516 The value must be a list and each element of the list must be one of the
|
|
|
517 @var{elements} specified. This appears in the customization buffer as a
|
|
|
518 checklist.
|
|
|
519
|
|
|
520 @item (repeat @var{element-type})
|
|
|
521 The value must be a list and each element of the list must fit the type
|
|
|
522 @var{element-type}. This appears in the customization buffer as a
|
|
|
523 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
|
|
|
524 more elements or removing elements.
|
|
|
525 @end table
|
|
|
526
|
|
|
527 @node Splicing into Lists
|
|
|
528 @subsection Splicing into Lists
|
|
|
529
|
|
|
530 The @code{:inline} feature lets you splice a variable number of
|
|
|
531 elements into the middle of a list or vector. You use it in a
|
|
|
532 @code{set}, @code{choice} or @code{repeat} type which appears among the
|
|
|
533 element-types of a @code{list} or @code{vector}.
|
|
|
534
|
|
|
535 Normally, each of the element-types in a @code{list} or @code{vector}
|
|
|
536 describes one and only one element of the list or vector. Thus, if an
|
|
|
537 element-type is a @code{repeat}, that specifies a list of unspecified
|
|
|
538 length which appears as one element.
|
|
|
539
|
|
|
540 But when the element-type uses @code{:inline}, the value it matches is
|
|
|
541 merged directly into the containing sequence. For example, if it
|
|
|
542 matches a list with three elements, those become three elements of the
|
|
|
543 overall sequence. This is analogous to using @samp{,@@} in the backquote
|
|
|
544 construct.
|
|
|
545
|
|
|
546 For example, to specify a list whose first element must be @code{t}
|
|
|
547 and whose remaining arguments should be zero or more of @code{foo} and
|
|
|
548 @code{bar}, use this customization type:
|
|
|
549
|
|
|
550 @example
|
|
|
551 (list (const t) (set :inline t foo bar))
|
|
|
552 @end example
|
|
|
553
|
|
|
554 @noindent
|
|
|
555 This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
|
|
|
556 and @code{(t foo bar)}.
|
|
|
557
|
|
|
558 When the element-type is a @code{choice}, you use @code{:inline} not
|
|
|
559 in the @code{choice} itself, but in (some of) the alternatives of the
|
|
|
560 @code{choice}. For example, to match a list which must start with a
|
|
|
561 file name, followed either by the symbol @code{t} or two strings, use
|
|
|
562 this customization type:
|
|
|
563
|
|
|
564 @example
|
|
|
565 (list file
|
|
|
566 (choice (const t)
|
|
|
567 (list :inline t string string)))
|
|
|
568 @end example
|
|
|
569
|
|
|
570 @noindent
|
|
|
571 If the user chooses the first alternative in the choice, then the
|
|
|
572 overall list has two elements and the second element is @code{t}. If
|
|
|
573 the user chooses the second alternative, then the overall list has three
|
|
|
574 elements and the second and third must be strings.
|
|
|
575
|
|
|
576 @node Type Keywords
|
|
|
577 @subsection Type Keywords
|
|
|
578
|
|
|
579 You can specify keyword-argument pairs in a customization type after the
|
|
|
580 type name symbol. Here are the keywords you can use, and their
|
|
|
581 meanings:
|
|
|
582
|
|
|
583 @table @code
|
|
|
584 @item :value @var{default}
|
|
|
585 This is used for a type that appears as an alternative inside of
|
|
|
586 @code{choice}; it specifies the default value to use, at first, if and
|
|
|
587 when the user selects this alternative with the menu in the
|
|
|
588 customization buffer.
|
|
|
589
|
|
|
590 Of course, if the actual value of the option fits this alternative, it
|
|
|
591 will appear showing the actual value, not @var{default}.
|
|
|
592
|
|
|
593 If @code{nil} is not a valid value for the alternative, then it is
|
|
|
594 essential to specify a valid default with @code{:value}.
|
|
|
595
|
|
|
596 @item :format @var{format-string}
|
|
|
597 This string will be inserted in the buffer to represent the value
|
|
|
598 corresponding to the type. The following @samp{%} escapes are available
|
|
|
599 for use in @var{format-string}:
|
|
|
600
|
|
|
601 @table @samp
|
|
|
602 @item %[@var{button}%]
|
|
|
603 Display the text @var{button} marked as a button. The @code{:action}
|
|
|
604 attribute specifies what the button will do if the user invokes it;
|
|
|
605 its value is a function which takes two arguments---the widget which
|
|
|
606 the button appears in, and the event.
|
|
|
607
|
|
|
608 There is no way to specify two different buttons with different
|
|
|
609 actions.
|
|
|
610
|
|
|
611 @item %@{@var{sample}%@}
|
|
|
612 Show @var{sample} in a special face specified by @code{:sample-face}.
|
|
|
613
|
|
|
614 @item %v
|
|
|
615 Substitute the item's value. How the value is represented depends on
|
|
|
616 the kind of item, and (for variables) on the customization type.
|
|
|
617
|
|
|
618 @item %d
|
|
|
619 Substitute the item's documentation string.
|
|
|
620
|
|
|
621 @item %h
|
|
|
622 Like @samp{%d}, but if the documentation string is more than one line,
|
|
|
623 add an active field to control whether to show all of it or just the
|
|
|
624 first line.
|
|
|
625
|
|
|
626 @item %t
|
|
|
627 Substitute the tag here. You specify the tag with the @code{:tag}
|
|
|
628 keyword.
|
|
|
629
|
|
|
630 @item %%
|
|
444
|
631 Display a literal @samp{%}.
|
|
318
|
632 @end table
|
|
|
633
|
|
|
634 @item :action @var{action}
|
|
|
635 Perform @var{action} if the user clicks on a button.
|
|
|
636
|
|
|
637 @item :button-face @var{face}
|
|
|
638 Use the face @var{face} (a face name or a list of face names) for button
|
|
|
639 text displayed with @samp{%[@dots{}%]}.
|
|
|
640
|
|
|
641 @item :button-prefix @var{prefix}
|
|
|
642 @itemx :button-suffix @var{suffix}
|
|
|
643 These specify the text to display before and after a button.
|
|
|
644 Each can be:
|
|
|
645
|
|
|
646 @table @asis
|
|
|
647 @item @code{nil}
|
|
|
648 No text is inserted.
|
|
|
649
|
|
|
650 @item a string
|
|
|
651 The string is inserted literally.
|
|
|
652
|
|
|
653 @item a symbol
|
|
|
654 The symbol's value is used.
|
|
|
655 @end table
|
|
|
656
|
|
|
657 @item :tag @var{tag}
|
|
|
658 Use @var{tag} (a string) as the tag for the value (or part of the value)
|
|
|
659 that corresponds to this type.
|
|
|
660
|
|
|
661 @item :doc @var{doc}
|
|
|
662 Use @var{doc} as the documentation string for this value (or part of the
|
|
|
663 value) that corresponds to this type. In order for this to work, you
|
|
|
664 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
|
|
|
665 in that value.
|
|
|
666
|
|
|
667 The usual reason to specify a documentation string for a type is to
|
|
|
668 provide more information about the meanings of alternatives inside a
|
|
|
669 @code{:choice} type or the parts of some other composite type.
|
|
|
670
|
|
|
671 @item :help-echo @var{motion-doc}
|
|
|
672 When you move to this item with @code{widget-forward} or
|
|
|
673 @code{widget-backward}, it will display the string @var{motion-doc}
|
|
|
674 in the echo area.
|
|
|
675
|
|
|
676 @item :match @var{function}
|
|
|
677 Specify how to decide whether a value matches the type. The
|
|
|
678 corresponding value, @var{function}, should be a function that accepts
|
|
|
679 two arguments, a widget and a value; it should return non-@code{nil} if
|
|
|
680 the value is acceptable.
|
|
|
681
|
|
|
682 @ignore
|
|
|
683 @item :indent @var{columns}
|
|
|
684 Indent this item by @var{columns} columns. The indentation is used for
|
|
|
685 @samp{%n}, and automatically for group names, for checklists and radio
|
|
|
686 buttons, and for editable lists. It affects the whole of the
|
|
|
687 item except for the first line.
|
|
|
688
|
|
|
689 @item :offset @var{columns}
|
|
|
690 An integer indicating how many extra spaces to indent the subitems of
|
|
|
691 this item. By default, subitems are indented the same as their parent.
|
|
|
692
|
|
|
693 @item :extra-offset
|
|
|
694 An integer indicating how many extra spaces to add to this item's
|
|
|
695 indentation, compared to its parent.
|
|
|
696
|
|
|
697 @item :notify
|
|
|
698 A function called each time the item or a subitem is changed. The
|
|
|
699 function is called with two or three arguments. The first argument is
|
|
|
700 the item itself, the second argument is the item that was changed, and
|
|
|
701 the third argument is the event leading to the change, if any.
|
|
|
702
|
|
|
703 @item :menu-tag
|
|
|
704 Tag used in the menu when the widget is used as an option in a
|
|
|
705 @code{menu-choice} widget.
|
|
|
706
|
|
|
707 @item :menu-tag-get
|
|
|
708 Function used for finding the tag when the widget is used as an option
|
|
|
709 in a @code{menu-choice} widget. By default, the tag used will be either the
|
|
|
710 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
|
|
|
711 representation of the @code{:value} property if not.
|
|
|
712
|
|
|
713 @item :validate
|
|
444
|
714 A function which takes a widget as an argument, and returns @code{nil} if the
|
|
318
|
715 widgets current value is valid for the widget. Otherwise, it should
|
|
|
716 return the widget containing the invalid data, and set that widgets
|
|
|
717 @code{:error} property to a string explaining the error.
|
|
|
718
|
|
|
719 You can use the function @code{widget-children-validate} for this job;
|
|
|
720 it tests that all children of @var{widget} are valid.
|
|
|
721
|
|
|
722 @item :tab-order
|
|
|
723 Specify the order in which widgets are traversed with
|
|
|
724 @code{widget-forward} or @code{widget-backward}. This is only partially
|
|
|
725 implemented.
|
|
|
726
|
|
|
727 @enumerate a
|
|
|
728 @item
|
|
|
729 Widgets with tabbing order @code{-1} are ignored.
|
|
|
730
|
|
444
|
731 @item
|
|
318
|
732 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
|
|
|
733 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
|
|
|
734 whichever comes first.
|
|
|
735
|
|
|
736 @item
|
|
|
737 When on a widget with no tabbing order specified, go to the next widget
|
|
|
738 in the buffer with a positive tabbing order, or @code{nil}
|
|
|
739 @end enumerate
|
|
|
740
|
|
|
741 @item :parent
|
|
|
742 The parent of a nested widget (e.g. a @code{menu-choice} item or an
|
|
|
743 element of a @code{editable-list} widget).
|
|
|
744
|
|
|
745 @item :sibling-args
|
|
|
746 This keyword is only used for members of a @code{radio-button-choice} or
|
|
|
747 @code{checklist}. The value should be a list of extra keyword
|
|
|
748 arguments, which will be used when creating the @code{radio-button} or
|
|
|
749 @code{checkbox} associated with this item.
|
|
|
750 @end ignore
|
|
|
751 @end table
|
|
775
|
752
|
|
|
753
|
|
|
754 @node Enabling Behavior, , Customization Types, Customization
|
|
|
755 @subsection Enabling Behavior
|
|
|
756 @cindex behavior
|
|
|
757
|
|
|
758 @c #### Does this belong here?
|
|
|
759
|
|
|
760 Some functionality requires a fair amount of effort to enable globally
|
|
|
761 in a session. For example, someone who discovers filladapt and really
|
|
|
762 likes it must toggle it separately in each buffer. On the other hand,
|
|
|
763 after trying it for a while she might like to disable it everywhere,
|
|
|
764 having decided it doesn't work very well for her. Such a functionality
|
|
|
765 is called a @dfn{behavior}.
|
|
|
766
|
|
|
767 @code{define-behavior} allows the programmer to register functions to
|
|
|
768 enable or disable a package globally in a session. The user sees a
|
|
|
769 consistent interface through the @code{enable-behavior} and
|
|
|
770 @code{disable-behavior} functions. These functions were introduced in
|
|
|
771 XEmacs 21.5.6.
|
|
|
772
|
|
|
773 @defvar behavior-hash-table
|
|
|
774
|
|
|
775 Internal table of registered behaviors.
|
|
|
776 @end defvar
|
|
|
777
|
|
|
778 @defvar behavior-history
|
|
|
779
|
|
|
780 History of entered behaviors.
|
|
|
781 @end defvar
|
|
|
782
|
|
|
783 @defun define-behavior name doc-string [cl-keys ...]
|
|
|
784
|
|
|
785 Define a behavior named @var{name}.
|
|
|
786
|
|
|
787 @var{doc-string} must be specified. It is a description of what the
|
|
|
788 behavior does when it's enabled and how to further control it (typically
|
|
|
789 through custom variables). Accepted keywords are
|
|
|
790
|
|
|
791 @table @code
|
|
|
792 @item :title
|
|
|
793 A "pretty" version of the name, for use in menus. If omitted
|
|
|
794 a prettified name will be generated.
|
|
|
795
|
|
|
796 @item :require
|
|
|
797 A single symbol or a list of such symbols, which need to be
|
|
|
798 present at enable time, or will be loaded using @code{require}.
|
|
|
799
|
|
|
800 @item :enable
|
|
|
801 A function of no variables, which turns the behavior on.
|
|
|
802
|
|
|
803 @item :disable
|
|
|
804 A function of no variables, which turns the behavior off.
|
|
|
805 @end table
|
|
|
806
|
|
|
807 Behaviors are assumed to be global, and to take effect immediately; if
|
|
|
808 the underlying package is per-buffer, the enabler may have to scan all
|
|
|
809 existing buffers and frob them. When a behavior is disabled, it should
|
|
|
810 completely go away @strong{everywhere}, as if it were never invoked at
|
|
|
811 all.
|
|
|
812
|
|
|
813 The @code{:disable} keyword can be missing. This is bad practice. In
|
|
|
814 such a case, attempting to disable the behavior will signal an error
|
|
|
815 unless you use the @code{force} option.
|
|
|
816 @end defun
|
|
|
817
|
|
|
818 @defun read-behavior prompt [require-match [initial-contents [history [default]]]]
|
|
|
819
|
|
|
820 Return a behavior symbol from the minibuffer, prompting with string
|
|
|
821 @var{prompt}.
|
|
|
822
|
|
|
823 The optional arguments @var{require-match}, @var{initial-contents},
|
|
|
824 @var{history}, and @var{default} are passed to @code{completing-read},
|
|
|
825 and have semantics derived from that function. @ref{Minibuffer
|
|
|
826 Completion}. The default value of @var{history} is
|
|
|
827 @code{behavior-history}.
|
|
|
828 @end defun
|
|
|
829
|
|
|
830 @defun behavior-enabled-p name
|
|
|
831
|
|
|
832 Return non-nil if the behavior registered under @var{name} is enabled.
|
|
|
833
|
|
|
834 Unimplemented in 21.5.6.
|
|
|
835 @end defun
|
|
|
836
|
|
|
837 @defun enable-behavior behavior [force]
|
|
|
838 Enable the behavior registered under the symbol @var{behavior}.
|
|
|
839
|
|
|
840 The optional argument @var{force} is unimplemented in 21.5.6.
|
|
|
841
|
|
|
842 Called interactively, prompt the user for @var{behavior}, and take
|
|
|
843 @var{force} from the prefix argument.
|
|
|
844 @end defun
|
|
|
845
|
|
|
846 @defun disable-behavior (behavior &optional force)
|
|
|
847 Disable the behavior registered under the symbol @var{behavior}.
|
|
|
848
|
|
|
849 The optional argument @var{force} is unimplemented in 21.5.6.
|
|
|
850
|
|
|
851 Called interactively, prompt the user for @var{behavior}, and take
|
|
|
852 @var{force} from the prefix argument.
|
|
|
853 @end defun
|
|
|
854
|
