Mercurial > emacs
annotate lispref/customize.texi @ 22363:d00f146c3e9d
#include sys/file.h
(sys_access): Provide our own implementation which recognizes D_OK.
(is_exec): New function.
(stat): Use it.
(init_environment): Set TMPDIR to an existing directory.
Abort if none of the usual places is available.
(sys_rename): On Windows 95, choose a temp name that
includes the original file's base name and use an explicit loop
rather than calling mktemp. Only attempt to unlink the newname if
the rename fails, rather than second-guessing whether the old and
new names refer to the same file.
author | Karl Heuer <kwzh@gnu.org> |
---|---|
date | Fri, 05 Jun 1998 16:08:32 +0000 |
parents | f0cd03a7dac9 |
children | a9820c4e8c9e |
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 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
34 @item :tag @var{name} |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
35 Use @var{name}, a string, instead of the item's name, to label the item |
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 | |
45 item. Be careful not to overdo this! | |
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 | |
52 There are three alternatives you can use for @var{link-data}: | |
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}. |
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 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
112 @defmac defgroup group members doc [keyword value]... |
21006 | 113 @tindex defgroup |
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 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
118 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
|
119 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
|
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 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
123 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
|
124 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
|
125 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
|
126 Useful widgets are @code{custom-variable} for a variable, |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
127 @code{custom-face} for a face, and @code{custom-group} for a group. |
21006 | 128 |
129 In addition to the common keywords (@pxref{Common Keywords}), you can | |
130 use this keyword in @code{defgroup}: | |
131 | |
132 @table @code | |
133 @item :prefix @var{prefix} | |
134 If the name of an item in the group starts with @var{prefix}, then the | |
135 tag for that item is constructed (by default) by omitting @var{prefix}. | |
136 | |
137 One group can have any number of prefixes. | |
138 @end table | |
139 @end defmac | |
140 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
141 The prefix-discarding feature is currently turned off, which means |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
142 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
|
143 found that discarding the specified prefixes often led to confusing |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
144 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
|
145 @code{defgroup} definitions for various groups added @code{:prefix} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
146 keywords whenever they make logical sense---that is, whenever the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
147 variables in the library have a common prefix. |
21006 | 148 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
149 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
|
150 necessary to check the specific effects of discarding a particular |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
151 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
|
152 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
|
153 should not be used in that case. |
21006 | 154 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
155 It should be possible to recheck all the customization groups, delete |
21006 | 156 the @code{:prefix} specifications which give unclear results, and then |
157 turn this feature back on, if someone would like to do the work. | |
158 | |
159 @node Variable Definitions | |
160 @section Defining Customization Variables | |
161 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
162 Use @code{defcustom} to declare user-editable variables. |
21006 | 163 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
164 @defmac defcustom option default doc [keyword value]... |
21006 | 165 @tindex defcustom |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
166 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
|
167 quote @var{option}. The argument @var{doc} specifies the documentation |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
168 string for the variable. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
169 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
170 If @var{option} is void, @code{defcustom} initializes it to |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
171 @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
|
172 value; be careful in writing it, because it can be evaluated on more |
21006 | 173 than one occasion. |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
174 @end defmac |
21006 | 175 |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
176 @code{defcustom} accepts the following additional keywords: |
21006 | 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} | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
194 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
|
195 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
|
196 @var{version} must be a string. For example, |
21006 | 197 |
198 @example | |
199 (defcustom foo-max 34 | |
200 "*Maximum number of foo's allowed." | |
201 :type 'integer | |
202 :group 'foo | |
203 :version "20.3") | |
204 @end example | |
205 | |
206 @item :set @var{setfunction} | |
207 Specify @var{setfunction} as the way to change the value of this option. | |
208 The function @var{setfunction} should take two arguments, a symbol and | |
209 the new value, and should do whatever is necessary to update the value | |
210 properly for this option (which may not mean simply setting the option | |
211 as a Lisp variable). The default for @var{setfunction} is | |
212 @code{set-default}. | |
213 | |
214 @item :get @var{getfunction} | |
215 Specify @var{getfunction} as the way to extract the value of this | |
216 option. The function @var{getfunction} should take one argument, a | |
217 symbol, and should return the ``current value'' for that symbol (which | |
218 need not be the symbol's Lisp value). The default is | |
219 @code{default-value}. | |
220 | |
221 @item :initialize @var{function} | |
222 @var{function} should be a function used to initialize the variable when | |
223 the @code{defcustom} is evaluated. It should take two arguments, the | |
224 symbol and value. Here are some predefined functions meant for use in | |
225 this way: | |
226 | |
227 @table @code | |
228 @item custom-initialize-set | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
229 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
|
230 do not reinitialize it if it is already non-void. This is the default |
21006 | 231 @code{:initialize} function. |
232 | |
233 @item custom-initialize-default | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
234 Like @code{custom-initialize-set}, but use the function |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
235 @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
|
236 @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
|
237 @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
|
238 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
|
239 customizing the variable will do so. |
21006 | 240 |
241 @item custom-initialize-reset | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
242 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
|
243 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
|
244 function using the current value (returned by the @code{:get} method). |
21006 | 245 |
246 @item custom-initialize-changed | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
247 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
|
248 already set or has been customized; otherwise, just use |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
249 @code{set-default}. |
21006 | 250 @end table |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
251 @end table |
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) |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
263 (show-paren-mode (or value 0))) |
21682
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 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
372 @item hook |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
373 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
|
374 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
|
375 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
|
376 @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
|
377 the hook; see @ref{Variable Definitions}. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
378 |
21006 | 379 @item symbol |
380 The value must be a symbol. It appears in the customization buffer as | |
381 the name of the symbol. | |
382 | |
383 @item function | |
384 The value must be either a lambda expression or a function name. When | |
385 it is a function name, you can do completion with @kbd{M-@key{TAB}}. | |
386 | |
387 @item variable | |
388 The value must be a variable name, and you can do completion with | |
389 @kbd{M-@key{TAB}}. | |
390 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
391 @item face |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
392 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
|
393 completion with @kbd{M-@key{TAB}}. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
394 |
21006 | 395 @item boolean |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
396 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
|
397 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
|
398 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
|
399 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
|
400 meaning of the alternative. |
21006 | 401 @end table |
402 | |
403 @node Composite Types | |
404 @subsection Composite Types | |
405 | |
406 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
|
407 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
|
408 doing that: |
21006 | 409 |
410 @table @code | |
411 @item (restricted-sexp :match-alternatives @var{criteria}) | |
412 The value may be any Lisp object that satisfies one of @var{criteria}. | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
413 @var{criteria} should be a list, and each element should be |
21006 | 414 one of these possibilities: |
415 | |
416 @itemize @bullet | |
417 @item | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
418 A predicate---that is, a function of one argument that has no side |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
419 effects, and returns either @code{nil} or non-@code{nil} according to |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
420 the argument. Using a predicate in the list says that objects for which |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
421 the predicate returns non-@code{nil} are acceptable. |
21006 | 422 |
423 @item | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
424 A quoted constant---that is, @code{'@var{object}}. This sort of element |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
425 in the list says that @var{object} itself is an acceptable value. |
21006 | 426 @end itemize |
427 | |
428 For example, | |
429 | |
430 @example | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
431 (restricted-sexp :match-alternatives |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
432 (integerp 't 'nil)) |
21006 | 433 @end example |
434 | |
435 @noindent | |
436 allows integers, @code{t} and @code{nil} as legitimate values. | |
437 | |
438 The customization buffer shows all legitimate values using their read | |
439 syntax, and the user edits them textually. | |
440 | |
441 @item (cons @var{car-type} @var{cdr-type}) | |
442 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
|
443 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string |
21006 | 444 symbol)} is a customization type which matches values such as |
445 @code{("foo" . foo)}. | |
446 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
447 In the customization buffer, the @sc{car} and the @sc{cdr} are |
21006 | 448 displayed and edited separately, each according to the type |
449 that you specify for it. | |
450 | |
451 @item (list @var{element-types}@dots{}) | |
452 The value must be a list with exactly as many elements as the | |
453 @var{element-types} you have specified; and each element must fit the | |
454 corresponding @var{element-type}. | |
455 | |
456 For example, @code{(list integer string function)} describes a list of | |
457 three elements; the first element must be an integer, the second a | |
458 string, and the third a function. | |
459 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
460 In the customization buffer, each element is displayed and edited |
21006 | 461 separately, according to the type specified for it. |
462 | |
463 @item (vector @var{element-types}@dots{}) | |
464 Like @code{list} except that the value must be a vector instead of a | |
465 list. The elements work the same as in @code{list}. | |
466 | |
467 @item (choice @var{alternative-types}...) | |
468 The value must fit at least one of @var{alternative-types}. | |
469 For example, @code{(choice integer string)} allows either an | |
470 integer or a string. | |
471 | |
472 In the customization buffer, the user selects one of the alternatives | |
473 using a menu, and can then edit the value in the usual way for that | |
474 alternative. | |
475 | |
476 Normally the strings in this menu are determined automatically from the | |
477 choices; however, you can specify different strings for the menu by | |
478 including the @code{:tag} keyword in the alternatives. For example, if | |
479 an integer stands for a number of spaces, while a string is text to use | |
480 verbatim, you might write the customization type this way, | |
481 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
482 @example |
21006 | 483 (choice (integer :tag "Number of spaces") |
484 (string :tag "Literal text")) | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
485 @end example |
21006 | 486 |
487 @noindent | |
488 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}. | |
489 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
490 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
|
491 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
|
492 using the @code{:value} keyword. @xref{Type Keywords}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
493 |
21006 | 494 @item (const @var{value}) |
495 The value must be @var{value}---nothing else is allowed. | |
496 | |
497 The main use of @code{const} is inside of @code{choice}. For example, | |
498 @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
|
499 @code{nil}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
500 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
501 @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
|
502 For example, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
503 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
504 @example |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
505 (choice (const :tag "Yes" t) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
506 (const :tag "No" nil) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
507 (const :tag "Ask" foo)) |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
508 @end example |
21006 | 509 |
510 @item (function-item @var{function}) | |
511 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
|
512 displays the documentation string as well as the function name. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
513 The documentation string is either the one you specify with |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
514 @code{:doc}, or @var{function}'s own documentation string. |
21006 | 515 |
516 @item (variable-item @var{variable}) | |
517 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
|
518 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
|
519 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
|
520 @var{variable}'s own documentation string. |
21006 | 521 |
522 @item (set @var{elements}@dots{}) | |
523 The value must be a list and each element of the list must be one of the | |
524 @var{elements} specified. This appears in the customization buffer as a | |
525 checklist. | |
526 | |
527 @item (repeat @var{element-type}) | |
528 The value must be a list and each element of the list must fit the type | |
529 @var{element-type}. This appears in the customization buffer as a | |
530 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding | |
531 more elements or removing elements. | |
532 @end table | |
533 | |
534 @node Splicing into Lists | |
535 @subsection Splicing into Lists | |
536 | |
537 The @code{:inline} feature lets you splice a variable number of | |
538 elements into the middle of a list or vector. You use it in a | |
539 @code{set}, @code{choice} or @code{repeat} type which appears among the | |
540 element-types of a @code{list} or @code{vector}. | |
541 | |
542 Normally, each of the element-types in a @code{list} or @code{vector} | |
543 describes one and only one element of the list or vector. Thus, if an | |
544 element-type is a @code{repeat}, that specifies a list of unspecified | |
545 length which appears as one element. | |
546 | |
547 But when the element-type uses @code{:inline}, the value it matches is | |
548 merged directly into the containing sequence. For example, if it | |
549 matches a list with three elements, those become three elements of the | |
550 overall sequence. This is analogous to using @samp{,@@} in the backquote | |
551 construct. | |
552 | |
553 For example, to specify a list whose first element must be @code{t} | |
554 and whose remaining arguments should be zero or more of @code{foo} and | |
555 @code{bar}, use this customization type: | |
556 | |
557 @example | |
558 (list (const t) (set :inline t foo bar)) | |
559 @end example | |
560 | |
561 @noindent | |
562 This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)} | |
563 and @code{(t foo bar)}. | |
564 | |
565 When the element-type is a @code{choice}, you use @code{:inline} not | |
566 in the @code{choice} itself, but in (some of) the alternatives of the | |
567 @code{choice}. For example, to match a list which must start with a | |
568 file name, followed either by the symbol @code{t} or two strings, use | |
569 this customization type: | |
570 | |
571 @example | |
572 (list file | |
573 (choice (const t) | |
574 (list :inline t string string))) | |
575 @end example | |
576 | |
577 @noindent | |
578 If the user chooses the first alternative in the choice, then the | |
579 overall list has two elements and the second element is @code{t}. If | |
580 the user chooses the second alternative, then the overall list has three | |
581 elements and the second and third must be strings. | |
582 | |
583 @node Type Keywords | |
584 @subsection Type Keywords | |
585 | |
586 You can specify keyword-argument pairs in a customization type after the | |
587 type name symbol. Here are the keywords you can use, and their | |
588 meanings: | |
589 | |
590 @table @code | |
591 @item :value @var{default} | |
592 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
|
593 @code{choice}; it specifies the default value to use, at first, if and |
21006 | 594 when the user selects this alternative with the menu in the |
595 customization buffer. | |
596 | |
597 Of course, if the actual value of the option fits this alternative, it | |
598 will appear showing the actual value, not @var{default}. | |
599 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
600 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
|
601 essential to specify a valid default with @code{:value}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
602 |
21006 | 603 @item :format @var{format-string} |
604 This string will be inserted in the buffer to represent the value | |
605 corresponding to the type. The following @samp{%} escapes are available | |
606 for use in @var{format-string}: | |
607 | |
608 @table @samp | |
609 @item %[@var{button}%] | |
610 Display the text @var{button} marked as a button. The @code{:action} | |
611 attribute specifies what the button will do if the user invokes it; | |
612 its value is a function which takes two arguments---the widget which | |
613 the button appears in, and the event. | |
614 | |
615 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
|
616 actions. |
21006 | 617 |
618 @item %@{@var{sample}%@} | |
619 Show @var{sample} in a special face specified by @code{:sample-face}. | |
620 | |
621 @item %v | |
622 Substitute the item's value. How the value is represented depends on | |
623 the kind of item, and (for variables) on the customization type. | |
624 | |
625 @item %d | |
626 Substitute the item's documentation string. | |
627 | |
628 @item %h | |
629 Like @samp{%d}, but if the documentation string is more than one line, | |
630 add an active field to control whether to show all of it or just the | |
631 first line. | |
632 | |
633 @item %t | |
634 Substitute the tag here. You specify the tag with the @code{:tag} | |
635 keyword. | |
636 | |
637 @item %% | |
638 Display a literal @samp{%}. | |
639 @end table | |
640 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
641 @item :action @var{action} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
642 Perform @var{action} if the user clicks on a button. |
21006 | 643 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
644 @item :button-face @var{face} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
645 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
|
646 text displayed with @samp{%[@dots{}%]}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
647 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
648 @item :button-prefix @var{prefix} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
649 @itemx :button-suffix @var{suffix} |
21006 | 650 These specify the text to display before and after a button. |
651 Each can be: | |
652 | |
653 @table @asis | |
654 @item @code{nil} | |
655 No text is inserted. | |
656 | |
657 @item a string | |
658 The string is inserted literally. | |
659 | |
660 @item a symbol | |
661 The symbol's value is used. | |
662 @end table | |
663 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
664 @item :tag @var{tag} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
665 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
|
666 that corresponds to this type. |
21006 | 667 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
668 @item :doc @var{doc} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
669 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
|
670 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
|
671 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
|
672 in that value. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
673 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
674 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
|
675 provide more information about the meanings of alternatives inside a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
676 @code{:choice} type or the parts of some other composite type. |
21006 | 677 |
678 @item :help-echo @var{motion-doc} | |
679 When you move to this item with @code{widget-forward} or | |
680 @code{widget-backward}, it will display the string @var{motion-doc} | |
681 in the echo area. | |
682 | |
683 @item :match @var{function} | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
684 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
|
685 corresponding value, @var{function}, should be a function that accepts |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21006
diff
changeset
|
686 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
|
687 the value is acceptable. |
21006 | 688 |
689 @ignore | |
690 @item :indent @var{columns} | |
691 Indent this item by @var{columns} columns. The indentation is used for | |
692 @samp{%n}, and automatically for group names, for checklists and radio | |
693 buttons, and for editable lists. It affects the whole of the | |
694 item except for the first line. | |
695 | |
696 @item :offset @var{columns} | |
697 An integer indicating how many extra spaces to indent the subitems of | |
698 this item. By default, subitems are indented the same as their parent. | |
699 | |
700 @item :extra-offset | |
701 An integer indicating how many extra spaces to add to this item's | |
702 indentation, compared to its parent. | |
703 | |
704 @item :notify | |
705 A function called each time the item or a subitem is changed. The | |
706 function is called with two or three arguments. The first argument is | |
707 the item itself, the second argument is the item that was changed, and | |
708 the third argument is the event leading to the change, if any. | |
709 | |
710 @item :menu-tag | |
711 Tag used in the menu when the widget is used as an option in a | |
712 @code{menu-choice} widget. | |
713 | |
714 @item :menu-tag-get | |
715 Function used for finding the tag when the widget is used as an option | |
716 in a @code{menu-choice} widget. By default, the tag used will be either the | |
717 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ} | |
718 representation of the @code{:value} property if not. | |
719 | |
720 @item :validate | |
721 A function which takes a widget as an argument, and return nil if the | |
722 widgets current value is valid for the widget. Otherwise, it should | |
723 return the widget containing the invalid data, and set that widgets | |
724 @code{:error} property to a string explaining the error. | |
725 | |
726 You can use the function @code{widget-children-validate} for this job; | |
727 it tests that all children of @var{widget} are valid. | |
728 | |
729 @item :tab-order | |
730 Specify the order in which widgets are traversed with | |
731 @code{widget-forward} or @code{widget-backward}. This is only partially | |
732 implemented. | |
733 | |
734 @enumerate a | |
735 @item | |
736 Widgets with tabbing order @code{-1} are ignored. | |
737 | |
738 @item | |
739 (Unimplemented) When on a widget with tabbing order @var{n}, go to the | |
740 next widget in the buffer with tabbing order @var{n+1} or @code{nil}, | |
741 whichever comes first. | |
742 | |
743 @item | |
744 When on a widget with no tabbing order specified, go to the next widget | |
745 in the buffer with a positive tabbing order, or @code{nil} | |
746 @end enumerate | |
747 | |
748 @item :parent | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
749 The parent of a nested widget (e.g., a @code{menu-choice} item or an |
21006 | 750 element of a @code{editable-list} widget). |
751 | |
752 @item :sibling-args | |
753 This keyword is only used for members of a @code{radio-button-choice} or | |
754 @code{checklist}. The value should be a list of extra keyword | |
755 arguments, which will be used when creating the @code{radio-button} or | |
756 @code{checkbox} associated with this item. | |
757 @end ignore | |
758 @end table |