GNU Info
(elisp)Simple Types
Simple Types
------------
This section describes all the simple customization types.
`sexp'
The value may be any Lisp object that can be printed and read
back. You can use `sexp' as a fall-back for any option, if you
don't want to take the time to work out a more specific type to
use.
`integer'
The value must be an integer, and is represented textually in the
customization buffer.
`number'
The value must be a number, and is represented textually in the
customization buffer.
`string'
The value must be a string, and the customization buffer shows
just the contents, with no delimiting `"' characters and no
quoting with `\'.
`regexp'
Like `string' except that the string must be a valid regular
expression.
`character'
The value must be a character code. A character code is actually
an integer, but this type shows the value by inserting the
character in the buffer, rather than by showing the number.
`file'
The value must be a file name, and you can do completion with
`M-<TAB>'.
`(file :must-match t)'
The value must be a file name for an existing file, and you can do
completion with `M-<TAB>'.
`directory'
The value must be a directory name, and you can do completion with
`M-<TAB>'.
`hook'
The value must be a list of functions (or a single function, but
that is obsolete usage). This customization type is used for hook
variables. You can use the `:options' keyword in a hook variable's
`defcustom' to specify a list of functions recommended for use in
the hook; see Note: Variable Definitions.
`alist'
The value must be a list of cons-cells, the CAR of each cell
representing a key, and the CDR of the same cell representing an
associated value. The user can add and delete key/value pairs, and
edit both the key and the value of each pair.
You can specify the key and value types like this:
(alist :key-type KEY-TYPE :value-type VALUE-TYPE)
where KEY-TYPE and VALUE-TYPE are customization type
specifications. The default key type is `sexp', and the default
value type is `sexp'.
The user can add any key matching the specified key type, but you
can give some keys a preferential treatment by specifying them
with the `:options' (see Note: Variable Definitions). The
specified keys will always be shown in the customize buffer
(together with a suitable value), with a checkbox to include or
exclude or disable the key/value pair from the alist. The user
will not be able to edit the keys specified by the `:options'
keyword argument.
The argument to the `:options' keywords should be a list of option
specifications. Ordinarily, the options are simply atoms, which
are the specified keys. For example:
:options '("foo" "bar" "baz")
specifies that there are three "known" keys, namely `"foo"',
`"bar"' and `"baz"', which will always be shown first.
You may want to restrict the value type for specific keys, for
example, the value associated with the `"bar"' key can only be an
integer. You can specify this by using a list instead of an atom
in the option specification. The first element will specify the
key, like before, while the second element will specify the value
type.
:options '("foo" ("bar" integer) "baz")
Finally, you may want to change how the key is presented. By
default, the key is simply shown as a `const', since the user
cannot change the special keys specified with the `:options'
keyword. However, you may want to use a more specialized type for
presenting the key, like `function-item' if you know it is a
symbol with a function binding. This is done by using a
customization type specification instead of a symbol for the key.
:options '("foo" ((function-item some-function) integer) "baz")
Many alists use lists with two elements, instead of cons cells.
For example,
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE).")
instead of
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
"Each element is a cons-cell (KEY . VALUE).")
Because of the way lists are implemented on top of cons cells, you
can treat `list-alist' in the example above as a cons cell alist,
where the value type is a list with a single element containing
the real value.
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE)."
:type '(alist :value-type (group integer)))
The `group' widget is used here instead of `list' only because the
formatting is better suited for the purpose.
Similarily, you can have alists with more values associated with
each key, using variations of this trick:
(defcustom person-data '(("brian" 50 t)
("dorith" 55 nil)
("ken" 52 t))
"Alist of basic info about people.
Each element has the form (NAME AGE MALE-FLAG)."
:type '(alist :value-type (group age boolean)))
(defcustom pets '(("brian")
("dorith" "dog" "guppy")
("ken" "cat"))
"Alist of people's pets.
In an element (KEY . VALUE), KEY is the person's name,
and the VALUE is a list of that person's pets."
:type '(alist :value-type (repeat string)))
`plist'
The `plist' custom type is similar to the `alist' (see above),
except that the information is stored as a property list, i.e. a
list of this form:
(KEY VALUE KEY VALUE KEY VALUE ...)
The default `:key-type' for `plist' is `symbol', rather than
`sexp'.
`symbol'
The value must be a symbol. It appears in the customization
buffer as the name of the symbol.
`function'
The value must be either a lambda expression or a function name.
When it is a function name, you can do completion with `M-<TAB>'.
`variable'
The value must be a variable name, and you can do completion with
`M-<TAB>'.
`face'
The value must be a symbol which is a face name, and you can do
completion with `M-<TAB>'.
`boolean'
The value is boolean--either `nil' or `t'. Note that by using
`choice' and `const' together (see the next section), you can
specify that the value must be `nil' or `t', but also specify the
text to describe each value in a way that fits the specific
meaning of the alternative.
`coding-system'
The value must be a coding-system name, and you can do completion
with `M-<TAB>'.
`color'
The value must be a valid color name, and you can do completion
with `M-<TAB>'. A sample is provided,
automatically generated by info2www version 1.2.2.9