1 This is Info file ../info/custom.info, produced by Makeinfo version
2 1.68 from the input file custom.texi.
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.
148 *Note Sexp Types: (widget)Sexp Types, for information about
149 widgets to use together with the `:type' keyword.
151 Internally, custom uses the symbol property `custom-type' to keep
152 track of the variables type, `standard-value' for the program specified
153 default value, `saved-value' for a value saved by the user, and
154 `variable-documentation' for the documentation string.
156 Use `custom-add-option' to specify that a specific function is
157 useful as an member of a hook.
159 - Function: custom-add-option SYMBOL OPTION
160 To the variable SYMBOL add OPTION.
162 If SYMBOL is a hook variable, OPTION should be a hook member. For
163 other types variables, the effect is undefined."
166 File: custom.info, Node: Declaring Faces, Next: Usage for Package Authors, Prev: Declaring Variables, Up: Top
171 Faces are declared with `defface'.
173 - Function: defface FACE SPEC DOC [KEYWORD VALUE]...
174 Declare FACE as a customizable face that defaults to SPEC. FACE
175 does not need to be quoted.
177 If FACE has been set with `custom-set-face', set the face
178 attributes as specified by that function, otherwise set the face
179 attributes according to SPEC.
181 DOC is the face documentation.
183 SPEC should be an alist of the form `((DISPLAY ATTS)...)'.
185 ATTS is a list of face attributes and their values. The possible
186 attributes are defined in the variable `custom-face-attributes'.
188 The ATTS of the first entry in SPEC where the DISPLAY matches the
189 frame should take effect in that frame. DISPLAY can either be the
190 symbol `t', which will match all frames, or an alist of the form
193 For the DISPLAY to match a FRAME, the REQ property of the frame
194 must match one of the ITEM. The following REQ are defined:
197 (the value of (window-system))
198 Should be one of `x' or `tty'.
201 (the frame's color support)
202 Should be one of `color', `grayscale', or `mono'.
205 (what color is used for the background text)
206 Should be one of `light' or `dark'.
208 Internally, custom uses the symbol property `face-defface-spec' for
209 the program specified default face properties, `saved-face' for
210 properties saved by the user, and `face-documentation' for the
211 documentation string.
215 File: custom.info, Node: Usage for Package Authors, Next: Utilities, Prev: Declaring Faces, Up: Top
217 Usage for Package Authors
218 =========================
220 The recommended usage for the author of a typical emacs lisp package
221 is to create one group identifying the package, and make all user
222 options and faces members of that group. If the package has more than
223 around 20 such options, they should be divided into a number of
224 subgroups, with each subgroup being member of the top level group.
226 The top level group for the package should itself be member of one or
227 more of the standard customization groups. There exists a group for
228 each *finder* keyword. Press `C-h p' to see a list of finder keywords,
229 and add you group to each of them, using the `:group' keyword.
232 File: custom.info, Node: Utilities, Next: The Init File, Prev: Usage for Package Authors, Up: Top
237 These utilities can come in handy when adding customization support.
239 - Widget: custom-manual
240 Widget type for specifying the info manual entry for a
241 customization option. It takes one argument, an info address.
243 - Function: custom-add-to-group GROUP MEMBER WIDGET
244 To existing GROUP add a new MEMBER of type WIDGET, If there
245 already is an entry for that member, overwrite it.
247 - Function: custom-add-link SYMBOL WIDGET
248 To the custom option SYMBOL add the link WIDGET.
250 - Function: custom-add-load SYMBOL LOAD
251 To the custom option SYMBOL add the dependency LOAD. LOAD should
252 be either a library file name, or a feature name.
254 - Function: customize-menu-create SYMBOL &optional NAME
255 Create menu for customization group SYMBOL. If optional NAME is
256 given, use that as the name of the menu. Otherwise the menu will
257 be named `Customize'. The menu is in a format applicable to
261 File: custom.info, Node: The Init File, Next: Wishlist, Prev: Utilities, Up: Top
266 When you save the customizations, call to `custom-set-variables',
267 `custom-set-faces' are inserted into the file specified by
268 `custom-file'. By default `custom-file' is your `.emacs' file. If you
269 use another file, you must explicitly load it yourself. The two
270 functions will initialize variables and faces as you have specified.
273 File: custom.info, Node: Wishlist, Prev: The Init File, Up: Top
278 * Better support for keyboard operations in the customize buffer.
280 * Integrate with `w3' so you can get customization buffers with much
281 better formatting. I'm thinking about adding a
282 <custom>name</custom> tag. The latest w3 have some support for
283 this, so come up with a convincing example.
285 * Add an `examples' section, with explained examples of custom type
288 * Support selectable color themes. I.e., change many faces by
289 setting one variable.
291 * Support undo using lmi's `gnus-undo.el'.
293 * Make it possible to append to `choice', `radio', and `set' options.
295 * Ask whether set or modified variables should be saved in
298 Ditto for `kill-emacs-query-functions'.
300 * Command to check if there are any customization options that does
301 not belong to an existing group.
303 * Optionally disable the point-cursor and instead highlight the
304 selected item in XEmacs. This is like the *Completions* buffer in
305 XEmacs. Suggested by Jens Lautenbacher
306 `<jens@lemming0.lem.uni-karlsruhe.de>'.
308 * Explain why it is necessary that all choices have different default
311 * Add some direct support for meta variables, i.e. make it possible
312 to specify that this variable should be reset when that variable is
317 * Describe the `:type' syntax in this manual.
319 * Find a place is this manual for the following text:
323 Use a radio if you can't find a good way to describe the item in
324 the choice menu text. I.e. it is better to use a radio if you
325 expect the user would otherwise manually select each item from the
326 choice menu in turn to see what it expands too.
328 Avoid radios if some of the items expands to complex structures.
330 I mostly use radios when most of the items are of type
331 `function-item' or `variable-item'.
333 * Update customize buffers when `custom-set-variable' or
334 `custom-save-customized' is called.
336 * Better handling of saved but uninitialized items.
338 * Detect when faces have been changed outside customize.
340 * Enable mouse help in Emacs by default.
342 * Add an easy way to display the standard settings when an item is
345 * See if it is feasible to scan files for customization information
346 instead of loading them,
348 * Add hint message when user push a non-pushable tag.
350 Suggest that the user unhide if hidden, and edit the value directly
353 * Use checkboxes and radio buttons in the state menus.
355 * Add option to hide `[hide]' for short options. Default, on.
357 * Add option to hide `[state]' for options with their standard
360 * There should be a way to specify site defaults for user options.
362 * There should be more buffer styles. The default `nested style,
363 the old `outline' style, a `numeric' style with numbers instead of
364 stars, an `empty' style with just the group name, and `compact'
365 with only one line per item.
367 * Newline and tab should be displayed as `^J' and `^I' in the
368 `regexp' and `file' widgets. I think this can be done in XEmacs
369 by adding a display table to the face.
371 * Use glyphs to draw the `customize-browse' tree.
373 Add echo and balloon help. You should be able to read the
374 documentation simply by moving the mouse pointer above the name.
384 Node: Declaring Groups
\7f1651
385 Node: Declaring Variables
\7f2752
386 Node: Declaring Faces
\7f5843
387 Node: Usage for Package Authors
\7f7541
388 Node: Utilities
\7f8320
389 Node: The Init File
\7f9404
390 Node: Wishlist
\7f9856