|
98
|
1 \input texinfo.tex
|
|
|
2
|
|
|
3 @c %**start of header
|
|
|
4 @setfilename custom
|
|
|
5 @settitle The Customization Library
|
|
|
6 @iftex
|
|
|
7 @afourpaper
|
|
|
8 @headings double
|
|
|
9 @end iftex
|
|
|
10 @c %**end of header
|
|
|
11
|
|
|
12 @node Top, Introduction, (dir), (dir)
|
|
|
13 @comment node-name, next, previous, up
|
|
|
14 @top The Customization Library
|
|
|
15
|
|
149
|
16 Version: 1.97
|
|
98
|
17
|
|
|
18 @menu
|
|
|
19 * Introduction::
|
|
|
20 * User Commands::
|
|
|
21 * The Customization Buffer::
|
|
|
22 * Declarations::
|
|
|
23 * Utilities::
|
|
|
24 * The Init File::
|
|
|
25 * Wishlist::
|
|
|
26 @end menu
|
|
|
27
|
|
|
28 @node Introduction, User Commands, Top, Top
|
|
|
29 @comment node-name, next, previous, up
|
|
|
30 @section Introduction
|
|
|
31
|
|
|
32 This library allows customization of @dfn{user options}. Currently two
|
|
|
33 types of user options are supported, namely @dfn{variables} and
|
|
|
34 @dfn{faces}. Each user option can have four different values
|
|
|
35 simultaneously:
|
|
|
36 @table @dfn
|
|
|
37 @item factory setting
|
|
|
38 The value specified by the programmer.
|
|
|
39 @item saved value
|
|
|
40 The value saved by the user as the default for this variable. This
|
|
|
41 overwrites the factory setting when starting a new emacs.
|
|
|
42 @item current value
|
|
|
43 The value used by Emacs. This will not be remembered next time you
|
|
|
44 run Emacs.
|
|
|
45 @item widget value
|
|
|
46 The value entered by the user in a customization buffer, but not yet
|
|
|
47 applied.
|
|
|
48 @end table
|
|
|
49
|
|
|
50 Variables also have a @dfn{type}, which specifies what kind of values
|
|
|
51 the variable can hold, and how the value is presented in a customization
|
|
|
52 buffer. By default a variable can hold any valid expression, but the
|
|
|
53 programmer can specify a more limited type when declaring the variable.
|
|
|
54
|
|
|
55 The user options are organized in a number of @dfn{groups}. Each group
|
|
|
56 can contain a number user options, as well as other groups. The groups
|
|
|
57 allows the user to concentrate on a specific part of emacs.
|
|
|
58
|
|
|
59 @node User Commands, The Customization Buffer, Introduction, Top
|
|
|
60 @comment node-name, next, previous, up
|
|
|
61 @section User Commands
|
|
|
62
|
|
|
63 The following commands will create a customization buffer:
|
|
|
64
|
|
|
65 @table @code
|
|
|
66 @item customize
|
|
|
67 Create a customization buffer containing a specific group, by default
|
|
|
68 the @code{emacs} group.
|
|
|
69
|
|
|
70 @item customize-variable
|
|
|
71 Create a customization buffer containing a single variable.
|
|
|
72
|
|
|
73 @item customize-face
|
|
|
74 Create a customization buffer containing a single face.
|
|
|
75
|
|
|
76 @item customize-apropos
|
|
|
77 Create a customization buffer containing all variables, faces, and
|
|
|
78 groups that match a user specified regular expression.
|
|
149
|
79
|
|
|
80 @item customize-saved
|
|
|
81 Create a customization buffer containing all variables and faces that
|
|
|
82 have been saved with customize.
|
|
|
83
|
|
|
84 @item customize-customized
|
|
|
85 Create a customization buffer containing all variables and faces that
|
|
|
86 have been customized but not saved.
|
|
98
|
87 @end table
|
|
|
88
|
|
149
|
89 You can also set variables without creating a customization buffer.
|
|
|
90
|
|
|
91 @deffn Command customize-set-variable var val
|
|
|
92 Set the default for @var{variable} to @var{value}.
|
|
|
93 @var{value} is a Lisp object.
|
|
|
94
|
|
|
95 If @var{variable} has a @code{custom-set} property, that is used for setting
|
|
|
96 @var{variable}, otherwise @code{set-default} is used.
|
|
|
97
|
|
|
98 The @code{customized-value} property of the @var{variable} will be set
|
|
|
99 to a list with a quoted @var{value} as its sole list member.
|
|
|
100
|
|
|
101 If @var{variable} has a @code{variable-interactive} property, that is
|
|
|
102 used as if it were the arg to `interactive' (which see) to interactively
|
|
|
103 read the value.
|
|
|
104
|
|
|
105 If @var{variable} has a @code{custom-type} property, it must be a widget
|
|
|
106 and the @code{:prompt-value} property of that widget will be used for
|
|
|
107 reading the value.
|
|
|
108 @end deffn
|
|
|
109
|
|
|
110 All variables that have been set either from a customization buffer or
|
|
|
111 with @code{customize-set-variable} can be saved with the command
|
|
|
112 @code{custom-save-customized}.
|
|
|
113
|
|
|
114 @deffn Command custom-save-customized
|
|
|
115 Save all variables that have been set with customize in this session.
|
|
|
116 @end deffn
|
|
|
117
|
|
|
118
|
|
98
|
119 @node The Customization Buffer, Declarations, User Commands, Top
|
|
|
120 @comment node-name, next, previous, up
|
|
|
121 @section The Customization Buffer.
|
|
|
122
|
|
|
123 The customization buffer allows the user to make temporary or permanent
|
|
|
124 changes to how specific aspects of emacs works, by setting and editing
|
|
|
125 user options.
|
|
|
126
|
|
|
127 The customization buffer contains three types of text:
|
|
|
128
|
|
|
129 @table @dfn
|
|
|
130 @item informative text
|
|
|
131 where the normal editing commands are disabled.
|
|
|
132
|
|
|
133 @item editable fields
|
|
|
134 where you can edit with the usual emacs commands. Editable fields are
|
|
|
135 usually displayed with a grey background if your terminal supports
|
|
|
136 colors, or an italic font otherwise.
|
|
|
137
|
|
|
138 @item buttons
|
|
|
139 which can be activated by either pressing the @kbd{@key{ret}} while
|
|
|
140 point is located on the text, or pushing @kbd{mouse-2} while the mouse
|
|
|
141 pointer is above the tex. Buttons are usually displayed in a bold
|
|
|
142 font.
|
|
|
143 @end table
|
|
|
144
|
|
|
145 You can move to the next the next editable field or button by pressing
|
|
|
146 @kbd{@key{tab}} or the previous with @kbd{M-@key{tab}}. Some buttons
|
|
|
147 have a small helpful message about their purpose, which will be
|
|
|
148 displayed when you move to it with the @key{tab} key.
|
|
|
149
|
|
|
150 The buffer is divided into three part, an introductory text, a list of
|
|
|
151 customization options, and a line of customization buttons. Each part
|
|
|
152 will be described in the following.
|
|
|
153
|
|
|
154 @menu
|
|
|
155 * The Introductory Text::
|
|
|
156 * The Customization Options::
|
|
|
157 * The Variable Options::
|
|
|
158 * The Face Options::
|
|
|
159 * The Group Options::
|
|
|
160 * The State Button::
|
|
|
161 * The Customization Buttons::
|
|
|
162 @end menu
|
|
|
163
|
|
|
164 @node The Introductory Text, The Customization Options, The Customization Buffer, The Customization Buffer
|
|
|
165 @comment node-name, next, previous, up
|
|
|
166 @subsection The Introductory Text
|
|
|
167
|
|
|
168 The start of the buffer contains a short explanation of what it is, and
|
|
|
169 how to get help. It will typically look like this:
|
|
|
170
|
|
|
171 @example
|
|
|
172 This is a customization buffer.
|
|
|
173 Push RET or click mouse-2 on the word _help_ for more information.
|
|
|
174 @end example
|
|
|
175
|
|
|
176 Rather boring. It is mostly just informative text, but the word
|
|
|
177 @samp{help} is a button that will bring up this document when
|
|
|
178 activated.
|
|
|
179
|
|
|
180 @node The Customization Options, The Variable Options, The Introductory Text, The Customization Buffer
|
|
|
181 @comment node-name, next, previous, up
|
|
|
182 @subsection The Customization Options
|
|
|
183
|
|
|
184 Each customization option looks similar to the following text:
|
|
|
185
|
|
|
186 @example
|
|
|
187 *** custom-background-mode: default
|
|
|
188 State: this item is unchanged from its factory setting.
|
|
|
189 [ ] [?] The brightness of the background.
|
|
|
190 @end example
|
|
|
191
|
|
|
192 The option contains the parts described below.
|
|
|
193
|
|
|
194 @table @samp
|
|
|
195 @item ***
|
|
|
196 The Level Button. The customization options in the buffer are organized
|
|
|
197 in a hierarchy, which is indicated by the number of stars in the level
|
|
|
198 button. The top level options will be shown as @samp{*}. When they are
|
|
|
199 expanded, the suboptions will be shown as @samp{**}. The example option
|
|
|
200 is thus a subsuboption.
|
|
|
201
|
|
|
202 Activating the level buttons will toggle between hiding and exposing the
|
|
|
203 content of that option. The content can either be the value of the
|
|
|
204 option, as in this example, or a list of suboptions.
|
|
|
205
|
|
|
206 @item custom-background-mode
|
|
|
207 This is the tag of the the option. The tag is a name of a variable, a
|
|
|
208 face, or customization group. Activating the tag has an effect that
|
|
|
209 depends on the exact type of the option. In this particular case,
|
|
|
210 activating the tag will bring up a menu that will allow you to choose
|
|
|
211 from the three possible values of the `custom-background-mode'
|
|
|
212 variable.
|
|
|
213
|
|
|
214 @item default
|
|
|
215 After the tag, the options value is shown. Depending on its type, you
|
|
|
216 may be able to edit the value directly. If an option should contain a
|
|
|
217 file name, it is displayed in an editable field, i.e. you can edit it
|
|
|
218 using the standard emacs editing commands.
|
|
|
219
|
|
|
220 @item State: this item is unchanged from its factory setting.
|
|
|
221 The state line. This line will explain the state of the option,
|
|
|
222 e.g. whether it is currently hidden, or whether it has been modified or
|
|
|
223 not. Activating the button will allow you to change the state, e.g. set
|
|
|
224 or reset the changes you have made. This is explained in detail in the
|
|
|
225 following sections.
|
|
|
226
|
|
|
227 @item [ ]
|
|
|
228 The magic button. This is an abbreviated version of the state line.
|
|
|
229
|
|
|
230 @item [?]
|
|
|
231 The documentation button. If the documentation is more than one line,
|
|
|
232 this button will be present. Activating the button will toggle whether
|
|
|
233 the complete documentation is shown, or only the first line.
|
|
|
234
|
|
|
235 @item The brightness of the background.
|
|
|
236 This is a documentation string explaining the purpose of this particular
|
|
|
237 customization option.
|
|
|
238
|
|
|
239 @end table
|
|
|
240
|
|
|
241 @node The Variable Options, The Face Options, The Customization Options, The Customization Buffer
|
|
|
242 @comment node-name, next, previous, up
|
|
|
243 @subsection The Variable Options
|
|
|
244
|
|
|
245 The most common customization options are emacs lisp variables. The
|
|
|
246 actual editing of these variables depend on what type values the
|
|
|
247 variable is expected to contain. For example, a lisp variable whose
|
|
|
248 value should be a string will typically be represented with an editable
|
|
|
249 text field in the buffer, where you can change the string directly. If
|
|
|
250 the value is a list, each item in the list will be presented in the
|
|
|
251 buffer buffer on a separate line, with buttons to insert new items in
|
|
|
252 the list, or delete existing items from the list. You may want to see
|
|
|
253 @ref{User Interface,,, widget, The Widget Library}, where some examples
|
|
|
254 of editing are discussed.
|
|
|
255
|
|
|
256 You can either choose to edit the value directly, or edit the lisp
|
|
|
257 value for that variable. The lisp value is a lisp expression that
|
|
|
258 will be evaluated when you start emacs. The result of the evaluation
|
|
|
259 will be used as the initial value for that variable. Editing the
|
|
|
260 lisp value is for experts only, but if the current value of the
|
|
|
261 variable is of a wrong type (i.e. a symbol where a string is expected),
|
|
|
262 the `edit lisp' mode will always be selected.
|
|
|
263
|
|
|
264 You can see what mode is currently selected by looking at the state
|
|
|
265 button. If it uses parenthesises (like @samp{( )}) it is in edit lisp
|
|
|
266 mode, with square brackets (like @samp{[ ]}) it is normal edit mode.
|
|
|
267 You can switch mode by activating the state button, and select either
|
|
|
268 @samp{Edit} or @samp{Edit lisp} from the menu.
|
|
|
269
|
|
|
270 You can change the state of the variable with the other menu items:
|
|
|
271
|
|
|
272 @table @samp
|
|
|
273 @item Set
|
|
|
274 When you have made your modifications in the buffer, you need to
|
|
|
275 activate this item to make the modifications take effect. The
|
|
|
276 modifications will be forgotten next time you run emacs.
|
|
|
277
|
|
|
278 @item Save
|
|
|
279 Unless you activate this item instead! This will mark the modification
|
|
|
280 as permanent, i.e. the changes will be remembered in the next emacs
|
|
|
281 session.
|
|
|
282
|
|
|
283 @item Reset
|
|
|
284 If you have made some modifications and not yet applied them, you can
|
|
|
285 undo the modification by activating this item.
|
|
|
286
|
|
|
287 @item Reset to Saved
|
|
|
288 Activating this item will reset the value of the variable to the last
|
|
|
289 value you marked as permanent with `Save'.
|
|
|
290
|
|
|
291 @item Reset to Factory Settings
|
|
|
292 Activating this item will undo all modifications you have made, and
|
|
|
293 reset the value to the initial value specified by the program itself.
|
|
|
294 @end table
|
|
|
295
|
|
|
296 By default, the value of large or complicated variables are hidden. You
|
|
|
297 can show the value by clicking on the level button.
|
|
|
298
|
|
|
299 @node The Face Options, The Group Options, The Variable Options, The Customization Buffer
|
|
|
300 @comment node-name, next, previous, up
|
|
|
301 @subsection The Face Options
|
|
|
302
|
|
|
303 A face is an object that controls the appearance of some buffer text.
|
|
|
304 The face has a number of possible attributes, such as boldness,
|
|
|
305 foreground color, and more. For each attribute you can specify whether
|
|
|
306 this attribute is controlled by the face, and if so, what the value is.
|
|
|
307 For example, if the attribute bold is not controlled by a face, using
|
|
|
308 that face on some buffer text will not affect its boldness. If the bold
|
|
|
309 attribute is controlled by the face, it can be turned either on or of.
|
|
|
310
|
|
|
311 It is possible to specify that a face should have different attributes
|
|
|
312 on different device types. For example, a face may make text red on a
|
|
120
|
313 color device, and bold on a monochrome device. You do this by
|
|
|
314 activating `Edit All' in the state menu.
|
|
98
|
315
|
|
|
316 The way this is presented in the customization buffer is to have a list
|
|
|
317 of display specifications, and for each display specification a list of
|
|
|
318 face attributes. For each face attribute, there is a checkbox
|
|
|
319 specifying whether this attribute has effect and what the value is.
|
|
|
320 Here is an example:
|
|
|
321
|
|
|
322 @example
|
|
|
323 *** custom-invalid-face: (sample)
|
|
120
|
324 State: this item is unchanged from its factory setting.
|
|
98
|
325 [ ] Face used when the customize item is invalid.
|
|
120
|
326 [INS] [DEL] Display: [ ] Type: [ ] X [ ] PM [ ] Win32 [ ] DOS [ ] TTY
|
|
98
|
327 [X] Class: [X] Color [ ] Grayscale [ ] Monochrome
|
|
|
328 [ ] Background: [ ] Light [ ] Dark
|
|
|
329 Attributes: [ ] Bold: off
|
|
|
330 [ ] Italic: off
|
|
|
331 [ ] Underline: off
|
|
|
332 [X] Foreground: yellow (sample)
|
|
|
333 [X] Background: red (sample)
|
|
|
334 [ ] Stipple:
|
|
|
335 [INS] [DEL] Display: all
|
|
|
336 Attributes: [X] Bold: on
|
|
|
337 [X] Italic: on
|
|
|
338 [X] Underline: on
|
|
|
339 [ ] Foreground: default (sample)
|
|
|
340 [ ] Background: default (sample)
|
|
|
341 [ ] Stipple:
|
|
|
342 [INS]
|
|
|
343 @end example
|
|
|
344
|
|
|
345 This has two display specifications. The first will match all color
|
|
120
|
346 displays, independently on what window system the device belongs to, and
|
|
98
|
347 whether background color is dark or light. For devices matching this
|
|
|
348 specification, @samp{custom-invalid-face} will force text to be
|
|
|
349 displayed in yellow on red, but leave all other attributes alone.
|
|
|
350
|
|
|
351 The second display will simply match everything. Since the list is
|
|
|
352 prioritised, this means that it will match all non-color displays. For
|
|
|
353 these, the face will not affect the foreground or background color, but
|
|
|
354 force the font to be both bold, italic, and underline.
|
|
|
355
|
|
|
356 You can add or delete display specifications by activating the
|
|
|
357 @samp{[INS]} and @samp{[DEL]} buttons, and modify them by clicking on
|
|
|
358 the check boxes. The first checkbox in each line in the display
|
|
|
359 specification is special. It specify whether this particular property
|
|
|
360 will even be relevant. By not checking the box in the first display, we
|
|
120
|
361 match all device types, also device types other than those listed.
|
|
98
|
362
|
|
|
363 After modifying the face, you can activate the state button to make the
|
|
|
364 changes take effect. The menu items in the state button menu is similar
|
|
|
365 to the state menu items for variables described in the previous section.
|
|
|
366
|
|
|
367 @node The Group Options, The State Button, The Face Options, The Customization Buffer
|
|
|
368 @comment node-name, next, previous, up
|
|
|
369 @subsection The Group Options
|
|
|
370
|
|
|
371 Since Emacs has approximately a zillion configuration options, they have
|
|
|
372 been organized in groups. Each group can contain other groups, thus
|
|
|
373 creating a customization hierarchy. The nesting of the customization
|
|
|
374 within the visible part of this hierarchy is indicated by the number of
|
|
|
375 stars in the level button.
|
|
|
376
|
|
|
377 Since there is really no customization needed for the group itself, the
|
|
|
378 menu items in the groups state button will affect all modified group
|
|
|
379 members recursively. Thus, if you activate the @samp{Set} menu item,
|
|
|
380 all variables and faces that have been modified and belong to that group
|
|
|
381 will be applied. For those members that themselves are groups, it will
|
|
|
382 work as if you had activated the @samp{Set} menu item on them as well.
|
|
|
383
|
|
|
384 @node The State Button, The Customization Buttons, The Group Options, The Customization Buffer
|
|
|
385 @comment node-name, next, previous, up
|
|
|
386 @subsection The State Line and The Magic Button
|
|
|
387
|
|
|
388 The state line has two purposes. The first is to hold the state menu,
|
|
|
389 as described in the previous sections. The second is to indicate the
|
|
|
390 state of each customization item.
|
|
|
391
|
|
|
392 For the magic button, this is done by the character inside the brackets.
|
|
|
393 The following states have been defined, the first that applies to the
|
|
|
394 current item will be used:
|
|
|
395
|
|
|
396 @table @samp
|
|
|
397 @item -
|
|
|
398 The option is currently hidden. For group options that means the
|
|
|
399 members are not shown, for variables and faces that the value is not
|
|
|
400 shown. You cannot perform any of the state change operations on a
|
|
|
401 hidden customization option.
|
|
|
402
|
|
|
403 @item *
|
|
|
404 The value if this option has been modified in the buffer, but not yet
|
|
|
405 applied.
|
|
|
406
|
|
|
407 @item +
|
|
|
408 The item has has been set by the user.
|
|
|
409
|
|
|
410 @item :
|
|
|
411 The current value of this option is different from the saved value.
|
|
|
412
|
|
|
413 @item !
|
|
|
414 The saved value of this option is different from the factory setting.
|
|
|
415
|
|
|
416 @item @@
|
|
|
417 The factory setting of this option is not known. This occurs when you
|
|
|
418 try to customize variables or faces that have not been explicitly
|
|
|
419 declared as customizable.
|
|
|
420
|
|
|
421 @item SPC
|
|
|
422 The factory setting is still in effect.
|
|
|
423
|
|
|
424 @end table
|
|
|
425
|
|
|
426 For non-hidden group options, the state shown is the most severe state
|
|
|
427 of its members, where more severe means that it appears earlier in the
|
|
|
428 list above (except hidden members, which are ignored).
|
|
|
429
|
|
|
430 @node The Customization Buttons, , The State Button, The Customization Buffer
|
|
|
431 @comment node-name, next, previous, up
|
|
|
432 @subsection The Customization Buttons
|
|
|
433
|
|
|
434 The last part of the customization buffer looks like this:
|
|
|
435
|
|
|
436 @example
|
|
108
|
437 [Set] [Save] [Reset] [Done]
|
|
98
|
438 @end example
|
|
|
439
|
|
|
440 Activating the @samp{[Set]}, @samp{[Save]}, or @samp{[Reset]}
|
|
|
441 button will affect all modified customization items that are visible in
|
|
108
|
442 the buffer. @samp{[Done]} will bury the buffer.
|
|
98
|
443
|
|
|
444 @node Declarations, Utilities, The Customization Buffer, Top
|
|
|
445 @comment node-name, next, previous, up
|
|
|
446 @section Declarations
|
|
|
447
|
|
120
|
448 This section describes how to declare customization groups, variables,
|
|
|
449 and faces. It doesn't contain any examples, but please look at the file
|
|
|
450 @file{cus-edit.el} which contains many declarations you can learn from.
|
|
|
451
|
|
98
|
452 @menu
|
|
|
453 * Declaring Groups::
|
|
|
454 * Declaring Variables::
|
|
|
455 * Declaring Faces::
|
|
102
|
456 * Usage for Package Authors::
|
|
98
|
457 @end menu
|
|
|
458
|
|
|
459 All the customization declarations can be changes by keyword arguments.
|
|
|
460 Groups, variables, and faces all share these common keywords:
|
|
|
461
|
|
|
462 @table @code
|
|
|
463 @item :group
|
|
|
464 @var{value} should be a customization group.
|
|
|
465 Add @var{symbol} to that group.
|
|
|
466 @item :link
|
|
|
467 @var{value} should be a widget type.
|
|
|
468 Add @var{value} to the extrenal links for this customization option.
|
|
|
469 Useful widget types include @code{custom-manual}, @code{info-link}, and
|
|
|
470 @code{url-link}.
|
|
|
471 @item :load
|
|
|
472 Add @var{value} to the files that should be loaded nefore displaying
|
|
|
473 this customization option. The value should be iether a string, which
|
|
|
474 should be a string which will be loaded with @code{load-library} unless
|
|
|
475 present in @code{load-history}, or a symbol which will be loaded with
|
|
|
476 @code{require}.
|
|
|
477 @item :tag
|
|
|
478 @var{Value} should be a short string used for identifying the option in
|
|
|
479 customization menus and buffers. By default the tag will be
|
|
|
480 automatically created from the options name.
|
|
|
481 @end table
|
|
|
482
|
|
|
483 @node Declaring Groups, Declaring Variables, Declarations, Declarations
|
|
|
484 @comment node-name, next, previous, up
|
|
|
485 @subsection Declaring Groups
|
|
|
486
|
|
|
487 Use @code{defgroup} to declare new customization groups.
|
|
|
488
|
|
|
489 @defun defgroup symbol members doc [keyword value]...
|
|
|
490 Declare @var{symbol} as a customization group containing @var{members}.
|
|
|
491 @var{symbol} does not need to be quoted.
|
|
|
492
|
|
|
493 @var{doc} is the group documentation.
|
|
|
494
|
|
|
495 @var{members} should be an alist of the form ((@var{name}
|
|
|
496 @var{widget})...) where @var{name} is a symbol and @var{widget} is a
|
|
|
497 widget for editing that symbol. Useful widgets are
|
|
|
498 @code{custom-variable} for editing variables, @code{custom-face} for
|
|
|
499 editing faces, and @code{custom-group} for editing groups.@refill
|
|
|
500
|
|
|
501 Internally, custom uses the symbol property @code{custom-group} to keep
|
|
|
502 track of the group members, and @code{group-documentation} for the
|
|
|
503 documentation string.
|
|
|
504
|
|
|
505 The following additional @var{keyword}'s are defined:
|
|
|
506
|
|
|
507 @table @code
|
|
|
508 @item :prefix
|
|
|
509 @var{value} should be a string. If the string is a prefix for the name
|
|
|
510 of a member of the group, that prefix will be ignored when creating a
|
|
|
511 tag for that member.
|
|
|
512 @end table
|
|
|
513 @end defun
|
|
|
514
|
|
|
515 @node Declaring Variables, Declaring Faces, Declaring Groups, Declarations
|
|
|
516 @comment node-name, next, previous, up
|
|
|
517 @subsection Declaring Variables
|
|
|
518
|
|
|
519 Use @code{defcustom} to declare user editable variables.
|
|
|
520
|
|
|
521 @defun defcustom symbol value doc [keyword value]...
|
|
|
522 Declare @var{symbol} as a customizable variable that defaults to @var{value}.
|
|
|
523 Neither @var{symbol} nor @var{value} needs to be quoted.
|
|
|
524 If @var{symbol} is not already bound, initialize it to @var{value}.
|
|
|
525
|
|
|
526 @var{doc} is the variable documentation.
|
|
|
527
|
|
|
528 The following additional @var{keyword}'s are defined:
|
|
|
529
|
|
|
530 @table @code
|
|
|
531 @item :type
|
|
|
532 @var{value} should be a widget type.
|
|
149
|
533
|
|
98
|
534 @item :options
|
|
|
535 @var{value} should be a list of possible members of the specified type.
|
|
|
536 For hooks, this is a list of function names.
|
|
149
|
537
|
|
|
538 @item :initialize
|
|
|
539 @var{value} should be a function used to initialize the variable. It
|
|
|
540 takes two arguments, the symbol and value given in the @code{defcustom} call.
|
|
|
541 Some predefined functions are:
|
|
|
542
|
|
|
543 @table @code
|
|
|
544 @item custom-initialize-set
|
|
|
545 Use the @code{:set} method to initialize the variable. Do not
|
|
|
546 initialize it if already bound. This is the default @code{:initialize}
|
|
|
547 method.
|
|
|
548
|
|
|
549 @item custom-initialize-default
|
|
|
550 Always use @code{set-default} to initialize the variable, even if a
|
|
|
551 @code{:set} method has been specified.
|
|
|
552
|
|
|
553 @item custom-initialize-reset
|
|
|
554 If the variable is already bound, reset it by calling the @code{:set}
|
|
|
555 method with the value returned by the @code{:get} method.
|
|
|
556
|
|
|
557 @item custom-initialize-changed
|
|
|
558 Like @code{custom-initialize-reset}, but use @code{set-default} to
|
|
|
559 initialize the variable if it is not bound and has not been set
|
|
|
560 already.
|
|
|
561 @end table
|
|
|
562
|
|
|
563 @item :set
|
|
|
564 @var{value} should be a function to set the value of the symbol. It
|
|
|
565 takes two arguments, the symbol to set and the value to give it. The
|
|
|
566 default is @code{set-default}.
|
|
|
567
|
|
|
568 @item :get
|
|
|
569 @var{value} should be a function to extract the value of symbol. The
|
|
|
570 function takes one argument, a symbol, and should return the current
|
|
|
571 value for that symbol. The default is @code{default-value}.
|
|
|
572
|
|
|
573 @item :require
|
|
|
574 @var{value} should be a feature symbol. Each feature will be required
|
|
|
575 after initialization, of the the user have saved this option.
|
|
|
576
|
|
98
|
577 @end table
|
|
|
578
|
|
|
579 @xref{Sexp Types,,,widget,The Widget Library}, for information about
|
|
|
580 widgets to use together with the @code{:type} keyword.
|
|
|
581 @end defun
|
|
|
582
|
|
|
583 Internally, custom uses the symbol property @code{custom-type} to keep
|
|
|
584 track of the variables type, @code{factory-value} for the program
|
|
|
585 specified default value, @code{saved-value} for a value saved by the
|
|
|
586 user, and @code{variable-documentation} for the documentation string.
|
|
|
587
|
|
|
588 Use @code{custom-add-option} to specify that a specific function is
|
|
|
589 useful as an meber of a hook.
|
|
|
590
|
|
|
591 @defun custom-add-option symbol option
|
|
|
592 To the variable @var{symbol} add @var{option}.
|
|
|
593
|
|
|
594 If @var{symbol} is a hook variable, @var{option} should be a hook
|
|
|
595 member. For other types variables, the effect is undefined."
|
|
|
596 @end defun
|
|
|
597
|
|
102
|
598 @node Declaring Faces, Usage for Package Authors, Declaring Variables, Declarations
|
|
98
|
599 @comment node-name, next, previous, up
|
|
|
600 @subsection Declaring Faces
|
|
|
601
|
|
|
602 Faces are declared with @code{defface}.
|
|
|
603
|
|
|
604 @defun defface face spec doc [keyword value]...
|
|
|
605
|
|
|
606 Declare @var{face} as a customizable face that defaults to @var{spec}.
|
|
|
607 @var{face} does not need to be quoted.
|
|
|
608
|
|
|
609 If @var{face} has been set with `custom-set-face', set the face attributes
|
|
|
610 as specified by that function, otherwise set the face attributes
|
|
|
611 according to @var{spec}.
|
|
|
612
|
|
|
613 @var{doc} is the face documentation.
|
|
|
614
|
|
|
615 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
|
|
|
616
|
|
|
617 @var{atts} is a list of face attributes and their values. The possible
|
|
|
618 attributes are defined in the variable `custom-face-attributes'.
|
|
|
619 Alternatively, @var{atts} can be a face in which case the attributes of
|
|
|
620 that face is used.
|
|
|
621
|
|
|
622 The @var{atts} of the first entry in @var{spec} where the @var{display}
|
|
|
623 matches the frame should take effect in that frame. @var{display} can
|
|
|
624 either be the symbol `t', which will match all frames, or an alist of
|
|
|
625 the form @samp{((@var{req} @var{item}...)...)}@refill
|
|
|
626
|
|
|
627 For the @var{display} to match a FRAME, the @var{req} property of the
|
|
|
628 frame must match one of the @var{item}. The following @var{req} are
|
|
|
629 defined:@refill
|
|
|
630
|
|
|
631 @table @code
|
|
|
632 @item type
|
|
108
|
633 (the value of (window-system))@*
|
|
98
|
634 Should be one of @code{x} or @code{tty}.
|
|
|
635
|
|
|
636 @item class
|
|
108
|
637 (the frame's color support)@*
|
|
98
|
638 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
|
|
|
639
|
|
|
640 @item background
|
|
108
|
641 (what color is used for the background text)@*
|
|
98
|
642 Should be one of @code{light} or @code{dark}.
|
|
|
643 @end table
|
|
|
644
|
|
149
|
645 Internally, custom uses the symbol property @code{face-defface-spec} for
|
|
|
646 the program specified default face properties, @code{saved-face} for
|
|
|
647 properties saved by the user, and @code{face-documentation} for the
|
|
98
|
648 documentation string.@refill
|
|
|
649
|
|
|
650 @end defun
|
|
|
651
|
|
102
|
652 @node Usage for Package Authors, , Declaring Faces, Declarations
|
|
|
653 @comment node-name, next, previous, up
|
|
|
654 @subsection Usage for Package Authors
|
|
|
655
|
|
|
656 The recommended usage for the author of a typical emacs lisp package is
|
|
|
657 to create one group identifying the package, and make all user options
|
|
|
658 and faces members of that group. If the package has more than around 20
|
|
|
659 such options, they should be divided into a number of subgroups, with
|
|
|
660 each subgroup being member of the top level group.
|
|
|
661
|
|
|
662 The top level group for the package should itself be member of one or
|
|
|
663 more of the standard customization groups. There exists a group for
|
|
|
664 each @emph{finder} keyword. Press @kbd{C-c p} to see a list of finder
|
|
|
665 keywords, and add you group to each of them, using the @code{:group}
|
|
|
666 keyword.
|
|
|
667
|
|
98
|
668 @node Utilities, The Init File, Declarations, Top
|
|
|
669 @comment node-name, next, previous, up
|
|
|
670 @section Utilities
|
|
|
671
|
|
|
672 These utilities can come in handy when adding customization support.
|
|
|
673
|
|
|
674 @deffn Widget custom-manual
|
|
|
675 Widget type for specifying the info manual entry for a customization
|
|
|
676 option. It takes one argument, an info address.
|
|
|
677 @end deffn
|
|
|
678
|
|
|
679 @defun custom-add-to-group group member widget
|
|
|
680 To existing @var{group} add a new @var{member} of type @var{widget},
|
|
|
681 If there already is an entry for that member, overwrite it.
|
|
|
682 @end defun
|
|
|
683
|
|
|
684 @defun custom-add-link symbol widget
|
|
|
685 To the custom option @var{symbol} add the link @var{widget}.
|
|
|
686 @end defun
|
|
|
687
|
|
|
688 @defun custom-add-load symbol load
|
|
|
689 To the custom option @var{symbol} add the dependency @var{load}.
|
|
|
690 @var{load} should be either a library file name, or a feature name.
|
|
|
691 @end defun
|
|
|
692
|
|
124
|
693 @defun customize-menu-create symbol &optional name
|
|
98
|
694 Create menu for customization group @var{symbol}.
|
|
|
695 If optional @var{name} is given, use that as the name of the menu.
|
|
124
|
696 Otherwise the menu will be named `Customize'.
|
|
98
|
697 The menu is in a format applicable to @code{easy-menu-define}.
|
|
|
698 @end defun
|
|
|
699
|
|
|
700 @node The Init File, Wishlist, Utilities, Top
|
|
|
701 @comment node-name, next, previous, up
|
|
|
702 @section The Init File
|
|
|
703
|
|
|
704 When you save the customizations, call to @code{custom-set-variables},
|
|
|
705 @code{custom-set-faces} are inserted into the file specified by
|
|
|
706 @code{custom-file}. By default @code{custom-file} is your @file{.emacs}
|
|
116
|
707 file. If you use another file, you must explicitly load it yourself.
|
|
|
708 The two functions will initialize variables and faces as you have
|
|
|
709 specified.
|
|
98
|
710
|
|
|
711 @node Wishlist, , The Init File, Top
|
|
|
712 @comment node-name, next, previous, up
|
|
|
713 @section Wishlist
|
|
|
714
|
|
|
715 @itemize @bullet
|
|
|
716 @item
|
|
120
|
717 Better support for keyboard operations in the customize buffer.
|
|
98
|
718
|
|
|
719 @item
|
|
|
720 Integrate with @file{w3} so you can customization buffers with much
|
|
|
721 better formatting. I'm thinking about adding a <custom>name</custom>
|
|
108
|
722 tag. The latest w3 have some support for this, so come up with a
|
|
|
723 convincing example.
|
|
98
|
724
|
|
|
725 @item
|
|
|
726 Add an `examples' section, with explained examples of custom type
|
|
|
727 definitions.
|
|
|
728
|
|
|
729 @item
|
|
110
|
730 Support selectable color themes. I.e., change many faces by setting one
|
|
|
731 variable.
|
|
|
732
|
|
|
733 @item
|
|
98
|
734 Support undo using lmi's @file{gnus-undo.el}.
|
|
|
735
|
|
|
736 @item
|
|
|
737 Make it possible to append to `choice', `radio', and `set' options.
|
|
|
738
|
|
|
739 @item
|
|
|
740 Ask whether set or modified variables should be saved in
|
|
|
741 @code{kill-buffer-hook}.
|
|
|
742
|
|
|
743 Ditto for @code{kill-emacs-query-functions}.
|
|
|
744
|
|
|
745 @item
|
|
|
746 Command to check if there are any customization options that
|
|
|
747 does not belong to an existing group.
|
|
|
748
|
|
|
749 @item
|
|
|
750 Optionally disable the point-cursor and instead highlight the selected
|
|
|
751 item in XEmacs. This is like the *Completions* buffer in XEmacs.
|
|
|
752 Suggested by Jens Lautenbacher
|
|
|
753 @samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill
|
|
|
754
|
|
120
|
755 @item
|
|
|
756 Empty customization groups should start open (harder than it looks).
|
|
|
757
|
|
124
|
758 @item
|
|
|
759 Make it possible to include a comment/remark/annotation when saving an
|
|
|
760 option.
|
|
|
761
|
|
149
|
762 @item
|
|
|
763 Add some direct support for meta variables, i.e. make it possible to
|
|
|
764 specify that this variable should be reset when that variable is
|
|
|
765 changed.
|
|
|
766
|
|
|
767 @item
|
|
|
768 Add tutorial.
|
|
|
769
|
|
|
770 @item
|
|
|
771 Describe the @code{:type} syntax in this manual.
|
|
|
772
|
|
|
773 @item
|
|
|
774 Find a place is this manual for the following text:
|
|
|
775
|
|
|
776 @strong{Radio vs. Buttons}
|
|
|
777
|
|
|
778 Use a radio if you can't find a good way to describe the item in the
|
|
|
779 choice menu text. I.e. it is better to use a radio if you expect the
|
|
|
780 user would otherwise manually select each item from the choice menu in
|
|
|
781 turn to see what it expands too.
|
|
|
782
|
|
|
783 Avoid radios if some of the items expands to complex structures.
|
|
|
784
|
|
|
785 I mostly use radios when most of the items are of type
|
|
|
786 @code{function-item} or @code{variable-item}.
|
|
|
787
|
|
|
788 @item
|
|
|
789 Update customize buffers when @code{custom-set-variable} or
|
|
|
790 @code{custom-save-customized} is called.
|
|
|
791
|
|
|
792 @item
|
|
|
793 Better handling of saved but uninitialized items.
|
|
|
794
|
|
98
|
795 @end itemize
|
|
|
796
|
|
|
797 @contents
|
|
|
798 @bye
|
