|
16
|
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
|
|
|
16 Version: 1.20
|
|
|
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.
|
|
|
79 @end table
|
|
|
80
|
|
|
81 @node The Customization Buffer, Declarations, User Commands, Top
|
|
|
82 @comment node-name, next, previous, up
|
|
|
83 @section The Customization Buffer.
|
|
|
84
|
|
|
85 The customization buffer allows the user to make temporary or permanent
|
|
|
86 changes to how specific aspects of emacs works, by setting and editing
|
|
|
87 user options.
|
|
|
88
|
|
|
89 The customization buffer contains three types of text:
|
|
|
90
|
|
|
91 @table @dfn
|
|
|
92 @item informative text
|
|
|
93 where the normal editing commands are disabled.
|
|
|
94
|
|
|
95 @item editable fields
|
|
|
96 where you can edit with the usual emacs commands. Editable fields are
|
|
|
97 usually displayed with a grey background if your terminal supports
|
|
|
98 colors, or an italic font otherwise.
|
|
|
99
|
|
|
100 @item buttons
|
|
|
101 which can be activated by either pressing the @kbd{@key{ret}} while
|
|
|
102 point is located on the text, or pushing @kbd{mouse-2} while the mouse
|
|
|
103 pointer is above the tex. Buttons are usually displayed in a bold
|
|
|
104 font.
|
|
|
105 @end table
|
|
|
106
|
|
|
107 You can move to the next the next editable field or button by pressing
|
|
|
108 @kbd{@key{tab}} or the previous with @kbd{M-@key{tab}}. Some buttons
|
|
|
109 have a small helpful message about their purpose, which will be
|
|
|
110 displayed when you move to it with the @key{tab} key.
|
|
|
111
|
|
|
112 The buffer is divided into three part, an introductory text, a list of
|
|
|
113 customization options, and a line of customization buttons. Each part
|
|
|
114 will be described in the following.
|
|
|
115
|
|
|
116 @menu
|
|
|
117 * The Introductory Text::
|
|
|
118 * The Customization Options::
|
|
|
119 * The Variable Options::
|
|
|
120 * The Face Options::
|
|
|
121 * The Group Options::
|
|
|
122 * The State Button::
|
|
|
123 * The Customization Buttons::
|
|
|
124 @end menu
|
|
|
125
|
|
|
126 @node The Introductory Text, The Customization Options, The Customization Buffer, The Customization Buffer
|
|
|
127 @comment node-name, next, previous, up
|
|
|
128 @subsection The Introductory Text
|
|
|
129
|
|
|
130 The start of the buffer contains a short explanation of what it is, and
|
|
|
131 how to get help. It will typically look like this:
|
|
|
132
|
|
|
133 @example
|
|
|
134 This is a customization buffer.
|
|
|
135 Push RET or click mouse-2 on the word _help_ for more information.
|
|
|
136 @end example
|
|
|
137
|
|
|
138 Rather boring. It is mostly just informative text, but the word
|
|
|
139 @samp{help} is a button that will bring up this document when
|
|
|
140 activated.
|
|
|
141
|
|
|
142 @node The Customization Options, The Variable Options, The Introductory Text, The Customization Buffer
|
|
|
143 @comment node-name, next, previous, up
|
|
|
144 @subsection The Customization Options
|
|
|
145
|
|
|
146 Each customization option looks similar to the following text:
|
|
|
147
|
|
|
148 @example
|
|
|
149 *** custom-background-mode: default
|
|
|
150 State: this item is unchanged from its factory setting.
|
|
|
151 [ ] [?] The brightness of the background.
|
|
|
152 @end example
|
|
|
153
|
|
|
154 The option contains the parts described below.
|
|
|
155
|
|
|
156 @table @samp
|
|
|
157 @item ***
|
|
|
158 The Level Button. The customization options in the buffer are organized
|
|
|
159 in a hierarchy, which is indicated by the number of stars in the level
|
|
|
160 button. The top level options will be shown as @samp{*}. When they are
|
|
|
161 expanded, the suboptions will be shown as @samp{**}. The example option
|
|
|
162 is thus a subsuboption.
|
|
|
163
|
|
|
164 Activating the level buttons will toggle between hiding and exposing the
|
|
|
165 content of that option. The content can either be the value of the
|
|
|
166 option, as in this example, or a list of suboptions.
|
|
|
167
|
|
|
168 @item custom-background-mode
|
|
|
169 This is the tag of the the option. The tag is a name of a variable, a
|
|
|
170 face, or customization group. Activating the tag has an effect that
|
|
|
171 depends on the exact type of the option. In this particular case,
|
|
|
172 activating the tag will bring up a menu that will allow you to choose
|
|
|
173 from the three possible values of the `custom-background-mode'
|
|
|
174 variable.
|
|
|
175
|
|
|
176 @item default
|
|
|
177 After the tag, the options value is shown. Depending on its type, you
|
|
|
178 may be able to edit the value directly. If an option should contain a
|
|
|
179 file name, it is displayed in an editable field, i.e. you can edit it
|
|
|
180 using the standard emacs editing commands.
|
|
|
181
|
|
|
182 @item State: this item is unchanged from its factory setting.
|
|
|
183 The state line. This line will explain the state of the option,
|
|
|
184 e.g. whether it is currently hidden, or whether it has been modified or
|
|
|
185 not. Activating the button will allow you to change the state, e.g. set
|
|
|
186 or reset the changes you have made. This is explained in detail in the
|
|
|
187 following sections.
|
|
|
188
|
|
|
189 @item [ ]
|
|
|
190 The magic button. This is an abbreviated version of the state line.
|
|
|
191
|
|
|
192 @item [?]
|
|
|
193 The documentation button. If the documentation is more than one line,
|
|
|
194 this button will be present. Activating the button will toggle whether
|
|
|
195 the complete documentation is shown, or only the first line.
|
|
|
196
|
|
|
197 @item The brightness of the background.
|
|
|
198 This is a documentation string explaining the purpose of this particular
|
|
|
199 customization option.
|
|
|
200
|
|
|
201 @end table
|
|
|
202
|
|
|
203 @node The Variable Options, The Face Options, The Customization Options, The Customization Buffer
|
|
|
204 @comment node-name, next, previous, up
|
|
|
205 @subsection The Variable Options
|
|
|
206
|
|
|
207 The most common customization options are emacs lisp variables. The
|
|
|
208 actual editing of these variables depend on what type values the
|
|
|
209 variable is expected to contain. For example, a lisp variable whose
|
|
|
210 value should be a string will typically be represented with an editable
|
|
|
211 text field in the buffer, where you can change the string directly. If
|
|
|
212 the value is a list, each item in the list will be presented in the
|
|
|
213 buffer buffer on a separate line, with buttons to insert new items in
|
|
|
214 the list, or delete existing items from the list. You may want to see
|
|
|
215 @ref{User Interface,,, widget, The Widget Library}, where some examples
|
|
|
216 of editing are discussed.
|
|
|
217
|
|
|
218 You can either choose to edit the value directly, or edit the lisp
|
|
|
219 value for that variable. The lisp value is a lisp expression that
|
|
|
220 will be evaluated when you start emacs. The result of the evaluation
|
|
|
221 will be used as the initial value for that variable. Editing the
|
|
|
222 lisp value is for experts only, but if the current value of the
|
|
|
223 variable is of a wrong type (i.e. a symbol where a string is expected),
|
|
|
224 the `edit lisp' mode will always be selected.
|
|
|
225
|
|
|
226 You can see what mode is currently selected by looking at the state
|
|
|
227 button. If it uses parenthesises (like @samp{( )}) it is in edit lisp
|
|
|
228 mode, with square brackets (like @samp{[ ]}) it is normal edit mode.
|
|
|
229 You can switch mode by activating the state button, and select either
|
|
|
230 @samp{Edit} or @samp{Edit lisp} from the menu.
|
|
|
231
|
|
|
232 You can change the state of the variable with the other menu items:
|
|
|
233
|
|
|
234 @table @samp
|
|
|
235 @item Set
|
|
|
236 When you have made your modifications in the buffer, you need to
|
|
|
237 activate this item to make the modifications take effect. The
|
|
|
238 modifications will be forgotten next time you run emacs.
|
|
|
239
|
|
|
240 @item Save
|
|
|
241 Unless you activate this item instead! This will mark the modification
|
|
|
242 as permanent, i.e. the changes will be remembered in the next emacs
|
|
|
243 session.
|
|
|
244
|
|
|
245 @item Reset
|
|
|
246 If you have made some modifications and not yet applied them, you can
|
|
|
247 undo the modification by activating this item.
|
|
|
248
|
|
|
249 @item Reset to Saved
|
|
|
250 Activating this item will reset the value of the variable to the last
|
|
|
251 value you marked as permanent with `Save'.
|
|
|
252
|
|
|
253 @item Reset to Factory Settings
|
|
|
254 Activating this item will undo all modifications you have made, and
|
|
|
255 reset the value to the initial value specified by the program itself.
|
|
|
256 @end table
|
|
|
257
|
|
|
258 By default, the value of large or complicated variables are hidden. You
|
|
|
259 can show the value by clicking on the level button.
|
|
|
260
|
|
|
261 @node The Face Options, The Group Options, The Variable Options, The Customization Buffer
|
|
|
262 @comment node-name, next, previous, up
|
|
|
263 @subsection The Face Options
|
|
|
264
|
|
|
265 A face is an object that controls the appearance of some buffer text.
|
|
|
266 The face has a number of possible attributes, such as boldness,
|
|
|
267 foreground color, and more. For each attribute you can specify whether
|
|
|
268 this attribute is controlled by the face, and if so, what the value is.
|
|
|
269 For example, if the attribute bold is not controlled by a face, using
|
|
|
270 that face on some buffer text will not affect its boldness. If the bold
|
|
|
271 attribute is controlled by the face, it can be turned either on or of.
|
|
|
272
|
|
|
273 It is possible to specify that a face should have different attributes
|
|
|
274 on different device types. For example, a face may make text red on a
|
|
|
275 color device, and bold on a monochrome device.
|
|
|
276
|
|
|
277 The way this is presented in the customization buffer is to have a list
|
|
|
278 of display specifications, and for each display specification a list of
|
|
|
279 face attributes. For each face attribute, there is a checkbox
|
|
|
280 specifying whether this attribute has effect and what the value is.
|
|
|
281 Here is an example:
|
|
|
282
|
|
|
283 @example
|
|
|
284 *** custom-invalid-face: (sample)
|
|
|
285 [ ] Face used when the customize item is invalid.
|
|
|
286 [INS] [DEL] Display: [ ] Type: [ ] X [ ] TTY
|
|
|
287 [X] Class: [X] Color [ ] Grayscale [ ] Monochrome
|
|
|
288 [ ] Background: [ ] Light [ ] Dark
|
|
|
289 Attributes: [ ] Bold: off
|
|
|
290 [ ] Italic: off
|
|
|
291 [ ] Underline: off
|
|
|
292 [X] Foreground: yellow (sample)
|
|
|
293 [X] Background: red (sample)
|
|
|
294 [ ] Stipple:
|
|
|
295 [INS] [DEL] Display: all
|
|
|
296 Attributes: [X] Bold: on
|
|
|
297 [X] Italic: on
|
|
|
298 [X] Underline: on
|
|
|
299 [ ] Foreground: default (sample)
|
|
|
300 [ ] Background: default (sample)
|
|
|
301 [ ] Stipple:
|
|
|
302 [INS]
|
|
|
303 @end example
|
|
|
304
|
|
|
305 This has two display specifications. The first will match all color
|
|
|
306 displays, independently on whether the device is X11 or a tty, and
|
|
|
307 whether background color is dark or light. For devices matching this
|
|
|
308 specification, @samp{custom-invalid-face} will force text to be
|
|
|
309 displayed in yellow on red, but leave all other attributes alone.
|
|
|
310
|
|
|
311 The second display will simply match everything. Since the list is
|
|
|
312 prioritised, this means that it will match all non-color displays. For
|
|
|
313 these, the face will not affect the foreground or background color, but
|
|
|
314 force the font to be both bold, italic, and underline.
|
|
|
315
|
|
|
316 You can add or delete display specifications by activating the
|
|
|
317 @samp{[INS]} and @samp{[DEL]} buttons, and modify them by clicking on
|
|
|
318 the check boxes. The first checkbox in each line in the display
|
|
|
319 specification is special. It specify whether this particular property
|
|
|
320 will even be relevant. By not checking the box in the first display, we
|
|
|
321 match all device types, also device types other than X11 and tty, for
|
|
|
322 example ms-windows, nextstep, and mac os.
|
|
|
323
|
|
|
324 After modifying the face, you can activate the state button to make the
|
|
|
325 changes take effect. The menu items in the state button menu is similar
|
|
|
326 to the state menu items for variables described in the previous section.
|
|
|
327
|
|
|
328 @node The Group Options, The State Button, The Face Options, The Customization Buffer
|
|
|
329 @comment node-name, next, previous, up
|
|
|
330 @subsection The Group Options
|
|
|
331
|
|
|
332 Since Emacs has approximately a zillion configuration options, they have
|
|
|
333 been organized in groups. Each group can contain other groups, thus
|
|
|
334 creating a customization hierarchy. The nesting of the customization
|
|
|
335 within the visible part of this hierarchy is indicated by the number of
|
|
|
336 stars in the level button.
|
|
|
337
|
|
|
338 Since there is really no customization needed for the group itself, the
|
|
|
339 menu items in the groups state button will affect all modified group
|
|
|
340 members recursively. Thus, if you activate the @samp{Set} menu item,
|
|
|
341 all variables and faces that have been modified and belong to that group
|
|
|
342 will be applied. For those members that themselves are groups, it will
|
|
|
343 work as if you had activated the @samp{Set} menu item on them as well.
|
|
|
344
|
|
|
345 @node The State Button, The Customization Buttons, The Group Options, The Customization Buffer
|
|
|
346 @comment node-name, next, previous, up
|
|
|
347 @subsection The State Line and The Magic Button
|
|
|
348
|
|
|
349 The state line has two purposes. The first is to hold the state menu,
|
|
|
350 as described in the previous sections. The second is to indicate the
|
|
|
351 state of each customization item.
|
|
|
352
|
|
|
353 For the magic button, this is done by the character inside the brackets.
|
|
|
354 The following states have been defined, the first that applies to the
|
|
|
355 current item will be used:
|
|
|
356
|
|
|
357 @table @samp
|
|
|
358 @item -
|
|
|
359 The option is currently hidden. For group options that means the
|
|
|
360 members are not shown, for variables and faces that the value is not
|
|
|
361 shown. You cannot perform any of the state change operations on a
|
|
|
362 hidden customization option.
|
|
|
363
|
|
|
364 @item *
|
|
|
365 The value if this option has been modified in the buffer, but not yet
|
|
|
366 applied.
|
|
|
367
|
|
|
368 @item +
|
|
|
369 The item has has been set by the user.
|
|
|
370
|
|
|
371 @item :
|
|
|
372 The current value of this option is different from the saved value.
|
|
|
373
|
|
|
374 @item !
|
|
|
375 The saved value of this option is different from the factory setting.
|
|
|
376
|
|
|
377 @item @@
|
|
|
378 The factory setting of this option is not known. This occurs when you
|
|
|
379 try to customize variables or faces that have not been explicitly
|
|
|
380 declared as customizable.
|
|
|
381
|
|
|
382 @item SPC
|
|
|
383 The factory setting is still in effect.
|
|
|
384
|
|
|
385 @end table
|
|
|
386
|
|
|
387 For non-hidden group options, the state shown is the most severe state
|
|
|
388 of its members, where more severe means that it appears earlier in the
|
|
|
389 list above (except hidden members, which are ignored).
|
|
|
390
|
|
|
391 @node The Customization Buttons, , The State Button, The Customization Buffer
|
|
|
392 @comment node-name, next, previous, up
|
|
|
393 @subsection The Customization Buttons
|
|
|
394
|
|
|
395 The last part of the customization buffer looks like this:
|
|
|
396
|
|
|
397 @example
|
|
|
398 [Set] [Save] [Reset]
|
|
|
399 @end example
|
|
|
400
|
|
|
401 Activating the @samp{[Set]}, @samp{[Save]}, or @samp{[Reset]}
|
|
|
402 button will affect all modified customization items that are visible in
|
|
|
403 the buffer.
|
|
|
404
|
|
|
405 @node Declarations, Utilities, The Customization Buffer, Top
|
|
|
406 @comment node-name, next, previous, up
|
|
|
407 @section Declarations
|
|
|
408
|
|
|
409 @menu
|
|
|
410 * Declaring Groups::
|
|
|
411 * Declaring Variables::
|
|
|
412 * Declaring Faces::
|
|
|
413 @end menu
|
|
|
414
|
|
|
415 All the customization declarations can be changes by keyword arguments.
|
|
|
416 Groups, variables, and faces all share these common keywords:
|
|
|
417
|
|
|
418 @table @code
|
|
|
419 @item :group
|
|
|
420 @var{value} should be a customization group.
|
|
|
421 Add @var{symbol} to that group.
|
|
|
422 @item :link
|
|
|
423 @var{value} should be a widget type.
|
|
|
424 Add @var{value} to the extrenal links for this customization option.
|
|
|
425 Useful widget types include @code{custom-manual}, @code{info-link}, and
|
|
|
426 @code{url-link}.
|
|
|
427 @item :load
|
|
|
428 Add @var{value} to the files that should be loaded nefore displaying
|
|
|
429 this customization option. The value should be iether a string, which
|
|
|
430 should be a string which will be loaded with @code{load-library} unless
|
|
|
431 present in @code{load-history}, or a symbol which will be loaded with
|
|
|
432 @code{require}.
|
|
|
433 @item :tag
|
|
|
434 @var{Value} should be a short string used for identifying the option in
|
|
|
435 customization menus and buffers. By default the tag will be
|
|
|
436 automatically created from the options name.
|
|
|
437 @end table
|
|
|
438
|
|
|
439 @node Declaring Groups, Declaring Variables, Declarations, Declarations
|
|
|
440 @comment node-name, next, previous, up
|
|
|
441 @subsection Declaring Groups
|
|
|
442
|
|
|
443 Use @code{defgroup} to declare new customization groups.
|
|
|
444
|
|
|
445 @defun defgroup symbol members doc [keyword value]...
|
|
|
446 Declare @var{symbol} as a customization group containing @var{members}.
|
|
|
447 @var{symbol} does not need to be quoted.
|
|
|
448
|
|
|
449 @var{doc} is the group documentation.
|
|
|
450
|
|
|
451 @var{members} should be an alist of the form ((@var{name}
|
|
|
452 @var{widget})...) where @var{name} is a symbol and @var{widget} is a
|
|
|
453 widget for editing that symbol. Useful widgets are
|
|
|
454 @code{custom-variable} for editing variables, @code{custom-face} for
|
|
|
455 editing faces, and @code{custom-group} for editing groups.@refill
|
|
|
456
|
|
|
457 Internally, custom uses the symbol property @code{custom-group} to keep
|
|
|
458 track of the group members, and @code{group-documentation} for the
|
|
|
459 documentation string.
|
|
|
460
|
|
|
461 The following additional @var{keyword}'s are defined:
|
|
|
462
|
|
|
463 @table @code
|
|
|
464 @item :prefix
|
|
|
465 @var{value} should be a string. If the string is a prefix for the name
|
|
|
466 of a member of the group, that prefix will be ignored when creating a
|
|
|
467 tag for that member.
|
|
|
468 @end table
|
|
|
469 @end defun
|
|
|
470
|
|
|
471 @node Declaring Variables, Declaring Faces, Declaring Groups, Declarations
|
|
|
472 @comment node-name, next, previous, up
|
|
|
473 @subsection Declaring Variables
|
|
|
474
|
|
|
475 Use @code{defcustom} to declare user editable variables.
|
|
|
476
|
|
|
477 @defun defcustom symbol value doc [keyword value]...
|
|
|
478 Declare @var{symbol} as a customizable variable that defaults to @var{value}.
|
|
|
479 Neither @var{symbol} nor @var{value} needs to be quoted.
|
|
|
480 If @var{symbol} is not already bound, initialize it to @var{value}.
|
|
|
481
|
|
|
482 @var{doc} is the variable documentation.
|
|
|
483
|
|
|
484 The following additional @var{keyword}'s are defined:
|
|
|
485
|
|
|
486 @table @code
|
|
|
487 @item :type
|
|
|
488 @var{value} should be a widget type.
|
|
|
489 @item :options
|
|
|
490 @var{value} should be a list of possible members of the specified type.
|
|
|
491 For hooks, this is a list of function names.
|
|
|
492 @end table
|
|
|
493
|
|
|
494 @xref{Sexp Types,,,widget,The Widget Library}, for information about
|
|
|
495 widgets to use together with the @code{:type} keyword.
|
|
|
496 @end defun
|
|
|
497
|
|
|
498 Internally, custom uses the symbol property @code{custom-type} to keep
|
|
|
499 track of the variables type, @code{factory-value} for the program
|
|
|
500 specified default value, @code{saved-value} for a value saved by the
|
|
|
501 user, and @code{variable-documentation} for the documentation string.
|
|
|
502
|
|
|
503 Use @code{custom-add-option} to specify that a specific function is
|
|
|
504 useful as an meber of a hook.
|
|
|
505
|
|
|
506 @defun custom-add-option symbol option
|
|
|
507 To the variable @var{symbol} add @var{option}.
|
|
|
508
|
|
|
509 If @var{symbol} is a hook variable, @var{option} should be a hook
|
|
|
510 member. For other types variables, the effect is undefined."
|
|
|
511 @end defun
|
|
|
512
|
|
|
513 @node Declaring Faces, , Declaring Variables, Declarations
|
|
|
514 @comment node-name, next, previous, up
|
|
|
515 @subsection Declaring Faces
|
|
|
516
|
|
|
517 Faces are declared with @code{defface}.
|
|
|
518
|
|
|
519 @defun defface face spec doc [keyword value]...
|
|
|
520
|
|
|
521 Declare @var{face} as a customizable face that defaults to @var{spec}.
|
|
|
522 @var{face} does not need to be quoted.
|
|
|
523
|
|
|
524 If @var{face} has been set with `custom-set-face', set the face attributes
|
|
|
525 as specified by that function, otherwise set the face attributes
|
|
|
526 according to @var{spec}.
|
|
|
527
|
|
|
528 @var{doc} is the face documentation.
|
|
|
529
|
|
|
530 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
|
|
|
531
|
|
|
532 @var{atts} is a list of face attributes and their values. The possible
|
|
|
533 attributes are defined in the variable `custom-face-attributes'.
|
|
|
534 Alternatively, @var{atts} can be a face in which case the attributes of
|
|
|
535 that face is used.
|
|
|
536
|
|
|
537 The @var{atts} of the first entry in @var{spec} where the @var{display}
|
|
|
538 matches the frame should take effect in that frame. @var{display} can
|
|
|
539 either be the symbol `t', which will match all frames, or an alist of
|
|
|
540 the form @samp{((@var{req} @var{item}...)...)}@refill
|
|
|
541
|
|
|
542 For the @var{display} to match a FRAME, the @var{req} property of the
|
|
|
543 frame must match one of the @var{item}. The following @var{req} are
|
|
|
544 defined:@refill
|
|
|
545
|
|
|
546 @table @code
|
|
|
547 @item type
|
|
|
548 (the value of (window-system))@br
|
|
|
549 Should be one of @code{x} or @code{tty}.
|
|
|
550
|
|
|
551 @item class
|
|
|
552 (the frame's color support)@br
|
|
|
553 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
|
|
|
554
|
|
|
555 @item background
|
|
|
556 (what color is used for the background text)@br
|
|
|
557 Should be one of @code{light} or @code{dark}.
|
|
|
558 @end table
|
|
|
559
|
|
|
560 Internally, custom uses the symbol property @code{factory-face} for the
|
|
|
561 program specified default face properties, @code{saved-face} for
|
|
|
562 properties saved by the user, and @code{face-documentation} for the
|
|
|
563 documentation string.@refill
|
|
|
564
|
|
|
565 @end defun
|
|
|
566
|
|
|
567 @node Utilities, The Init File, Declarations, Top
|
|
|
568 @comment node-name, next, previous, up
|
|
|
569 @section Utilities
|
|
|
570
|
|
|
571 These utilities can come in handy when adding customization support.
|
|
|
572
|
|
|
573 @deffn Widget custom-manual
|
|
|
574 Widget type for specifying the info manual entry for a customization
|
|
|
575 option. It takes one argument, an info address.
|
|
|
576 @end deffn
|
|
|
577
|
|
|
578 @defun custom-add-to-group group member widget
|
|
|
579 To existing @var{group} add a new @var{member} of type @var{widget},
|
|
|
580 If there already is an entry for that member, overwrite it.
|
|
|
581 @end defun
|
|
|
582
|
|
|
583 @defun custom-add-link symbol widget
|
|
|
584 To the custom option @var{symbol} add the link @var{widget}.
|
|
|
585 @end defun
|
|
|
586
|
|
|
587 @defun custom-add-load symbol load
|
|
|
588 To the custom option @var{symbol} add the dependency @var{load}.
|
|
|
589 @var{load} should be either a library file name, or a feature name.
|
|
|
590 @end defun
|
|
|
591
|
|
|
592 @defun custom-menu-create symbol &optional name
|
|
|
593 Create menu for customization group @var{symbol}.
|
|
|
594 If optional @var{name} is given, use that as the name of the menu.
|
|
|
595 Otherwise make up a name from @var{symbol}.
|
|
|
596 The menu is in a format applicable to @code{easy-menu-define}.
|
|
|
597 @end defun
|
|
|
598
|
|
|
599 @node The Init File, Wishlist, Utilities, Top
|
|
|
600 @comment node-name, next, previous, up
|
|
|
601 @section The Init File
|
|
|
602
|
|
|
603 When you save the customizations, call to @code{custom-set-variables},
|
|
|
604 @code{custom-set-faces} are inserted into the file specified by
|
|
|
605 @code{custom-file}. By default @code{custom-file} is your @file{.emacs}
|
|
|
606 file. The two functions will initialize variables and faces as you have
|
|
|
607 specified.
|
|
|
608
|
|
|
609 @node Wishlist, , The Init File, Top
|
|
|
610 @comment node-name, next, previous, up
|
|
|
611 @section Wishlist
|
|
|
612
|
|
|
613 @itemize @bullet
|
|
|
614 @item
|
|
|
615 The menu items should be grayed out when the information is
|
|
|
616 missing. I.e. if a variable doesn't have a factory setting, the user
|
|
|
617 should not be allowed to select the @samp{Factory} menu item.
|
|
|
618
|
|
|
619 @item
|
|
|
620 We need @strong{much} better support for keyboard operations in the
|
|
|
621 customize buffer.
|
|
|
622
|
|
|
623 @item
|
|
|
624 Support real specifiers under XEmacs.
|
|
|
625
|
|
|
626 @item
|
|
|
627 Integrate with @file{w3} so you can customization buffers with much
|
|
|
628 better formatting. I'm thinking about adding a <custom>name</custom>
|
|
|
629 tag.
|
|
|
630
|
|
|
631 @item
|
|
|
632 Add an `examples' section, with explained examples of custom type
|
|
|
633 definitions.
|
|
|
634
|
|
|
635 @item
|
|
|
636 Support undo using lmi's @file{gnus-undo.el}.
|
|
|
637
|
|
|
638 @item
|
|
|
639 Make it possible to append to `choice', `radio', and `set' options.
|
|
|
640
|
|
|
641 @end itemize
|
|
|
642
|
|
|
643 @contents
|
|
|
644 @bye
|
