Mercurial > hg > xemacs-beta

comparison man/custom.texi @ 422:95016f13131a r21-2-19

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-19
author cvs
date Mon, 13 Aug 2007 11:25:01 +0200
parents da8ed4261e83
children
comparison
equal deleted inserted replaced
421:fff06e11db74 422:95016f13131a
1 \input texinfo.tex 1 \input texinfo.tex
2 2
3 @c %**start of header 3 @c %**start of header
4 @setfilename ../info/custom 4 @setfilename ../info/custom.info
5 @settitle The Customization Library 5 @settitle The Customization Library
6 @iftex 6 @iftex
7 @afourpaper 7 @afourpaper
8 @headings double 8 @headings double
9 @end iftex 9 @end iftex
23 This manual describes how to declare customization groups, variables, 23 This manual describes how to declare customization groups, variables,
24 and faces. It doesn't contain any examples, but please look at the file 24 and faces. It doesn't contain any examples, but please look at the file
25 @file{cus-edit.el} which contains many declarations you can learn from. 25 @file{cus-edit.el} which contains many declarations you can learn from.
26 26
27 @menu 27 @menu
28 * Declaring Groups:: 28 * Declaring Groups::
29 * Declaring Variables:: 29 * Declaring Variables::
30 * Declaring Faces:: 30 * Declaring Faces::
31 * Usage for Package Authors:: 31 * Usage for Package Authors::
32 * Utilities:: 32 * Utilities::
33 * The Init File:: 33 * The Init File::
34 * Wishlist:: 34 * Wishlist::
35 @end menu 35 @end menu
36 36
37 All the customization declarations can be changes by keyword arguments. 37 All the customization declarations can be changes by keyword arguments.
38 Groups, variables, and faces all share these common keywords: 38 Groups, variables, and faces all share these common keywords:
39 39
40 @table @code 40 @table @code
41 @item :group 41 @item :group
42 @var{value} should be a customization group. 42 @var{value} should be a customization group.
43 Add @var{symbol} to that group. 43 Add @var{symbol} to that group.
44 @item :link 44 @item :link
45 @var{value} should be a widget type. 45 @var{value} should be a widget type.
46 Add @var{value} to the external links for this customization option. 46 Add @var{value} to the external links for this customization option.
47 Useful widget types include @code{custom-manual}, @code{info-link}, and 47 Useful widget types include @code{custom-manual}, @code{info-link}, and
48 @code{url-link}. 48 @code{url-link}.
49 @item :load 49 @item :load
50 Add @var{value} to the files that should be loaded before displaying 50 Add @var{value} to the files that should be loaded before displaying
51 this customization option. The value should be either a string, which 51 this customization option. The value should be either a string, which
52 should be a string which will be loaded with @code{load-library} unless 52 should be a string which will be loaded with @code{load-library} unless
53 present in @code{load-history}, or a symbol which will be loaded with 53 present in @code{load-history}, or a symbol which will be loaded with
54 @code{require}. 54 @code{require}.
55 @item :tag 55 @item :tag
56 @var{Value} should be a short string used for identifying the option in 56 @var{Value} should be a short string used for identifying the option in
57 customization menus and buffers. By default the tag will be 57 customization menus and buffers. By default the tag will be
58 automatically created from the options name. 58 automatically created from the options name.
59 @end table 59 @end table
60 60
61 @node Declaring Groups, Declaring Variables, Top, Top 61 @node Declaring Groups, Declaring Variables, Top, Top
62 @comment node-name, next, previous, up 62 @comment node-name, next, previous, up
63 @section Declaring Groups 63 @section Declaring Groups
64 64
65 Use @code{defgroup} to declare new customization groups. 65 Use @code{defgroup} to declare new customization groups.
66 66
67 @defun defgroup symbol members doc [keyword value]... 67 @defun defgroup symbol members doc [keyword value]...
68 Declare @var{symbol} as a customization group containing @var{members}. 68 Declare @var{symbol} as a customization group containing @var{members}.
69 @var{symbol} does not need to be quoted. 69 @var{symbol} does not need to be quoted.
70 70
71 @var{doc} is the group documentation. 71 @var{doc} is the group documentation.
72 72
73 @var{members} should be an alist of the form ((@var{name} 73 @var{members} should be an alist of the form ((@var{name}
76 @code{custom-variable} for editing variables, @code{custom-face} for 76 @code{custom-variable} for editing variables, @code{custom-face} for
77 editing faces, and @code{custom-group} for editing groups.@refill 77 editing faces, and @code{custom-group} for editing groups.@refill
78 78
79 Internally, custom uses the symbol property @code{custom-group} to keep 79 Internally, custom uses the symbol property @code{custom-group} to keep
80 track of the group members, and @code{group-documentation} for the 80 track of the group members, and @code{group-documentation} for the
81 documentation string. 81 documentation string.
82 82
83 The following additional @var{keyword}'s are defined: 83 The following additional @var{keyword}'s are defined:
84 84
85 @table @code 85 @table @code
86 @item :prefix 86 @item :prefix
104 @var{doc} is the variable documentation. 104 @var{doc} is the variable documentation.
105 105
106 The following additional @var{keyword}'s are defined: 106 The following additional @var{keyword}'s are defined:
107 107
108 @table @code 108 @table @code
109 @item :type 109 @item :type
110 @var{value} should be a widget type. 110 @var{value} should be a widget type.
111 111
112 @item :options 112 @item :options
113 @var{value} should be a list of possible members of the specified type. 113 @var{value} should be a list of possible members of the specified type.
114 For hooks, this is a list of function names. 114 For hooks, this is a list of function names.
120 120
121 @table @code 121 @table @code
122 @item custom-initialize-set 122 @item custom-initialize-set
123 Use the @code{:set} method to initialize the variable. Do not 123 Use the @code{:set} method to initialize the variable. Do not
124 initialize it if already bound. This is the default @code{:initialize} 124 initialize it if already bound. This is the default @code{:initialize}
125 method. 125 method.
126 126
127 @item custom-initialize-default 127 @item custom-initialize-default
128 Always use @code{set-default} to initialize the variable, even if a 128 Always use @code{set-default} to initialize the variable, even if a
129 @code{:set} method has been specified. 129 @code{:set} method has been specified.
130 130
133 method with the value returned by the @code{:get} method. 133 method with the value returned by the @code{:get} method.
134 134
135 @item custom-initialize-changed 135 @item custom-initialize-changed
136 Like @code{custom-initialize-reset}, but use @code{set-default} to 136 Like @code{custom-initialize-reset}, but use @code{set-default} to
137 initialize the variable if it is not bound and has not been set 137 initialize the variable if it is not bound and has not been set
138 already. 138 already.
139 @end table 139 @end table
140 140
141 @item :set 141 @item :set
142 @var{value} should be a function to set the value of the symbol. It 142 @var{value} should be a function to set the value of the symbol. It
143 takes two arguments, the symbol to set and the value to give it. The 143 takes two arguments, the symbol to set and the value to give it. The
144 default is @code{set-default}. 144 default is @code{set-default}.
145 145
146 @item :get 146 @item :get
149 value for that symbol. The default is @code{default-value}. 149 value for that symbol. The default is @code{default-value}.
150 150
151 @item :require 151 @item :require
152 @var{value} should be a feature symbol. Each feature will be required 152 @var{value} should be a feature symbol. Each feature will be required
153 when the `defcustom' is evaluated, or when Emacs is started if the user 153 when the `defcustom' is evaluated, or when Emacs is started if the user
154 has saved this option. 154 has saved this option.
155 155
156 @end table 156 @end table
157 157
158 @xref{Sexp Types,,,widget,The Widget Library}, for information about 158 @xref{Sexp Types,,,widget,The Widget Library}, for information about
159 widgets to use together with the @code{:type} keyword. 159 widgets to use together with the @code{:type} keyword.
178 @comment node-name, next, previous, up 178 @comment node-name, next, previous, up
179 @section Declaring Faces 179 @section Declaring Faces
180 180
181 Faces are declared with @code{defface}. 181 Faces are declared with @code{defface}.
182 182
183 @defun defface face spec doc [keyword value]... 183 @defun defface face spec doc [keyword value]...
184 184
185 Declare @var{face} as a customizable face that defaults to @var{spec}. 185 Declare @var{face} as a customizable face that defaults to @var{spec}.
186 @var{face} does not need to be quoted. 186 @var{face} does not need to be quoted.
187 187
188 If @var{face} has been set with `custom-set-face', set the face attributes 188 If @var{face} has been set with `custom-set-face', set the face attributes
216 216
217 @item background 217 @item background
218 (what color is used for the background text)@* 218 (what color is used for the background text)@*
219 Should be one of @code{light} or @code{dark}. 219 Should be one of @code{light} or @code{dark}.
220 @end table 220 @end table
221 221
222 Internally, custom uses the symbol property @code{face-defface-spec} for 222 Internally, custom uses the symbol property @code{face-defface-spec} for
223 the program specified default face properties, @code{saved-face} for 223 the program specified default face properties, @code{saved-face} for
224 properties saved by the user, and @code{face-documentation} for the 224 properties saved by the user, and @code{face-documentation} for the
225 documentation string.@refill 225 documentation string.@refill
226 226
238 238
239 The top level group for the package should itself be member of one or 239 The top level group for the package should itself be member of one or
240 more of the standard customization groups. There exists a group for 240 more of the standard customization groups. There exists a group for
241 each @emph{finder} keyword. Press @kbd{C-h p} to see a list of finder 241 each @emph{finder} keyword. Press @kbd{C-h p} to see a list of finder
242 keywords, and add you group to each of them, using the @code{:group} 242 keywords, and add you group to each of them, using the @code{:group}
243 keyword. 243 keyword.
244 244
245 @node Utilities, The Init File, Usage for Package Authors, Top 245 @node Utilities, The Init File, Usage for Package Authors, Top
246 @comment node-name, next, previous, up 246 @comment node-name, next, previous, up
247 @section Utilities 247 @section Utilities
248 248
249 These utilities can come in handy when adding customization support. 249 These utilities can come in handy when adding customization support.
250 250
251 @deffn Widget custom-manual 251 @deffn Widget custom-manual
252 Widget type for specifying the info manual entry for a customization 252 Widget type for specifying the info manual entry for a customization
253 option. It takes one argument, an info address. 253 option. It takes one argument, an info address.
254 @end deffn 254 @end deffn
267 @var{load} should be either a library file name, or a feature name. 267 @var{load} should be either a library file name, or a feature name.
268 @end defun 268 @end defun
269 269
270 @defun customize-menu-create symbol &optional name 270 @defun customize-menu-create symbol &optional name
271 Create menu for customization group @var{symbol}. 271 Create menu for customization group @var{symbol}.
272 If optional @var{name} is given, use that as the name of the menu. 272 If optional @var{name} is given, use that as the name of the menu.
273 Otherwise the menu will be named `Customize'. 273 Otherwise the menu will be named `Customize'.
274 The menu is in a format applicable to @code{easy-menu-define}. 274 The menu is in a format applicable to @code{easy-menu-define}.
275 @end defun 275 @end defun
276 276
277 @node The Init File, Wishlist, Utilities, Top 277 @node The Init File, Wishlist, Utilities, Top
288 @node Wishlist, , The Init File, Top 288 @node Wishlist, , The Init File, Top
289 @comment node-name, next, previous, up 289 @comment node-name, next, previous, up
290 @section Wishlist 290 @section Wishlist
291 291
292 @itemize @bullet 292 @itemize @bullet
293 @item 293 @item
294 Better support for keyboard operations in the customize buffer. 294 Better support for keyboard operations in the customize buffer.
295 295
296 @item 296 @item
297 Integrate with @file{w3} so you can get customization buffers with much 297 Integrate with @file{w3} so you can get customization buffers with much
298 better formatting. I'm thinking about adding a <custom>name</custom> 298 better formatting. I'm thinking about adding a <custom>name</custom>
299 tag. The latest w3 have some support for this, so come up with a 299 tag. The latest w3 have some support for this, so come up with a
300 convincing example. 300 convincing example.
301 301
302 @item 302 @item
303 Add an `examples' section, with explained examples of custom type 303 Add an `examples' section, with explained examples of custom type
304 definitions. 304 definitions.
305 305
306 @item 306 @item
307 Support selectable color themes. I.e., change many faces by setting one 307 Support selectable color themes. I.e., change many faces by setting one
308 variable. 308 variable.
309 309
314 @item 314 @item
315 Make it possible to append to `choice', `radio', and `set' options. 315 Make it possible to append to `choice', `radio', and `set' options.
316 316
317 @item 317 @item
318 Ask whether set or modified variables should be saved in 318 Ask whether set or modified variables should be saved in
319 @code{kill-buffer-hook}. 319 @code{kill-buffer-hook}.
320 320
321 Ditto for @code{kill-emacs-query-functions}. 321 Ditto for @code{kill-emacs-query-functions}.
322 322
323 @item 323 @item
324 Command to check if there are any customization options that 324 Command to check if there are any customization options that
325 does not belong to an existing group. 325 does not belong to an existing group.
326 326
327 @item 327 @item
328 Optionally disable the point-cursor and instead highlight the selected 328 Optionally disable the point-cursor and instead highlight the selected
329 item in XEmacs. This is like the *Completions* buffer in XEmacs. 329 item in XEmacs. This is like the *Completions* buffer in XEmacs.
330 Suggested by Jens Lautenbacher 330 Suggested by Jens Lautenbacher
333 @item 333 @item
334 Explain why it is necessary that all choices have different default 334 Explain why it is necessary that all choices have different default
335 values. 335 values.
336 336
337 @item 337 @item
338 Make it possible to include a comment/remark/annotation when saving an
339 option.
340
341 @item
342 Add some direct support for meta variables, i.e. make it possible to 338 Add some direct support for meta variables, i.e. make it possible to
343 specify that this variable should be reset when that variable is 339 specify that this variable should be reset when that variable is
344 changed. 340 changed.
345 341
346 @item 342 @item
347 Add tutorial. 343 Add tutorial.
348 344
349 @item 345 @item
380 @item 376 @item
381 Add an easy way to display the standard settings when an item is modified. 377 Add an easy way to display the standard settings when an item is modified.
382 378
383 @item 379 @item
384 See if it is feasible to scan files for customization information 380 See if it is feasible to scan files for customization information
385 instead of loading them, 381 instead of loading them,
386 382
387 @item 383 @item
388 Add hint message when user push a non-pushable tag. 384 Add hint message when user push a non-pushable tag.
389 385
390 Suggest that the user unhide if hidden, and edit the value directly 386 Suggest that the user unhide if hidden, and edit the value directly
394 Use checkboxes and radio buttons in the state menus. 390 Use checkboxes and radio buttons in the state menus.
395 391
396 @item 392 @item
397 Add option to hide @samp{[hide]} for short options. Default, on. 393 Add option to hide @samp{[hide]} for short options. Default, on.
398 394
399 @item 395 @item
400 Add option to hide @samp{[state]} for options with their standard 396 Add option to hide @samp{[state]} for options with their standard
401 settings. 397 settings.
402 398
403 @item 399 @item
404 There should be a way to specify site defaults for user options. 400 There should be a way to specify site defaults for user options.
405 401
406 @item 402 @item
407 There should be more buffer styles. The default `nested style, the old 403 There should be more buffer styles. The default `nested style, the old
408 `outline' style, a `numeric' style with numbers instead of stars, an 404 `outline' style, a `numeric' style with numbers instead of stars, an