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