4 @setfilename ../info/custom
5 @settitle The Customization Library
13 @dircategory XEmacs Editor
15 * Customizations: (custom). Customization Library.
20 @node Top, Declaring Groups, (dir), (dir)
21 @comment node-name, next, previous, up
22 @top The Customization Library
24 This manual describes how to declare customization groups, variables,
25 and faces. It doesn't contain any examples, but please look at the file
26 @file{cus-edit.el} which contains many declarations you can learn from.
30 * Declaring Variables::
32 * Usage for Package Authors::
38 All the customization declarations can be changes by keyword arguments.
39 Groups, variables, and faces all share these common keywords:
43 @var{value} should be a customization group.
44 Add @var{symbol} to that group.
46 @var{value} should be a widget type.
47 Add @var{value} to the external links for this customization option.
48 Useful widget types include @code{custom-manual}, @code{info-link}, and
51 Add @var{value} to the files that should be loaded before displaying
52 this customization option. The value should be either a string, which
53 should be a string which will be loaded with @code{load-library} unless
54 present in @code{load-history}, or a symbol which will be loaded with
57 @var{Value} should be a short string used for identifying the option in
58 customization menus and buffers. By default the tag will be
59 automatically created from the options name.
62 @node Declaring Groups, Declaring Variables, Top, Top
63 @comment node-name, next, previous, up
64 @section Declaring Groups
66 Use @code{defgroup} to declare new customization groups.
68 @defun defgroup symbol members doc [keyword value]...
69 Declare @var{symbol} as a customization group containing @var{members}.
70 @var{symbol} does not need to be quoted.
72 @var{doc} is the group documentation.
74 @var{members} should be an alist of the form ((@var{name}
75 @var{widget})...) where @var{name} is a symbol and @var{widget} is a
76 widget for editing that symbol. Useful widgets are
77 @code{custom-variable} for editing variables, @code{custom-face} for
78 editing faces, and @code{custom-group} for editing groups.@refill
80 Internally, custom uses the symbol property @code{custom-group} to keep
81 track of the group members, and @code{group-documentation} for the
84 The following additional @var{keyword}'s are defined:
88 @var{value} should be a string. If the string is a prefix for the name
89 of a member of the group, that prefix will be ignored when creating a
94 @node Declaring Variables, Declaring Faces, Declaring Groups, Top
95 @comment node-name, next, previous, up
96 @section Declaring Variables
98 Use @code{defcustom} to declare user editable variables.
100 @defun defcustom symbol value doc [keyword value]...
101 Declare @var{symbol} as a customizable variable that defaults to @var{value}.
102 Neither @var{symbol} nor @var{value} needs to be quoted.
103 If @var{symbol} is not already bound, initialize it to @var{value}.
105 @var{doc} is the variable documentation.
107 The following additional @var{keyword}'s are defined:
111 @var{value} should be a widget type.
114 @var{value} should be a list of possible members of the specified type.
115 For hooks, this is a list of function names.
118 @var{value} should be a function used to initialize the variable. It
119 takes two arguments, the symbol and value given in the @code{defcustom} call.
120 Some predefined functions are:
123 @item custom-initialize-set
124 Use the @code{:set} method to initialize the variable. Do not
125 initialize it if already bound. This is the default @code{:initialize}
128 @item custom-initialize-default
129 Always use @code{set-default} to initialize the variable, even if a
130 @code{:set} method has been specified.
132 @item custom-initialize-reset
133 If the variable is already bound, reset it by calling the @code{:set}
134 method with the value returned by the @code{:get} method.
136 @item custom-initialize-changed
137 Like @code{custom-initialize-reset}, but use @code{set-default} to
138 initialize the variable if it is not bound and has not been set
143 @var{value} should be a function to set the value of the symbol. It
144 takes two arguments, the symbol to set and the value to give it. The
145 default is @code{set-default}.
148 @var{value} should be a function to extract the value of symbol. The
149 function takes one argument, a symbol, and should return the current
150 value for that symbol. The default is @code{default-value}.
153 @var{value} should be a feature symbol. Each feature will be required
154 when the `defcustom' is evaluated, or when Emacs is started if the user
155 has saved this option.
159 @xref{Sexp Types,,,widget,The Widget Library}, for information about
160 widgets to use together with the @code{:type} keyword.
163 Internally, custom uses the symbol property @code{custom-type} to keep
164 track of the variables type, @code{standard-value} for the program
165 specified default value, @code{saved-value} for a value saved by the
166 user, and @code{variable-documentation} for the documentation string.
168 Use @code{custom-add-option} to specify that a specific function is
169 useful as an member of a hook.
171 @defun custom-add-option symbol option
172 To the variable @var{symbol} add @var{option}.
174 If @var{symbol} is a hook variable, @var{option} should be a hook
175 member. For other types variables, the effect is undefined."
178 @node Declaring Faces, Usage for Package Authors, Declaring Variables, Top
179 @comment node-name, next, previous, up
180 @section Declaring Faces
182 Faces are declared with @code{defface}.
184 @defun defface face spec doc [keyword value]...
186 Declare @var{face} as a customizable face that defaults to @var{spec}.
187 @var{face} does not need to be quoted.
189 If @var{face} has been set with `custom-set-face', set the face attributes
190 as specified by that function, otherwise set the face attributes
191 according to @var{spec}.
193 @var{doc} is the face documentation.
195 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
197 @var{atts} is a list of face attributes and their values. The possible
198 attributes are defined in the variable `custom-face-attributes'.
200 The @var{atts} of the first entry in @var{spec} where the @var{display}
201 matches the frame should take effect in that frame. @var{display} can
202 either be the symbol `t', which will match all frames, or an alist of
203 the form @samp{((@var{req} @var{item}...)...)}@refill
205 For the @var{display} to match a FRAME, the @var{req} property of the
206 frame must match one of the @var{item}. The following @var{req} are
211 (the value of (window-system))@*
212 Should be one of @code{x} or @code{tty}.
215 (the frame's color support)@*
216 Should be one of @code{color}, @code{grayscale}, or @code{mono}.
219 (what color is used for the background text)@*
220 Should be one of @code{light} or @code{dark}.
223 Internally, custom uses the symbol property @code{face-defface-spec} for
224 the program specified default face properties, @code{saved-face} for
225 properties saved by the user, and @code{face-documentation} for the
226 documentation string.@refill
230 @node Usage for Package Authors, Utilities, Declaring Faces, Top
231 @comment node-name, next, previous, up
232 @section Usage for Package Authors
234 The recommended usage for the author of a typical emacs lisp package is
235 to create one group identifying the package, and make all user options
236 and faces members of that group. If the package has more than around 20
237 such options, they should be divided into a number of subgroups, with
238 each subgroup being member of the top level group.
240 The top level group for the package should itself be member of one or
241 more of the standard customization groups. There exists a group for
242 each @emph{finder} keyword. Press @kbd{C-h p} to see a list of finder
243 keywords, and add you group to each of them, using the @code{:group}
246 @node Utilities, The Init File, Usage for Package Authors, Top
247 @comment node-name, next, previous, up
250 These utilities can come in handy when adding customization support.
252 @deffn Widget custom-manual
253 Widget type for specifying the info manual entry for a customization
254 option. It takes one argument, an info address.
257 @defun custom-add-to-group group member widget
258 To existing @var{group} add a new @var{member} of type @var{widget},
259 If there already is an entry for that member, overwrite it.
262 @defun custom-add-link symbol widget
263 To the custom option @var{symbol} add the link @var{widget}.
266 @defun custom-add-load symbol load
267 To the custom option @var{symbol} add the dependency @var{load}.
268 @var{load} should be either a library file name, or a feature name.
271 @defun customize-menu-create symbol &optional name
272 Create menu for customization group @var{symbol}.
273 If optional @var{name} is given, use that as the name of the menu.
274 Otherwise the menu will be named `Customize'.
275 The menu is in a format applicable to @code{easy-menu-define}.
278 @node The Init File, Wishlist, Utilities, Top
279 @comment node-name, next, previous, up
280 @section The Init File
282 When you save the customizations, call to @code{custom-set-variables},
283 @code{custom-set-faces} are inserted into the file specified by
284 @code{custom-file}. By default @code{custom-file} is your @file{.emacs}
285 file. If you use another file, you must explicitly load it yourself.
286 The two functions will initialize variables and faces as you have
289 @node Wishlist, , The Init File, Top
290 @comment node-name, next, previous, up
295 Better support for keyboard operations in the customize buffer.
298 Integrate with @file{w3} so you can get customization buffers with much
299 better formatting. I'm thinking about adding a <custom>name</custom>
300 tag. The latest w3 have some support for this, so come up with a
304 Add an `examples' section, with explained examples of custom type
308 Support selectable color themes. I.e., change many faces by setting one
312 Support undo using lmi's @file{gnus-undo.el}.
316 Make it possible to append to `choice', `radio', and `set' options.
319 Ask whether set or modified variables should be saved in
320 @code{kill-buffer-hook}.
322 Ditto for @code{kill-emacs-query-functions}.
325 Command to check if there are any customization options that
326 does not belong to an existing group.
329 Optionally disable the point-cursor and instead highlight the selected
330 item in XEmacs. This is like the *Completions* buffer in XEmacs.
331 Suggested by Jens Lautenbacher
332 @samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill
335 Explain why it is necessary that all choices have different default
339 Make it possible to include a comment/remark/annotation when saving an
343 Add some direct support for meta variables, i.e. make it possible to
344 specify that this variable should be reset when that variable is
351 Describe the @code{:type} syntax in this manual.
354 Find a place is this manual for the following text:
356 @strong{Radio vs. Buttons}
358 Use a radio if you can't find a good way to describe the item in the
359 choice menu text. I.e. it is better to use a radio if you expect the
360 user would otherwise manually select each item from the choice menu in
361 turn to see what it expands too.
363 Avoid radios if some of the items expands to complex structures.
365 I mostly use radios when most of the items are of type
366 @code{function-item} or @code{variable-item}.
369 Update customize buffers when @code{custom-set-variable} or
370 @code{custom-save-customized} is called.
373 Better handling of saved but uninitialized items.
376 Detect when faces have been changed outside customize.
379 Enable mouse help in Emacs by default.
382 Add an easy way to display the standard settings when an item is modified.
385 See if it is feasible to scan files for customization information
386 instead of loading them,
389 Add hint message when user push a non-pushable tag.
391 Suggest that the user unhide if hidden, and edit the value directly
395 Use checkboxes and radio buttons in the state menus.
398 Add option to hide @samp{[hide]} for short options. Default, on.
401 Add option to hide @samp{[state]} for options with their standard
405 There should be a way to specify site defaults for user options.
408 There should be more buffer styles. The default `nested style, the old
409 `outline' style, a `numeric' style with numbers instead of stars, an
410 `empty' style with just the group name, and `compact' with only one line
414 Newline and tab should be displayed as @samp{^J} and @samp{^I} in the
415 @code{regexp} and @code{file} widgets. I think this can be done in
416 XEmacs by adding a display table to the face.
419 Use glyphs to draw the @code{customize-browse} tree.
421 Add echo and balloon help. You should be able to read the documentation
422 simply by moving the mouse pointer above the name.