— Macro: defgroup group real-name &rest keys

Declares a new customization group whose name is defined by the symbol group. The string real-name is the title of the group as seen by the user.

keys is a list, defining the properties of the group. The members of the list are grouped into pairs of elements, the first element names the property, the second defines its value.

:group group

Specifies the parent customization group of this group. The value of this key is not evaluated.

:require struct

Before displaying the customization UI for this group, require the structure struct. This guarantees that all customizable variables will be known at display time. The value of this key is not evaluated.

:layout symbol

Use a particular UI widget to display this group. The value is a symbol, one of:

single

Holds a single customizable item.

vbox

Holds any number of customizable items, arranging them vertically. This is the default.

hbox

Holds any number of customizable items, arranging them horizontally.

frame

Embed the items in a vbox in a frame.

keymaps

Use a special UI widget for customizing keymaps.

The value of this key is not evaluated.

This macro also creates an interactive function named customize:group allowing the GUI to be invoked to configure the new group.

While defgroup is a macro, there is a corresponding custom-declare-group function.

— Macro: defcustom variable value documentation &rest keys

The first three arguments are analogous to the defvar special form, they declare a special variable stored in the symbol variable, whose value is set to value if the variable is currently unbound, with a documentation string documentation.

All other parameters are key-value pairs as with defgroup. The possible pairs are as follows:

:group group

Specifies the customization group that this variable is a member of. This is a list of symbols, indicating a series of nested groups, e.g., (workspace edge-flip). A variable in a top-level customization group can also be specified as a plain symbol, e.g., workspace. The value of this key is not evaluated.

:type type

Specifies the required type of the variable. The current possibilities are:

(symbol [option ...])

A symbol. The UI looks for a symbol property :options and interprets it as the list of valid symbols to select from. The option arguments allow you to define a list at eval time. It is also possible to change this list at run time by changing the custom symbol's :options property; see the access functions custom-add-options and custom-set-options for more information.

(choice option ...)

One of the option elements. Each option is a symbol. Unlike the symbol type, there is no expectation that this list will change at run-time.

string

An arbitrary string.

(number [[min] max]

Integer number. Two additional arguments specify the minimum and maximum allowed values for the integer. One additional argument specified the maximum allowed value; the minimum defaults to zero. Zero additional arguments implies no minimum nor maximum.

boolean

True (t) or false (nil) value.

color

A color.

font

A font name.

file

A file name.

program

A file name that must be an executable program.

command

A Sawfish command.

event

A Sawfish event.

keymap

A Sawfish keymap.

frame-style

The name of a defined Sawfish frame style.

icon

An X icon.

modifier-list

A list of X modifier keys.

Except where specified, the values of these keys are not evaluated.

:require feature

Denotes that the feature feature must be loaded if the variable is set to a non-nil value by user customizations. This is necessary because customization options are loaded on startup, possibly before the modules that define them. The value of this key is not evaluated.

:allow-nil bool

Specifies whether the variable may be nil, instead of a member of its actual type. This is only supported by the string, symbol, font and color types.

:set function

Specifies that the variable must be set by calling function instead of the default custom-set-variable. The function should accept three arguments: (variable value &optional require).

The usual action of this function is to translate the value into the correct type, then call custom-set-variable. This translation is necessary since many of the UI widgets accept strings representing more complex types (i.e. a color's name, instead of the actual object)

:get function

Provides a function for reading the current value of the variable. Should return a value that's acceptable to the UI widget associated with the variable. Called with a single argument, the symbol containing the variable.

:before-set function

:after-set function

Functions called both immediately before and after setting the value of the variable. Called with a single parameter: the variable itself.

:range (min . max)

The allowed range for numeric variables. If min is nil the the default minimum allowed value is zero; if max is nil then the default maximum is unbounded. This is obsolete, since the :number type now supports range declarations. The value of this key is not evaluated.

:tooltop string

A tooltip that appears when the user's mouse hovers over the widget item.

:depends symbol

This widget item is only settable when the symbol-value for symbol is non-nil.

While defcustom is a macro, there is a corresponding custom-declare-variable function.

     (defgroup move "Move/Resize")
     
     (defcustom move-outline-mode 'opaque
       "The method of drawing windows being moved interactively."
       :type (set opaque box)
       :group move)
     
     (defcustom move-snap-epsilon 8
       "Proximity in pixels before snapping to a window edge."
       :group move
       :type (number 0 64))

— Function: custom-add-option variable option

Add symbol value option to the list of symbols that can be stored in variable. The new option goes on the end of the list.

— Function: custom-get-options variable

Return the list of symbols that can be stored in variable.