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