1 |
@c -*-texinfo-*- |
@c -*-texinfo-*- |
2 |
@c This is part of the GNU Emacs Lisp Reference Manual. |
@c This is part of the GNU Emacs Lisp Reference Manual. |
3 |
@c Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc. |
@c Copyright (C) 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc. |
4 |
@c See the file elisp.texi for copying conditions. |
@c See the file elisp.texi for copying conditions. |
5 |
@setfilename ../info/customize |
@setfilename ../info/customize |
6 |
@node Customization, Loading, Macros, Top |
@node Customization, Loading, Macros, Top |
13 |
|
|
14 |
@menu |
@menu |
15 |
* Common Keywords:: |
* Common Keywords:: |
16 |
* Group Definitions:: |
* Group Definitions:: |
17 |
* Variable Definitions:: |
* Variable Definitions:: |
18 |
* Customization Types:: |
* Customization Types:: |
19 |
@end menu |
@end menu |
20 |
|
|
242 |
@item :get @var{getfunction} |
@item :get @var{getfunction} |
243 |
Specify @var{getfunction} as the way to extract the value of this |
Specify @var{getfunction} as the way to extract the value of this |
244 |
option. The function @var{getfunction} should take one argument, a |
option. The function @var{getfunction} should take one argument, a |
245 |
symbol, and should return the ``current value'' for that symbol (which |
symbol, and should return whatever customize should use as the |
246 |
need not be the symbol's Lisp value). The default is |
``current value'' for that symbol (which need not be the symbol's Lisp |
247 |
@code{default-value}. |
value). The default is @code{default-value}. |
248 |
|
|
249 |
|
You have to really understand the workings of Custom to use |
250 |
|
@code{:get} correctly. It is meant for values that are treated in |
251 |
|
Custom as variables but are not actually stored in Lisp variables. It |
252 |
|
is almost surely a mistake to specify @code{getfunction} for a value |
253 |
|
that really is stored in a Lisp variable. |
254 |
|
|
255 |
@item :initialize @var{function} |
@item :initialize @var{function} |
256 |
@var{function} should be a function used to initialize the variable when |
@var{function} should be a function used to initialize the variable when |
261 |
@table @code |
@table @code |
262 |
@item custom-initialize-set |
@item custom-initialize-set |
263 |
Use the variable's @code{:set} function to initialize the variable, but |
Use the variable's @code{:set} function to initialize the variable, but |
264 |
do not reinitialize it if it is already non-void. This is the default |
do not reinitialize it if it is already non-void. |
|
@code{:initialize} function. |
|
265 |
|
|
266 |
@item custom-initialize-default |
@item custom-initialize-default |
267 |
Like @code{custom-initialize-set}, but use the function |
Like @code{custom-initialize-set}, but use the function |
272 |
customizing the variable will do so. |
customizing the variable will do so. |
273 |
|
|
274 |
@item custom-initialize-reset |
@item custom-initialize-reset |
275 |
Always use the @code{:set} function to initialize the variable. If the |
Always use the @code{:set} function to initialize the variable. If |
276 |
variable is already non-void, reset it by calling the @code{:set} |
the variable is already non-void, reset it by calling the @code{:set} |
277 |
function using the current value (returned by the @code{:get} method). |
function using the current value (returned by the @code{:get} method). |
278 |
|
This is the default @code{:initialize} function. |
279 |
|
|
280 |
@item custom-initialize-changed |
@item custom-initialize-changed |
281 |
Use the @code{:set} function to initialize the variable, if it is |
Use the @code{:set} function to initialize the variable, if it is |
344 |
customization buffer for editing. |
customization buffer for editing. |
345 |
|
|
346 |
You specify the customization type in @code{defcustom} with the |
You specify the customization type in @code{defcustom} with the |
347 |
@code{:type} keyword. The argument of @code{:type} is evaluated; since |
@code{:type} keyword. The argument of @code{:type} is evaluated, but |
348 |
types that vary at run time are rarely useful, normally you use a quoted |
only once when the @code{defcustom} is executed, so it isn't useful |
349 |
constant. For example: |
for the value to vary. Normally we use a quoted constant. For |
350 |
|
example: |
351 |
|
|
352 |
@example |
@example |
353 |
(defcustom diff-command "diff" |
(defcustom diff-command "diff" |
394 |
in the customization buffer. |
in the customization buffer. |
395 |
|
|
396 |
@item number |
@item number |
397 |
The value must be a number, and is represented textually in the |
The value must be a number (floating point or integer), and is |
398 |
customization buffer. |
represented textually in the customization buffer. |
399 |
|
|
400 |
|
@item float |
401 |
|
The value must be a floating point number, and is represented |
402 |
|
textually in the customization buffer. |
403 |
|
|
404 |
@item string |
@item string |
405 |
The value must be a string, and the customization buffer shows just the |
The value must be a string, and the customization buffer shows just the |
502 |
@end smallexample |
@end smallexample |
503 |
|
|
504 |
@noindent |
@noindent |
505 |
instead of |
instead of |
506 |
|
|
507 |
@smallexample |
@smallexample |
508 |
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) |
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) |
527 |
key, using variations of this trick: |
key, using variations of this trick: |
528 |
|
|
529 |
@smallexample |
@smallexample |
530 |
(defcustom person-data '(("brian" 50 t) |
(defcustom person-data '(("brian" 50 t) |
531 |
("dorith" 55 nil) |
("dorith" 55 nil) |
532 |
("ken" 52 t)) |
("ken" 52 t)) |
533 |
"Alist of basic info about people. |
"Alist of basic info about people. |
534 |
Each element has the form (NAME AGE MALE-FLAG)." |
Each element has the form (NAME AGE MALE-FLAG)." |
535 |
:type '(alist :value-type (group age boolean))) |
:type '(alist :value-type (group age boolean))) |
536 |
|
|
537 |
(defcustom pets '(("brian") |
(defcustom pets '(("brian") |
538 |
("dorith" "dog" "guppy") |
("dorith" "dog" "guppy") |
539 |
("ken" "cat")) |
("ken" "cat")) |
540 |
"Alist of people's pets. |
"Alist of people's pets. |
589 |
|
|
590 |
@node Composite Types |
@node Composite Types |
591 |
@subsection Composite Types |
@subsection Composite Types |
592 |
|
@cindex arguments (of composite type) |
593 |
|
|
594 |
When none of the simple types is appropriate, you can use composite |
When none of the simple types is appropriate, you can use composite |
595 |
types, which build new types from other types. Here are several ways of |
types, which build new types from other types or from specified data. |
596 |
doing that: |
The specified types or data are called the @dfn{arguments} of the |
597 |
|
composite type. The composite type normally looks like this: |
|
@table @code |
|
|
@item (restricted-sexp :match-alternatives @var{criteria}) |
|
|
The value may be any Lisp object that satisfies one of @var{criteria}. |
|
|
@var{criteria} should be a list, and each element should be |
|
|
one of these possibilities: |
|
|
|
|
|
@itemize @bullet |
|
|
@item |
|
|
A predicate---that is, a function of one argument that has no side |
|
|
effects, and returns either @code{nil} or non-@code{nil} according to |
|
|
the argument. Using a predicate in the list says that objects for which |
|
|
the predicate returns non-@code{nil} are acceptable. |
|
|
|
|
|
@item |
|
|
A quoted constant---that is, @code{'@var{object}}. This sort of element |
|
|
in the list says that @var{object} itself is an acceptable value. |
|
|
@end itemize |
|
|
|
|
|
For example, |
|
598 |
|
|
599 |
@example |
@example |
600 |
(restricted-sexp :match-alternatives |
(@var{constructor} @var{arguments}@dots{}) |
|
(integerp 't 'nil)) |
|
601 |
@end example |
@end example |
602 |
|
|
603 |
@noindent |
@noindent |
604 |
allows integers, @code{t} and @code{nil} as legitimate values. |
but you can also add keyword-value pairs before the arguments, like |
605 |
|
this: |
606 |
|
|
607 |
The customization buffer shows all legitimate values using their read |
@example |
608 |
syntax, and the user edits them textually. |
(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{}) |
609 |
|
@end example |
610 |
|
|
611 |
|
Here is a table of constructors and how to use them to write |
612 |
|
composite types: |
613 |
|
|
614 |
|
@table @code |
615 |
@item (cons @var{car-type} @var{cdr-type}) |
@item (cons @var{car-type} @var{cdr-type}) |
616 |
The value must be a cons cell, its @sc{car} must fit @var{car-type}, and |
The value must be a cons cell, its @sc{car} must fit @var{car-type}, and |
617 |
its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string |
its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string |
665 |
a @code{const}, you should specify a valid default for that alternative |
a @code{const}, you should specify a valid default for that alternative |
666 |
using the @code{:value} keyword. @xref{Type Keywords}. |
using the @code{:value} keyword. @xref{Type Keywords}. |
667 |
|
|
668 |
|
If some values are covered by more than one of the alternatives, |
669 |
|
customize will choose the first alternative that the value fits. This |
670 |
|
means you should always list the most specific types first, and the |
671 |
|
most general last. Here's an example of proper usage: |
672 |
|
|
673 |
|
@example |
674 |
|
(choice (const :tag "Off" nil) symbol (sexp :tag "Other")) |
675 |
|
@end example |
676 |
|
|
677 |
|
@noindent |
678 |
|
This way, the special value @code{nil} is not treated like other |
679 |
|
symbols, and symbols are not treated like other Lisp expressions. |
680 |
|
|
681 |
@item (radio @var{element-types}@dots{}) |
@item (radio @var{element-types}@dots{}) |
682 |
This is similar to @code{choice}, except that the choices are displayed |
This is similar to @code{choice}, except that the choices are displayed |
683 |
using `radio buttons' rather than a menu. This has the advantage of |
using `radio buttons' rather than a menu. This has the advantage of |
772 |
@var{element-type}. This appears in the customization buffer as a |
@var{element-type}. This appears in the customization buffer as a |
773 |
list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding |
list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding |
774 |
more elements or removing elements. |
more elements or removing elements. |
775 |
|
|
776 |
|
@item (restricted-sexp :match-alternatives @var{criteria}) |
777 |
|
This is the most general composite type construct. The value may be |
778 |
|
any Lisp object that satisfies one of @var{criteria}. @var{criteria} |
779 |
|
should be a list, and each element should be one of these |
780 |
|
possibilities: |
781 |
|
|
782 |
|
@itemize @bullet |
783 |
|
@item |
784 |
|
A predicate---that is, a function of one argument that has no side |
785 |
|
effects, and returns either @code{nil} or non-@code{nil} according to |
786 |
|
the argument. Using a predicate in the list says that objects for which |
787 |
|
the predicate returns non-@code{nil} are acceptable. |
788 |
|
|
789 |
|
@item |
790 |
|
A quoted constant---that is, @code{'@var{object}}. This sort of element |
791 |
|
in the list says that @var{object} itself is an acceptable value. |
792 |
|
@end itemize |
793 |
|
|
794 |
|
For example, |
795 |
|
|
796 |
|
@example |
797 |
|
(restricted-sexp :match-alternatives |
798 |
|
(integerp 't 'nil)) |
799 |
|
@end example |
800 |
|
|
801 |
|
@noindent |
802 |
|
allows integers, @code{t} and @code{nil} as legitimate values. |
803 |
|
|
804 |
|
The customization buffer shows all legitimate values using their read |
805 |
|
syntax, and the user edits them textually. |
806 |
|
@end table |
807 |
|
|
808 |
|
Here is a table of the keywords you can use in keyword-value pairs |
809 |
|
in a composite type: |
810 |
|
|
811 |
|
@table @code |
812 |
|
@item :tag @var{tag} |
813 |
|
Use @var{tag} as the name of this alternative, for user communication |
814 |
|
purposes. This is useful for a type that appears inside of a |
815 |
|
@code{choice}. |
816 |
|
|
817 |
|
@item :match-alternatives @var{criteria} |
818 |
|
Use @var{criteria} to match possible values. This is used only in |
819 |
|
@code{restricted-sexp}. |
820 |
|
|
821 |
|
@item :args @var{argumentlist} |
822 |
|
Use the elements of @var{argumentlist} as the arguments of the type |
823 |
|
construct. For instance, @code{(const :args (foo))} is equivalent to |
824 |
|
@code{(const foo)}. You rarely need to write @code{:args} explicitly, |
825 |
|
because normally the arguments are recognized automatically as |
826 |
|
whatever follows the last keyword-value pair. |
827 |
@end table |
@end table |
828 |
|
|
829 |
@node Splicing into Lists |
@node Splicing into Lists |
845 |
overall sequence. This is analogous to using @samp{,@@} in the backquote |
overall sequence. This is analogous to using @samp{,@@} in the backquote |
846 |
construct. |
construct. |
847 |
|
|
848 |
For example, to specify a list whose first element must be @code{t} |
For example, to specify a list whose first element must be @code{baz} |
849 |
and whose remaining arguments should be zero or more of @code{foo} and |
and whose remaining arguments should be zero or more of @code{foo} and |
850 |
@code{bar}, use this customization type: |
@code{bar}, use this customization type: |
851 |
|
|
852 |
@example |
@example |
853 |
(list (const t) (set :inline t foo bar)) |
(list (const baz) (set :inline t (const foo) (const bar))) |
854 |
@end example |
@end example |
855 |
|
|
856 |
@noindent |
@noindent |
857 |
This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)} |
This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)} |
858 |
and @code{(t foo bar)}. |
and @code{(baz foo bar)}. |
859 |
|
|
860 |
When the element-type is a @code{choice}, you use @code{:inline} not |
When the element-type is a @code{choice}, you use @code{:inline} not |
861 |
in the @code{choice} itself, but in (some of) the alternatives of the |
in the @code{choice} itself, but in (some of) the alternatives of the |
930 |
keyword. |
keyword. |
931 |
|
|
932 |
@item %% |
@item %% |
933 |
Display a literal @samp{%}. |
Display a literal @samp{%}. |
934 |
@end table |
@end table |
935 |
|
|
936 |
@item :action @var{action} |
@item :action @var{action} |
1033 |
@item |
@item |
1034 |
Widgets with tabbing order @code{-1} are ignored. |
Widgets with tabbing order @code{-1} are ignored. |
1035 |
|
|
1036 |
@item |
@item |
1037 |
(Unimplemented) When on a widget with tabbing order @var{n}, go to the |
(Unimplemented) When on a widget with tabbing order @var{n}, go to the |
1038 |
next widget in the buffer with tabbing order @var{n+1} or @code{nil}, |
next widget in the buffer with tabbing order @var{n+1} or @code{nil}, |
1039 |
whichever comes first. |
whichever comes first. |