Defgroup and Defcustom

Customization options are organized into groups. Each group has a name and contains a set of related options. Groups can be assigned to parent groups using the :group parameter during construction.

defgroup group real-name &rest keys

Macro

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.

defcustom variable value documentation &rest keys

Macro

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.

Note that where necessary the types themselves define default :set, :get and :widget values that may be overridden by values in the defcustom call. Usually, however, this will not be necessary.

Consider the following example:

     (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))
     

This defines a group and two customization options.

There are two special accessor functions to make it easier to deal with lists of allowed symbols.

custom-add-option variable option

Function

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.

custom-get-options variable

Function

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