1 This is ../info/custom.info, produced by makeinfo version 4.8 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Customizations: (custom). Customization Library.
10 File: custom.info, Node: Top, Next: Declaring Groups, Prev: (dir), Up: (dir)
12 The Customization Library
13 *************************
15 This manual describes how to declare customization groups, variables,
16 and faces. It doesn't contain any examples, but please look at the file
17 `cus-edit.el' which contains many declarations you can learn from.
22 * Declaring Variables::
24 * Usage for Package Authors::
29 All the customization declarations can be changes by keyword
30 arguments. Groups, variables, and faces all share these common
34 VALUE should be a customization group. Add SYMBOL to that group.
37 VALUE should be a widget type. Add VALUE to the external links
38 for this customization option. Useful widget types include
39 `custom-manual', `info-link', and `url-link'.
42 Add VALUE to the files that should be loaded before displaying
43 this customization option. The value should be either a string,
44 which should be a string which will be loaded with `load-library'
45 unless present in `load-history', or a symbol which will be loaded
49 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 File: custom.info, Node: Declaring Groups, Next: Declaring Variables, Prev: Top, Up: Top
59 Use `defgroup' to declare new customization groups.
61 -- Function: defgroup symbol members doc [keyword value]...
62 Declare SYMBOL as a customization group containing MEMBERS.
63 SYMBOL does not need to be quoted.
65 DOC is the group documentation.
67 MEMBERS should be an alist of the form ((NAME WIDGET)...) where
68 NAME is a symbol and WIDGET is a widget for editing that symbol.
69 Useful widgets are `custom-variable' for editing variables,
70 `custom-face' for editing faces, and `custom-group' for editing
73 Internally, custom uses the symbol property `custom-group' to keep
74 track of the group members, and `group-documentation' for the
77 The following additional KEYWORD's are defined:
80 VALUE should be a string. If the string is a prefix for the
81 name of a member of the group, that prefix will be ignored
82 when creating a tag for that member.
85 File: custom.info, Node: Declaring Variables, Next: Declaring Faces, Prev: Declaring Groups, Up: Top
90 Use `defcustom' to declare user editable variables.
92 -- Function: defcustom symbol value doc [keyword value]...
93 Declare SYMBOL as a customizable variable that defaults to VALUE.
94 Neither SYMBOL nor VALUE needs to be quoted. If SYMBOL is not
95 already bound, initialize it to VALUE.
97 DOC is the variable documentation.
99 The following additional KEYWORD's are defined:
102 VALUE should be a widget type.
105 VALUE should be a list of possible members of the specified
106 type. For hooks, this is a list of function names.
109 VALUE should be a function used to initialize the variable.
110 It takes two arguments, the symbol and value given in the
111 `defcustom' call. Some predefined functions are:
113 `custom-initialize-set'
114 Use the `:set' method to initialize the variable. Do not
115 initialize it if already bound. This is the default
116 `:initialize' method.
118 `custom-initialize-default'
119 Always use `set-default' to initialize the variable,
120 even if a `:set' method has been specified.
122 `custom-initialize-reset'
123 If the variable is already bound, reset it by calling
124 the `:set' method with the value returned by the `:get'
127 `custom-initialize-changed'
128 Like `custom-initialize-reset', but use `set-default' to
129 initialize the variable if it is not bound and has not
133 VALUE should be a function to set the value of the symbol. It
134 takes two arguments, the symbol to set and the value to give
135 it. The default is `set-default'.
138 VALUE should be a function to extract the value of symbol.
139 The function takes one argument, a symbol, and should return
140 the current value for that symbol. The default is
144 VALUE should be a feature symbol. Each feature will be
145 required when the `defcustom' is evaluated, or when Emacs is
146 started if the user has saved this option.
149 *Note Sexp Types: (widget)Sexp Types, for information about
150 widgets to use together with the `:type' keyword.
152 Internally, custom uses the symbol property `custom-type' to keep
153 track of the variables type, `standard-value' for the program specified
154 default value, `saved-value' for a value saved by the user, and
155 `variable-documentation' for the documentation string.
157 Use `custom-add-option' to specify that a specific function is
158 useful as a member of a hook.
160 -- Function: custom-add-option symbol option
161 To the variable SYMBOL add OPTION.
163 If SYMBOL is a hook variable, OPTION should be a hook member. For
164 other types of variables, the effect is undefined."
167 File: custom.info, Node: Declaring Faces, Next: Usage for Package Authors, Prev: Declaring Variables, Up: Top
172 Faces are declared with `defface'.
174 -- Function: defface face spec doc [keyword value]...
175 Declare FACE as a customizable face that defaults to SPEC. FACE
176 does not need to be quoted.
178 If FACE has been set with `custom-set-face', set the face
179 attributes as specified by that function, otherwise set the face
180 attributes according to SPEC.
182 DOC is the face documentation.
184 SPEC should be an alist of the form `((DISPLAY ATTS)...)'.
186 ATTS is a list of face attributes and their values. The possible
187 attributes are defined in the variable `custom-face-attributes'.
189 The ATTS of the first entry in SPEC where the DISPLAY matches the
190 frame should take effect in that frame. DISPLAY can either be the
191 symbol `t', which will match all frames, or an alist of the form
194 For the DISPLAY to match a FRAME, the REQ property of the frame
195 must match one of the ITEM. The following REQ are defined:
198 (the value of (window-system))
199 Should be one of `x' or `tty'.
202 (the frame's color support)
203 Should be one of `color', `grayscale', or `mono'.
206 (what color is used for the background text)
207 Should be one of `light' or `dark'.
209 Internally, custom uses the symbol property `face-defface-spec' for
210 the program specified default face properties, `saved-face' for
211 properties saved by the user, and `face-documentation' for the
212 documentation string.
216 File: custom.info, Node: Usage for Package Authors, Next: Utilities, Prev: Declaring Faces, Up: Top
218 Usage for Package Authors
219 =========================
221 The recommended usage for the author of a typical emacs lisp package is
222 to create one group identifying the package, and make all user options
223 and faces members of that group. If the package has more than around 20
224 such options, they should be divided into a number of subgroups, with
225 each subgroup being member of the top level group.
227 The top level group for the package should itself be member of one or
228 more of the standard customization groups. There exists a group for
229 each _finder_ keyword. Press `C-h p' to see a list of finder keywords,
230 and add you group to each of them, using the `:group' keyword.
233 File: custom.info, Node: Utilities, Next: The Init File, Prev: Usage for Package Authors, Up: Top
238 These utilities can come in handy when adding customization support.
240 -- Widget: custom-manual
241 Widget type for specifying the info manual entry for a
242 customization option. It takes one argument, an info address.
244 -- Function: custom-add-to-group group member widget
245 To existing GROUP add a new MEMBER of type WIDGET, If there
246 already is an entry for that member, overwrite it.
248 -- Function: custom-add-link symbol widget
249 To the custom option SYMBOL add the link WIDGET.
251 -- Function: custom-add-load symbol load
252 To the custom option SYMBOL add the dependency LOAD. LOAD should
253 be either a library file name, or a feature name.
255 -- Function: customize-menu-create symbol &optional name
256 Create menu for customization group SYMBOL. If optional NAME is
257 given, use that as the name of the menu. Otherwise the menu will
258 be named `Customize'. The menu is in a format applicable to
262 File: custom.info, Node: The Init File, Next: Wishlist, Prev: Utilities, Up: Top
267 Customizations are saved to the file specified by `custom-file', as
268 calls to `custom-set-variables' and `custom-set-faces'.
270 When you save customizations, the current implementation removes the
271 calls to `custom-set-variables' and `custom-set-faces', and replaces
272 them with code generated on the basis of the current customization
275 By default `custom-file' is your `.emacs' file (for GNU Emacs and
276 older XEmacs) and is `custom.el' in the same directory as `init.el' (in
277 XEmacs 21.4 and later). If you use another file, you must explicitly
280 As of XEmacs 21.4.7, when `custom-file' is present, it is loaded
281 _after_ `init.el'. This is likely to change in the future, because (1)
282 actions in `init.el' often would like to depend on customizations for
283 consistent appearance and (2) Custom is quite brutal about enforcing
284 its idea of the correct values at initialization.
287 File: custom.info, Node: Wishlist, Prev: The Init File, Up: Top
292 * Better support for keyboard operations in the customize buffer.
294 * Integrate with `w3' so you can get customization buffers with much
295 better formatting. I'm thinking about adding a
296 <custom>name</custom> tag. The latest w3 have some support for
297 this, so come up with a convincing example.
299 * Add an `examples' section, with explained examples of custom type
302 * Support selectable color themes. I.e., change many faces by
303 setting one variable.
305 * Support undo using lmi's `gnus-undo.el'.
307 * Make it possible to append to `choice', `radio', and `set' options.
309 * Ask whether set or modified variables should be saved in
312 Ditto for `kill-emacs-query-functions'.
314 * Command to check if there are any customization options that does
315 not belong to an existing group.
317 * Optionally disable the point-cursor and instead highlight the
318 selected item in XEmacs. This is like the *Completions* buffer in
319 XEmacs. Suggested by Jens Lautenbacher
320 `<jens@lemming0.lem.uni-karlsruhe.de>'.
322 * Explain why it is necessary that all choices have different default
325 * Add some direct support for meta variables, i.e. make it possible
326 to specify that this variable should be reset when that variable is
331 * Describe the `:type' syntax in this manual.
333 * Find a place is this manual for the following text:
337 Use a radio if you can't find a good way to describe the item in
338 the choice menu text. I.e. it is better to use a radio if you
339 expect the user would otherwise manually select each item from the
340 choice menu in turn to see what it expands too.
342 Avoid radios if some of the items expands to complex structures.
344 I mostly use radios when most of the items are of type
345 `function-item' or `variable-item'.
347 * Update customize buffers when `custom-set-variable' or
348 `custom-save-customized' is called.
350 * Better handling of saved but uninitialized items.
352 * Detect when faces have been changed outside customize.
354 * Enable mouse help in Emacs by default.
356 * Add an easy way to display the standard settings when an item is
359 * See if it is feasible to scan files for customization information
360 instead of loading them,
362 * Add hint message when user push a non-pushable tag.
364 Suggest that the user unhide if hidden, and edit the value directly
367 * Use checkboxes and radio buttons in the state menus.
369 * Add option to hide `[hide]' for short options. Default, on.
371 * Add option to hide `[state]' for options with their standard
374 * There should be a way to specify site defaults for user options.
376 * There should be more buffer styles. The default `nested style,
377 the old `outline' style, a `numeric' style with numbers instead of
378 stars, an `empty' style with just the group name, and `compact'
379 with only one line per item.
381 * Newline and tab should be displayed as `^J' and `^I' in the
382 `regexp' and `file' widgets. I think this can be done in XEmacs
383 by adding a display table to the face.
385 * Use glyphs to draw the `customize-browse' tree.
387 Add echo and balloon help. You should be able to read the
388 documentation simply by moving the mouse pointer above the name.
399 Node: Declaring Groups
\7f1622
400 Node: Declaring Variables
\7f2721
401 Node: Declaring Faces
\7f5814
402 Node: Usage for Package Authors
\7f7510
403 Node: Utilities
\7f8286
404 Node: The Init File
\7f9372
405 Node: Wishlist
\7f10399