49.1.3 Changing a Variable

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 ‘ [Hide]’, 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 variable.

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 and Setting Variables). 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, the ‘ [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 ‘ [State]’ 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; the ‘ 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 C-M-i ( 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 value of 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 labeled ‘ 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 ‘ Erase Customization’ operation. There are actually four reset operations:

‘ Undo Edits’

If you have modified but not yet set the variable, this restores the text in the customization buffer to match the actual value.

‘ Revert This Session's Customizations’

This restores the value of the variable to the last saved value, if there was one. Otherwise it restores the standard value. It updates the text accordingly.

‘ Erase Customization’

This sets the variable to its standard value. Any saved value that you have is also eliminated.

‘ Set to Backup Value’

This sets the variable to a previous value that was set in the customization buffer in this session. If you customize a variable and then reset it, which discards the customized value, you can get the discarded value back again with this operation.

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]

The ‘ [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 or -Q option (see Initial Options).

The command C-c C-c ( Custom-set) is equivalent to using the ‘ [Set for Current Session]’ button. The command C-x C-s ( Custom-save) is like using the ‘ [Save for Future Sessions]’ button.

The ‘ [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 custom-buffer-done-kill to t.