Mercurial > emacs

annotate doc/lispref/customize.texi @ 111660:42b6f450ae22

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