|
98
|
1 \input texinfo.tex
|
|
|
2
|
|
|
3 @c %**start of header
|
|
355
|
4 @setfilename ../info/custom.info
|
|
98
|
5 @settitle The Customization Library
|
|
|
6 @iftex
|
|
|
7 @afourpaper
|
|
|
8 @headings double
|
|
|
9 @end iftex
|
|
|
10 @c %**end of header
|
|
|
11
|
|
343
|
12 @ifinfo
|
|
|
13 @dircategory XEmacs Editor
|
|
|
14 @direntry
|
|
|
15 * Customizations: (custom). Customization Library.
|
|
|
16 package.
|
|
|
17 @end direntry
|
|
|
18 @end ifinfo
|
|
|
19
|
|
155
|
20 @node Top, Declaring Groups, (dir), (dir)
|
|
98
|
21 @comment node-name, next, previous, up
|
|
|
22 @top The Customization Library
|
|
|
23
|
|
155
|
24 This manual describes how to declare customization groups, variables,
|
|
120
|
25 and faces. It doesn't contain any examples, but please look at the file
|
|
|
26 @file{cus-edit.el} which contains many declarations you can learn from.
|
|
|
27
|
|
98
|
28 @menu
|
|
|
29 * Declaring Groups::
|
|
|
30 * Declaring Variables::
|
|
|
31 * Declaring Faces::
|
|
102
|
32 * Usage for Package Authors::
|
|
155
|
33 * Utilities::
|
|
|
34 * The Init File::
|
|
|
35 * Wishlist::
|
|
98
|
36 @end menu
|
|
|
37
|
|
|
38 All the customization declarations can be changes by keyword arguments.
|
|
|
39 Groups, variables, and faces all share these common keywords:
|
|
|
40
|
|
|
41 @table @code
|
|
|
42 @item :group
|
|
|
43 @var{value} should be a customization group.
|
|
|
44 Add @var{symbol} to that group.
|
|
|
45 @item :link
|
|
|
46 @var{value} should be a widget type.
|
|
161
|
47 Add @var{value} to the external links for this customization option.
|
|
98
|
48 Useful widget types include @code{custom-manual}, @code{info-link}, and
|
|
|
49 @code{url-link}.
|
|
|
50 @item :load
|
|
161
|
51 Add @var{value} to the files that should be loaded before displaying
|
|
|
52 this customization option. The value should be either a string, which
|
|
98
|
53 should be a string which will be loaded with @code{load-library} unless
|
|
|
54 present in @code{load-history}, or a symbol which will be loaded with
|
|
|
55 @code{require}.
|
|
|
56 @item :tag
|
|
|
57 @var{Value} should be a short string used for identifying the option in
|
|
|
58 customization menus and buffers. By default the tag will be
|
|
|
59 automatically created from the options name.
|
|
|
60 @end table
|
|
|
61
|
|
155
|
62 @node Declaring Groups, Declaring Variables, Top, Top
|
|
98
|
63 @comment node-name, next, previous, up
|
|
155
|
64 @section Declaring Groups
|
|
98
|
65
|
|
|
66 Use @code{defgroup} to declare new customization groups.
|
|
|
67
|
|
|
68 @defun defgroup symbol members doc [keyword value]...
|
|
|
69 Declare @var{symbol} as a customization group containing @var{members}.
|
|
|
70 @var{symbol} does not need to be quoted.
|
|
|
71
|
|
|
72 @var{doc} is the group documentation.
|
|
|
73
|
|
|
74 @var{members} should be an alist of the form ((@var{name}
|
|
|
75 @var{widget})...) where @var{name} is a symbol and @var{widget} is a
|
|
|
76 widget for editing that symbol. Useful widgets are
|
|
|
77 @code{custom-variable} for editing variables, @code{custom-face} for
|
|
|
78 editing faces, and @code{custom-group} for editing groups.@refill
|
|
|
79
|
|
|
80 Internally, custom uses the symbol property @code{custom-group} to keep
|
|
|
81 track of the group members, and @code{group-documentation} for the
|
|
|
82 documentation string.
|
|
|
83
|
|
|
84 The following additional @var{keyword}'s are defined:
|
|
|
85
|
|
|
86 @table @code
|
|
|
87 @item :prefix
|
|
|
88 @var{value} should be a string. If the string is a prefix for the name
|
|
|
89 of a member of the group, that prefix will be ignored when creating a
|
|
|
90 tag for that member.
|
|
|
91 @end table
|
|
|
92 @end defun
|
|
|
93
|
|
155
|
94 @node Declaring Variables, Declaring Faces, Declaring Groups, Top
|
|
98
|
95 @comment node-name, next, previous, up
|
|
155
|
96 @section Declaring Variables
|
|
98
|
97
|
|
|
98 Use @code{defcustom} to declare user editable variables.
|
|
|
99
|
|
|
100 @defun defcustom symbol value doc [keyword value]...
|
|
|
101 Declare @var{symbol} as a customizable variable that defaults to @var{value}.
|
|
|
102 Neither @var{symbol} nor @var{value} needs to be quoted.
|
|
|
103 If @var{symbol} is not already bound, initialize it to @var{value}.
|
|
|
104
|
|
|
105 @var{doc} is the variable documentation.
|
|
|
106
|
|
|
107 The following additional @var{keyword}'s are defined:
|
|
|
108
|
|
|
109 @table @code
|
|
155
|
110 @item :type
|
|
98
|
111 @var{value} should be a widget type.
|
|
149
|
112
|
|
98
|
113 @item :options
|
|
|
114 @var{value} should be a list of possible members of the specified type.
|
|
|
115 For hooks, this is a list of function names.
|
|
149
|
116
|
|
|
117 @item :initialize
|
|
|
118 @var{value} should be a function used to initialize the variable. It
|
|
|
119 takes two arguments, the symbol and value given in the @code{defcustom} call.
|
|
|
120 Some predefined functions are:
|
|
|
121
|
|
|
122 @table @code
|
|
|
123 @item custom-initialize-set
|
|
|
124 Use the @code{:set} method to initialize the variable. Do not
|
|
|
125 initialize it if already bound. This is the default @code{:initialize}
|
|
|
126 method.
|
|
|
127
|
|
|
128 @item custom-initialize-default
|
|
|
129 Always use @code{set-default} to initialize the variable, even if a
|
|
|
130 @code{:set} method has been specified.
|
|
|
131
|
|
|
132 @item custom-initialize-reset
|
|
|
133 If the variable is already bound, reset it by calling the @code{:set}
|
|
|
134 method with the value returned by the @code{:get} method.
|
|
|
135
|
|
|
136 @item custom-initialize-changed
|
|
|
137 Like @code{custom-initialize-reset}, but use @code{set-default} to
|
|
|
138 initialize the variable if it is not bound and has not been set
|
|
|
139 already.
|
|
|
140 @end table
|
|
|
141
|
|
|
142 @item :set
|
|
|
143 @var{value} should be a function to set the value of the symbol. It
|
|
|
144 takes two arguments, the symbol to set and the value to give it. The
|
|
|
145 default is @code{set-default}.
|
|
|
146
|
|
|
147 @item :get
|
|
|
148 @var{value} should be a function to extract the value of symbol. The
|
|
|
149 function takes one argument, a symbol, and should return the current
|
|
|
150 value for that symbol. The default is @code{default-value}.
|
|
|
151
|
|
|
152 @item :require
|
|
|
153 @var{value} should be a feature symbol. Each feature will be required
|
|
161
|
154 when the `defcustom' is evaluated, or when Emacs is started if the user
|
|
|
155 has saved this option.
|
|
149
|
156
|
|
98
|
157 @end table
|
|
|
158
|
|
|
159 @xref{Sexp Types,,,widget,The Widget Library}, for information about
|
|
|
160 widgets to use together with the @code{:type} keyword.
|
|
|
161 @end defun
|
|
|
162
|
|
|
163 Internally, custom uses the symbol property @code{custom-type} to keep
|
|
153
|
164 track of the variables type, @code{standard-value} for the program
|
|
98
|
165 specified default value, @code{saved-value} for a value saved by the
|
|
|
166 user, and @code{variable-documentation} for the documentation string.
|
|
|
167
|
|
|
168 Use @code{custom-add-option} to specify that a specific function is
|
|
161
|
169 useful as an member of a hook.
|
|
98
|
170
|
|
|
171 @defun custom-add-option symbol option
|
|
|
172 To the variable @var{symbol} add @var{option}.
|
|
|
173
|
|
|
174 If @var{symbol} is a hook variable, @var{option} should be a hook
|
|
|
175 member. For other types variables, the effect is undefined."
|
|
|
176 @end defun
|
|
|
177
|
|
155
|
178 @node Declaring Faces, Usage for Package Authors, Declaring Variables, Top
|
|
98
|
179 @comment node-name, next, previous, up
|
|
155
|
180 @section Declaring Faces
|
|
98
|
181
|
|
|
182 Faces are declared with @code{defface}.
|
|
|
183
|
|
|
184 @defun defface face spec doc [keyword value]...
|
|
|
185
|
|
|
186 Declare @var{face} as a customizable face that defaults to @var{spec}.
|
|
|
187 @var{face} does not need to be quoted.
|
|
|
188
|
|
|
189 If @var{face} has been set with `custom-set-face', set the face attributes
|
|
|
190 as specified by that function, otherwise set the face attributes
|
|
|
191 according to @var{spec}.
|
|
|
192
|
|
|
193 @var{doc} is the face documentation.
|
|
|
194
|
|
|
195 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
|
|
|
196
|
|
|
197 @var{atts} is a list of face attributes and their values. The possible
|
|
|
198 attributes are defined in the variable `custom-face-attributes'.
|
|
|
199
|
|
|
200 The @var{atts} of the first entry in @var{spec} where the @var{display}
|
|
|
201 matches the frame should take effect in that frame. @var{display} can
|
|
|
202 either be the symbol `t', which will match all frames, or an alist of
|
|
|
203 the form @samp{((@var{req} @var{item}...)...)}@refill
|
|
|
204
|
|
|
205 For the @var{display} to match a FRAME, the @var{req} property of the
|
|
|
206 frame must match one of the @var{item}. The following @var{req} are
|
|
|
207 defined:@refill
|
|
|
208
|
|
|
209 @table @code
|
|
|
210 @item type
|
|
108
|
211 (the value of (window-system))@*
|
|
98
|
212 Should be one of @code{x} or @code{tty}.
|
|
|
213
|
|
|
214 @item class
|
|
108
|
215 (the frame's color support)@*
|
|
98
|
216 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
|
|
|
217
|
|
|
218 @item background
|
|
108
|
219 (what color is used for the background text)@*
|
|
98
|
220 Should be one of @code{light} or @code{dark}.
|
|
|
221 @end table
|
|
|
222
|
|
149
|
223 Internally, custom uses the symbol property @code{face-defface-spec} for
|
|
|
224 the program specified default face properties, @code{saved-face} for
|
|
|
225 properties saved by the user, and @code{face-documentation} for the
|
|
98
|
226 documentation string.@refill
|
|
|
227
|
|
|
228 @end defun
|
|
|
229
|
|
155
|
230 @node Usage for Package Authors, Utilities, Declaring Faces, Top
|
|
102
|
231 @comment node-name, next, previous, up
|
|
155
|
232 @section Usage for Package Authors
|
|
102
|
233
|
|
|
234 The recommended usage for the author of a typical emacs lisp package is
|
|
|
235 to create one group identifying the package, and make all user options
|
|
|
236 and faces members of that group. If the package has more than around 20
|
|
|
237 such options, they should be divided into a number of subgroups, with
|
|
|
238 each subgroup being member of the top level group.
|
|
|
239
|
|
|
240 The top level group for the package should itself be member of one or
|
|
|
241 more of the standard customization groups. There exists a group for
|
|
173
|
242 each @emph{finder} keyword. Press @kbd{C-h p} to see a list of finder
|
|
102
|
243 keywords, and add you group to each of them, using the @code{:group}
|
|
|
244 keyword.
|
|
|
245
|
|
155
|
246 @node Utilities, The Init File, Usage for Package Authors, Top
|
|
98
|
247 @comment node-name, next, previous, up
|
|
|
248 @section Utilities
|
|
|
249
|
|
|
250 These utilities can come in handy when adding customization support.
|
|
|
251
|
|
|
252 @deffn Widget custom-manual
|
|
|
253 Widget type for specifying the info manual entry for a customization
|
|
|
254 option. It takes one argument, an info address.
|
|
|
255 @end deffn
|
|
|
256
|
|
|
257 @defun custom-add-to-group group member widget
|
|
|
258 To existing @var{group} add a new @var{member} of type @var{widget},
|
|
|
259 If there already is an entry for that member, overwrite it.
|
|
|
260 @end defun
|
|
|
261
|
|
|
262 @defun custom-add-link symbol widget
|
|
|
263 To the custom option @var{symbol} add the link @var{widget}.
|
|
|
264 @end defun
|
|
|
265
|
|
|
266 @defun custom-add-load symbol load
|
|
|
267 To the custom option @var{symbol} add the dependency @var{load}.
|
|
|
268 @var{load} should be either a library file name, or a feature name.
|
|
|
269 @end defun
|
|
|
270
|
|
124
|
271 @defun customize-menu-create symbol &optional name
|
|
98
|
272 Create menu for customization group @var{symbol}.
|
|
|
273 If optional @var{name} is given, use that as the name of the menu.
|
|
124
|
274 Otherwise the menu will be named `Customize'.
|
|
98
|
275 The menu is in a format applicable to @code{easy-menu-define}.
|
|
|
276 @end defun
|
|
|
277
|
|
155
|
278 @node The Init File, Wishlist, Utilities, Top
|
|
98
|
279 @comment node-name, next, previous, up
|
|
|
280 @section The Init File
|
|
|
281
|
|
|
282 When you save the customizations, call to @code{custom-set-variables},
|
|
|
283 @code{custom-set-faces} are inserted into the file specified by
|
|
|
284 @code{custom-file}. By default @code{custom-file} is your @file{.emacs}
|
|
116
|
285 file. If you use another file, you must explicitly load it yourself.
|
|
|
286 The two functions will initialize variables and faces as you have
|
|
|
287 specified.
|
|
98
|
288
|
|
155
|
289 @node Wishlist, , The Init File, Top
|
|
98
|
290 @comment node-name, next, previous, up
|
|
|
291 @section Wishlist
|
|
|
292
|
|
|
293 @itemize @bullet
|
|
|
294 @item
|
|
120
|
295 Better support for keyboard operations in the customize buffer.
|
|
98
|
296
|
|
|
297 @item
|
|
155
|
298 Integrate with @file{w3} so you can get customization buffers with much
|
|
98
|
299 better formatting. I'm thinking about adding a <custom>name</custom>
|
|
108
|
300 tag. The latest w3 have some support for this, so come up with a
|
|
|
301 convincing example.
|
|
98
|
302
|
|
|
303 @item
|
|
|
304 Add an `examples' section, with explained examples of custom type
|
|
|
305 definitions.
|
|
|
306
|
|
|
307 @item
|
|
110
|
308 Support selectable color themes. I.e., change many faces by setting one
|
|
|
309 variable.
|
|
|
310
|
|
|
311 @item
|
|
98
|
312 Support undo using lmi's @file{gnus-undo.el}.
|
|
|
313
|
|
167
|
314
|
|
98
|
315 @item
|
|
|
316 Make it possible to append to `choice', `radio', and `set' options.
|
|
|
317
|
|
|
318 @item
|
|
|
319 Ask whether set or modified variables should be saved in
|
|
|
320 @code{kill-buffer-hook}.
|
|
|
321
|
|
|
322 Ditto for @code{kill-emacs-query-functions}.
|
|
|
323
|
|
|
324 @item
|
|
|
325 Command to check if there are any customization options that
|
|
|
326 does not belong to an existing group.
|
|
|
327
|
|
|
328 @item
|
|
|
329 Optionally disable the point-cursor and instead highlight the selected
|
|
|
330 item in XEmacs. This is like the *Completions* buffer in XEmacs.
|
|
|
331 Suggested by Jens Lautenbacher
|
|
|
332 @samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill
|
|
|
333
|
|
120
|
334 @item
|
|
161
|
335 Explain why it is necessary that all choices have different default
|
|
155
|
336 values.
|
|
120
|
337
|
|
124
|
338 @item
|
|
|
339 Make it possible to include a comment/remark/annotation when saving an
|
|
|
340 option.
|
|
|
341
|
|
149
|
342 @item
|
|
|
343 Add some direct support for meta variables, i.e. make it possible to
|
|
|
344 specify that this variable should be reset when that variable is
|
|
|
345 changed.
|
|
|
346
|
|
|
347 @item
|
|
|
348 Add tutorial.
|
|
|
349
|
|
|
350 @item
|
|
|
351 Describe the @code{:type} syntax in this manual.
|
|
|
352
|
|
|
353 @item
|
|
|
354 Find a place is this manual for the following text:
|
|
|
355
|
|
|
356 @strong{Radio vs. Buttons}
|
|
|
357
|
|
|
358 Use a radio if you can't find a good way to describe the item in the
|
|
|
359 choice menu text. I.e. it is better to use a radio if you expect the
|
|
|
360 user would otherwise manually select each item from the choice menu in
|
|
|
361 turn to see what it expands too.
|
|
|
362
|
|
|
363 Avoid radios if some of the items expands to complex structures.
|
|
|
364
|
|
|
365 I mostly use radios when most of the items are of type
|
|
|
366 @code{function-item} or @code{variable-item}.
|
|
|
367
|
|
|
368 @item
|
|
|
369 Update customize buffers when @code{custom-set-variable} or
|
|
|
370 @code{custom-save-customized} is called.
|
|
|
371
|
|
|
372 @item
|
|
|
373 Better handling of saved but uninitialized items.
|
|
|
374
|
|
153
|
375 @item
|
|
|
376 Detect when faces have been changed outside customize.
|
|
|
377
|
|
|
378 @item
|
|
155
|
379 Enable mouse help in Emacs by default.
|
|
153
|
380
|
|
|
381 @item
|
|
|
382 Add an easy way to display the standard settings when an item is modified.
|
|
|
383
|
|
155
|
384 @item
|
|
|
385 See if it is feasible to scan files for customization information
|
|
|
386 instead of loading them,
|
|
|
387
|
|
|
388 @item
|
|
|
389 Add hint message when user push a non-pushable tag.
|
|
|
390
|
|
|
391 Suggest that the user unhide if hidden, and edit the value directly
|
|
|
392 otherwise.
|
|
|
393
|
|
163
|
394 @item
|
|
|
395 Use checkboxes and radio buttons in the state menus.
|
|
|
396
|
|
|
397 @item
|
|
|
398 Add option to hide @samp{[hide]} for short options. Default, on.
|
|
|
399
|
|
|
400 @item
|
|
|
401 Add option to hide @samp{[state]} for options with their standard
|
|
|
402 settings.
|
|
|
403
|
|
|
404 @item
|
|
|
405 There should be a way to specify site defaults for user options.
|
|
|
406
|
|
|
407 @item
|
|
|
408 There should be more buffer styles. The default `nested style, the old
|
|
|
409 `outline' style, a `numeric' style with numbers instead of stars, an
|
|
|
410 `empty' style with just the group name, and `compact' with only one line
|
|
|
411 per item.
|
|
|
412
|
|
167
|
413 @item
|
|
|
414 Newline and tab should be displayed as @samp{^J} and @samp{^I} in the
|
|
|
415 @code{regexp} and @code{file} widgets. I think this can be done in
|
|
|
416 XEmacs by adding a display table to the face.
|
|
|
417
|
|
173
|
418 @item
|
|
|
419 Use glyphs to draw the @code{customize-browse} tree.
|
|
|
420
|
|
|
421 Add echo and balloon help. You should be able to read the documentation
|
|
|
422 simply by moving the mouse pointer above the name.
|
|
|
423
|
|
|
424 Add parent links.
|
|
|
425
|
|
|
426 Add colors.
|
|
|
427
|
|
98
|
428 @end itemize
|
|
|
429
|
|
|
430 @contents
|
|
|
431 @bye
|
