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