5 @settitle The Customization Library
12 @node Top, Introduction, (dir), (dir)
13 @comment node-name, next, previous, up
14 @top The Customization Library
21 * The Customization Buffer::
28 @node Introduction, User Commands, Top, Top
29 @comment node-name, next, previous, up
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
38 The value specified by the programmer.
40 The value saved by the user as the default for this variable. This
41 overwrites the factory setting when starting a new emacs.
43 The value used by Emacs. This will not be remembered next time you
46 The value entered by the user in a customization buffer, but not yet
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.
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.
59 @node User Commands, The Customization Buffer, Introduction, Top
60 @comment node-name, next, previous, up
61 @section User Commands
63 The following commands will create a customization buffer:
67 Create a customization buffer containing a specific group, by default
68 the @code{emacs} group.
70 @item customize-variable
71 Create a customization buffer containing a single variable.
74 Create a customization buffer containing a single face.
76 @item customize-apropos
77 Create a customization buffer containing all variables, faces, and
78 groups that match a user specified regular expression.
81 @node The Customization Buffer, Declarations, User Commands, Top
82 @comment node-name, next, previous, up
83 @section The Customization Buffer.
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
89 The customization buffer contains three types of text:
92 @item informative text
93 where the normal editing commands are disabled.
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.
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
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.
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.
117 * The Introductory Text::
118 * The Customization Options::
119 * The Variable Options::
121 * The Group Options::
123 * The Customization Buttons::
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
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:
134 This is a customization buffer.
135 Push RET or click mouse-2 on the word _help_ for more information.
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
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
146 Each customization option looks similar to the following text:
149 *** custom-background-mode: default
150 [ ] [?] The brightness of the background.
153 The option contains the parts described below.
157 The Level Button. The customization options in the buffer are organized
158 in a hierarchy, which is indicated by the number of stars in the level
159 button. The top level options will be shown as @samp{*}. When they are
160 expanded, the suboptions will be shown as @samp{**}. The example option
161 is thus a subsuboption.
163 Activating the level buttons will toggle between hiding and exposing the
164 content of that option. The content can either be the value of the
165 option, as in this example, or a list of suboptions.
167 @item custom-background-mode
168 This is the tag of the the option. The tag is a name of a variable, a
169 face, or customization group. Activating the tag has an effect that
170 depends on the exact type of the option. In this particular case,
171 activating the tag will bring up a menu that will allow you to choose
172 from the three possible values of the `custom-background-mode'
176 After the tag, the options value is shown. Depending on its type, you
177 may be able to edit the value directly. If an option should contain a
178 file name, it is displayed in an editable field, i.e. you can edit it
179 using the standard emacs editing commands.
182 The state button. This look of this button will indicate the state of
183 the option, e.g. whether it is currently hidden, or whether it has been
184 modified or not. Activating the button will allow you to change the
185 state, e.g. set or reset the changes you have made. This is explained
186 in detail in the following sections.
189 The documentation button. If the documentation is more than one line,
190 this button will be present. Activating the button will toggle whether
191 the complete documentation is shown, or only the first line.
193 @item The brightness of the background.
194 This is a documentation string explaining the purpose of this particular
195 customization option.
199 @node The Variable Options, The Face Options, The Customization Options, The Customization Buffer
200 @comment node-name, next, previous, up
201 @subsection The Variable Options
203 The most common customization options are emacs lisp variables. The
204 actual editing of these variables depend on what type values the
205 variable is expected to contain. For example, a lisp variable whose
206 value should be a string will typically be represented with an editable
207 text field in the buffer, where you can change the string directly. If
208 the value is a list, each item in the list will be presented in the
209 buffer buffer on a separate line, with buttons to insert new items in
210 the list, or delete existing items from the list. You may want to see
211 @ref{User Interface,,, widget, The Widget Library}, where some examples
212 of editing are discussed.
214 You can either choose to edit the value directly, or edit the lisp
215 value for that variable. The lisp value is a lisp expression that
216 will be evaluated when you start emacs. The result of the evaluation
217 will be used as the initial value for that variable. Editing the
218 lisp value is for experts only, but if the current value of the
219 variable is of a wrong type (i.e. a symbol where a string is expected),
220 the `edit lisp' mode will always be selected.
222 You can see what mode is currently selected by looking at the state
223 button. If it uses parenthesises (like @samp{( )}) it is in edit lisp
224 mode, with square brackets (like @samp{[ ]}) it is normal edit mode.
225 You can switch mode by activating the state button, and select either
226 @samp{Edit} or @samp{Edit lisp} from the menu.
228 You can change the state of the variable with the other menu items:
232 When you have made your modifications in the buffer, you need to
233 activate this item to make the modifications take effect. The
234 modifications will be forgotten next time you run emacs.
237 Unless you activate this item instead! This will mark the modification
238 as permanent, i.e. the changes will be remembered in the next emacs
242 If you have made some modifications and not yet applied them, you can
243 undo the modification by activating this item.
246 Activating this item will reset the value of the variable to the last
247 value you marked as permanent with `Save'.
249 @item Reset to Factory Settings
250 Activating this item will undo all modifications you have made, and
251 reset the value to the initial value specified by the program itself.
254 By default, the value of large or complicated variables are hidden. You
255 can show the value by clicking on the level button.
257 @node The Face Options, The Group Options, The Variable Options, The Customization Buffer
258 @comment node-name, next, previous, up
259 @subsection The Face Options
261 A face is an object that controls the appearance of some buffer text.
262 The face has a number of possible attributes, such as boldness,
263 foreground color, and more. For each attribute you can specify whether
264 this attribute is controlled by the face, and if so, what the value is.
265 For example, if the attribute bold is not controlled by a face, using
266 that face on some buffer text will not affect its boldness. If the bold
267 attribute is controlled by the face, it can be turned either on or of.
269 It is possible to specify that a face should have different attributes
270 on different device types. For example, a face may make text red on a
271 color device, and bold on a monochrome device.
273 The way this is presented in the customization buffer is to have a list
274 of display specifications, and for each display specification a list of
275 face attributes. For each face attribute, there is a checkbox
276 specifying whether this attribute has effect and what the value is.
280 *** custom-invalid-face: (sample)
281 [ ] Face used when the customize item is invalid.
282 [INS] [DEL] Display: [ ] Type: [ ] X [ ] TTY
283 [X] Class: [X] Color [ ] Grayscale [ ] Monochrome
284 [ ] Background: [ ] Light [ ] Dark
285 Attributes: [ ] Bold: off
288 [X] Foreground: yellow (sample)
289 [X] Background: red (sample)
291 [INS] [DEL] Display: all
292 Attributes: [X] Bold: on
295 [ ] Foreground: default (sample)
296 [ ] Background: default (sample)
301 This has two display specifications. The first will match all color
302 displays, independently on whether the device is X11 or a tty, and
303 whether background color is dark or light. For devices matching this
304 specification, @samp{custom-invalid-face} will force text to be
305 displayed in yellow on red, but leave all other attributes alone.
307 The second display will simply match everything. Since the list is
308 prioritised, this means that it will match all non-color displays. For
309 these, the face will not affect the foreground or background color, but
310 force the font to be both bold, italic, and underline.
312 You can add or delete display specifications by activating the
313 @samp{[INS]} and @samp{[DEL]} buttons, and modify them by clicking on
314 the check boxes. The first checkbox in each line in the display
315 specification is special. It specify whether this particular property
316 will even be relevant. By not checking the box in the first display, we
317 match all device types, also device types other than X11 and tty, for
318 example ms-windows, nextstep, and mac os.
320 After modifying the face, you can activate the state button to make the
321 changes take effect. The menu items in the state button menu is similar
322 to the state menu items for variables described in the previous section.
324 @node The Group Options, The State Button, The Face Options, The Customization Buffer
325 @comment node-name, next, previous, up
326 @subsection The Group Options
328 Since Emacs has approximately a zillion configuration options, they have
329 been organized in groups. Each group can contain other groups, thus
330 creating a customization hierarchy. The nesting of the customization
331 within the visible part of this hierarchy is indicated by the number of
332 stars in the level button.
334 Since there is really no customization needed for the group itself, the
335 menu items in the groups state button will affect all modified group
336 members recursively. Thus, if you activate the @samp{Set} menu item,
337 all variables and faces that have been modified and belong to that group
338 will be applied. For those members that themselves are groups, it will
339 work as if you had activated the @samp{Set} menu item on them as well.
341 @node The State Button, The Customization Buttons, The Group Options, The Customization Buffer
342 @comment node-name, next, previous, up
343 @subsection The State Button
345 The state button has two purposes. The first is to hold the state menu,
346 as described in the previous sections. The second is to indicate the
347 state of each customization item. This is done by the character inside
348 the brackets. The following states have been defined, the first that
349 applies to the current item will be used:
353 The option is currently hidden. For group options that means the
354 members are not shown, for variables and faces that the value is not
355 shown. You cannot perform any of the state change operations on a
356 hidden customization option.
359 The value if this option has been modified in the buffer, but not yet
363 The item has has been set by the user.
366 The current value of this option is different from the saved value.
369 The saved value of this option is different from the factory setting.
372 The factory setting of this option is not known. This occurs when you
373 try to customize variables or faces that have not been explicitly
374 declared as customizable.
377 The factory setting is still in effect.
381 For non-hidden group options, the state shown is the most severe state
382 of its members, where more severe means that it appears earlier in the
383 list above (except hidden members, which are ignored).
385 @node The Customization Buttons, , The State Button, The Customization Buffer
386 @comment node-name, next, previous, up
387 @subsection The Customization Buttons
389 The last part of the customization buffer looks like this:
395 Activating the @samp{[Set]}, @samp{[Save]}, or @samp{[Reset]}
396 button will affect all modified customization items that are visible in
399 @node Declarations, Utilities, The Customization Buffer, Top
400 @comment node-name, next, previous, up
401 @section Declarations
405 * Declaring Variables::
409 All the customization declarations can be changes by keyword arguments.
410 Groups, variables, and faces all share these common keywords:
414 @var{value} should be a customization group.
415 Add @var{symbol} to that group.
417 @var{value} should be a widget type.
418 Add @var{value} to the extrenal links for this customization option.
419 Useful widget types include @code{custom-manual}, @code{info-link}, and
422 Add @var{value} to the files that should be loaded nefore displaying
423 this customization option. The value should be iether a string, which
424 should be a string which will be loaded with @code{load-library} unless
425 present in @code{load-history}, or a symbol which will be loaded with
428 @var{Value} should be a short string used for identifying the option in
429 customization menus and buffers. By default the tag will be
430 automatically created from the options name.
433 @node Declaring Groups, Declaring Variables, Declarations, Declarations
434 @comment node-name, next, previous, up
435 @subsection Declaring Groups
437 Use @code{defgroup} to declare new customization groups.
439 @defun defgroup symbol members doc [keyword value]...
440 Declare @var{symbol} as a customization group containing @var{members}.
441 @var{symbol} does not need to be quoted.
443 @var{doc} is the group documentation.
445 @var{members} should be an alist of the form ((@var{name}
446 @var{widget})...) where @var{name} is a symbol and @var{widget} is a
447 widget for editing that symbol. Useful widgets are
448 @code{custom-variable} for editing variables, @code{custom-face} for
449 editing faces, and @code{custom-group} for editing groups.@refill
451 Internally, custom uses the symbol property @code{custom-group} to keep
452 track of the group members, and @code{group-documentation} for the
453 documentation string.
455 The following additional @var{keyword}'s are defined:
459 @var{value} should be a string. If the string is a prefix for the name
460 of a member of the group, that prefix will be ignored when creating a
464 @node Declaring Variables, Declaring Faces, Declaring Groups, Declarations
465 @comment node-name, next, previous, up
466 @subsection Declaring Variables
468 Use @code{defcustom} to declare user editable variables.
470 @defun defcustom symbol value doc [keyword value]...
471 Declare @var{symbol} as a customizable variable that defaults to @var{value}.
472 Neither @var{symbol} nor @var{value} needs to be quoted.
473 If @var{symbol} is not already bound, initialize it to @var{value}.
475 @var{doc} is the variable documentation.
477 The following additional @var{keyword}'s are defined:
481 @var{value} should be a widget type.
483 @var{value} should be a list of possible members of the specified type.
484 For hooks, this is a list of function names.
487 @xref{Sexp Types,,,widget,The Widget Library}, for information about
488 widgets to use together with the @code{:type} keyword.
491 Internally, custom uses the symbol property @code{custom-type} to keep
492 track of the variables type, @code{factory-value} for the program
493 specified default value, @code{saved-value} for a value saved by the
494 user, and @code{variable-documentation} for the documentation string.
496 Use @code{custom-add-option} to specify that a specific function is
497 useful as an meber of a hook.
499 @defun custom-add-option symbol option
500 To the variable @var{symbol} add @var{option}.
502 If @var{symbol} is a hook variable, @var{option} should be a hook
503 member. For other types variables, the effect is undefined."
506 @node Declaring Faces, , Declaring Variables, Declarations
507 @comment node-name, next, previous, up
508 @subsection Declaring Faces
510 Faces are declared with @code{defface}.
512 @defun defface face spec doc [keyword value]...
514 Declare @var{face} as a customizable face that defaults to @var{spec}.
515 @var{face} does not need to be quoted.
517 If @var{face} has been set with `custom-set-face', set the face attributes
518 as specified by that function, otherwise set the face attributes
519 according to @var{spec}.
521 @var{doc} is the face documentation.
523 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
525 @var{atts} is a list of face attributes and their values. The possible
526 attributes are defined in the variable `custom-face-attributes'.
527 Alternatively, @var{atts} can be a face in which case the attributes of
530 The @var{atts} of the first entry in @var{spec} where the @var{display}
531 matches the frame should take effect in that frame. @var{display} can
532 either be the symbol `t', which will match all frames, or an alist of
533 the form @samp{((@var{req} @var{item}...)...)}@refill
535 For the @var{display} to match a FRAME, the @var{req} property of the
536 frame must match one of the @var{item}. The following @var{req} are
541 (the value of (window-system))@br
542 Should be one of @code{x} or @code{tty}.
545 (the frame's color support)@br
546 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
549 (what color is used for the background text)@br
550 Should be one of @code{light} or @code{dark}.
553 Internally, custom uses the symbol property @code{factory-face} for the
554 program specified default face properties, @code{saved-face} for
555 properties saved by the user, and @code{face-documentation} for the
556 documentation string.@refill
560 @node Utilities, The Init File, Declarations, Top
561 @comment node-name, next, previous, up
564 These utilities can come in handy when adding customization support.
566 @deffn Widget custom-manual
567 Widget type for specifying the info manual entry for a customization
568 option. It takes one argument, an info address.
571 @defun custom-add-to-group group member widget
572 To existing @var{group} add a new @var{member} of type @var{widget},
573 If there already is an entry for that member, overwrite it.
576 @defun custom-add-link symbol widget
577 To the custom option @var{symbol} add the link @var{widget}.
580 @defun custom-add-load symbol load
581 To the custom option @var{symbol} add the dependency @var{load}.
582 @var{load} should be either a library file name, or a feature name.
585 @defun custom-menu-create symbol &optional name
586 Create menu for customization group @var{symbol}.
587 If optional @var{name} is given, use that as the name of the menu.
588 Otherwise make up a name from @var{symbol}.
589 The menu is in a format applicable to @code{easy-menu-define}.
592 @node The Init File, Wishlist, Utilities, Top
593 @comment node-name, next, previous, up
594 @section The Init File
596 When you save the customizations, call to @code{custom-set-variables},
597 @code{custom-set-faces} are inserted into the file specified by
598 @code{custom-file}. By default @code{custom-file} is your @file{.emacs}
599 file. The two functions will initialize variables and faces as you have
602 @node Wishlist, , The Init File, Top
603 @comment node-name, next, previous, up
608 The menu items should be grayed out when the information is
609 missing. I.e. if a variable doesn't have a factory setting, the user
610 should not be allowed to select the @samp{Factory} menu item.
613 We need @strong{much} better support for keyboard operations in the
617 Support real specifiers under XEmacs.
620 Integrate with @file{w3} so you can customization buffers with much
621 better formatting. I'm thinking about adding a <custom>name</custom>
625 Add an `examples' section, with explained examples of custom type