Mercurial > emacs
annotate lispref/customize.texi @ 21963:b717a61747c5
(regex_compile): When checking after exactn
for a repetition operator, don't look beyond end of pattern arg.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Wed, 06 May 1998 20:46:35 +0000 |
parents | 90da2489c498 |
children | d4ac295a98b3 |
rev | line source |
---|---|
21006 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1997, 1998 Free Software Foundation, Inc. | |
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 | |
22 @section Common Keywords for All Kinds of Items | |
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 | |
34 @item :group @var{group} | |
35 Put this customization item in group @var{group}. When you use | |
36 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of | |
37 @var{group}. | |
38 | |
39 If you use this keyword more than once, you can put a single item into | |
40 more than one group. Displaying any of those groups will show this | |
41 item. Be careful not to overdo this! | |
42 | |
43 @item :link @var{link-data} | |
44 Include an external link after the documentation string for this item. | |
45 This is a sentence containing an active field which references some | |
46 other documentation. | |
47 | |
48 There are three alternatives you can use for @var{link-data}: | |
49 | |
50 @table @code | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
51 @item :tag @var{name} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
52 Use @var{name}, a string, instead of the item's name, to label the item |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
53 in customization menus and buffers. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
54 |
21006 | 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}. |
21006 | 67 @end table |
68 | |
69 You can specify the text to use in the customization buffer by adding | |
70 @code{:tag @var{name}} after the first element of the @var{link-data}; | |
71 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to | |
72 the Emacs manual which appears in the buffer as @samp{foo}. | |
73 | |
74 An item can have more than one external link; however, most items have | |
75 none at all. | |
76 | |
77 @item :load @var{file} | |
78 Load file @var{file} (a string) before displaying this customization | |
79 item. Loading is done with @code{load-library}, and only if the file is | |
80 not already loaded. | |
81 | |
82 @item :require @var{feature} | |
83 Require feature @var{feature} (a symbol) when installing a value for | |
84 this item (an option or a face) that was saved using the customization | |
85 feature. This is done by calling @code{require}. | |
86 | |
87 The most common reason to use @code{:require} is when a variable enables | |
88 a feature such as a minor mode, and just setting the variable won't have | |
89 any effect unless the code which implements the mode is loaded. | |
90 @end table | |
91 | |
92 @node Group Definitions | |
93 @section Defining Custom Groups | |
94 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
95 Each Emacs Lisp package should have one main customization group which |
21006 | 96 contains all the options, faces and other groups in the package. If the |
97 package has a small number of options and faces, use just one group and | |
98 put everything in it. When there are more than twelve or so options and | |
99 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
|
100 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
|
101 put some of the options and faces in the package's main group alongside |
21006 | 102 the subgroups. |
103 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
104 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
|
105 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
|
106 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
|
107 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
|
108 keyword. |
21006 | 109 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
110 The way to declare new customization groups is with @code{defgroup}. |
21006 | 111 |
112 @tindex defgroup | |
113 @defmac defgroup group members doc [keyword value]... | |
114 Declare @var{group} as a customization group containing @var{members}. | |
115 Do not quote the symbol @var{group}. The argument @var{doc} specifies | |
116 the documentation string for the group. | |
117 | |
118 The arguments @var{members} can be an alist whose elements specify | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
119 customization items to be members of the group; however, normally |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
120 @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
|
121 using the @code{:group} keyword when defining those members. |
21006 | 122 |
123 @ignore | |
124 @code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and | |
125 @var{widget} is a widget for editing that symbol. Useful widgets are | |
126 @code{custom-variable} for editing variables, @code{custom-face} for | |
127 editing faces, and @code{custom-group} for editing groups. | |
128 @end ignore | |
129 | |
130 In addition to the common keywords (@pxref{Common Keywords}), you can | |
131 use this keyword in @code{defgroup}: | |
132 | |
133 @table @code | |
134 @item :prefix @var{prefix} | |
135 If the name of an item in the group starts with @var{prefix}, then the | |
136 tag for that item is constructed (by default) by omitting @var{prefix}. | |
137 | |
138 One group can have any number of prefixes. | |
139 @end table | |
140 @end defmac | |
141 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
142 The prefix-discarding feature is currently turned off, which means |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
143 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
|
144 found that discarding the specified prefixes often led to confusing |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
145 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
|
146 @code{defgroup} definitions for various groups added @code{:prefix} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
147 keywords whenever they make logical sense---that is, whenever the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
148 variables in the library have a common prefix. |
21006 | 149 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
150 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
|
151 necessary to check the specific effects of discarding a particular |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
152 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
|
153 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
|
154 should not be used in that case. |
21006 | 155 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
156 It should be possible to recheck all the customization groups, delete |
21006 | 157 the @code{:prefix} specifications which give unclear results, and then |
158 turn this feature back on, if someone would like to do the work. | |
159 | |
160 @node Variable Definitions | |
161 @section Defining Customization Variables | |
162 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
163 Use @code{defcustom} to declare user-editable variables. |
21006 | 164 |
165 @tindex defcustom | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
166 @defmac defcustom option default doc [keyword value]... |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
167 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
|
168 quote @var{option}. The argument @var{doc} specifies the documentation |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
169 string for the variable. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
170 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
171 If @var{option} is void, @code{defcustom} initializes it to |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
172 @var{default}. @var{default} should be an expression to compute the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
173 value; be careful in writing it, because it can be be evaluated on more |
21006 | 174 than one occasion. |
175 | |
176 The following additional keywords are defined: | |
177 | |
178 @table @code | |
179 @item :type @var{type} | |
180 Use @var{type} as the data type for this option. It specifies which | |
181 values are legitimate, and how to display the value. | |
182 @xref{Customization Types}, for more information. | |
183 | |
184 @item :options @var{list} | |
185 Specify @var{list} as the list of reasonable values for use in this | |
186 option. | |
187 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
188 Currently this is meaningful only when the type is @code{hook}. In that |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
189 case, the elements of @var{list} should be functions that are useful as |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
190 elements of the hook value. The user is not restricted to using only |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
191 these functions, but they are offered as convenient alternatives. |
21006 | 192 |
193 @item :version @var{version} | |
194 This option specifies that the variable's default value was changed in | |
195 Emacs version @var{version}. For example, | |
196 | |
197 @example | |
198 (defcustom foo-max 34 | |
199 "*Maximum number of foo's allowed." | |
200 :type 'integer | |
201 :group 'foo | |
202 :version "20.3") | |
203 @end example | |
204 | |
205 @item :set @var{setfunction} | |
206 Specify @var{setfunction} as the way to change the value of this option. | |
207 The function @var{setfunction} should take two arguments, a symbol and | |
208 the new value, and should do whatever is necessary to update the value | |
209 properly for this option (which may not mean simply setting the option | |
210 as a Lisp variable). The default for @var{setfunction} is | |
211 @code{set-default}. | |
212 | |
213 @item :get @var{getfunction} | |
214 Specify @var{getfunction} as the way to extract the value of this | |
215 option. The function @var{getfunction} should take one argument, a | |
216 symbol, and should return the ``current value'' for that symbol (which | |
217 need not be the symbol's Lisp value). The default is | |
218 @code{default-value}. | |
219 | |
220 @item :initialize @var{function} | |
221 @var{function} should be a function used to initialize the variable when | |
222 the @code{defcustom} is evaluated. It should take two arguments, the | |
223 symbol and value. Here are some predefined functions meant for use in | |
224 this way: | |
225 | |
226 @table @code | |
227 @item custom-initialize-set | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
228 Use the variable's @code{:set} function to initialize the variable, but |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
229 do not reinitialize it if it is already non-void. This is the default |
21006 | 230 @code{:initialize} function. |
231 | |
232 @item custom-initialize-default | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
233 Like @code{custom-initialize-set}, but use the function |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
234 @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
|
235 @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
|
236 @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
|
237 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
|
238 customizing the variable will do so. |
21006 | 239 |
240 @item custom-initialize-reset | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
241 Always use the @code{:set} function to initialize the variable. If the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
242 variable is already non-void, reset it by calling the @code{:set} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
243 function using the current value (returned by the @code{:get} method). |
21006 | 244 |
245 @item custom-initialize-changed | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
246 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
|
247 already set or has been customized; otherwise, just use |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
248 @code{set-default}. |
21006 | 249 @end table |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
250 @end table |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
251 @end defmac |
21006 | 252 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
253 The @code{:require} option is useful for an option that turns on the |
21006 | 254 operation of a certain feature. Assuming that the package is coded to |
255 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
|
256 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
|
257 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
|
258 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
259 @example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
260 (defcustom show-paren-mode nil |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
261 "Toggle Show Paren mode@enddots{}" |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
262 :set (lambda (symbol value) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
263 (show-paren-mode (or value 0))) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
264 :initialize 'custom-initialize-default |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
265 :type 'boolean |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
266 :group 'paren-showing |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
267 :require 'paren) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
268 @end example |
21006 | 269 |
270 @ignore | |
271 Use @code{custom-add-option} to specify that a specific function is | |
272 useful as an member of a hook. | |
273 | |
274 @defun custom-add-option symbol option | |
275 To the variable @var{symbol} add @var{option}. | |
276 | |
277 If @var{symbol} is a hook variable, @var{option} should be a hook | |
278 member. For other types variables, the effect is undefined." | |
279 @end defun | |
280 @end ignore | |
281 | |
282 Internally, @code{defcustom} uses the symbol property | |
283 @code{standard-value} to record the expression for the default value, | |
284 and @code{saved-value} to record the value saved by the user with the | |
285 customization buffer. The @code{saved-value} property is actually a | |
286 list whose car is an expression which evaluates to the value. | |
287 | |
288 @node Customization Types | |
289 @section Customization Types | |
290 | |
291 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
|
292 its @dfn{customization type}. That is a Lisp object which describes (1) |
21006 | 293 which values are legitimate and (2) how to display the value in the |
294 customization buffer for editing. | |
295 | |
296 You specify the customization type in @code{defcustom} with the | |
297 @code{:type} keyword. The argument of @code{:type} is evaluated; since | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
298 types that vary at run time are rarely useful, normally you use a quoted |
21006 | 299 constant. For example: |
300 | |
301 @example | |
302 (defcustom diff-command "diff" | |
303 "*The command to use to run diff." | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
304 :type '(string) |
21006 | 305 :group 'diff) |
306 @end example | |
307 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
308 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
|
309 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
|
310 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
|
311 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
|
312 optionally write keyword-value pairs (@pxref{Type Keywords}). |
21006 | 313 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
314 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
|
315 @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
|
316 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
|
317 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
|
318 equivalent to @code{(string)}. |
21006 | 319 |
320 @menu | |
321 * Simple Types:: | |
322 * Composite Types:: | |
323 * Splicing into Lists:: | |
324 * Type Keywords:: | |
325 @end menu | |
326 | |
327 @node Simple Types | |
328 @subsection Simple Types | |
329 | |
330 This section describes all the simple customization types. | |
331 | |
332 @table @code | |
333 @item sexp | |
334 The value may be any Lisp object that can be printed and read back. You | |
335 can use @code{sexp} as a fall-back for any option, if you don't want to | |
336 take the time to work out a more specific type to use. | |
337 | |
338 @item integer | |
339 The value must be an integer, and is represented textually | |
340 in the customization buffer. | |
341 | |
342 @item number | |
343 The value must be a number, and is represented textually in the | |
344 customization buffer. | |
345 | |
346 @item string | |
347 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
|
348 contents, with no delimiting @samp{"} characters and no quoting with |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
349 @samp{\}. |
21006 | 350 |
351 @item regexp | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
352 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
|
353 expression. |
21006 | 354 |
355 @item character | |
356 The value must be a character code. A character code is actually an | |
357 integer, but this type shows the value by inserting the character in the | |
358 buffer, rather than by showing the number. | |
359 | |
360 @item file | |
361 The value must be a file name, and you can do completion with | |
362 @kbd{M-@key{TAB}}. | |
363 | |
364 @item (file :must-match t) | |
365 The value must be a file name for an existing file, and you can do | |
366 completion with @kbd{M-@key{TAB}}. | |
367 | |
368 @item directory | |
369 The value must be a directory name, and you can do completion with | |
370 @kbd{M-@key{TAB}}. | |
371 | |
372 @item symbol | |
373 The value must be a symbol. It appears in the customization buffer as | |
374 the name of the symbol. | |
375 | |
376 @item function | |
377 The value must be either a lambda expression or a function name. When | |
378 it is a function name, you can do completion with @kbd{M-@key{TAB}}. | |
379 | |
380 @item variable | |
381 The value must be a variable name, and you can do completion with | |
382 @kbd{M-@key{TAB}}. | |
383 | |
384 @item boolean | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
385 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
|
386 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
|
387 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
|
388 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
|
389 meaning of the alternative. |
21006 | 390 @end table |
391 | |
392 @node Composite Types | |
393 @subsection Composite Types | |
394 | |
395 When none of the simple types is appropriate, you can use composite | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
396 types, which build new types from other types. Here are several ways of |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
397 doing that: |
21006 | 398 |
399 @table @code | |
400 @item (restricted-sexp :match-alternatives @var{criteria}) | |
401 The value may be any Lisp object that satisfies one of @var{criteria}. | |
402 @var{criteria} should be a list, and each elements should be | |
403 one of these possibilities: | |
404 | |
405 @itemize @bullet | |
406 @item | |
407 A predicate---that is, a function of one argument that returns non-@code{nil} | |
408 if the argument fits a certain type. This means that objects of that type | |
409 are acceptable. | |
410 | |
411 @item | |
412 A quoted constant---that is, @code{'@var{object}}. This means that | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
413 @var{object} itself is an acceptable value. |
21006 | 414 @end itemize |
415 | |
416 For example, | |
417 | |
418 @example | |
419 (restricted-sexp :match-alternatives (integerp 't 'nil)) | |
420 @end example | |
421 | |
422 @noindent | |
423 allows integers, @code{t} and @code{nil} as legitimate values. | |
424 | |
425 The customization buffer shows all legitimate values using their read | |
426 syntax, and the user edits them textually. | |
427 | |
428 @item (cons @var{car-type} @var{cdr-type}) | |
429 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and | |
430 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(const string | |
431 symbol)} is a customization type which matches values such as | |
432 @code{("foo" . foo)}. | |
433 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
434 In the customization buffer, the @sc{car} and the @sc{cdr} are |
21006 | 435 displayed and edited separately, each according to the type |
436 that you specify for it. | |
437 | |
438 @item (list @var{element-types}@dots{}) | |
439 The value must be a list with exactly as many elements as the | |
440 @var{element-types} you have specified; and each element must fit the | |
441 corresponding @var{element-type}. | |
442 | |
443 For example, @code{(list integer string function)} describes a list of | |
444 three elements; the first element must be an integer, the second a | |
445 string, and the third a function. | |
446 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
447 In the customization buffer, the each element is displayed and edited |
21006 | 448 separately, according to the type specified for it. |
449 | |
450 @item (vector @var{element-types}@dots{}) | |
451 Like @code{list} except that the value must be a vector instead of a | |
452 list. The elements work the same as in @code{list}. | |
453 | |
454 @item (choice @var{alternative-types}...) | |
455 The value must fit at least one of @var{alternative-types}. | |
456 For example, @code{(choice integer string)} allows either an | |
457 integer or a string. | |
458 | |
459 In the customization buffer, the user selects one of the alternatives | |
460 using a menu, and can then edit the value in the usual way for that | |
461 alternative. | |
462 | |
463 Normally the strings in this menu are determined automatically from the | |
464 choices; however, you can specify different strings for the menu by | |
465 including the @code{:tag} keyword in the alternatives. For example, if | |
466 an integer stands for a number of spaces, while a string is text to use | |
467 verbatim, you might write the customization type this way, | |
468 | |
469 @smallexample | |
470 (choice (integer :tag "Number of spaces") | |
471 (string :tag "Literal text")) | |
472 @end smallexample | |
473 | |
474 @noindent | |
475 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}. | |
476 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
477 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
|
478 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
|
479 using the @code{:value} keyword. @xref{Type Keywords}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
480 |
21006 | 481 @item (const @var{value}) |
482 The value must be @var{value}---nothing else is allowed. | |
483 | |
484 The main use of @code{const} is inside of @code{choice}. For example, | |
485 @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
|
486 @code{nil}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
487 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
488 @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
|
489 For example, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
490 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
491 @smallexample |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
492 (choice (const :tag "Yes" t) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
493 (const :tag "No" nil) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
494 (const :tag "Ask" foo)) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
495 @end smallexample |
21006 | 496 |
497 @item (function-item @var{function}) | |
498 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
|
499 displays the documentation string as well as the function name. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
500 The documentation string is either the one you specify with |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
501 @code{:doc}, or @var{function}'s own documentation string. |
21006 | 502 |
503 @item (variable-item @var{variable}) | |
504 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
|
505 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
|
506 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
|
507 @var{variable}'s own documentation string. |
21006 | 508 |
509 @item (set @var{elements}@dots{}) | |
510 The value must be a list and each element of the list must be one of the | |
511 @var{elements} specified. This appears in the customization buffer as a | |
512 checklist. | |
513 | |
514 @item (repeat @var{element-type}) | |
515 The value must be a list and each element of the list must fit the type | |
516 @var{element-type}. This appears in the customization buffer as a | |
517 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding | |
518 more elements or removing elements. | |
519 @end table | |
520 | |
521 @node Splicing into Lists | |
522 @subsection Splicing into Lists | |
523 | |
524 The @code{:inline} feature lets you splice a variable number of | |
525 elements into the middle of a list or vector. You use it in a | |
526 @code{set}, @code{choice} or @code{repeat} type which appears among the | |
527 element-types of a @code{list} or @code{vector}. | |
528 | |
529 Normally, each of the element-types in a @code{list} or @code{vector} | |
530 describes one and only one element of the list or vector. Thus, if an | |
531 element-type is a @code{repeat}, that specifies a list of unspecified | |
532 length which appears as one element. | |
533 | |
534 But when the element-type uses @code{:inline}, the value it matches is | |
535 merged directly into the containing sequence. For example, if it | |
536 matches a list with three elements, those become three elements of the | |
537 overall sequence. This is analogous to using @samp{,@@} in the backquote | |
538 construct. | |
539 | |
540 For example, to specify a list whose first element must be @code{t} | |
541 and whose remaining arguments should be zero or more of @code{foo} and | |
542 @code{bar}, use this customization type: | |
543 | |
544 @example | |
545 (list (const t) (set :inline t foo bar)) | |
546 @end example | |
547 | |
548 @noindent | |
549 This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)} | |
550 and @code{(t foo bar)}. | |
551 | |
552 When the element-type is a @code{choice}, you use @code{:inline} not | |
553 in the @code{choice} itself, but in (some of) the alternatives of the | |
554 @code{choice}. For example, to match a list which must start with a | |
555 file name, followed either by the symbol @code{t} or two strings, use | |
556 this customization type: | |
557 | |
558 @example | |
559 (list file | |
560 (choice (const t) | |
561 (list :inline t string string))) | |
562 @end example | |
563 | |
564 @noindent | |
565 If the user chooses the first alternative in the choice, then the | |
566 overall list has two elements and the second element is @code{t}. If | |
567 the user chooses the second alternative, then the overall list has three | |
568 elements and the second and third must be strings. | |
569 | |
570 @node Type Keywords | |
571 @subsection Type Keywords | |
572 | |
573 You can specify keyword-argument pairs in a customization type after the | |
574 type name symbol. Here are the keywords you can use, and their | |
575 meanings: | |
576 | |
577 @table @code | |
578 @item :value @var{default} | |
579 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
|
580 @code{choice}; it specifies the default value to use, at first, if and |
21006 | 581 when the user selects this alternative with the menu in the |
582 customization buffer. | |
583 | |
584 Of course, if the actual value of the option fits this alternative, it | |
585 will appear showing the actual value, not @var{default}. | |
586 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
587 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
|
588 essential to specify a valid default with @code{:value}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
589 |
21006 | 590 @item :format @var{format-string} |
591 This string will be inserted in the buffer to represent the value | |
592 corresponding to the type. The following @samp{%} escapes are available | |
593 for use in @var{format-string}: | |
594 | |
595 @table @samp | |
596 @item %[@var{button}%] | |
597 Display the text @var{button} marked as a button. The @code{:action} | |
598 attribute specifies what the button will do if the user invokes it; | |
599 its value is a function which takes two arguments---the widget which | |
600 the button appears in, and the event. | |
601 | |
602 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
|
603 actions. |
21006 | 604 |
605 @item %@{@var{sample}%@} | |
606 Show @var{sample} in a special face specified by @code{:sample-face}. | |
607 | |
608 @item %v | |
609 Substitute the item's value. How the value is represented depends on | |
610 the kind of item, and (for variables) on the customization type. | |
611 | |
612 @item %d | |
613 Substitute the item's documentation string. | |
614 | |
615 @item %h | |
616 Like @samp{%d}, but if the documentation string is more than one line, | |
617 add an active field to control whether to show all of it or just the | |
618 first line. | |
619 | |
620 @item %t | |
621 Substitute the tag here. You specify the tag with the @code{:tag} | |
622 keyword. | |
623 | |
624 @item %% | |
625 Display a literal @samp{%}. | |
626 @end table | |
627 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
628 @item :action @var{action} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
629 Perform @var{action} if the user clicks on a button. |
21006 | 630 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
631 @item :button-face @var{face} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
632 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
|
633 text displayed with @samp{%[@dots{}%]}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
634 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
635 @item :button-prefix @var{prefix} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
636 @itemx :button-suffix @var{suffix} |
21006 | 637 These specify the text to display before and after a button. |
638 Each can be: | |
639 | |
640 @table @asis | |
641 @item @code{nil} | |
642 No text is inserted. | |
643 | |
644 @item a string | |
645 The string is inserted literally. | |
646 | |
647 @item a symbol | |
648 The symbol's value is used. | |
649 @end table | |
650 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
651 @item :tag @var{tag} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
652 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
|
653 that corresponds to this type. |
21006 | 654 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
655 @item :doc @var{doc} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
656 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
|
657 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
|
658 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
|
659 in that value. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
660 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
661 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
|
662 provide more information about the meanings of alternatives inside a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
663 @code{:choice} type or the parts of some other composite type. |
21006 | 664 |
665 @item :help-echo @var{motion-doc} | |
666 When you move to this item with @code{widget-forward} or | |
667 @code{widget-backward}, it will display the string @var{motion-doc} | |
668 in the echo area. | |
669 | |
670 @item :match @var{function} | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
671 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
|
672 corresponding value, @var{function}, should be a function that accepts |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
673 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
|
674 the value is acceptable. |
21006 | 675 |
676 @ignore | |
677 @item :indent @var{columns} | |
678 Indent this item by @var{columns} columns. The indentation is used for | |
679 @samp{%n}, and automatically for group names, for checklists and radio | |
680 buttons, and for editable lists. It affects the whole of the | |
681 item except for the first line. | |
682 | |
683 @item :offset @var{columns} | |
684 An integer indicating how many extra spaces to indent the subitems of | |
685 this item. By default, subitems are indented the same as their parent. | |
686 | |
687 @item :extra-offset | |
688 An integer indicating how many extra spaces to add to this item's | |
689 indentation, compared to its parent. | |
690 | |
691 @item :notify | |
692 A function called each time the item or a subitem is changed. The | |
693 function is called with two or three arguments. The first argument is | |
694 the item itself, the second argument is the item that was changed, and | |
695 the third argument is the event leading to the change, if any. | |
696 | |
697 @item :menu-tag | |
698 Tag used in the menu when the widget is used as an option in a | |
699 @code{menu-choice} widget. | |
700 | |
701 @item :menu-tag-get | |
702 Function used for finding the tag when the widget is used as an option | |
703 in a @code{menu-choice} widget. By default, the tag used will be either the | |
704 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ} | |
705 representation of the @code{:value} property if not. | |
706 | |
707 @item :validate | |
708 A function which takes a widget as an argument, and return nil if the | |
709 widgets current value is valid for the widget. Otherwise, it should | |
710 return the widget containing the invalid data, and set that widgets | |
711 @code{:error} property to a string explaining the error. | |
712 | |
713 You can use the function @code{widget-children-validate} for this job; | |
714 it tests that all children of @var{widget} are valid. | |
715 | |
716 @item :tab-order | |
717 Specify the order in which widgets are traversed with | |
718 @code{widget-forward} or @code{widget-backward}. This is only partially | |
719 implemented. | |
720 | |
721 @enumerate a | |
722 @item | |
723 Widgets with tabbing order @code{-1} are ignored. | |
724 | |
725 @item | |
726 (Unimplemented) When on a widget with tabbing order @var{n}, go to the | |
727 next widget in the buffer with tabbing order @var{n+1} or @code{nil}, | |
728 whichever comes first. | |
729 | |
730 @item | |
731 When on a widget with no tabbing order specified, go to the next widget | |
732 in the buffer with a positive tabbing order, or @code{nil} | |
733 @end enumerate | |
734 | |
735 @item :parent | |
736 The parent of a nested widget (e.g. a @code{menu-choice} item or an | |
737 element of a @code{editable-list} widget). | |
738 | |
739 @item :sibling-args | |
740 This keyword is only used for members of a @code{radio-button-choice} or | |
741 @code{checklist}. The value should be a list of extra keyword | |
742 arguments, which will be used when creating the @code{radio-button} or | |
743 @code{checkbox} associated with this item. | |
744 @end ignore | |
745 @end table |