4 @setfilename ../info/custom
5 @settitle The Customization Library
12 @node Top, Declaring Groups, (dir), (dir)
13 @comment node-name, next, previous, up
14 @top The Customization Library
16 This manual describes how to declare customization groups, variables,
17 and faces. It doesn't contain any examples, but please look at the file
18 @file{cus-edit.el} which contains many declarations you can learn from.
22 * Declaring Variables::
24 * Usage for Package Authors::
30 All the customization declarations can be changes by keyword arguments.
31 Groups, variables, and faces all share these common keywords:
35 @var{value} should be a customization group.
36 Add @var{symbol} to that group.
38 @var{value} should be a widget type.
39 Add @var{value} to the external links for this customization option.
40 Useful widget types include @code{custom-manual}, @code{info-link}, and
43 Add @var{value} to the files that should be loaded before displaying
44 this customization option. The value should be either a string, which
45 should be a string which will be loaded with @code{load-library} unless
46 present in @code{load-history}, or a symbol which will be loaded with
49 @var{Value} should be a short string used for identifying the option in
50 customization menus and buffers. By default the tag will be
51 automatically created from the options name.
54 @node Declaring Groups, Declaring Variables, Top, Top
55 @comment node-name, next, previous, up
56 @section Declaring Groups
58 Use @code{defgroup} to declare new customization groups.
60 @defun defgroup symbol members doc [keyword value]...
61 Declare @var{symbol} as a customization group containing @var{members}.
62 @var{symbol} does not need to be quoted.
64 @var{doc} is the group documentation.
66 @var{members} should be an alist of the form ((@var{name}
67 @var{widget})...) where @var{name} is a symbol and @var{widget} is a
68 widget for editing that symbol. Useful widgets are
69 @code{custom-variable} for editing variables, @code{custom-face} for
70 editing faces, and @code{custom-group} for editing groups.@refill
72 Internally, custom uses the symbol property @code{custom-group} to keep
73 track of the group members, and @code{group-documentation} for the
76 The following additional @var{keyword}'s are defined:
80 @var{value} should be a string. If the string is a prefix for the name
81 of a member of the group, that prefix will be ignored when creating a
86 @node Declaring Variables, Declaring Faces, Declaring Groups, Top
87 @comment node-name, next, previous, up
88 @section Declaring Variables
90 Use @code{defcustom} to declare user editable variables.
92 @defun defcustom symbol value doc [keyword value]...
93 Declare @var{symbol} as a customizable variable that defaults to @var{value}.
94 Neither @var{symbol} nor @var{value} needs to be quoted.
95 If @var{symbol} is not already bound, initialize it to @var{value}.
97 @var{doc} is the variable documentation.
99 The following additional @var{keyword}'s are defined:
103 @var{value} should be a widget type.
106 @var{value} should be a list of possible members of the specified type.
107 For hooks, this is a list of function names.
110 @var{value} should be a function used to initialize the variable. It
111 takes two arguments, the symbol and value given in the @code{defcustom} call.
112 Some predefined functions are:
115 @item custom-initialize-set
116 Use the @code{:set} method to initialize the variable. Do not
117 initialize it if already bound. This is the default @code{:initialize}
120 @item custom-initialize-default
121 Always use @code{set-default} to initialize the variable, even if a
122 @code{:set} method has been specified.
124 @item custom-initialize-reset
125 If the variable is already bound, reset it by calling the @code{:set}
126 method with the value returned by the @code{:get} method.
128 @item custom-initialize-changed
129 Like @code{custom-initialize-reset}, but use @code{set-default} to
130 initialize the variable if it is not bound and has not been set
135 @var{value} should be a function to set the value of the symbol. It
136 takes two arguments, the symbol to set and the value to give it. The
137 default is @code{set-default}.
140 @var{value} should be a function to extract the value of symbol. The
141 function takes one argument, a symbol, and should return the current
142 value for that symbol. The default is @code{default-value}.
145 @var{value} should be a feature symbol. Each feature will be required
146 when the `defcustom' is evaluated, or when Emacs is started if the user
147 has saved this option.
151 @xref{Sexp Types,,,widget,The Widget Library}, for information about
152 widgets to use together with the @code{:type} keyword.
155 Internally, custom uses the symbol property @code{custom-type} to keep
156 track of the variables type, @code{standard-value} for the program
157 specified default value, @code{saved-value} for a value saved by the
158 user, and @code{variable-documentation} for the documentation string.
160 Use @code{custom-add-option} to specify that a specific function is
161 useful as an member of a hook.
163 @defun custom-add-option symbol option
164 To the variable @var{symbol} add @var{option}.
166 If @var{symbol} is a hook variable, @var{option} should be a hook
167 member. For other types variables, the effect is undefined."
170 @node Declaring Faces, Usage for Package Authors, Declaring Variables, Top
171 @comment node-name, next, previous, up
172 @section Declaring Faces
174 Faces are declared with @code{defface}.
176 @defun defface face spec doc [keyword value]...
178 Declare @var{face} as a customizable face that defaults to @var{spec}.
179 @var{face} does not need to be quoted.
181 If @var{face} has been set with `custom-set-face', set the face attributes
182 as specified by that function, otherwise set the face attributes
183 according to @var{spec}.
185 @var{doc} is the face documentation.
187 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
189 @var{atts} is a list of face attributes and their values. The possible
190 attributes are defined in the variable `custom-face-attributes'.
192 The @var{atts} of the first entry in @var{spec} where the @var{display}
193 matches the frame should take effect in that frame. @var{display} can
194 either be the symbol `t', which will match all frames, or an alist of
195 the form @samp{((@var{req} @var{item}...)...)}@refill
197 For the @var{display} to match a FRAME, the @var{req} property of the
198 frame must match one of the @var{item}. The following @var{req} are
203 (the value of (window-system))@*
204 Should be one of @code{x} or @code{tty}.
207 (the frame's color support)@*
208 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
211 (what color is used for the background text)@*
212 Should be one of @code{light} or @code{dark}.
215 Internally, custom uses the symbol property @code{face-defface-spec} for
216 the program specified default face properties, @code{saved-face} for
217 properties saved by the user, and @code{face-documentation} for the
218 documentation string.@refill
222 @node Usage for Package Authors, Utilities, Declaring Faces, Top
223 @comment node-name, next, previous, up
224 @section Usage for Package Authors
226 The recommended usage for the author of a typical emacs lisp package is
227 to create one group identifying the package, and make all user options
228 and faces members of that group. If the package has more than around 20
229 such options, they should be divided into a number of subgroups, with
230 each subgroup being member of the top level group.
232 The top level group for the package should itself be member of one or
233 more of the standard customization groups. There exists a group for
234 each @emph{finder} keyword. Press @kbd{C-h p} to see a list of finder
235 keywords, and add you group to each of them, using the @code{:group}
238 @node Utilities, The Init File, Usage for Package Authors, Top
239 @comment node-name, next, previous, up
242 These utilities can come in handy when adding customization support.
244 @deffn Widget custom-manual
245 Widget type for specifying the info manual entry for a customization
246 option. It takes one argument, an info address.
249 @defun custom-add-to-group group member widget
250 To existing @var{group} add a new @var{member} of type @var{widget},
251 If there already is an entry for that member, overwrite it.
254 @defun custom-add-link symbol widget
255 To the custom option @var{symbol} add the link @var{widget}.
258 @defun custom-add-load symbol load
259 To the custom option @var{symbol} add the dependency @var{load}.
260 @var{load} should be either a library file name, or a feature name.
263 @defun customize-menu-create symbol &optional name
264 Create menu for customization group @var{symbol}.
265 If optional @var{name} is given, use that as the name of the menu.
266 Otherwise the menu will be named `Customize'.
267 The menu is in a format applicable to @code{easy-menu-define}.
270 @node The Init File, Wishlist, Utilities, Top
271 @comment node-name, next, previous, up
272 @section The Init File
274 When you save the customizations, call to @code{custom-set-variables},
275 @code{custom-set-faces} are inserted into the file specified by
276 @code{custom-file}. By default @code{custom-file} is your @file{.emacs}
277 file. If you use another file, you must explicitly load it yourself.
278 The two functions will initialize variables and faces as you have
281 @node Wishlist, , The Init File, Top
282 @comment node-name, next, previous, up
287 Better support for keyboard operations in the customize buffer.
290 Integrate with @file{w3} so you can get customization buffers with much
291 better formatting. I'm thinking about adding a <custom>name</custom>
292 tag. The latest w3 have some support for this, so come up with a
296 Add an `examples' section, with explained examples of custom type
300 Support selectable color themes. I.e., change many faces by setting one
304 Support undo using lmi's @file{gnus-undo.el}.
308 Make it possible to append to `choice', `radio', and `set' options.
311 Ask whether set or modified variables should be saved in
312 @code{kill-buffer-hook}.
314 Ditto for @code{kill-emacs-query-functions}.
317 Command to check if there are any customization options that
318 does not belong to an existing group.
321 Optionally disable the point-cursor and instead highlight the selected
322 item in XEmacs. This is like the *Completions* buffer in XEmacs.
323 Suggested by Jens Lautenbacher
324 @samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill
327 Explain why it is necessary that all choices have different default
331 Make it possible to include a comment/remark/annotation when saving an
335 Add some direct support for meta variables, i.e. make it possible to
336 specify that this variable should be reset when that variable is
343 Describe the @code{:type} syntax in this manual.
346 Find a place is this manual for the following text:
348 @strong{Radio vs. Buttons}
350 Use a radio if you can't find a good way to describe the item in the
351 choice menu text. I.e. it is better to use a radio if you expect the
352 user would otherwise manually select each item from the choice menu in
353 turn to see what it expands too.
355 Avoid radios if some of the items expands to complex structures.
357 I mostly use radios when most of the items are of type
358 @code{function-item} or @code{variable-item}.
361 Update customize buffers when @code{custom-set-variable} or
362 @code{custom-save-customized} is called.
365 Better handling of saved but uninitialized items.
368 Detect when faces have been changed outside customize.
371 Enable mouse help in Emacs by default.
374 Add an easy way to display the standard settings when an item is modified.
377 See if it is feasible to scan files for customization information
378 instead of loading them,
381 Add hint message when user push a non-pushable tag.
383 Suggest that the user unhide if hidden, and edit the value directly
387 Use checkboxes and radio buttons in the state menus.
390 Add option to hide @samp{[hide]} for short options. Default, on.
393 Add option to hide @samp{[state]} for options with their standard
397 There should be a way to specify site defaults for user options.
400 There should be more buffer styles. The default `nested style, the old
401 `outline' style, a `numeric' style with numbers instead of stars, an
402 `empty' style with just the group name, and `compact' with only one line
406 Newline and tab should be displayed as @samp{^J} and @samp{^I} in the
407 @code{regexp} and @code{file} widgets. I think this can be done in
408 XEmacs by adding a display table to the face.
411 Use glyphs to draw the @code{customize-browse} tree.
413 Add echo and balloon help. You should be able to read the documentation
414 simply by moving the mouse pointer above the name.