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