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