Mercurial > hg > xemacs-beta
annotate man/lispref/customize.texi @ 5378:4f0a1f4cc111
Improve support for min-colors req in `defface'.
lisp/faces.el (face-spec-set-match-display):
Protect against `display-color-cells' returning nil.
Delete unreferenced let-binding of `min-colors'.
man/lispref/customize.texi (Face Definitions): New node.
(Customization): Add entry to menu.
(Variable Definitions): Add cross-ref for `defface'.
(Customization Types): Fixup Previous link.
man/lispref/faces.texi (Faces):
Clarify that built-in properties of faces are computed at runtime.
| author | Stephen J. Turnbull <stephen@xemacs.org> |
|---|---|
| date | Sat, 19 Mar 2011 22:13:14 +0900 |
| parents | eed841acc858 |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 318 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1997, 1998 Free Software Foundation, Inc. |
| 318 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../info/customize | |
| 6 @node Customization, , , Top | |
| 7 @chapter Writing Customization Definitions | |
| 8 | |
| 9 This chapter describes how to declare user options for customization, | |
| 10 and also customization groups for classifying them. We use the term | |
| 11 @dfn{customization item} to include both kinds of customization | |
| 12 definitions---as well as face definitions. | |
| 13 | |
| 14 @menu | |
| 15 * Common Keywords:: | |
| 444 | 16 * Group Definitions:: |
| 17 * Variable Definitions:: | |
|
5378
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
18 * Face Definitions:: |
| 318 | 19 * Customization Types:: |
| 775 | 20 * Enabling Behavior:: |
| 318 | 21 @end menu |
| 22 | |
| 23 @node Common Keywords | |
| 24 @section Common Keywords for All Kinds of Items | |
| 25 | |
| 26 All kinds of customization declarations (for variables and groups, and | |
| 27 for faces) accept keyword arguments for specifying various information. | |
| 28 This section describes some keywords that apply to all kinds. | |
| 29 | |
| 30 All of these keywords, except @code{:tag}, can be used more than once | |
| 31 in a given item. Each use of the keyword has an independent effect. | |
| 32 The keyword @code{:tag} is an exception because any given item can only | |
| 33 display one name. | |
| 34 | |
| 35 @table @code | |
| 36 @item :tag @var{name} | |
| 37 Use @var{name}, a string, instead of the item's name, to label the item | |
| 38 in customization menus and buffers. | |
| 39 | |
| 40 @item :group @var{group} | |
| 41 Put this customization item in group @var{group}. When you use | |
| 42 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of | |
| 43 @var{group}. | |
| 44 | |
| 45 If you use this keyword more than once, you can put a single item into | |
| 46 more than one group. Displaying any of those groups will show this | |
| 47 item. Be careful not to overdo this! | |
| 48 | |
| 49 @item :link @var{link-data} | |
| 50 Include an external link after the documentation string for this item. | |
| 51 This is a sentence containing an active field which references some | |
| 52 other documentation. | |
| 53 | |
| 54 There are three alternatives you can use for @var{link-data}: | |
| 55 | |
| 56 @table @code | |
| 57 @item (custom-manual @var{info-node}) | |
| 58 Link to an Info node; @var{info-node} is a string which specifies the | |
| 59 node name, as in @code{"(emacs)Top"}. The link appears as | |
| 60 @samp{[manual]} in the customization buffer. | |
| 61 | |
| 62 @item (info-link @var{info-node}) | |
| 63 Like @code{custom-manual} except that the link appears | |
| 64 in the customization buffer with the Info node name. | |
| 65 | |
| 66 @item (url-link @var{url}) | |
| 67 Link to a web page; @var{url} is a string which specifies the @sc{url}. | |
| 68 The link appears in the customization buffer as @var{url}. | |
| 69 @end table | |
| 70 | |
| 71 You can specify the text to use in the customization buffer by adding | |
| 72 @code{:tag @var{name}} after the first element of the @var{link-data}; | |
| 73 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to | |
| 74 the Emacs manual which appears in the buffer as @samp{foo}. | |
| 75 | |
| 76 An item can have more than one external link; however, most items have | |
| 77 none at all. | |
| 78 | |
| 79 @item :load @var{file} | |
| 80 Load file @var{file} (a string) before displaying this customization | |
| 81 item. Loading is done with @code{load-library}, and only if the file is | |
| 82 not already loaded. | |
| 83 | |
| 84 @item :require @var{feature} | |
| 85 Require feature @var{feature} (a symbol) when installing a value for | |
| 86 this item (an option or a face) that was saved using the customization | |
| 87 feature. This is done by calling @code{require}. | |
| 88 | |
| 89 The most common reason to use @code{:require} is when a variable enables | |
| 90 a feature such as a minor mode, and just setting the variable won't have | |
| 91 any effect unless the code which implements the mode is loaded. | |
| 92 @end table | |
| 93 | |
| 94 @node Group Definitions | |
| 95 @section Defining Custom Groups | |
| 96 | |
| 97 Each Emacs Lisp package should have one main customization group which | |
| 98 contains all the options, faces and other groups in the package. If the | |
| 99 package has a small number of options and faces, use just one group and | |
| 100 put everything in it. When there are more than twelve or so options and | |
| 101 faces, then you should structure them into subgroups, and put the | |
| 102 subgroups under the package's main customization group. It is OK to | |
| 103 put some of the options and faces in the package's main group alongside | |
| 104 the subgroups. | |
| 105 | |
| 106 The package's main or only group should be a member of one or more of | |
| 107 the standard customization groups. (To display the full list of them, | |
| 108 use @kbd{M-x customize}.) Choose one or more of them (but not too | |
| 109 many), and add your group to each of them using the @code{:group} | |
| 110 keyword. | |
| 111 | |
| 112 The way to declare new customization groups is with @code{defgroup}. | |
| 113 | |
| 114 @tindex defgroup | |
| 115 @defmac defgroup group members doc [keyword value]... | |
| 116 Declare @var{group} as a customization group containing @var{members}. | |
| 117 Do not quote the symbol @var{group}. The argument @var{doc} specifies | |
| 118 the documentation string for the group. | |
| 119 | |
| 120 The argument @var{members} is a list specifying an initial set of | |
| 121 customization items to be members of the group. However, most often | |
| 122 @var{members} is @code{nil}, and you specify the group's members by | |
| 123 using the @code{:group} keyword when defining those members. | |
| 124 | |
| 125 If you want to specify group members through @var{members}, each element | |
| 126 should have the form @code{(@var{name} @var{widget})}. Here @var{name} | |
| 127 is a symbol, and @var{widget} is a widget type for editing that symbol. | |
| 128 Useful widgets are @code{custom-variable} for a variable, | |
| 129 @code{custom-face} for a face, and @code{custom-group} for a group. | |
| 130 | |
| 131 In addition to the common keywords (@pxref{Common Keywords}), you can | |
| 132 use this keyword in @code{defgroup}: | |
| 133 | |
| 134 @table @code | |
| 135 @item :prefix @var{prefix} | |
| 136 If the name of an item in the group starts with @var{prefix}, then the | |
| 137 tag for that item is constructed (by default) by omitting @var{prefix}. | |
| 138 | |
| 139 One group can have any number of prefixes. | |
| 140 @end table | |
| 141 @end defmac | |
| 142 | |
| 143 @c Doesn't apply to XEmacs | |
| 144 @c | |
| 145 @c The prefix-discarding feature is currently turned off, which means | |
| 146 @c that @code{:prefix} currently has no effect. We did this because we | |
| 147 @c found that discarding the specified prefixes often led to confusing | |
| 148 @c names for options. This happened because the people who wrote the | |
| 149 @c @code{defgroup} definitions for various groups added @code{:prefix} | |
| 150 @c keywords whenever they make logical sense---that is, whenever the | |
| 151 @c variables in the library have a common prefix. | |
| 152 | |
| 153 @c In order to obtain good results with @code{:prefix}, it would be | |
| 154 @c necessary to check the specific effects of discarding a particular | |
| 155 @c prefix, given the specific items in a group and their names and | |
| 156 @c documentation. If the resulting text is not clear, then @code{:prefix} | |
| 157 @c should not be used in that case. | |
| 158 | |
| 159 @c It should be possible to recheck all the customization groups, delete | |
| 160 @c the @code{:prefix} specifications which give unclear results, and then | |
| 161 @c turn this feature back on, if someone would like to do the work. | |
| 162 | |
| 163 @node Variable Definitions | |
| 164 @section Defining Customization Variables | |
| 165 | |
| 166 Use @code{defcustom} to declare user-editable variables. | |
|
5378
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
167 For face declarations, use @code{defface} instead. @xref{Face Definitions}. |
| 318 | 168 |
| 169 @tindex defcustom | |
| 170 @defmac defcustom option default doc [keyword value]... | |
| 171 Declare @var{option} as a customizable user option variable. Do not | |
| 172 quote @var{option}. The argument @var{doc} specifies the documentation | |
| 173 string for the variable. | |
| 174 | |
| 175 If @var{option} is void, @code{defcustom} initializes it to | |
| 176 @var{default}. @var{default} should be an expression to compute the | |
| 177 value; be careful in writing it, because it can be evaluated on more | |
| 178 than one occasion. | |
| 179 | |
| 180 The following additional keywords are defined: | |
| 181 | |
| 182 @table @code | |
| 183 @item :type @var{type} | |
| 184 Use @var{type} as the data type for this option. It specifies which | |
| 185 values are legitimate, and how to display the value. | |
| 186 @xref{Customization Types}, for more information. | |
| 187 | |
| 188 @item :options @var{list} | |
| 189 Specify @var{list} as the list of reasonable values for use in this | |
| 190 option. | |
| 191 | |
| 192 Currently this is meaningful only when the type is @code{hook}. In that | |
| 193 case, the elements of @var{list} should be functions that are useful as | |
| 194 elements of the hook value. The user is not restricted to using only | |
| 195 these functions, but they are offered as convenient alternatives. | |
| 196 | |
| 197 @item :version @var{version} | |
| 198 This option specifies that the variable was first introduced, or its | |
| 199 default value was changed, in Emacs version @var{version}. The value | |
| 200 @var{version} must be a string. For example, | |
| 201 | |
| 202 @example | |
| 203 (defcustom foo-max 34 | |
| 204 "*Maximum number of foo's allowed." | |
| 205 :type 'integer | |
| 206 :group 'foo | |
| 207 :version "20.3") | |
| 208 @end example | |
| 209 | |
| 210 @item :set @var{setfunction} | |
| 211 Specify @var{setfunction} as the way to change the value of this option. | |
| 212 The function @var{setfunction} should take two arguments, a symbol and | |
| 213 the new value, and should do whatever is necessary to update the value | |
| 214 properly for this option (which may not mean simply setting the option | |
| 215 as a Lisp variable). The default for @var{setfunction} is | |
| 216 @code{set-default}. | |
| 217 | |
| 218 @item :get @var{getfunction} | |
| 219 Specify @var{getfunction} as the way to extract the value of this | |
| 220 option. The function @var{getfunction} should take one argument, a | |
| 221 symbol, and should return the ``current value'' for that symbol (which | |
| 222 need not be the symbol's Lisp value). The default is | |
| 223 @code{default-value}. | |
| 224 | |
| 225 @item :initialize @var{function} | |
| 226 @var{function} should be a function used to initialize the variable when | |
| 227 the @code{defcustom} is evaluated. It should take two arguments, the | |
| 228 symbol and value. Here are some predefined functions meant for use in | |
| 229 this way: | |
| 230 | |
| 231 @table @code | |
| 232 @item custom-initialize-set | |
| 233 Use the variable's @code{:set} function to initialize the variable, but | |
| 234 do not reinitialize it if it is already non-void. This is the default | |
| 235 @code{:initialize} function. | |
| 236 | |
| 237 @item custom-initialize-default | |
| 238 Like @code{custom-initialize-set}, but use the function | |
| 239 @code{set-default} to set the variable, instead of the variable's | |
| 240 @code{:set} function. This is the usual choice for a variable whose | |
| 241 @code{:set} function enables or disables a minor mode; with this choice, | |
| 242 defining the variable will not call the minor mode function, but | |
| 243 customizing the variable will do so. | |
| 244 | |
| 245 @item custom-initialize-reset | |
| 246 Always use the @code{:set} function to initialize the variable. If the | |
| 247 variable is already non-void, reset it by calling the @code{:set} | |
| 248 function using the current value (returned by the @code{:get} method). | |
| 249 | |
| 250 @item custom-initialize-changed | |
| 251 Use the @code{:set} function to initialize the variable, if it is | |
| 252 already set or has been customized; otherwise, just use | |
| 253 @code{set-default}. | |
| 254 @end table | |
| 255 @end table | |
| 256 @end defmac | |
| 257 | |
| 258 The @code{:require} option is useful for an option that turns on the | |
| 259 operation of a certain feature. Assuming that the package is coded to | |
| 260 check the value of the option, you still need to arrange for the package | |
| 261 to be loaded. You can do that with @code{:require}. @xref{Common | |
| 262 Keywords}. Here is an example, from the library @file{paren.el}: | |
| 263 | |
| 264 @example | |
| 265 (defcustom show-paren-mode nil | |
| 266 "Toggle Show Paren mode@enddots{}" | |
| 267 :set (lambda (symbol value) | |
| 398 | 268 (show-paren-mode (or value 0))) |
| 318 | 269 :initialize 'custom-initialize-default |
| 270 :type 'boolean | |
| 271 :group 'paren-showing | |
| 272 :require 'paren) | |
| 273 @end example | |
| 274 | |
| 275 @ignore | |
| 276 Use @code{custom-add-option} to specify that a specific function is | |
| 277 useful as an member of a hook. | |
| 278 | |
| 279 @defun custom-add-option symbol option | |
| 280 To the variable @var{symbol} add @var{option}. | |
| 281 | |
| 282 If @var{symbol} is a hook variable, @var{option} should be a hook | |
| 283 member. For other types variables, the effect is undefined." | |
| 284 @end defun | |
| 285 @end ignore | |
| 286 | |
| 287 Internally, @code{defcustom} uses the symbol property | |
| 288 @code{standard-value} to record the expression for the default value, | |
| 289 and @code{saved-value} to record the value saved by the user with the | |
| 290 customization buffer. The @code{saved-value} property is actually a | |
| 291 list whose car is an expression which evaluates to the value. | |
| 292 | |
|
5378
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
293 @node Face Definitions, Customization Types, Variable Definitions, Customization |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
294 @section Face Definitions |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
295 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
296 Use @code{defface} to declare a new face. Conventions used in |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
297 specifying properties are similar to those for general customizable |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
298 variables. @xref{Variable Definitions}. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
299 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
300 @defun defface face spec doc &rest args |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
301 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
302 Declare @var{face} as a customizable face that defaults to @var{spec}. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
303 @var{face} does not need to be quoted. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
304 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
305 Third argument @var{doc} is the face documentation. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
306 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
307 If @var{face} has been set with `custom-set-face', set the face attributes |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
308 as specified by that function, otherwise set the face attributes |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
309 according to @var{spec}. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
310 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
311 The remaining arguments @var{args} are a property list, which has the |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
312 form |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
313 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
314 @var{keyword} @var{value}... |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
315 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
316 The following @var{keyword}s are defined: |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
317 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
318 @table @code |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
319 @item :group |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
320 @var{value} is a customization group. Add @var{face} to that group. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
321 @end table |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
322 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
323 @var{spec} is an alist of the form ((@var{display} @var{atts})...). |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
324 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
325 @var{atts} is a list of face attributes and their values. The possible |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
326 attributes are defined in the variable `custom-face-attributes'. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
327 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
328 The @var{atts} of the first entry in @var{spec} where the |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
329 @var{display} matches the frame take effect in that frame. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
330 @var{display} can either be the symbol t, which will match all frames, |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
331 or an alist of the form \((@var{req} @var{item}...)...) |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
332 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
333 For @var{display} to match a frame, the @var{req} property of the |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
334 frame must match one of the @var{item}. The following @var{req} are |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
335 defined: |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
336 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
337 @table @code |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
338 @item @code{type} (the value of @code{window-system}) |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
339 Should be one of @code{x}, @code{mswindows}, or @code{tty}. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
340 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
341 @code{class} (the frame's color support) |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
342 Should be one of @code{color}, @code{grayscale}, or @code{mono}. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
343 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
344 @code{min-colors} (the minimum number of colors the frame supports) |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
345 Should be in integer which is compared to @code{display-color-cells} |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
346 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
347 @code{background} (what color is used for the background text) |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
348 Should be one of @code{light} or @code{dark}. |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
349 @end table |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
350 @end defun |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
351 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
352 |
|
4f0a1f4cc111
Improve support for min-colors req in `defface'.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
1833
diff
changeset
|
353 @node Customization Types, Enabling Behavior, Face Definitions, Customization |
| 318 | 354 @section Customization Types |
| 355 | |
| 356 When you define a user option with @code{defcustom}, you must specify | |
| 357 its @dfn{customization type}. That is a Lisp object which describes (1) | |
| 358 which values are legitimate and (2) how to display the value in the | |
| 359 customization buffer for editing. | |
| 360 | |
| 361 You specify the customization type in @code{defcustom} with the | |
| 362 @code{:type} keyword. The argument of @code{:type} is evaluated; since | |
| 363 types that vary at run time are rarely useful, normally you use a quoted | |
| 364 constant. For example: | |
| 365 | |
| 366 @example | |
| 367 (defcustom diff-command "diff" | |
| 368 "*The command to use to run diff." | |
| 369 :type '(string) | |
| 370 :group 'diff) | |
| 371 @end example | |
| 372 | |
| 373 In general, a customization type is a list whose first element is a | |
| 374 symbol, one of the customization type names defined in the following | |
| 375 sections. After this symbol come a number of arguments, depending on | |
| 376 the symbol. Between the type symbol and its arguments, you can | |
| 377 optionally write keyword-value pairs (@pxref{Type Keywords}). | |
| 378 | |
| 379 Some of the type symbols do not use any arguments; those are called | |
| 380 @dfn{simple types}. For a simple type, if you do not use any | |
| 381 keyword-value pairs, you can omit the parentheses around the type | |
| 382 symbol. For example just @code{string} as a customization type is | |
| 383 equivalent to @code{(string)}. | |
| 384 | |
| 385 @menu | |
| 386 * Simple Types:: | |
| 387 * Composite Types:: | |
| 388 * Splicing into Lists:: | |
| 389 * Type Keywords:: | |
| 1833 | 390 * Defining New Types:: |
| 318 | 391 @end menu |
| 392 | |
| 393 @node Simple Types | |
| 394 @subsection Simple Types | |
| 395 | |
| 396 This section describes all the simple customization types. | |
| 397 | |
| 398 @table @code | |
| 399 @item sexp | |
| 400 The value may be any Lisp object that can be printed and read back. You | |
| 401 can use @code{sexp} as a fall-back for any option, if you don't want to | |
| 402 take the time to work out a more specific type to use. | |
| 403 | |
| 404 @item integer | |
| 405 The value must be an integer, and is represented textually | |
| 406 in the customization buffer. | |
| 407 | |
| 408 @item number | |
| 409 The value must be a number, and is represented textually in the | |
| 410 customization buffer. | |
| 411 | |
| 412 @item string | |
| 413 The value must be a string, and the customization buffer shows just the | |
| 414 contents, with no delimiting @samp{"} characters and no quoting with | |
| 415 @samp{\}. | |
| 416 | |
| 417 @item regexp | |
| 418 Like @code{string} except that the string must be a valid regular | |
| 419 expression. | |
| 420 | |
| 421 @item character | |
| 422 The value must be a character code. A character code is actually an | |
| 423 integer, but this type shows the value by inserting the character in the | |
| 424 buffer, rather than by showing the number. | |
| 425 | |
| 426 @item file | |
| 427 The value must be a file name, and you can do completion with | |
| 428 @kbd{M-@key{TAB}}. | |
| 429 | |
| 430 @item (file :must-match t) | |
| 431 The value must be a file name for an existing file, and you can do | |
| 432 completion with @kbd{M-@key{TAB}}. | |
| 433 | |
| 434 @item directory | |
| 435 The value must be a directory name, and you can do completion with | |
| 436 @kbd{M-@key{TAB}}. | |
| 437 | |
| 438 @item symbol | |
| 439 The value must be a symbol. It appears in the customization buffer as | |
| 440 the name of the symbol. | |
| 441 | |
| 442 @item function | |
| 443 The value must be either a lambda expression or a function name. When | |
| 444 it is a function name, you can do completion with @kbd{M-@key{TAB}}. | |
| 445 | |
| 446 @item variable | |
| 447 The value must be a variable name, and you can do completion with | |
| 448 @kbd{M-@key{TAB}}. | |
| 449 | |
| 450 @item face | |
| 451 The value must be a symbol which is a face name. | |
| 452 | |
| 453 @item boolean | |
| 454 The value is boolean---either @code{nil} or @code{t}. Note that by | |
| 455 using @code{choice} and @code{const} together (see the next section), | |
| 456 you can specify that the value must be @code{nil} or @code{t}, but also | |
| 457 specify the text to describe each value in a way that fits the specific | |
| 458 meaning of the alternative. | |
| 459 @end table | |
| 460 | |
| 461 @node Composite Types | |
| 462 @subsection Composite Types | |
| 463 | |
| 464 When none of the simple types is appropriate, you can use composite | |
| 465 types, which build new types from other types. Here are several ways of | |
| 466 doing that: | |
| 467 | |
| 468 @table @code | |
| 469 @item (restricted-sexp :match-alternatives @var{criteria}) | |
| 470 The value may be any Lisp object that satisfies one of @var{criteria}. | |
| 471 @var{criteria} should be a list, and each elements should be | |
| 472 one of these possibilities: | |
| 473 | |
| 474 @itemize @bullet | |
| 475 @item | |
| 476 A predicate---that is, a function of one argument that returns non-@code{nil} | |
| 477 if the argument fits a certain type. This means that objects of that type | |
| 478 are acceptable. | |
| 479 | |
| 480 @item | |
| 481 A quoted constant---that is, @code{'@var{object}}. This means that | |
| 482 @var{object} itself is an acceptable value. | |
| 483 @end itemize | |
| 484 | |
| 485 For example, | |
| 486 | |
| 487 @example | |
| 488 (restricted-sexp :match-alternatives (integerp 't 'nil)) | |
| 489 @end example | |
| 490 | |
| 491 @noindent | |
| 492 allows integers, @code{t} and @code{nil} as legitimate values. | |
| 493 | |
| 494 The customization buffer shows all legitimate values using their read | |
| 495 syntax, and the user edits them textually. | |
| 496 | |
| 497 @item (cons @var{car-type} @var{cdr-type}) | |
| 498 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and | |
| 499 its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string | |
| 500 symbol)} is a customization type which matches values such as | |
| 501 @code{("foo" . foo)}. | |
| 502 | |
| 503 In the customization buffer, the @sc{car} and the @sc{cdr} are | |
| 504 displayed and edited separately, each according to the type | |
| 505 that you specify for it. | |
| 506 | |
| 507 @item (list @var{element-types}@dots{}) | |
| 508 The value must be a list with exactly as many elements as the | |
| 509 @var{element-types} you have specified; and each element must fit the | |
| 510 corresponding @var{element-type}. | |
| 511 | |
| 512 For example, @code{(list integer string function)} describes a list of | |
| 513 three elements; the first element must be an integer, the second a | |
| 514 string, and the third a function. | |
| 515 | |
| 516 In the customization buffer, the each element is displayed and edited | |
| 517 separately, according to the type specified for it. | |
| 518 | |
| 519 @item (vector @var{element-types}@dots{}) | |
| 520 Like @code{list} except that the value must be a vector instead of a | |
| 521 list. The elements work the same as in @code{list}. | |
| 522 | |
| 523 @item (choice @var{alternative-types}...) | |
| 524 The value must fit at least one of @var{alternative-types}. | |
| 525 For example, @code{(choice integer string)} allows either an | |
| 526 integer or a string. | |
| 527 | |
| 528 In the customization buffer, the user selects one of the alternatives | |
| 529 using a menu, and can then edit the value in the usual way for that | |
| 530 alternative. | |
| 531 | |
| 532 Normally the strings in this menu are determined automatically from the | |
| 533 choices; however, you can specify different strings for the menu by | |
| 534 including the @code{:tag} keyword in the alternatives. For example, if | |
| 535 an integer stands for a number of spaces, while a string is text to use | |
| 536 verbatim, you might write the customization type this way, | |
| 537 | |
| 538 @smallexample | |
| 539 (choice (integer :tag "Number of spaces") | |
| 540 (string :tag "Literal text")) | |
| 541 @end smallexample | |
| 542 | |
| 543 @noindent | |
| 544 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}. | |
| 545 | |
| 546 In any alternative for which @code{nil} is not a valid value, other than | |
| 547 a @code{const}, you should specify a valid default for that alternative | |
| 548 using the @code{:value} keyword. @xref{Type Keywords}. | |
| 549 | |
| 550 @item (const @var{value}) | |
| 551 The value must be @var{value}---nothing else is allowed. | |
| 552 | |
| 553 The main use of @code{const} is inside of @code{choice}. For example, | |
| 554 @code{(choice integer (const nil))} allows either an integer or | |
| 555 @code{nil}. | |
| 556 | |
| 557 @code{:tag} is often used with @code{const}, inside of @code{choice}. | |
| 558 For example, | |
| 559 | |
| 560 @smallexample | |
| 561 (choice (const :tag "Yes" t) | |
| 562 (const :tag "No" nil) | |
| 563 (const :tag "Ask" foo)) | |
| 564 @end smallexample | |
| 565 | |
| 566 @item (function-item @var{function}) | |
| 567 Like @code{const}, but used for values which are functions. This | |
| 568 displays the documentation string as well as the function name. | |
| 569 The documentation string is either the one you specify with | |
| 570 @code{:doc}, or @var{function}'s own documentation string. | |
| 571 | |
| 572 @item (variable-item @var{variable}) | |
| 573 Like @code{const}, but used for values which are variable names. This | |
| 574 displays the documentation string as well as the variable name. The | |
| 575 documentation string is either the one you specify with @code{:doc}, or | |
| 576 @var{variable}'s own documentation string. | |
| 577 | |
| 578 @item (set @var{elements}@dots{}) | |
| 579 The value must be a list and each element of the list must be one of the | |
| 580 @var{elements} specified. This appears in the customization buffer as a | |
| 581 checklist. | |
| 582 | |
| 583 @item (repeat @var{element-type}) | |
| 584 The value must be a list and each element of the list must fit the type | |
| 585 @var{element-type}. This appears in the customization buffer as a | |
| 586 list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding | |
| 587 more elements or removing elements. | |
| 588 @end table | |
| 589 | |
| 590 @node Splicing into Lists | |
| 591 @subsection Splicing into Lists | |
| 592 | |
| 593 The @code{:inline} feature lets you splice a variable number of | |
| 594 elements into the middle of a list or vector. You use it in a | |
| 595 @code{set}, @code{choice} or @code{repeat} type which appears among the | |
| 596 element-types of a @code{list} or @code{vector}. | |
| 597 | |
| 598 Normally, each of the element-types in a @code{list} or @code{vector} | |
| 599 describes one and only one element of the list or vector. Thus, if an | |
| 600 element-type is a @code{repeat}, that specifies a list of unspecified | |
| 601 length which appears as one element. | |
| 602 | |
| 603 But when the element-type uses @code{:inline}, the value it matches is | |
| 604 merged directly into the containing sequence. For example, if it | |
| 605 matches a list with three elements, those become three elements of the | |
| 606 overall sequence. This is analogous to using @samp{,@@} in the backquote | |
| 607 construct. | |
| 608 | |
| 609 For example, to specify a list whose first element must be @code{t} | |
| 610 and whose remaining arguments should be zero or more of @code{foo} and | |
| 611 @code{bar}, use this customization type: | |
| 612 | |
| 613 @example | |
| 614 (list (const t) (set :inline t foo bar)) | |
| 615 @end example | |
| 616 | |
| 617 @noindent | |
| 618 This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)} | |
| 619 and @code{(t foo bar)}. | |
| 620 | |
| 621 When the element-type is a @code{choice}, you use @code{:inline} not | |
| 622 in the @code{choice} itself, but in (some of) the alternatives of the | |
| 623 @code{choice}. For example, to match a list which must start with a | |
| 624 file name, followed either by the symbol @code{t} or two strings, use | |
| 625 this customization type: | |
| 626 | |
| 627 @example | |
| 628 (list file | |
| 629 (choice (const t) | |
| 630 (list :inline t string string))) | |
| 631 @end example | |
| 632 | |
| 633 @noindent | |
| 634 If the user chooses the first alternative in the choice, then the | |
| 635 overall list has two elements and the second element is @code{t}. If | |
| 636 the user chooses the second alternative, then the overall list has three | |
| 637 elements and the second and third must be strings. | |
| 638 | |
| 639 @node Type Keywords | |
| 640 @subsection Type Keywords | |
| 641 | |
| 642 You can specify keyword-argument pairs in a customization type after the | |
| 643 type name symbol. Here are the keywords you can use, and their | |
| 644 meanings: | |
| 645 | |
| 646 @table @code | |
| 647 @item :value @var{default} | |
| 648 This is used for a type that appears as an alternative inside of | |
| 649 @code{choice}; it specifies the default value to use, at first, if and | |
| 650 when the user selects this alternative with the menu in the | |
| 651 customization buffer. | |
| 652 | |
| 653 Of course, if the actual value of the option fits this alternative, it | |
| 654 will appear showing the actual value, not @var{default}. | |
| 655 | |
| 656 If @code{nil} is not a valid value for the alternative, then it is | |
| 657 essential to specify a valid default with @code{:value}. | |
| 658 | |
| 659 @item :format @var{format-string} | |
| 660 This string will be inserted in the buffer to represent the value | |
| 661 corresponding to the type. The following @samp{%} escapes are available | |
| 662 for use in @var{format-string}: | |
| 663 | |
| 664 @table @samp | |
| 665 @item %[@var{button}%] | |
| 666 Display the text @var{button} marked as a button. The @code{:action} | |
| 667 attribute specifies what the button will do if the user invokes it; | |
| 668 its value is a function which takes two arguments---the widget which | |
| 669 the button appears in, and the event. | |
| 670 | |
| 671 There is no way to specify two different buttons with different | |
| 672 actions. | |
| 673 | |
| 674 @item %@{@var{sample}%@} | |
| 675 Show @var{sample} in a special face specified by @code{:sample-face}. | |
| 676 | |
| 677 @item %v | |
| 678 Substitute the item's value. How the value is represented depends on | |
| 679 the kind of item, and (for variables) on the customization type. | |
| 680 | |
| 681 @item %d | |
| 682 Substitute the item's documentation string. | |
| 683 | |
| 684 @item %h | |
| 685 Like @samp{%d}, but if the documentation string is more than one line, | |
| 686 add an active field to control whether to show all of it or just the | |
| 687 first line. | |
| 688 | |
| 689 @item %t | |
| 690 Substitute the tag here. You specify the tag with the @code{:tag} | |
| 691 keyword. | |
| 692 | |
| 693 @item %% | |
| 444 | 694 Display a literal @samp{%}. |
| 318 | 695 @end table |
| 696 | |
| 697 @item :action @var{action} | |
| 698 Perform @var{action} if the user clicks on a button. | |
| 699 | |
| 700 @item :button-face @var{face} | |
| 701 Use the face @var{face} (a face name or a list of face names) for button | |
| 702 text displayed with @samp{%[@dots{}%]}. | |
| 703 | |
| 704 @item :button-prefix @var{prefix} | |
| 705 @itemx :button-suffix @var{suffix} | |
| 706 These specify the text to display before and after a button. | |
| 707 Each can be: | |
| 708 | |
| 709 @table @asis | |
| 710 @item @code{nil} | |
| 711 No text is inserted. | |
| 712 | |
| 713 @item a string | |
| 714 The string is inserted literally. | |
| 715 | |
| 716 @item a symbol | |
| 717 The symbol's value is used. | |
| 718 @end table | |
| 719 | |
| 720 @item :tag @var{tag} | |
| 721 Use @var{tag} (a string) as the tag for the value (or part of the value) | |
| 722 that corresponds to this type. | |
| 723 | |
| 724 @item :doc @var{doc} | |
| 725 Use @var{doc} as the documentation string for this value (or part of the | |
| 726 value) that corresponds to this type. In order for this to work, you | |
| 727 must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} | |
| 728 in that value. | |
| 729 | |
| 730 The usual reason to specify a documentation string for a type is to | |
| 731 provide more information about the meanings of alternatives inside a | |
| 732 @code{:choice} type or the parts of some other composite type. | |
| 733 | |
| 734 @item :help-echo @var{motion-doc} | |
| 735 When you move to this item with @code{widget-forward} or | |
| 736 @code{widget-backward}, it will display the string @var{motion-doc} | |
| 737 in the echo area. | |
| 738 | |
| 739 @item :match @var{function} | |
| 740 Specify how to decide whether a value matches the type. The | |
| 741 corresponding value, @var{function}, should be a function that accepts | |
| 742 two arguments, a widget and a value; it should return non-@code{nil} if | |
| 743 the value is acceptable. | |
| 744 | |
| 745 @ignore | |
| 746 @item :indent @var{columns} | |
| 747 Indent this item by @var{columns} columns. The indentation is used for | |
| 748 @samp{%n}, and automatically for group names, for checklists and radio | |
| 749 buttons, and for editable lists. It affects the whole of the | |
| 750 item except for the first line. | |
| 751 | |
| 752 @item :offset @var{columns} | |
| 753 An integer indicating how many extra spaces to indent the subitems of | |
| 754 this item. By default, subitems are indented the same as their parent. | |
| 755 | |
| 756 @item :extra-offset | |
| 757 An integer indicating how many extra spaces to add to this item's | |
| 758 indentation, compared to its parent. | |
| 759 | |
| 760 @item :notify | |
| 761 A function called each time the item or a subitem is changed. The | |
| 762 function is called with two or three arguments. The first argument is | |
| 763 the item itself, the second argument is the item that was changed, and | |
| 764 the third argument is the event leading to the change, if any. | |
| 765 | |
| 766 @item :menu-tag | |
| 767 Tag used in the menu when the widget is used as an option in a | |
| 768 @code{menu-choice} widget. | |
| 769 | |
| 770 @item :menu-tag-get | |
| 771 Function used for finding the tag when the widget is used as an option | |
| 772 in a @code{menu-choice} widget. By default, the tag used will be either the | |
| 773 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ} | |
| 774 representation of the @code{:value} property if not. | |
| 775 | |
| 776 @item :validate | |
| 444 | 777 A function which takes a widget as an argument, and returns @code{nil} if the |
| 318 | 778 widgets current value is valid for the widget. Otherwise, it should |
| 779 return the widget containing the invalid data, and set that widgets | |
| 780 @code{:error} property to a string explaining the error. | |
| 781 | |
| 782 You can use the function @code{widget-children-validate} for this job; | |
| 783 it tests that all children of @var{widget} are valid. | |
| 784 | |
| 785 @item :tab-order | |
| 786 Specify the order in which widgets are traversed with | |
| 787 @code{widget-forward} or @code{widget-backward}. This is only partially | |
| 788 implemented. | |
| 789 | |
| 790 @enumerate a | |
| 791 @item | |
| 792 Widgets with tabbing order @code{-1} are ignored. | |
| 793 | |
| 444 | 794 @item |
| 318 | 795 (Unimplemented) When on a widget with tabbing order @var{n}, go to the |
| 796 next widget in the buffer with tabbing order @var{n+1} or @code{nil}, | |
| 797 whichever comes first. | |
| 798 | |
| 799 @item | |
| 800 When on a widget with no tabbing order specified, go to the next widget | |
| 801 in the buffer with a positive tabbing order, or @code{nil} | |
| 802 @end enumerate | |
| 803 | |
| 804 @item :parent | |
| 805 The parent of a nested widget (e.g. a @code{menu-choice} item or an | |
| 904 | 806 element of an @code{editable-list} widget). |
| 318 | 807 |
| 808 @item :sibling-args | |
| 809 This keyword is only used for members of a @code{radio-button-choice} or | |
| 810 @code{checklist}. The value should be a list of extra keyword | |
| 811 arguments, which will be used when creating the @code{radio-button} or | |
| 812 @code{checkbox} associated with this item. | |
| 813 @end ignore | |
| 814 @end table | |
| 775 | 815 |
| 816 | |
| 817 @node Enabling Behavior, , Customization Types, Customization | |
| 818 @subsection Enabling Behavior | |
| 819 @cindex behavior | |
| 820 | |
| 821 @c #### Does this belong here? | |
| 822 | |
| 823 Some functionality requires a fair amount of effort to enable globally | |
| 824 in a session. For example, someone who discovers filladapt and really | |
| 825 likes it must toggle it separately in each buffer. On the other hand, | |
| 826 after trying it for a while she might like to disable it everywhere, | |
| 827 having decided it doesn't work very well for her. Such a functionality | |
| 828 is called a @dfn{behavior}. | |
| 829 | |
| 830 @code{define-behavior} allows the programmer to register functions to | |
| 831 enable or disable a package globally in a session. The user sees a | |
| 832 consistent interface through the @code{enable-behavior} and | |
| 833 @code{disable-behavior} functions. These functions were introduced in | |
| 834 XEmacs 21.5.6. | |
| 835 | |
| 836 @defvar behavior-hash-table | |
| 837 | |
| 838 Internal table of registered behaviors. | |
| 839 @end defvar | |
| 840 | |
| 841 @defvar behavior-history | |
| 842 | |
| 843 History of entered behaviors. | |
| 844 @end defvar | |
| 845 | |
| 846 @defun define-behavior name doc-string [cl-keys ...] | |
| 847 | |
| 848 Define a behavior named @var{name}. | |
| 849 | |
| 850 @var{doc-string} must be specified. It is a description of what the | |
| 851 behavior does when it's enabled and how to further control it (typically | |
| 852 through custom variables). Accepted keywords are | |
| 853 | |
| 854 @table @code | |
| 855 @item :title | |
| 856 A "pretty" version of the name, for use in menus. If omitted | |
| 857 a prettified name will be generated. | |
| 858 | |
| 859 @item :require | |
| 860 A single symbol or a list of such symbols, which need to be | |
| 861 present at enable time, or will be loaded using @code{require}. | |
| 862 | |
| 863 @item :enable | |
| 864 A function of no variables, which turns the behavior on. | |
| 865 | |
| 866 @item :disable | |
| 867 A function of no variables, which turns the behavior off. | |
| 868 @end table | |
| 869 | |
| 870 Behaviors are assumed to be global, and to take effect immediately; if | |
| 871 the underlying package is per-buffer, the enabler may have to scan all | |
| 872 existing buffers and frob them. When a behavior is disabled, it should | |
| 873 completely go away @strong{everywhere}, as if it were never invoked at | |
| 874 all. | |
| 875 | |
| 876 The @code{:disable} keyword can be missing. This is bad practice. In | |
| 877 such a case, attempting to disable the behavior will signal an error | |
| 878 unless you use the @code{force} option. | |
| 879 @end defun | |
| 880 | |
| 881 @defun read-behavior prompt [require-match [initial-contents [history [default]]]] | |
| 882 | |
| 883 Return a behavior symbol from the minibuffer, prompting with string | |
| 884 @var{prompt}. | |
| 885 | |
| 886 The optional arguments @var{require-match}, @var{initial-contents}, | |
| 887 @var{history}, and @var{default} are passed to @code{completing-read}, | |
| 888 and have semantics derived from that function. @ref{Minibuffer | |
| 889 Completion}. The default value of @var{history} is | |
| 890 @code{behavior-history}. | |
| 891 @end defun | |
| 892 | |
| 893 @defun behavior-enabled-p name | |
| 894 | |
| 895 Return non-nil if the behavior registered under @var{name} is enabled. | |
| 896 | |
| 897 Unimplemented in 21.5.6. | |
| 898 @end defun | |
| 899 | |
| 900 @defun enable-behavior behavior [force] | |
| 901 Enable the behavior registered under the symbol @var{behavior}. | |
| 902 | |
| 903 The optional argument @var{force} is unimplemented in 21.5.6. | |
| 904 | |
| 905 Called interactively, prompt the user for @var{behavior}, and take | |
| 906 @var{force} from the prefix argument. | |
| 907 @end defun | |
| 908 | |
| 909 @defun disable-behavior (behavior &optional force) | |
| 910 Disable the behavior registered under the symbol @var{behavior}. | |
| 911 | |
| 912 The optional argument @var{force} is unimplemented in 21.5.6. | |
| 913 | |
| 914 Called interactively, prompt the user for @var{behavior}, and take | |
| 915 @var{force} from the prefix argument. | |
| 916 @end defun | |
| 917 | |
| 1833 | 918 @node Defining New Types |
| 919 @subsection Defining New Types | |
| 920 | |
| 921 In the previous sections we have described how to construct elaborate | |
| 922 type specifications for @code{defcustom}. In some cases you may want to | |
| 923 give such a type specification a name. The obvious case is when you are | |
| 924 using the same type for many user options, rather than repeat the | |
| 925 specification for each option, you can give the type specification a | |
| 926 name once, and use that name each @code{defcustom}. The other case is | |
| 927 when a user option accept a recursive datastructure. To make it | |
| 928 possible for a datatype to refer to itself, it needs to have a name. | |
| 929 | |
| 930 Since custom types are implemented as widgets, the way to define a new | |
| 931 customize type is to define a new widget. We are not going to describe | |
| 932 the widget interface here in details, see @ref{Top, , Introduction, | |
| 933 widget, The Emacs Widget Library}, for that. Instead we are going to | |
| 934 demonstrate the minimal functionality needed for defining new customize | |
| 935 types by a simple example. | |
| 936 | |
| 937 @example | |
| 938 (define-widget 'binary-tree-of-string 'lazy | |
| 939 "A binary tree made of cons-cells and strings." | |
| 940 :offset 4 | |
| 941 :tag "Node" | |
| 942 :type '(choice (string :tag "Leaf" :value "") | |
| 943 (cons :tag "Interior" | |
| 944 :value ("" . "") | |
| 945 binary-tree-of-string | |
| 946 binary-tree-of-string))) | |
| 947 | |
| 948 (defcustom foo-bar "" | |
| 949 "Sample variable holding a binary tree of strings." | |
| 950 :type 'binary-tree-of-string) | |
| 951 @end example | |
| 952 | |
| 953 The function to define a new widget is name @code{define-widget}. The | |
| 954 first argument is the symbol we want to make a new widget type. The | |
| 955 second argument is a symbol representing an existing widget, the new | |
| 956 widget is going to be defined in terms of difference from the existing | |
| 957 widget. For the purpose of defining new customization types, the | |
| 958 @code{lazy} widget is perfect, because it accept a @code{:type} keyword | |
| 959 argument with the same syntax as the keyword argument to | |
| 960 @code{defcustom} with the same name. The third argument is a | |
| 961 documentation string for the new widget. You will be able to see that | |
| 962 string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string | |
| 963 @key{ret}} command. | |
| 964 | |
| 965 After these mandatory arguments follows the keyword arguments. The most | |
| 966 important is @code{:type}, which describes the datatype we want to match | |
| 967 with this widget. Here a @code{binary-tree-of-string} is described as | |
| 968 being either a string, or a cons-cell whose car and cdr are themselves | |
| 969 both @code{binary-tree-of-string}. Note the reference to the widget | |
| 970 type we are currently in the process of defining. The @code{:tag} | |
| 971 attribute is a string to name the widget in the user interface, and the | |
| 972 @code{:offset} argument are there to ensure that child nodes are | |
| 973 indented four spaces relatively to the parent node, making the tree | |
| 974 structure apparent in the customization buffer. | |
| 975 | |
| 976 The @code{defcustom} shows how the new widget can be used as an ordinary | |
| 977 customization type. |