annotate lispref/customize.texi @ 62300:758f5cc54b97

*** empty log message ***
author Richard M. Stallman <rms@gnu.org>
date Fri, 13 May 2005 23:09:41 +0000
parents 8f1f80a5bd64
children 99e9892a51d9 62afea0771d8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
62246
8f1f80a5bd64 (Customization): Add menu descriptions.
Lute Kamstra <lute@gnu.org>
parents: 61618
diff changeset
3 @c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003, 2005 Free Software Foundation, Inc.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4 @c See the file elisp.texi for copying conditions.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @setfilename ../info/customize
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @node Customization, Loading, Macros, Top
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @chapter Writing Customization Definitions
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
9 This chapter describes how to declare user options for customization,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
10 and also customization groups for classifying them. We use the term
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
11 @dfn{customization item} to include both kinds of customization
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
12 definitions---as well as face definitions (@pxref{Defining Faces}).
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 @menu
62246
8f1f80a5bd64 (Customization): Add menu descriptions.
Lute Kamstra <lute@gnu.org>
parents: 61618
diff changeset
15 * Common Keywords:: Common keyword arguments for all kinds of
8f1f80a5bd64 (Customization): Add menu descriptions.
Lute Kamstra <lute@gnu.org>
parents: 61618
diff changeset
16 customization declarations.
8f1f80a5bd64 (Customization): Add menu descriptions.
Lute Kamstra <lute@gnu.org>
parents: 61618
diff changeset
17 * Group Definitions:: Writing customization group definitions.
8f1f80a5bd64 (Customization): Add menu descriptions.
Lute Kamstra <lute@gnu.org>
parents: 61618
diff changeset
18 * Variable Definitions:: Declaring user options.
8f1f80a5bd64 (Customization): Add menu descriptions.
Lute Kamstra <lute@gnu.org>
parents: 61618
diff changeset
19 * Customization Types:: Specifying the type of a user option.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 @end menu
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 @node Common Keywords
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
23 @section Common Item Keywords
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
25 All kinds of customization declarations (for variables and groups, and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
26 for faces) accept keyword arguments for specifying various information.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
27 This section describes some keywords that apply to all kinds.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
29 All of these keywords, except @code{:tag}, can be used more than once
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
30 in a given item. Each use of the keyword has an independent effect.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
31 The keyword @code{:tag} is an exception because any given item can only
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
32 display one name.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @table @code
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
35 @item :tag @var{label}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
36 Use @var{label}, a string, instead of the item's name, to label the item
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
37 in customization menus and buffers.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
38
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 @item :group @var{group}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 Put this customization item in group @var{group}. When you use
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 @var{group}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 If you use this keyword more than once, you can put a single item into
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 more than one group. Displaying any of those groups will show this
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
46 item. Please don't overdo this, since the result would be annoying.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 @item :link @var{link-data}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 Include an external link after the documentation string for this item.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 This is a sentence containing an active field which references some
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 other documentation.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52
43477
5dc288e4ec82 *** empty log message ***
Pavel Janík <Pavel@Janik.cz>
parents: 40414
diff changeset
53 There are four alternatives you can use for @var{link-data}:
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 @table @code
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 @item (custom-manual @var{info-node})
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 Link to an Info node; @var{info-node} is a string which specifies the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 node name, as in @code{"(emacs)Top"}. The link appears as
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 @samp{[manual]} in the customization buffer.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 @item (info-link @var{info-node})
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 Like @code{custom-manual} except that the link appears
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 in the customization buffer with the Info node name.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 @item (url-link @var{url})
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
66 Link to a web page; @var{url} is a string which specifies the @acronym{URL}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
67 The link appears in the customization buffer as @var{url}.
32521
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
68
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
69 @item (emacs-commentary-link @var{library})
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
70 Link to the commentary section of a library; @var{library} is a string
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
71 which specifies the library name.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 @end table
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 You can specify the text to use in the customization buffer by adding
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 @code{:tag @var{name}} after the first element of the @var{link-data};
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 the Emacs manual which appears in the buffer as @samp{foo}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 An item can have more than one external link; however, most items have
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 none at all.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 @item :load @var{file}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 Load file @var{file} (a string) before displaying this customization
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 item. Loading is done with @code{load-library}, and only if the file is
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 not already loaded.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @item :require @var{feature}
60499
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
88 Execute @code{(require '@var{feature})} when your saved customizations
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
89 set the value of this item. @var{feature} should be a symbol.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 The most common reason to use @code{:require} is when a variable enables
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 a feature such as a minor mode, and just setting the variable won't have
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 any effect unless the code which implements the mode is loaded.
60499
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
94
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
95 @item :version @var{version}
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
96 This option specifies that the item was first introduced in Emacs
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
97 version @var{version}, or that its default value was changed in that
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
98 version. The value @var{version} must be a string.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 @end table
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 @node Group Definitions
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 @section Defining Custom Groups
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
104 Each Emacs Lisp package should have one main customization group which
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 contains all the options, faces and other groups in the package. If the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 package has a small number of options and faces, use just one group and
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 put everything in it. When there are more than twelve or so options and
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 faces, then you should structure them into subgroups, and put the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
109 subgroups under the package's main customization group. It is OK to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
110 put some of the options and faces in the package's main group alongside
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 the subgroups.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
113 The package's main or only group should be a member of one or more of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
114 the standard customization groups. (To display the full list of them,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
115 use @kbd{M-x customize}.) Choose one or more of them (but not too
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
116 many), and add your group to each of them using the @code{:group}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
117 keyword.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
119 The way to declare new customization groups is with @code{defgroup}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
121 @defmac defgroup group members doc [keyword value]...
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 Declare @var{group} as a customization group containing @var{members}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 Do not quote the symbol @var{group}. The argument @var{doc} specifies
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
124 the documentation string for the group. It should not start with a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
125 @samp{*} as in @code{defcustom}; that convention is for variables only.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
127 The argument @var{members} is a list specifying an initial set of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
128 customization items to be members of the group. However, most often
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
129 @var{members} is @code{nil}, and you specify the group's members by
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
130 using the @code{:group} keyword when defining those members.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
132 If you want to specify group members through @var{members}, each element
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
133 should have the form @code{(@var{name} @var{widget})}. Here @var{name}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
134 is a symbol, and @var{widget} is a widget type for editing that symbol.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
135 Useful widgets are @code{custom-variable} for a variable,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
136 @code{custom-face} for a face, and @code{custom-group} for a group.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137
60499
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
138 When you introduce a new group into Emacs, use the @code{:version}
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
139 keyword in the @code{defgroup}; then you need not use it for
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
140 the individual members of the group.
33150
7e53fab4d2a3 defgroup :version
Dave Love <fx@gnu.org>
parents: 32952
diff changeset
141
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 In addition to the common keywords (@pxref{Common Keywords}), you can
33150
7e53fab4d2a3 defgroup :version
Dave Love <fx@gnu.org>
parents: 32952
diff changeset
143 also use this keyword in @code{defgroup}:
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 @table @code
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 @item :prefix @var{prefix}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 If the name of an item in the group starts with @var{prefix}, then the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 tag for that item is constructed (by default) by omitting @var{prefix}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 One group can have any number of prefixes.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 @end table
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 @end defmac
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
154 The prefix-discarding feature is currently turned off, which means
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
155 that @code{:prefix} currently has no effect. We did this because we
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
156 found that discarding the specified prefixes often led to confusing
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
157 names for options. This happened because the people who wrote the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
158 @code{defgroup} definitions for various groups added @code{:prefix}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
159 keywords whenever they make logical sense---that is, whenever the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
160 variables in the library have a common prefix.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
162 In order to obtain good results with @code{:prefix}, it would be
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
163 necessary to check the specific effects of discarding a particular
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
164 prefix, given the specific items in a group and their names and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
165 documentation. If the resulting text is not clear, then @code{:prefix}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
166 should not be used in that case.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
168 It should be possible to recheck all the customization groups, delete
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 the @code{:prefix} specifications which give unclear results, and then
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 turn this feature back on, if someone would like to do the work.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 @node Variable Definitions
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @section Defining Customization Variables
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
175 Use @code{defcustom} to declare user-editable variables.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176
35009
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
177 @defmac defcustom option default doc [keyword value]@dots{}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
178 Declare @var{option} as a customizable user option variable. Do not
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
179 quote @var{option}. The argument @var{doc} specifies the documentation
35009
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
180 string for the variable. It should often start with a @samp{*} to mark
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
181 it as a @dfn{user option} (@pxref{Defining Variables}). Do not start
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
182 the documentation string with @samp{*} for options which cannot or
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
183 normally should not be set with @code{set-variable}; examples of the
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
184 former are global minor mode options such as
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
185 @code{global-font-lock-mode} and examples of the latter are hooks.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
186
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
187 If @var{option} is void, @code{defcustom} initializes it to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
188 @var{default}. @var{default} should be an expression to compute the
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
189 value; be careful in writing it, because it can be evaluated on more
35009
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
190 than one occasion. You should normally avoid using backquotes in
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
191 @var{default} because they are not expanded when editing the value,
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
192 causing list values to appear to have the wrong structure.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
193
56235
ba5561d20501 (Variable Definitions): Note about doc strings and :set.
Richard M. Stallman <rms@gnu.org>
parents: 54299
diff changeset
194 If you specify the @code{:set} option, to make the variable take other
ba5561d20501 (Variable Definitions): Note about doc strings and :set.
Richard M. Stallman <rms@gnu.org>
parents: 54299
diff changeset
195 special actions when set through the customization buffer, the
ba5561d20501 (Variable Definitions): Note about doc strings and :set.
Richard M. Stallman <rms@gnu.org>
parents: 54299
diff changeset
196 variable's documentation string should tell the user specifically how
ba5561d20501 (Variable Definitions): Note about doc strings and :set.
Richard M. Stallman <rms@gnu.org>
parents: 54299
diff changeset
197 to do the same job in hand-written Lisp code.
ba5561d20501 (Variable Definitions): Note about doc strings and :set.
Richard M. Stallman <rms@gnu.org>
parents: 54299
diff changeset
198
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
199 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
200 mode (@code{eval-defun}), a special feature of @code{eval-defun}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
201 arranges to set the variable unconditionally, without testing whether
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
202 its value is void. (The same feature applies to @code{defvar}.)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
203 @xref{Defining Variables}.
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
204 @end defmac
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
206 @code{defcustom} accepts the following additional keywords:
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 @table @code
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 @item :type @var{type}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 Use @var{type} as the data type for this option. It specifies which
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 values are legitimate, and how to display the value.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 @xref{Customization Types}, for more information.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @item :options @var{list}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 Specify @var{list} as the list of reasonable values for use in this
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
216 option. The user is not restricted to using only these values, but they
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
217 are offered as convenient alternatives.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
219 This is meaningful only for certain types, currently including
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
220 @code{hook}, @code{plist} and @code{alist}. See the definition of the
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
221 individual types for a description of how to use @code{:options}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @item :set @var{setfunction}
60499
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
224 Specify @var{setfunction} as the way to change the value of this
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
225 option. The function @var{setfunction} should take two arguments, a
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
226 symbol (the option name) and the new value, and should do whatever is
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
227 necessary to update the value properly for this option (which may not
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
228 mean simply setting the option as a Lisp variable). The default for
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
229 @var{setfunction} is @code{set-default}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 @item :get @var{getfunction}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 Specify @var{getfunction} as the way to extract the value of this
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 option. The function @var{getfunction} should take one argument, a
47783
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
234 symbol, and should return whatever customize should use as the
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
235 ``current value'' for that symbol (which need not be the symbol's Lisp
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
236 value). The default is @code{default-value}.
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
237
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
238 You have to really understand the workings of Custom to use
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
239 @code{:get} correctly. It is meant for values that are treated in
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
240 Custom as variables but are not actually stored in Lisp variables. It
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
241 is almost surely a mistake to specify @code{getfunction} for a value
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
242 that really is stored in a Lisp variable.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 @item :initialize @var{function}
60499
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
245 @var{function} should be a function used to initialize the variable
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
246 when the @code{defcustom} is evaluated. It should take two arguments,
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
247 the option name (a symbol) and the value. Here are some predefined
a33defc96586 (Common Keywords): Clarify :require. Mention :version here.
Richard M. Stallman <rms@gnu.org>
parents: 59768
diff changeset
248 functions meant for use in this way:
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @table @code
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 @item custom-initialize-set
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
252 Use the variable's @code{:set} function to initialize the variable, but
47783
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
253 do not reinitialize it if it is already non-void.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 @item custom-initialize-default
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
256 Like @code{custom-initialize-set}, but use the function
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
257 @code{set-default} to set the variable, instead of the variable's
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
258 @code{:set} function. This is the usual choice for a variable whose
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
259 @code{:set} function enables or disables a minor mode; with this choice,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
260 defining the variable will not call the minor mode function, but
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
261 customizing the variable will do so.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 @item custom-initialize-reset
47783
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
264 Always use the @code{:set} function to initialize the variable. If
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
265 the variable is already non-void, reset it by calling the @code{:set}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
266 function using the current value (returned by the @code{:get} method).
47783
e297e727596c (Variable Definitions): Update info on :get and default :initialize function.
Richard M. Stallman <rms@gnu.org>
parents: 46809
diff changeset
267 This is the default @code{:initialize} function.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 @item custom-initialize-changed
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
270 Use the @code{:set} function to initialize the variable, if it is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
271 already set or has been customized; otherwise, just use
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
272 @code{set-default}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 @end table
26826
8f36e5feb992 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25950
diff changeset
274
8f36e5feb992 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25950
diff changeset
275 @item :set-after @var{variables}
8f36e5feb992 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25950
diff changeset
276 When setting variables according to saved customizations, make sure to
8f36e5feb992 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25950
diff changeset
277 set the variables @var{variables} before this one; in other words, delay
8f36e5feb992 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25950
diff changeset
278 setting this variable until after those others have been handled. Use
8f36e5feb992 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25950
diff changeset
279 @code{:set-after} if setting this variable won't work properly unless
8f36e5feb992 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25950
diff changeset
280 those other variables already have their intended values.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
281 @end table
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
283 The @code{:require} option is useful for an option that turns on the
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 operation of a certain feature. Assuming that the package is coded to
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 check the value of the option, you still need to arrange for the package
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
286 to be loaded. You can do that with @code{:require}. @xref{Common
61618
72a73fd3289a (Variable Definitions): Replace tooltip-mode
Nick Roberts <nickrob@snap.net.nz>
parents: 60499
diff changeset
287 Keywords}. Here is an example, from the library @file{saveplace.el}:
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
288
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
289 @example
61618
72a73fd3289a (Variable Definitions): Replace tooltip-mode
Nick Roberts <nickrob@snap.net.nz>
parents: 60499
diff changeset
290 (defcustom save-place nil
72a73fd3289a (Variable Definitions): Replace tooltip-mode
Nick Roberts <nickrob@snap.net.nz>
parents: 60499
diff changeset
291 "*Non-nil means automatically save place in each file..."
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
292 :type 'boolean
61618
72a73fd3289a (Variable Definitions): Replace tooltip-mode
Nick Roberts <nickrob@snap.net.nz>
parents: 60499
diff changeset
293 :require 'saveplace
72a73fd3289a (Variable Definitions): Replace tooltip-mode
Nick Roberts <nickrob@snap.net.nz>
parents: 60499
diff changeset
294 :group 'save-place)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
295 @end example
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
297 If a customization item has a type such as @code{hook} or @code{alist},
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
298 which supports @code{:options}, you can add additional options to the
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
299 item, outside the @code{defcustom} declaration, by calling
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
300 @code{custom-add-option}. For example, if you define a function
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
301 @code{my-lisp-mode-initialization} intended to be called from
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
302 @code{emacs-lisp-mode-hook}, you might want to add that to the list of
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
303 options for @code{emacs-lisp-mode-hook}, but not by editing its
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
304 definition. You can do it thus:
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
305
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
306 @example
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
307 (custom-add-option 'emacs-lisp-mode-hook
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
308 'my-lisp-mode-initialization)
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
309 @end example
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @defun custom-add-option symbol option
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
312 To the customization @var{symbol}, add @var{option}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
314 The precise effect of adding @var{option} depends on the customization
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
315 type of @var{symbol}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @end defun
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 Internally, @code{defcustom} uses the symbol property
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 @code{standard-value} to record the expression for the default value,
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 and @code{saved-value} to record the value saved by the user with the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 customization buffer. The @code{saved-value} property is actually a
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 list whose car is an expression which evaluates to the value.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 @node Customization Types
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 @section Customization Types
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 When you define a user option with @code{defcustom}, you must specify
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
328 its @dfn{customization type}. That is a Lisp object which describes (1)
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 which values are legitimate and (2) how to display the value in the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 customization buffer for editing.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 You specify the customization type in @code{defcustom} with the
48404
cd3ad87f8d7a Clarify evaluation of :type arg in defcustom.
Richard M. Stallman <rms@gnu.org>
parents: 47783
diff changeset
333 @code{:type} keyword. The argument of @code{:type} is evaluated, but
cd3ad87f8d7a Clarify evaluation of :type arg in defcustom.
Richard M. Stallman <rms@gnu.org>
parents: 47783
diff changeset
334 only once when the @code{defcustom} is executed, so it isn't useful
cd3ad87f8d7a Clarify evaluation of :type arg in defcustom.
Richard M. Stallman <rms@gnu.org>
parents: 47783
diff changeset
335 for the value to vary. Normally we use a quoted constant. For
cd3ad87f8d7a Clarify evaluation of :type arg in defcustom.
Richard M. Stallman <rms@gnu.org>
parents: 47783
diff changeset
336 example:
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 @example
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 (defcustom diff-command "diff"
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 "*The command to use to run diff."
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
341 :type '(string)
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 :group 'diff)
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @end example
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
345 In general, a customization type is a list whose first element is a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
346 symbol, one of the customization type names defined in the following
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
347 sections. After this symbol come a number of arguments, depending on
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
348 the symbol. Between the type symbol and its arguments, you can
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
349 optionally write keyword-value pairs (@pxref{Type Keywords}).
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
351 Some of the type symbols do not use any arguments; those are called
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
352 @dfn{simple types}. For a simple type, if you do not use any
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
353 keyword-value pairs, you can omit the parentheses around the type
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
354 symbol. For example just @code{string} as a customization type is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
355 equivalent to @code{(string)}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 @menu
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 * Simple Types::
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 * Composite Types::
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 * Splicing into Lists::
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 * Type Keywords::
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
362 * Defining New Types::
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 @end menu
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364
40414
4d919b7986eb (Customization Types): Add a reference to the Widget manual.
Eli Zaretskii <eliz@gnu.org>
parents: 35009
diff changeset
365 All customization types are implemented as widgets; see @ref{Top, ,
50475
b65aa1d740eb Fix cross references.
Juanma Barranquero <lekktu@gmail.com>
parents: 49600
diff changeset
366 Introduction, widget, The Emacs Widget Library}, for details.
40414
4d919b7986eb (Customization Types): Add a reference to the Widget manual.
Eli Zaretskii <eliz@gnu.org>
parents: 35009
diff changeset
367
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 @node Simple Types
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 @subsection Simple Types
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 This section describes all the simple customization types.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 @table @code
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 @item sexp
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 The value may be any Lisp object that can be printed and read back. You
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 can use @code{sexp} as a fall-back for any option, if you don't want to
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 take the time to work out a more specific type to use.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 @item integer
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 The value must be an integer, and is represented textually
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 in the customization buffer.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 @item number
48711
7edccee41a2a (Simple Types): Clarify decription of custom type 'number.
Markus Rost <rost@math.uni-bielefeld.de>
parents: 48585
diff changeset
384 The value must be a number (floating point or integer), and is
7edccee41a2a (Simple Types): Clarify decription of custom type 'number.
Markus Rost <rost@math.uni-bielefeld.de>
parents: 48585
diff changeset
385 represented textually in the customization buffer.
7edccee41a2a (Simple Types): Clarify decription of custom type 'number.
Markus Rost <rost@math.uni-bielefeld.de>
parents: 48585
diff changeset
386
7edccee41a2a (Simple Types): Clarify decription of custom type 'number.
Markus Rost <rost@math.uni-bielefeld.de>
parents: 48585
diff changeset
387 @item float
7edccee41a2a (Simple Types): Clarify decription of custom type 'number.
Markus Rost <rost@math.uni-bielefeld.de>
parents: 48585
diff changeset
388 The value must be a floating point number, and is represented
7edccee41a2a (Simple Types): Clarify decription of custom type 'number.
Markus Rost <rost@math.uni-bielefeld.de>
parents: 48585
diff changeset
389 textually in the customization buffer.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 @item string
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 The value must be a string, and the customization buffer shows just the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
393 contents, with no delimiting @samp{"} characters and no quoting with
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
394 @samp{\}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 @item regexp
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
397 Like @code{string} except that the string must be a valid regular
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
398 expression.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 @item character
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 The value must be a character code. A character code is actually an
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 integer, but this type shows the value by inserting the character in the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 buffer, rather than by showing the number.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 @item file
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 The value must be a file name, and you can do completion with
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 @kbd{M-@key{TAB}}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 @item (file :must-match t)
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 The value must be a file name for an existing file, and you can do
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 completion with @kbd{M-@key{TAB}}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 @item directory
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 The value must be a directory name, and you can do completion with
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @kbd{M-@key{TAB}}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
417 @item hook
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
418 The value must be a list of functions (or a single function, but that is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
419 obsolete usage). This customization type is used for hook variables.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
420 You can use the @code{:options} keyword in a hook variable's
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
421 @code{defcustom} to specify a list of functions recommended for use in
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
422 the hook; see @ref{Variable Definitions}.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
423
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
424 @item alist
24952
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
425 The value must be a list of cons-cells, the @sc{car} of each cell
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
426 representing a key, and the @sc{cdr} of the same cell representing an
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
427 associated value. The user can add and delete key/value pairs, and
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
428 edit both the key and the value of each pair.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
429
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
430 You can specify the key and value types like this:
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
431
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
432 @smallexample
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
433 (alist :key-type @var{key-type} :value-type @var{value-type})
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
434 @end smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
435
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
436 @noindent
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
437 where @var{key-type} and @var{value-type} are customization type
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
438 specifications. The default key type is @code{sexp}, and the default
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
439 value type is @code{sexp}.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
440
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
441 The user can add any key matching the specified key type, but you can
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
442 give some keys a preferential treatment by specifying them with the
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
443 @code{:options} (see @ref{Variable Definitions}). The specified keys
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
444 will always be shown in the customize buffer (together with a suitable
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
445 value), with a checkbox to include or exclude or disable the key/value
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
446 pair from the alist. The user will not be able to edit the keys
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
447 specified by the @code{:options} keyword argument.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
448
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
449 The argument to the @code{:options} keywords should be a list of option
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
450 specifications. Ordinarily, the options are simply atoms, which are the
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
451 specified keys. For example:
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
452
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
453 @smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
454 :options '("foo" "bar" "baz")
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
455 @end smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
456
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
457 @noindent
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
458 specifies that there are three ``known'' keys, namely @code{"foo"},
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
459 @code{"bar"} and @code{"baz"}, which will always be shown first.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
460
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
461 You may want to restrict the value type for specific keys, for example,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
462 the value associated with the @code{"bar"} key can only be an integer.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
463 You can specify this by using a list instead of an atom in the option
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
464 specification. The first element will specify the key, like before,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
465 while the second element will specify the value type.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
466
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
467 @smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
468 :options '("foo" ("bar" integer) "baz")
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
469 @end smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
470
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
471 Finally, you may want to change how the key is presented. By default,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
472 the key is simply shown as a @code{const}, since the user cannot change
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
473 the special keys specified with the @code{:options} keyword. However,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
474 you may want to use a more specialized type for presenting the key, like
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
475 @code{function-item} if you know it is a symbol with a function binding.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
476 This is done by using a customization type specification instead of a
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
477 symbol for the key.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
478
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
479 @smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
480 :options '("foo" ((function-item some-function) integer) "baz")
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
481 @end smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
482
24952
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
483 Many alists use lists with two elements, instead of cons cells. For
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
484 example,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
485
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
486 @smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
487 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
488 "Each element is a list of the form (KEY VALUE).")
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
489 @end smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
490
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
491 @noindent
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48711
diff changeset
492 instead of
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
493
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
494 @smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
495 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
496 "Each element is a cons-cell (KEY . VALUE).")
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
497 @end smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
498
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
499 Because of the way lists are implemented on top of cons cells, you can
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
500 treat @code{list-alist} in the example above as a cons cell alist, where
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
501 the value type is a list with a single element containing the real
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
502 value.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
503
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
504 @smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
505 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
506 "Each element is a list of the form (KEY VALUE)."
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
507 :type '(alist :value-type (group integer)))
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
508 @end smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
509
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
510 The @code{group} widget is used here instead of @code{list} only because
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
511 the formatting is better suited for the purpose.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
512
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
513 Similarly, you can have alists with more values associated with each
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
514 key, using variations of this trick:
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
515
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
516 @smallexample
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48711
diff changeset
517 (defcustom person-data '(("brian" 50 t)
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
518 ("dorith" 55 nil)
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
519 ("ken" 52 t))
28398
844fb933c1aa *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
520 "Alist of basic info about people.
844fb933c1aa *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
521 Each element has the form (NAME AGE MALE-FLAG)."
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
522 :type '(alist :value-type (group integer boolean)))
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
523
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48711
diff changeset
524 (defcustom pets '(("brian")
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
525 ("dorith" "dog" "guppy")
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
526 ("ken" "cat"))
28398
844fb933c1aa *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
527 "Alist of people's pets.
844fb933c1aa *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
528 In an element (KEY . VALUE), KEY is the person's name,
844fb933c1aa *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
529 and the VALUE is a list of that person's pets."
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
530 :type '(alist :value-type (repeat string)))
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
531 @end smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
532
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
533 @item plist
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
534 The @code{plist} custom type is similar to the @code{alist} (see above),
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
535 except that the information is stored as a property list, i.e. a list of
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
536 this form:
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
537
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
538 @smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
539 (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
540 @end smallexample
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
541
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
542 The default @code{:key-type} for @code{plist} is @code{symbol},
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
543 rather than @code{sexp}.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23902
diff changeset
544
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 @item symbol
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 The value must be a symbol. It appears in the customization buffer as
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 the name of the symbol.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @item function
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 The value must be either a lambda expression or a function name. When
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 it is a function name, you can do completion with @kbd{M-@key{TAB}}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 @item variable
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 The value must be a variable name, and you can do completion with
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 @kbd{M-@key{TAB}}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
557 @item face
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
558 The value must be a symbol which is a face name, and you can do
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
559 completion with @kbd{M-@key{TAB}}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
560
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 @item boolean
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
562 The value is boolean---either @code{nil} or @code{t}. Note that by
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
563 using @code{choice} and @code{const} together (see the next section),
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
564 you can specify that the value must be @code{nil} or @code{t}, but also
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
565 specify the text to describe each value in a way that fits the specific
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
566 meaning of the alternative.
32521
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
567
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
568 @item coding-system
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
569 The value must be a coding-system name, and you can do completion with
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
570 @kbd{M-@key{TAB}}.
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
571
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
572 @item color
bfbe1fcac416 custom types emacs-commentary-link, coding-system, color
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
573 The value must be a valid color name, and you can do completion with
54299
9856d5a15940 Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 53319
diff changeset
574 @kbd{M-@key{TAB}}. A sample is provided.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @end table
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @node Composite Types
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 @subsection Composite Types
46643
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
579 @cindex arguments (of composite type)
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 When none of the simple types is appropriate, you can use composite
46643
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
582 types, which build new types from other types or from specified data.
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
583 The specified types or data are called the @dfn{arguments} of the
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
584 composite type. The composite type normally looks like this:
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @example
46643
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
587 (@var{constructor} @var{arguments}@dots{})
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @end example
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 @noindent
46643
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
591 but you can also add keyword-value pairs before the arguments, like
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
592 this:
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593
46643
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
594 @example
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
595 (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
596 @end example
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597
46643
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
598 Here is a table of constructors and how to use them to write
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
599 composite types:
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
600
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
601 @table @code
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 @item (cons @var{car-type} @var{cdr-type})
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
604 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 symbol)} is a customization type which matches values such as
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 @code{("foo" . foo)}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
608 In the customization buffer, the @sc{car} and the @sc{cdr} are
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 displayed and edited separately, each according to the type
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 that you specify for it.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 @item (list @var{element-types}@dots{})
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 The value must be a list with exactly as many elements as the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 @var{element-types} you have specified; and each element must fit the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 corresponding @var{element-type}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 For example, @code{(list integer string function)} describes a list of
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 three elements; the first element must be an integer, the second a
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 string, and the third a function.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
621 In the customization buffer, each element is displayed and edited
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 separately, according to the type specified for it.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 @item (vector @var{element-types}@dots{})
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 Like @code{list} except that the value must be a vector instead of a
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 list. The elements work the same as in @code{list}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627
35009
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
628 @item (choice @var{alternative-types}@dots{})
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 The value must fit at least one of @var{alternative-types}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 For example, @code{(choice integer string)} allows either an
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 integer or a string.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 In the customization buffer, the user selects one of the alternatives
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 using a menu, and can then edit the value in the usual way for that
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 alternative.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 Normally the strings in this menu are determined automatically from the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 choices; however, you can specify different strings for the menu by
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 including the @code{:tag} keyword in the alternatives. For example, if
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 an integer stands for a number of spaces, while a string is text to use
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 verbatim, you might write the customization type this way,
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
643 @example
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 (choice (integer :tag "Number of spaces")
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 (string :tag "Literal text"))
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
646 @end example
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @noindent
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
649 so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
651 In any alternative for which @code{nil} is not a valid value, other than
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
652 a @code{const}, you should specify a valid default for that alternative
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
653 using the @code{:value} keyword. @xref{Type Keywords}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
654
48585
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
655 If some values are covered by more than one of the alternatives,
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
656 customize will choose the first alternative that the value fits. This
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
657 means you should always list the most specific types first, and the
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
658 most general last. Here's an example of proper usage:
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
659
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
660 @example
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
661 (choice (const :tag "Off" nil) symbol (sexp :tag "Other"))
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
662 @end example
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
663
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
664 @noindent
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
665 This way, the special value @code{nil} is not treated like other
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
666 symbols, and symbols are not treated like other Lisp expressions.
be738e9c1a09 Explain about ordering of alternatives in `choice'.
Richard M. Stallman <rms@gnu.org>
parents: 48404
diff changeset
667
35009
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
668 @item (radio @var{element-types}@dots{})
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
669 This is similar to @code{choice}, except that the choices are displayed
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
670 using `radio buttons' rather than a menu. This has the advantage of
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
671 displaying documentation for the choices when applicable and so is often
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
672 a good choice for a choice between constant functions
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
673 (@code{function-item} customization types).
d80f2bfd0e05 Add `radio' type. User variable doc strings and backquote in
Dave Love <fx@gnu.org>
parents: 33150
diff changeset
674
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @item (const @var{value})
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 The value must be @var{value}---nothing else is allowed.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 The main use of @code{const} is inside of @code{choice}. For example,
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 @code{(choice integer (const nil))} allows either an integer or
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
680 @code{nil}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
681
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
682 @code{:tag} is often used with @code{const}, inside of @code{choice}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
683 For example,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
684
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
685 @example
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
686 (choice (const :tag "Yes" t)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
687 (const :tag "No" nil)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
688 (const :tag "Ask" foo))
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
689 @end example
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690
22433
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
691 @noindent
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
692 describes a variable for which @code{t} means yes, @code{nil} means no,
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
693 and @code{foo} means ``ask.''
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
694
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
695 @item (other @var{value})
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
696 This alternative can match any Lisp value, but if the user chooses this
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
697 alternative, that selects the value @var{value}.
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
698
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
699 The main use of @code{other} is as the last element of @code{choice}.
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
700 For example,
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
701
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
702 @example
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
703 (choice (const :tag "Yes" t)
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
704 (const :tag "No" nil)
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
705 (other :tag "Ask" foo))
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
706 @end example
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
707
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
708 @noindent
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
709 describes a variable for which @code{t} means yes, @code{nil} means no,
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
710 and anything else means ``ask.'' If the user chooses @samp{Ask} from
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
711 the menu of alternatives, that specifies the value @code{foo}; but any
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
712 other value (not @code{t}, @code{nil} or @code{foo}) displays as
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
713 @samp{Ask}, just like @code{foo}.
a9820c4e8c9e Describe widget type `other'.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
714
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 @item (function-item @var{function})
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 Like @code{const}, but used for values which are functions. This
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
717 displays the documentation string as well as the function name.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
718 The documentation string is either the one you specify with
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
719 @code{:doc}, or @var{function}'s own documentation string.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 @item (variable-item @var{variable})
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 Like @code{const}, but used for values which are variable names. This
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
723 displays the documentation string as well as the variable name. The
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
724 documentation string is either the one you specify with @code{:doc}, or
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
725 @var{variable}'s own documentation string.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726
23902
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
727 @item (set @var{types}@dots{})
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
728 The value must be a list, and each element of the list must match one of
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
729 the @var{types} specified.
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
730
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
731 This appears in the customization buffer as a checklist, so that each of
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
732 @var{types} may have either one corresponding element or none. It is
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
733 not possible to specify two different elements that match the same one
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
734 of @var{types}. For example, @code{(set integer symbol)} allows one
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
735 integer and/or one symbol in the list; it does not allow multiple
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
736 integers or multiple symbols. As a result, it is rare to use
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
737 nonspecific types such as @code{integer} in a @code{set}.
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
738
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
739 Most often, the @var{types} in a @code{set} are @code{const} types, as
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
740 shown here:
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
741
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
742 @example
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
743 (set (const :bold) (const :italic))
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
744 @end example
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
745
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
746 Sometimes they describe possible elements in an alist:
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
747
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
748 @example
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
749 (set (cons :tag "Height" (const height) integer)
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
750 (cons :tag "Width" (const width) integer))
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
751 @end example
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
752
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
753 @noindent
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
754 That lets the user specify a height value optionally
1c12a73f742d *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22433
diff changeset
755 and a width value optionally.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 @item (repeat @var{element-type})
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 The value must be a list and each element of the list must fit the type
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 @var{element-type}. This appears in the customization buffer as a
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
760 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761 more elements or removing elements.
46643
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
762
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
763 @item (restricted-sexp :match-alternatives @var{criteria})
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
764 This is the most general composite type construct. The value may be
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
765 any Lisp object that satisfies one of @var{criteria}. @var{criteria}
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
766 should be a list, and each element should be one of these
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
767 possibilities:
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
768
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
769 @itemize @bullet
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
770 @item
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
771 A predicate---that is, a function of one argument that has no side
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
772 effects, and returns either @code{nil} or non-@code{nil} according to
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
773 the argument. Using a predicate in the list says that objects for which
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
774 the predicate returns non-@code{nil} are acceptable.
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
775
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
776 @item
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
777 A quoted constant---that is, @code{'@var{object}}. This sort of element
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
778 in the list says that @var{object} itself is an acceptable value.
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
779 @end itemize
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
780
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
781 For example,
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
782
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
783 @example
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
784 (restricted-sexp :match-alternatives
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
785 (integerp 't 'nil))
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
786 @end example
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
787
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
788 @noindent
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
789 allows integers, @code{t} and @code{nil} as legitimate values.
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
790
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
791 The customization buffer shows all legitimate values using their read
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
792 syntax, and the user edits them textually.
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
793 @end table
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
794
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
795 Here is a table of the keywords you can use in keyword-value pairs
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
796 in a composite type:
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
797
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
798 @table @code
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
799 @item :tag @var{tag}
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
800 Use @var{tag} as the name of this alternative, for user communication
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
801 purposes. This is useful for a type that appears inside of a
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
802 @code{choice}.
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
803
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
804 @item :match-alternatives @var{criteria}
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
805 Use @var{criteria} to match possible values. This is used only in
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
806 @code{restricted-sexp}.
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
807
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
808 @item :args @var{argument-list}
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
809 Use the elements of @var{argument-list} as the arguments of the type
46643
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
810 construct. For instance, @code{(const :args (foo))} is equivalent to
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
811 @code{(const foo)}. You rarely need to write @code{:args} explicitly,
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
812 because normally the arguments are recognized automatically as
7715f3004d93 (Composite Types): Explain what arguments are. Show what keyword-value
Richard M. Stallman <rms@gnu.org>
parents: 44142
diff changeset
813 whatever follows the last keyword-value pair.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 @end table
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 @node Splicing into Lists
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 @subsection Splicing into Lists
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 The @code{:inline} feature lets you splice a variable number of
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 elements into the middle of a list or vector. You use it in a
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821 @code{set}, @code{choice} or @code{repeat} type which appears among the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 element-types of a @code{list} or @code{vector}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 Normally, each of the element-types in a @code{list} or @code{vector}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 describes one and only one element of the list or vector. Thus, if an
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 element-type is a @code{repeat}, that specifies a list of unspecified
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 length which appears as one element.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 But when the element-type uses @code{:inline}, the value it matches is
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 merged directly into the containing sequence. For example, if it
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 matches a list with three elements, those become three elements of the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 overall sequence. This is analogous to using @samp{,@@} in the backquote
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 construct.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834
46809
a7c081b4fc3c 2002-08-05 Per Abrahamsen <abraham@dina.kvl.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 46643
diff changeset
835 For example, to specify a list whose first element must be @code{baz}
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 and whose remaining arguments should be zero or more of @code{foo} and
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 @code{bar}, use this customization type:
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 @example
46809
a7c081b4fc3c 2002-08-05 Per Abrahamsen <abraham@dina.kvl.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 46643
diff changeset
840 (list (const baz) (set :inline t (const foo) (const bar)))
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 @end example
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @noindent
46809
a7c081b4fc3c 2002-08-05 Per Abrahamsen <abraham@dina.kvl.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 46643
diff changeset
844 This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
a7c081b4fc3c 2002-08-05 Per Abrahamsen <abraham@dina.kvl.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 46643
diff changeset
845 and @code{(baz foo bar)}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 When the element-type is a @code{choice}, you use @code{:inline} not
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 in the @code{choice} itself, but in (some of) the alternatives of the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 @code{choice}. For example, to match a list which must start with a
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 file name, followed either by the symbol @code{t} or two strings, use
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 this customization type:
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 @example
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 (list file
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 (choice (const t)
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 (list :inline t string string)))
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 @end example
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 @noindent
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 If the user chooses the first alternative in the choice, then the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 overall list has two elements and the second element is @code{t}. If
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 the user chooses the second alternative, then the overall list has three
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 elements and the second and third must be strings.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865 @node Type Keywords
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866 @subsection Type Keywords
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 You can specify keyword-argument pairs in a customization type after the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 type name symbol. Here are the keywords you can use, and their
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 meanings:
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872 @table @code
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 @item :value @var{default}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 This is used for a type that appears as an alternative inside of
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
875 @code{choice}; it specifies the default value to use, at first, if and
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 when the user selects this alternative with the menu in the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877 customization buffer.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879 Of course, if the actual value of the option fits this alternative, it
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
880 will appear showing the actual value, not @var{default}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
881
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
882 If @code{nil} is not a valid value for the alternative, then it is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
883 essential to specify a valid default with @code{:value}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
884
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 @item :format @var{format-string}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 This string will be inserted in the buffer to represent the value
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 corresponding to the type. The following @samp{%} escapes are available
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 for use in @var{format-string}:
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890 @table @samp
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 @item %[@var{button}%]
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 Display the text @var{button} marked as a button. The @code{:action}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 attribute specifies what the button will do if the user invokes it;
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 its value is a function which takes two arguments---the widget which
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 the button appears in, and the event.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 There is no way to specify two different buttons with different
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
898 actions.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 @item %@{@var{sample}%@}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 Show @var{sample} in a special face specified by @code{:sample-face}.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @item %v
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 Substitute the item's value. How the value is represented depends on
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 the kind of item, and (for variables) on the customization type.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 @item %d
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 Substitute the item's documentation string.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 @item %h
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 Like @samp{%d}, but if the documentation string is more than one line,
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 add an active field to control whether to show all of it or just the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 first line.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915 @item %t
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 Substitute the tag here. You specify the tag with the @code{:tag}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 keyword.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 @item %%
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48711
diff changeset
920 Display a literal @samp{%}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921 @end table
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
923 @item :action @var{action}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
924 Perform @var{action} if the user clicks on a button.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
926 @item :button-face @var{face}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
927 Use the face @var{face} (a face name or a list of face names) for button
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
928 text displayed with @samp{%[@dots{}%]}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
929
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
930 @item :button-prefix @var{prefix}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
931 @itemx :button-suffix @var{suffix}
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932 These specify the text to display before and after a button.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933 Each can be:
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 @table @asis
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 @item @code{nil}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 No text is inserted.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 @item a string
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 The string is inserted literally.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 @item a symbol
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 The symbol's value is used.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 @end table
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
946 @item :tag @var{tag}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
947 Use @var{tag} (a string) as the tag for the value (or part of the value)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
948 that corresponds to this type.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
950 @item :doc @var{doc}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
951 Use @var{doc} as the documentation string for this value (or part of the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
952 value) that corresponds to this type. In order for this to work, you
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
953 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
954 in that value.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
955
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
956 The usual reason to specify a documentation string for a type is to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
957 provide more information about the meanings of alternatives inside a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
958 @code{:choice} type or the parts of some other composite type.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960 @item :help-echo @var{motion-doc}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 When you move to this item with @code{widget-forward} or
30500
1d1ab0dfb528 :help-echo needn't be a string.
Dave Love <fx@gnu.org>
parents: 28398
diff changeset
962 @code{widget-backward}, it will display the string @var{motion-doc} in
1d1ab0dfb528 :help-echo needn't be a string.
Dave Love <fx@gnu.org>
parents: 28398
diff changeset
963 the echo area. In addition, @var{motion-doc} is used as the mouse
1d1ab0dfb528 :help-echo needn't be a string.
Dave Love <fx@gnu.org>
parents: 28398
diff changeset
964 @code{help-echo} string and may actually be a function or form evaluated
52267
248944d84147 (Type Keywords): Correct the description of `:help-echo' in the case
Luc Teirlinck <teirllm@auburn.edu>
parents: 50475
diff changeset
965 to yield a help string. If it is a function, it is called with one
248944d84147 (Type Keywords): Correct the description of `:help-echo' in the case
Luc Teirlinck <teirllm@auburn.edu>
parents: 50475
diff changeset
966 argument, the widget.
59768
56ad3ca04692 (Type Keywords): Uncomment the xref to the help-echo property documentation.
Eli Zaretskii <eliz@gnu.org>
parents: 58495
diff changeset
967 @xref{Text help-echo}.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 @item :match @var{function}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
970 Specify how to decide whether a value matches the type. The
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
971 corresponding value, @var{function}, should be a function that accepts
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
972 two arguments, a widget and a value; it should return non-@code{nil} if
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21006
diff changeset
973 the value is acceptable.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 @ignore
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 @item :indent @var{columns}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 Indent this item by @var{columns} columns. The indentation is used for
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978 @samp{%n}, and automatically for group names, for checklists and radio
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 buttons, and for editable lists. It affects the whole of the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 item except for the first line.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 @item :offset @var{columns}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 An integer indicating how many extra spaces to indent the subitems of
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 this item. By default, subitems are indented the same as their parent.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 @item :extra-offset
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 An integer indicating how many extra spaces to add to this item's
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 indentation, compared to its parent.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990 @item :notify
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 A function called each time the item or a subitem is changed. The
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992 function is called with two or three arguments. The first argument is
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993 the item itself, the second argument is the item that was changed, and
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 the third argument is the event leading to the change, if any.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 @item :menu-tag
44142
ad5105ded8ed (Type Keywords): Minor corrections and cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 43477
diff changeset
997 A tag used in the menu when the widget is used as an option in a
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 @code{menu-choice} widget.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 @item :menu-tag-get
44142
ad5105ded8ed (Type Keywords): Minor corrections and cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 43477
diff changeset
1001 A function used for finding the tag when the widget is used as an option
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 in a @code{menu-choice} widget. By default, the tag used will be either the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004 representation of the @code{:value} property if not.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006 @item :validate
44142
ad5105ded8ed (Type Keywords): Minor corrections and cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 43477
diff changeset
1007 A function which takes a widget as an argument, and return @code{nil}
ad5105ded8ed (Type Keywords): Minor corrections and cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 43477
diff changeset
1008 if the widget's current value is valid for the widget. Otherwise, it
ad5105ded8ed (Type Keywords): Minor corrections and cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 43477
diff changeset
1009 should return the widget containing the invalid data, and set that
ad5105ded8ed (Type Keywords): Minor corrections and cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 43477
diff changeset
1010 widget's @code{:error} property to a string explaining the error.
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 You can use the function @code{widget-children-validate} for this job;
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 it tests that all children of @var{widget} are valid.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 @item :tab-order
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 Specify the order in which widgets are traversed with
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 @code{widget-forward} or @code{widget-backward}. This is only partially
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 implemented.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 @enumerate a
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021 @item
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 Widgets with tabbing order @code{-1} are ignored.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48711
diff changeset
1024 @item
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027 whichever comes first.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 @item
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 When on a widget with no tabbing order specified, go to the next widget
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031 in the buffer with a positive tabbing order, or @code{nil}
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @end enumerate
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 @item :parent
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1035 The parent of a nested widget (e.g., a @code{menu-choice} item or an
21006
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036 element of a @code{editable-list} widget).
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 @item :sibling-args
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 This keyword is only used for members of a @code{radio-button-choice} or
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 @code{checklist}. The value should be a list of extra keyword
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 arguments, which will be used when creating the @code{radio-button} or
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 @code{checkbox} associated with this item.
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 @end ignore
00022857f529 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044 @end table
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52267
diff changeset
1045
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1046 @node Defining New Types
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1047 @subsection Defining New Types
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1048
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1049 In the previous sections we have described how to construct elaborate
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1050 type specifications for @code{defcustom}. In some cases you may want
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1051 to give such a type specification a name. The obvious case is when
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1052 you are using the same type for many user options: rather than repeat
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1053 the specification for each option, you can give the type specification
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1054 a name, and use that name each @code{defcustom}. The other case is
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1055 when a user option's value is a recursive data structure. To make it
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1056 possible for a datatype to refer to itself, it needs to have a name.
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1057
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1058 Since custom types are implemented as widgets, the way to define a new
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1059 customize type is to define a new widget. We are not going to describe
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1060 the widget interface here in details, see @ref{Top, , Introduction,
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1061 widget, The Emacs Widget Library}, for that. Instead we are going to
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1062 demonstrate the minimal functionality needed for defining new customize
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1063 types by a simple example.
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1064
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1065 @example
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1066 (define-widget 'binary-tree-of-string 'lazy
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1067 "A binary tree made of cons-cells and strings."
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1068 :offset 4
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1069 :tag "Node"
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1070 :type '(choice (string :tag "Leaf" :value "")
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1071 (cons :tag "Interior"
54299
9856d5a15940 Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 53319
diff changeset
1072 :value ("" . "")
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1073 binary-tree-of-string
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1074 binary-tree-of-string)))
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1075
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1076 (defcustom foo-bar ""
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1077 "Sample variable holding a binary tree of strings."
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1078 :type 'binary-tree-of-string)
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1079 @end example
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1080
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1081 The function to define a new widget is called @code{define-widget}. The
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1082 first argument is the symbol we want to make a new widget type. The
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1083 second argument is a symbol representing an existing widget, the new
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1084 widget is going to be defined in terms of difference from the existing
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1085 widget. For the purpose of defining new customization types, the
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1086 @code{lazy} widget is perfect, because it accepts a @code{:type} keyword
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1087 argument with the same syntax as the keyword argument to
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1088 @code{defcustom} with the same name. The third argument is a
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1089 documentation string for the new widget. You will be able to see that
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1090 string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string
54299
9856d5a15940 Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 53319
diff changeset
1091 @key{ret}} command.
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1092
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1093 After these mandatory arguments follow the keyword arguments. The most
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1094 important is @code{:type}, which describes the data type we want to match
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1095 with this widget. Here a @code{binary-tree-of-string} is described as
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1096 being either a string, or a cons-cell whose car and cdr are themselves
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1097 both @code{binary-tree-of-string}. Note the reference to the widget
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1098 type we are currently in the process of defining. The @code{:tag}
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1099 attribute is a string to name the widget in the user interface, and the
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1100 @code{:offset} argument is there to ensure that child nodes are
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1101 indented four spaces relative to the parent node, making the tree
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1102 structure apparent in the customization buffer.
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1103
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1104 The @code{defcustom} shows how the new widget can be used as an ordinary
54299
9856d5a15940 Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 53319
diff changeset
1105 customization type.
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1106
58495
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1107 The reason for the name @code{lazy} is that the other composite
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1108 widgets convert their inferior widgets to internal form when the
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1109 widget is instantiated in a buffer. This conversion is recursive, so
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1110 the inferior widgets will convert @emph{their} inferior widgets. If
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1111 the data structure is itself recursive, this conversion is an infinite
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1112 recursion. The @code{lazy} widget prevents the recursion: it convert
a30209899fa0 (Variable Definitions): Replace show-paren-mode example with tooltip-mode.
Richard M. Stallman <rms@gnu.org>
parents: 56235
diff changeset
1113 its @code{:type} argument only when needed.
53319
36b31fc002f2 2003-12-12 Jesper Harder <harder@ifa.au.dk>
Per Abrahamsen <abraham@dina.kvl.dk>
parents: 52978
diff changeset
1114
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52267
diff changeset
1115 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52267
diff changeset
1116 arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52267
diff changeset
1117 @end ignore