300 |
operation of a certain feature. Assuming that the package is coded to |
operation of a certain feature. Assuming that the package is coded to |
301 |
check the value of the option, you still need to arrange for the package |
check the value of the option, you still need to arrange for the package |
302 |
to be loaded. You can do that with @code{:require}. @xref{Common |
to be loaded. You can do that with @code{:require}. @xref{Common |
303 |
Keywords}. Here is an example, from the library @file{paren.el}: |
Keywords}. Here is an example, from the library @file{tooltip.el}: |
304 |
|
|
305 |
@example |
@example |
306 |
(defcustom show-paren-mode nil |
(defcustom tooltip-mode nil |
307 |
"Toggle Show Paren mode..." |
"Non-nil if Tooltip mode is enabled..." |
308 |
:set (lambda (symbol value) |
:set (lambda (symbol value) |
309 |
(show-paren-mode (or value 0))) |
(tooltip-mode (or value 0))) |
310 |
:initialize 'custom-initialize-default |
:initialize 'custom-initialize-default |
311 |
:type 'boolean |
:type 'boolean |
312 |
:group 'paren-showing |
:require 'tooltip |
313 |
:require 'paren) |
:group 'tooltip) |
314 |
@end example |
@end example |
315 |
|
|
316 |
If a customization item has a type such as @code{hook} or @code{alist}, |
If a customization item has a type such as @code{hook} or @code{alist}, |
529 |
The @code{group} widget is used here instead of @code{list} only because |
The @code{group} widget is used here instead of @code{list} only because |
530 |
the formatting is better suited for the purpose. |
the formatting is better suited for the purpose. |
531 |
|
|
532 |
Similarily, you can have alists with more values associated with each |
Similarly, you can have alists with more values associated with each |
533 |
key, using variations of this trick: |
key, using variations of this trick: |
534 |
|
|
535 |
@smallexample |
@smallexample |
538 |
("ken" 52 t)) |
("ken" 52 t)) |
539 |
"Alist of basic info about people. |
"Alist of basic info about people. |
540 |
Each element has the form (NAME AGE MALE-FLAG)." |
Each element has the form (NAME AGE MALE-FLAG)." |
541 |
:type '(alist :value-type (group age boolean))) |
:type '(alist :value-type (group integer boolean))) |
542 |
|
|
543 |
(defcustom pets '(("brian") |
(defcustom pets '(("brian") |
544 |
("dorith" "dog" "guppy") |
("dorith" "dog" "guppy") |
665 |
@end example |
@end example |
666 |
|
|
667 |
@noindent |
@noindent |
668 |
so that the menu offers @samp{Number of spaces} and @samp{Literal Text}. |
so that the menu offers @samp{Number of spaces} and @samp{Literal text}. |
669 |
|
|
670 |
In any alternative for which @code{nil} is not a valid value, other than |
In any alternative for which @code{nil} is not a valid value, other than |
671 |
a @code{const}, you should specify a valid default for that alternative |
a @code{const}, you should specify a valid default for that alternative |
824 |
Use @var{criteria} to match possible values. This is used only in |
Use @var{criteria} to match possible values. This is used only in |
825 |
@code{restricted-sexp}. |
@code{restricted-sexp}. |
826 |
|
|
827 |
@item :args @var{argumentlist} |
@item :args @var{argument-list} |
828 |
Use the elements of @var{argumentlist} as the arguments of the type |
Use the elements of @var{argument-list} as the arguments of the type |
829 |
construct. For instance, @code{(const :args (foo))} is equivalent to |
construct. For instance, @code{(const :args (foo))} is equivalent to |
830 |
@code{(const foo)}. You rarely need to write @code{:args} explicitly, |
@code{(const foo)}. You rarely need to write @code{:args} explicitly, |
831 |
because normally the arguments are recognized automatically as |
because normally the arguments are recognized automatically as |
1066 |
@subsection Defining New Types |
@subsection Defining New Types |
1067 |
|
|
1068 |
In the previous sections we have described how to construct elaborate |
In the previous sections we have described how to construct elaborate |
1069 |
type specifications for @code{defcustom}. In some cases you may want to |
type specifications for @code{defcustom}. In some cases you may want |
1070 |
give such a type specification a name. The obvious case is when you are |
to give such a type specification a name. The obvious case is when |
1071 |
using the same type for many user options, rather than repeat the |
you are using the same type for many user options: rather than repeat |
1072 |
specification for each option, you can give the type specification a |
the specification for each option, you can give the type specification |
1073 |
name once, and use that name each @code{defcustom}. The other case is |
a name, and use that name each @code{defcustom}. The other case is |
1074 |
when a user option accept a recursive datastructure. To make it |
when a user option's value is a recursive data structure. To make it |
1075 |
possible for a datatype to refer to itself, it needs to have a name. |
possible for a datatype to refer to itself, it needs to have a name. |
1076 |
|
|
1077 |
Since custom types are implemented as widgets, the way to define a new |
Since custom types are implemented as widgets, the way to define a new |
1097 |
:type 'binary-tree-of-string) |
:type 'binary-tree-of-string) |
1098 |
@end example |
@end example |
1099 |
|
|
1100 |
The function to define a new widget is name @code{define-widget}. The |
The function to define a new widget is called @code{define-widget}. The |
1101 |
first argument is the symbol we want to make a new widget type. The |
first argument is the symbol we want to make a new widget type. The |
1102 |
second argument is a symbol representing an existing widget, the new |
second argument is a symbol representing an existing widget, the new |
1103 |
widget is going to be defined in terms of difference from the existing |
widget is going to be defined in terms of difference from the existing |
1104 |
widget. For the purpose of defining new customization types, the |
widget. For the purpose of defining new customization types, the |
1105 |
@code{lazy} widget is perfect, because it accept a @code{:type} keyword |
@code{lazy} widget is perfect, because it accepts a @code{:type} keyword |
1106 |
argument with the same syntax as the keyword argument to |
argument with the same syntax as the keyword argument to |
1107 |
@code{defcustom} with the same name. The third argument is a |
@code{defcustom} with the same name. The third argument is a |
1108 |
documentation string for the new widget. You will be able to see that |
documentation string for the new widget. You will be able to see that |
1109 |
string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string |
string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string |
1110 |
@key{ret}} command. |
@key{ret}} command. |
1111 |
|
|
1112 |
After these mandatory arguments follows the keyword arguments. The most |
After these mandatory arguments follow the keyword arguments. The most |
1113 |
important is @code{:type}, which describes the datatype we want to match |
important is @code{:type}, which describes the data type we want to match |
1114 |
with this widget. Here a @code{binary-tree-of-string} is described as |
with this widget. Here a @code{binary-tree-of-string} is described as |
1115 |
being either a string, or a cons-cell whose car and cdr are themselves |
being either a string, or a cons-cell whose car and cdr are themselves |
1116 |
both @code{binary-tree-of-string}. Note the reference to the widget |
both @code{binary-tree-of-string}. Note the reference to the widget |
1117 |
type we are currently in the process of defining. The @code{:tag} |
type we are currently in the process of defining. The @code{:tag} |
1118 |
attribute is a string to name the widget in the user interface, and the |
attribute is a string to name the widget in the user interface, and the |
1119 |
@code{:offset} argument are there to ensure that child nodes are |
@code{:offset} argument is there to ensure that child nodes are |
1120 |
indented four spaces relatively to the parent node, making the tree |
indented four spaces relative to the parent node, making the tree |
1121 |
structure apparent in the customization buffer. |
structure apparent in the customization buffer. |
1122 |
|
|
1123 |
The @code{defcustom} shows how the new widget can be used as an ordinary |
The @code{defcustom} shows how the new widget can be used as an ordinary |
1124 |
customization type. |
customization type. |
1125 |
|
|
1126 |
If you wonder about the name @code{lazy}, know that the other composite |
The reason for the name @code{lazy} is that the other composite |
1127 |
widgets convert their inferior widgets to internal form when the widget |
widgets convert their inferior widgets to internal form when the |
1128 |
is instantiated in a buffer. This conversion is recursive, so the |
widget is instantiated in a buffer. This conversion is recursive, so |
1129 |
inferior widgets will convert @emph{their} inferior widgets. If the |
the inferior widgets will convert @emph{their} inferior widgets. If |
1130 |
datastructure is itself recursive, this conversion will go on forever, |
the data structure is itself recursive, this conversion is an infinite |
1131 |
or at least until Emacs run out of stack space. The @code{lazy} widget |
recursion. The @code{lazy} widget prevents the recursion: it convert |
1132 |
stop this recursion, it will only convert its @code{:type} argument when |
its @code{:type} argument only when needed. |
|
needed. |
|
1133 |
|
|
1134 |
@ignore |
@ignore |
1135 |
arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2 |
arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2 |