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