elisp: Type Keywords
14.4.4 Type Keywords
--------------------
You can specify keyword-argument pairs in a customization type after the
type name symbol. Here are the keywords you can use, and their
meanings:
‘:value DEFAULT’
Provide a default value.
If ‘nil’ is not a valid value for the alternative, then it is
essential to specify a valid default with ‘:value’.
If you use this for a type that appears as an alternative inside of
‘choice’; it specifies the default value to use, at first, if and
when the user selects this alternative with the menu in the
customization buffer.
Of course, if the actual value of the option fits this alternative,
it will appear showing the actual value, not DEFAULT.
‘:format FORMAT-STRING’
This string will be inserted in the buffer to represent the value
corresponding to the type. The following ‘%’ escapes are available
for use in FORMAT-STRING:
‘%[BUTTON%]’
Display the text BUTTON marked as a button. The ‘:action’
attribute specifies what the button will do if the user
invokes it; its value is a function which takes two
arguments—the widget which the button appears in, and the
event.
There is no way to specify two different buttons with
different actions.
‘%{SAMPLE%}’
Show SAMPLE in a special face specified by ‘:sample-face’.
‘%v’
Substitute the item’s value. How the value is represented
depends on the kind of item, and (for variables) on the
customization type.
‘%d’
Substitute the item’s documentation string.
‘%h’
Like ‘%d’, but if the documentation string is more than one
line, add a button to control whether to show all of it or
just the first line.
‘%t’
Substitute the tag here. You specify the tag with the ‘:tag’
keyword.
‘%%’
Display a literal ‘%’.
‘:action ACTION’
Perform ACTION if the user clicks on a button.
‘:button-face FACE’
Use the face FACE (a face name or a list of face names) for button
text displayed with ‘%[...%]’.
‘:button-prefix PREFIX’
‘:button-suffix SUFFIX’
These specify the text to display before and after a button. Each
can be:
‘nil’
No text is inserted.
a string
The string is inserted literally.
a symbol
The symbol’s value is used.
‘:tag TAG’
Use TAG (a string) as the tag for the value (or part of the value)
that corresponds to this type.
‘:doc DOC’
Use DOC as the documentation string for this value (or part of the
value) that corresponds to this type. In order for this to work,
you must specify a value for ‘:format’, and use ‘%d’ or ‘%h’ in
that value.
The usual reason to specify a documentation string for a type is to
provide more information about the meanings of alternatives inside
a ‘:choice’ type or the parts of some other composite type.
‘:help-echo MOTION-DOC’
When you move to this item with ‘widget-forward’ or
‘widget-backward’, it will display the string MOTION-DOC in the
echo area. In addition, MOTION-DOC is used as the mouse
‘help-echo’ string and may actually be a function or form evaluated
to yield a help string. If it is a function, it is called with one
argument, the widget.
‘:match FUNCTION’
Specify how to decide whether a value matches the type. The
corresponding value, FUNCTION, should be a function that accepts
two arguments, a widget and a value; it should return non-‘nil’ if
the value is acceptable.
‘:validate FUNCTION’
Specify a validation function for input. FUNCTION takes a widget
as an argument, and should return ‘nil’ if the widget’s current
value is valid for the widget. Otherwise, it should return the
widget containing the invalid data, and set that widget’s ‘:error’
property to a string explaining the error.
Info Catalog
elisp: Splicing into Lists
elisp: Customization Types
elisp: Defining New Types