5 @settitle The Customization Library
15 * The Customization Buffer::
17 * Declaring Variables::
23 @node Top, Introduction, (dir), (dir)
24 @comment node-name, next, previous, up
25 @top The Customization Library
32 * The Customization Buffer::
34 * Declaring Variables::
40 @node Introduction, User Commands, Top, Top
41 @comment node-name, next, previous, up
44 This library allows customization of @dfn{user options}. Currently two
45 types of user options are supported, namely @dfn{variables} and
46 @dfn{faces}. Each user option can have four different values
50 The value specified by the programmer.
52 The value specified by the user as the default for this variable. This
53 overwrites the factory setting when starting a new emacs.
55 The value used by Emacs. This will not be remembered next time you
58 The value entered by the user in a customization buffer, but not yet
62 Variables also have a @dfn{type}, which specifies what kind of values
63 the variable can hold, and how the value is presented in a customization
64 buffer. By default a variable can hold any valid expression, but the
65 programmer can specify a more limited type when declaring the variable.
67 The user options are organized in a number of @dfn{groups}. Each group
68 can contain a number user options, as well as other groups. The groups
69 allows the user to concentrate on a specific part of emacs.
71 @node User Commands, The Customization Buffer, Introduction, Top
72 @comment node-name, next, previous, up
73 @section User Commands
75 The following commands will create a customization buffer:
79 Create a customization buffer containing a specific group, by default
80 the @code{emacs} group.
82 @item customize-variable
83 Create a customization buffer containing a single variable.
86 Create a customization buffer containing a single face.
88 @item customize-apropos
89 Create a customization buffer containing all variables, faces, and
90 groups that match a user specified regular expression.
93 @node The Customization Buffer, Declaring Groups, User Commands, Top
94 @comment node-name, next, previous, up
95 @section The Customization Buffer.
97 The customization buffer allows the user to make temporary or permanent
98 changes to how specific aspects of emacs works, by setting and editing
101 The customization buffer contains three types of text:
104 @item informative text
105 where the normal editing commands are disabled.
107 @item editable fields
108 where you can edit with the usual emacs commands. Editable fields are
109 usually displayed with a grey background if your terminal supports
110 colors, or an italic font otherwise.
113 which can be activated by either pressing the @kbd{@key{ret}} while
114 point is located on the text, or pushing @kbd{mouse-2} while the mouse
115 pointer is above the tex. Buttons are usually displayed in a bold
119 You can move to the next the next editable field or button by pressing
120 @kbd{@key{tab}} or the previous with @kbd{M-@key{tab}}. Some buttons
121 have a small helpful message about their purpose, which will be
122 displayed when you move to it with the @key{tab} key.
124 The buffer is divided into three part, an introductory text, a list of
125 customization options, and a line of customization buttons. Each part
126 will be described in the following.
129 * The Introductory Text::
130 * The Customization Options::
131 * The Variable Options::
133 * The Group Options::
135 * The Customization Buttons::
138 @node The Introductory Text, The Customization Options, The Customization Buffer, The Customization Buffer
139 @comment node-name, next, previous, up
140 @subsection The Introductory Text
142 The start of the buffer contains a short explanation of what it is, and
143 how to get help. It will typically look like this:
146 This is a customization buffer.
147 Push RET or click mouse-2 on the word _help_ for more information.
150 Rather boring. It is mostly just informative text, but the word
151 @samp{help} is a button that will bring up this document when
154 @node The Customization Options, The Variable Options, The Introductory Text, The Customization Buffer
155 @comment node-name, next, previous, up
156 @subsection The Customization Options
158 Each customization option looks similar to the following text:
161 *** custom-background-mode: default
162 [ ] [?] The brightness of the background.
165 The option contains the parts described below.
169 The Level Button. The customization options in the buffer are organized
170 in a hierarchy, which is indicated by the number of stars in the level
171 button. The top level options will be shown as @samp{*}. When they are
172 expanded, the suboptions will be shown as @samp{**}. The example option
173 is thus a subsuboption.
175 Activating the level buttons will toggle between hiding and exposing the
176 content of that option. The content can either be the value of the
177 option, as in this example, or a list of suboptions.
179 @item custom-background-mode
180 This is the tag of the the option. The tag is a name of a variable, a
181 face, or customization group. Activating the tag has an effect that
182 depends on the exact type of the option. In this particular case,
183 activating the tag will bring up a menu that will allow you to choose
184 from the three possible values of the `custom-background-mode'
188 After the tag, the options value is shown. Depending on its type, you
189 may be able to edit the value directly. If an option should contain a
190 file name, it is displayed in an editable field, i.e. you can edit it
191 using the standard emacs editing commands.
194 The state button. This look of this button will indicate the state of
195 the option, e.g. whether it is currently hidden, or whether it has been
196 modified or not. Activating the button will allow you to change the
197 state, e.g. apply or reset the changes you have made. This is explained
198 in detail in the following sections.
201 The documentation button. If the documentation is more than one line,
202 this button will be present. Activating the button will toggle whether
203 the complete documentation is shown, or only the first line.
205 @item The brightness of the background.
206 This is a documentation string explaining the purpose of this particular
207 customization option.
211 @node The Variable Options, The Face Options, The Customization Options, The Customization Buffer
212 @comment node-name, next, previous, up
213 @subsection The Variable Options
215 The most common customization options are emacs lisp variables. The
216 actual editing of these variables depend on what type values the
217 variable is expected to contain. For example, a lisp variable whose
218 value should be a string will typically be represented with an editable
219 text field in the buffer, where you can change the string directly. If
220 the value is a list, each item in the list will be presented in the
221 buffer buffer on a separate line, with buttons to insert new items in
222 the list, or delete existing items from the list. You may want to see
223 @ref{User Interface,,, widget, The Widget Library}, where some examples
224 of editing are discussed.
226 You can either choose to edit the value directly, or edit the default
227 value for that variable. The default value is a lisp expression that
228 will be evaluated when you start emacs. The result of the evaluation
229 will be used as the initial value for that variable. Editing the
230 default value is for experts only, but if the current value of the
231 variable is of a wrong type (i.e. a symbol where a string is expected),
232 the `edit default' mode will always be selected.
234 You can see what mode is currently selected by looking at the state
235 button. If it uses parenthesises (like @samp{( )}) it is in `Edit
236 default' mode, with square brackets (like @samp{[ ]}) it is normal edit
237 mode. You can switch mode by activating the state button, and select
238 either @samp{Edit} or @samp{Edit default} from the menu.
240 You can change the state of the variable with the other menu items:
244 When you have made your modifications in the buffer, you need to
245 activate this item to make the modifications take effect. The
246 modifications will be forgotten next time you run emacs.
249 Unless you activate this item instead! This will mark the modification
250 as permanent, i.e. the changes will be remembered in the next emacs
254 If you have made some modifications and not yet applied them, you can
255 undo the modification by activating this item.
257 @item Reset to Default
258 Activating this item will reset the value of the variable to the last
259 value you marked as permanent with `Set Default'.
261 @item Reset to Factory Settings
262 Activating this item will undo all modifications you have made, and
263 reset the value to the initial value specified by the program itself.
266 By default, the value of large or complicated variables are hidden. You
267 can show the value by clicking on the level button.
269 @node The Face Options, The Group Options, The Variable Options, The Customization Buffer
270 @comment node-name, next, previous, up
271 @subsection The Face Options
273 A face is an object that controls the appearance of some buffer text.
274 The face has a number of possible attributes, such as boldness,
275 foreground color, and more. For each attribute you can specify whether
276 this attribute is controlled by the face, and if so, what the value is.
277 For example, if the attribute bold is not controlled by a face, using
278 that face on some buffer text will not affect its boldness. If the bold
279 attribute is controlled by the face, it can be turned either on or of.
281 It is possible to specify that a face should have different attributes
282 on different device types. For example, a face may make text red on a
283 color device, and bold on a monochrome device.
285 The way this is presented in the customization buffer is to have a list
286 of display specifications, and for each display specification a list of
287 face attributes. For each face attribute, there is a checkbox
288 specifying whether this attribute has effect and what the value is.
292 *** custom-invalid-face: (sample)
293 [ ] Face used when the customize item is invalid.
294 [INS] [DEL] Display: [ ] Type: [ ] X [ ] TTY
295 [X] Class: [X] Color [ ] Grayscale [ ] Monochrome
296 [ ] Background: [ ] Light [ ] Dark
297 Attributes: [ ] Bold: off
300 [X] Foreground: yellow (sample)
301 [X] Background: red (sample)
303 [INS] [DEL] Display: all
304 Attributes: [X] Bold: on
307 [ ] Foreground: default (sample)
308 [ ] Background: default (sample)
313 This has two display specifications. The first will match all color
314 displays, independently on whether the device is X11 or a tty, and
315 whether background color is dark or light. For devices matching this
316 specification, @samp{custom-invalid-face} will force text to be
317 displayed in yellow on red, but leave all other attributes alone.
319 The second display will simply match everything. Since the list is
320 prioritised, this means that it will match all non-color displays. For
321 these, the face will not affect the foreground or background color, but
322 force the font to be both bold, italic, and underline.
324 You can add or delete display specifications by activating the
325 @samp{[INS]} and @samp{[DEL]} buttons, and modify them by clicking on
326 the check boxes. The first checkbox in each line in the display
327 specification is special. It specify whether this particular property
328 will even be relevant. By not checking the box in the first display, we
329 match all device types, also device types other than X11 and tty, for
330 example ms-windows, nextstep, and mac os.
332 After modifying the face, you can activate the state button to make the
333 changes take effect. The menu items in the state button menu is similar
334 to the state menu items for variables described in the previous section.
336 @node The Group Options, The State Button, The Face Options, The Customization Buffer
337 @comment node-name, next, previous, up
338 @subsection The Group Options
340 Since Emacs has approximately a zillion configuration options, they have
341 been organized in groups. Each group can contain other groups, thus
342 creating a customization hierarchy. The nesting of the customization
343 within the visible part of this hierarchy is indicated by the number of
344 stars in the level button.
346 Since there is really no customization needed for the group itself, the
347 menu items in the groups state button will affect all modified group
348 members recursively. Thus, if you activate the @samp{Apply} menu item,
349 all variables and faces that have been modified and belong to that group
350 will be applied. For those members that themselves are groups, it will
351 work as if you had activated the @samp{Apply} menu item on them as well.
353 @node The State Button, The Customization Buttons, The Group Options, The Customization Buffer
354 @comment node-name, next, previous, up
355 @subsection The State Button
357 The state button has two purposes. The first is to hold the state menu,
358 as described in the previous sections. The second is to indicate the
359 state of each customization item. This is done by the character inside
360 the brackets. The following states have been defined, the first that
361 applies to the current item will be used:
365 The option is currently hidden. For group options that means the
366 members are not shown, for variables and faces that the value is not
367 shown. You cannot perform any of the state change operations on a
368 hidden customization option.
371 The value if this option has been modified in the buffer, but not yet
375 The current value of this option is different from the default value.
378 The default value of this option is different from the factory setting.
381 The factory setting of this option is not known. This occurs when you
382 try to customize variables or faces that have not been explicitly
383 declared as customizable.
386 The factory setting is still in effect.
390 For non-hidden group options, the state shown is the most severe state
391 of its members, where more severe means that it appears earlier in the
392 list above (except hidden members, which are ignored).
394 @node The Customization Buttons, , The State Button, The Customization Buffer
395 @comment node-name, next, previous, up
396 @subsection The Customization Buttons
398 The last part of the customization buffer looks like this:
401 [Apply] [Set Default] [Reset] [Save]
404 Activating the @samp{[Apply]}, @samp{[Set Default]}, or @samp{[Reset]}
405 button will affect all modified customization items that are visible in
408 Activating the @samp{[Save]} button will ensure that all customization
409 options who are marked as persistent with @samp{Set default} (either
410 with the button at the end of the buffer, or with any of the state
411 button menus), will actually be saved in your initialization file.
413 @node Declaring Groups, Declaring Variables, The Customization Buffer, Top
414 @comment node-name, next, previous, up
415 @section Declaring Groups
417 Use @code{defgroup} to declare new customization groups.
419 @defun defgroup symbol members doc [keyword value]...
420 Declare @var{symbol} as a customization group containing @var{members}.
421 @var{symbol} does not need to be quoted.
423 @var{doc} is the group documentation.
425 @var{members} should be an alist of the form ((@var{name}
426 @var{widget})...) where @var{name} is a symbol and @var{widget} is a
427 widget for editing that symbol. Useful widgets are
428 @code{custom-variable} for editing variables, @code{custom-face} for
429 editing faces, and @code{custom-group} for editing groups.@refill
431 The following @var{keyword}'s are defined:
435 @var{value} should be a customization group.
436 Add @var{symbol} to that group.
440 Internally, custom uses the symbol property @code{custom-group} to keep
441 track of the group members, and @code{group-documentation} for the
442 documentation string.
444 @node Declaring Variables, Declaring Faces, Declaring Groups, Top
445 @comment node-name, next, previous, up
446 @section Declaring Variables
448 Use @code{defcustom} to declare user editable variables.
450 @defun defcustom symbol value doc [keyword value]...
451 Declare @var{symbol} as a customizable variable that defaults to @var{value}.
452 Neither @var{symbol} nor @var{value} needs to be quoted.
453 If @var{symbol} is not already bound, initialize it to @var{value}.
455 @var{doc} is the variable documentation.
457 The following @var{keyword}'s are defined:
461 @var{value} should be a widget type.
463 @var{value} should be a list of possible members of the specified type.
464 For hooks, this is a list of function names.
466 @var{value} should be a customization group.
467 Add @var{symbol} to that group.
470 @xref{Sexp Types,,,widget,The Widget Library}, for information about
471 widgets to use together with the @code{:type} keyword.
474 Internally, custom uses the symbol property @code{custom-type} to keep
475 track of the variables type, @code{factory-value} for the program
476 specified default value, @code{default-value} for a user specified
477 default value, and @code{variable-documentation} for the documentation
481 @node Declaring Faces, The Init File, Declaring Variables, Top
482 @comment node-name, next, previous, up
483 @section Declaring Faces
485 Faces are declared with @code{defface}.
487 @defun defface face spec doc [keyword value]...
489 Declare @var{face} as a customizable face that defaults to @var{spec}.
490 @var{face} does not need to be quoted.
492 If @var{face} has been set with `custom-set-face', set the face attributes
493 as specified by that function, otherwise set the face attributes
494 according to @var{spec}.
496 @var{doc} is the face documentation.
498 The following @var{keyword}'s are defined:
502 @var{value} should be a customization group.
503 Add @var{symbol} to that group.
506 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
508 @var{atts} is a list of face attributes and their values. The possible
509 attributes are defined in the variable `custom-face-attributes'.
510 Alternatively, @var{atts} can be a face in which case the attributes of
513 The @var{atts} of the first entry in @var{spec} where the @var{display}
514 matches the frame should take effect in that frame. @var{display} can
515 either be the symbol `t', which will match all frames, or an alist of
516 the form @samp{((@var{req} @var{item}...)...)}@refill
518 For the @var{display} to match a FRAME, the @var{req} property of the
519 frame must match one of the @var{item}. The following @var{req} are
524 (the value of (window-system))@br
525 Should be one of @code{x} or @code{tty}.
528 (the frame's color support)@br
529 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
532 (what color is used for the background text)@br
533 Should be one of @code{light} or @code{dark}.
536 Internally, custom uses the symbol property @code{factory-face} for the
537 program specified default face properties, @code{default-face} for a
538 user specified default properties, and @code{face-documentation} for the
539 documentation string.@refill
543 @node The Init File, Wishlist, Declaring Faces, Top
544 @comment node-name, next, previous, up
545 @section The Init File
547 When you save the customizations, call to @code{custom-set-variables},
548 @code{custom-set-faces} are inserted into the file specified by
549 @code{custom-file}. By default @code{custom-file} is your @file{.emacs}
550 file. The two functions will initialize variables and faces as you have
553 @node Wishlist, , The Init File, Top
554 @comment node-name, next, previous, up
559 The menu items should be grayed out when the information is
560 missing. I.e. if a variable doesn't have a factory setting, the user
561 should not be allowed to select the @samp{Factory} menu item.
564 We need @strong{much} better support for keyboard operations in the
568 There should be a function to create a customize menu from a group.
571 There should be a `Help | Customize' entry in the menu bar with a user
572 specified number of levels of submenus.
575 It would be nice if one could set simple variables directly from the
579 Support real specifiers under XEmacs.
582 Integrate with @file{w3} so you can customization buffers with much
583 better formatting. I'm thinking about adding a <custom>name</custom>
587 Try to keep track of whether it is necessary to save or not.
590 Offer to save if you exit emacs with unsaved customizations.