Here is an example of what a variable, or user option, looks like in the customization buffer:
[Hide] Kill Ring Max: 60 [State]: STANDARD. Maximum length of kill ring before oldest elements are thrown away.
The first line shows that the variable is named
kill-ring-max, formatted as ‘
Kill Ring Max’ for easier
viewing. Its value is ‘
60’. The button labeled ‘
if activated, hides the variable’s value and state; this is useful to
avoid cluttering up the customization buffer with very long values
(for this reason, variables that have very long values may start out
hidden). If you use the ‘
[Hide]’ button, it changes to
[Show Value]’, which you can activate to reveal the value and
state. On a graphical display, the ‘
[Hide]’ and ‘
[Show Value]’ buttons are replaced with graphical triangles pointing
downwards and rightwards respectively.
The line after the variable name indicates the customization
state of the variable: in this example, ‘
STANDARD’ means you
have not changed the variable, so its value is the default one. The
[State]’ button gives a menu of operations for customizing the
Below the customization state is the documentation for the variable.
This is the same documentation that would be shown by the C-h v
command (see Examining). If the documentation is more than one
line long, only one line may be shown. If so, that line ends with a
[More]’ button; activate this to see the full documentation.
To enter a new value for ‘
Kill Ring Max’, just move point to
the value and edit it. For example, type M-d to delete the
60’ and type in another number. As you begin to alter the text,
[State]’ line will change:
[State]: EDITED, shown value does not take effect until you set or save it.
Editing the value does not make it take effect right away. To do
that, you must set the variable by activating the ‘
button and choosing ‘
Set for Current Session’. Then the
variable’s state becomes:
[State]: SET for current session only.
You don’t have to worry about specifying a value that is not valid;
Set for Current Session’ operation checks for validity and
will not install an unacceptable value.
While editing certain kinds of values, such as file names, directory
names, and Emacs command names, you can perform completion with
widget-complete), or the equivalent keys
M-TAB or ESC TAB. This behaves much
like minibuffer completion (see Completion).
Typing RET on an editable value field moves point forward to the next field or button, like TAB. You can thus type RET when you are finished editing a field, to move on to the next button or field. To insert a newline within an editable field, use C-o or C-q C-j.
For some variables, there is only a fixed set of legitimate values,
and you are not allowed to edit the value directly. Instead, a
[Value Menu]’ button appears before the value; activating this
button presents a choice of values. For a boolean “on or off”
value, the button says ‘
[Toggle]’, and flips the value. After
using the ‘
[Value Menu]’ or ‘
[Toggle]’ button, you must
again set the variable to make the chosen value take effect.
Some variables have values with complex structure. For example, the
minibuffer-frame-alist is an association list. Here
is how it appears in the customization buffer:
[Hide] Minibuffer Frame Alist: [INS] [DEL] Parameter: width Value: 80 [INS] [DEL] Parameter: height Value: 2 [INS] [ State ]: STANDARD. Alist of parameters for the initial minibuffer frame. [Hide] […more lines of documentation…]
In this case, each association in the list consists of two items, one
Parameter’ and one labeled ‘
Value’; both are
editable fields. You can delete an association from the list with the
[DEL]’ button next to it. To add an association, use the
[INS]’ button at the position where you want to insert it; the
very last ‘
[INS]’ button inserts at the end of the list.
When you set a variable, the new value takes effect only in the
current Emacs session. To save the value for future sessions,
use the ‘
[State]’ button and select the ‘
Save for Future Sessions’ operation. See Saving Customizations.
You can also restore the variable to its standard value by using the
[State]’ button and selecting the ‘
operation. There are actually four reset operations:
Revert This Session's Customizations’
Set to Backup Value’
Sometimes it is useful to record a comment about a specific
customization. Use the ‘
Add Comment’ item from the
[State]’ menu to create a field for entering the comment.
Near the top of the customization buffer are two lines of buttons:
Operate on all settings in this buffer: [Revert...] [Apply] [Apply and Save]
[Revert...]’ button drops a menu with the first 3 reset
operations described above. The ‘
[Apply]’ button applies the
settings for the current session. The ‘
[Apply and Save]’ button
applies the settings and saves them for future sessions; this button
does not appear if Emacs was started with the
-Q option (see Initial Options).
The command C-c C-c (
Custom-set) is equivalent to using
[Set for Current Session]’ button. The command C-x
Custom-save) is like using the ‘
[Save for Future Sessions]’ button.
[Exit]’ button switches out of the customization buffer,
and buries the buffer at the bottom of the buffer list. To make it
kill the customization buffer instead, change the variable