Source

xemacs-beta / man / custom.texi

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
\input texinfo.tex

@c %**start of header
@setfilename ../info/custom
@settitle The Customization Library
@iftex
@afourpaper
@headings double
@end iftex
@c %**end of header

@node Top, Declaring Groups, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top The Customization Library

This manual describes how to declare customization groups, variables,
and faces.  It doesn't contain any examples, but please look at the file
@file{cus-edit.el} which contains many declarations you can learn from.

@menu
* Declaring Groups::            
* Declaring Variables::         
* Declaring Faces::             
* Usage for Package Authors::   
* Utilities::                   
* The Init File::               
* Wishlist::                    
@end menu

All the customization declarations can be changes by keyword arguments.
Groups, variables, and faces all share these common keywords:

@table @code
@item :group
@var{value} should be a customization group. 
Add @var{symbol} to that group. 
@item :link
@var{value} should be a widget type. 
Add @var{value} to the external links for this customization option.
Useful widget types include @code{custom-manual}, @code{info-link}, and
@code{url-link}. 
@item :load
Add @var{value} to the files that should be loaded before displaying
this customization option.  The value should be either a string, which
should be a string which will be loaded with @code{load-library} unless
present in @code{load-history}, or a symbol which will be loaded with
@code{require}. 
@item :tag
@var{Value} should be a short string used for identifying the option in
customization menus and buffers.  By default the tag will be
automatically created from the options name.
@end table

@node Declaring Groups, Declaring Variables, Top, Top
@comment  node-name,  next,  previous,  up
@section Declaring Groups

Use @code{defgroup} to declare new customization groups. 

@defun defgroup symbol members doc [keyword value]...
Declare @var{symbol} as a customization group containing @var{members}. 
@var{symbol} does not need to be quoted.

@var{doc} is the group documentation.

@var{members} should be an alist of the form ((@var{name}
@var{widget})...) where @var{name} is a symbol and @var{widget} is a
widget for editing that symbol.  Useful widgets are
@code{custom-variable} for editing variables, @code{custom-face} for
editing faces, and @code{custom-group} for editing groups.@refill

Internally, custom uses the symbol property @code{custom-group} to keep
track of the group members, and @code{group-documentation} for the
documentation string. 

The following additional @var{keyword}'s are defined:

@table @code
@item :prefix
@var{value} should be a string.  If the string is a prefix for the name
of a member of the group, that prefix will be ignored when creating a
tag for that member.
@end table
@end defun

@node Declaring Variables, Declaring Faces, Declaring Groups, Top
@comment  node-name,  next,  previous,  up
@section Declaring Variables

Use @code{defcustom} to declare user editable variables.

@defun defcustom symbol value doc [keyword value]...
Declare @var{symbol} as a customizable variable that defaults to @var{value}.
Neither @var{symbol} nor @var{value} needs to be quoted.
If @var{symbol} is not already bound, initialize it to @var{value}.

@var{doc} is the variable documentation.

The following additional @var{keyword}'s are defined:

@table @code
@item :type     
@var{value} should be a widget type.

@item :options
@var{value} should be a list of possible members of the specified type.
For hooks, this is a list of function names.

@item :initialize
@var{value} should be a function used to initialize the variable.  It
takes two arguments, the symbol and value given in the @code{defcustom} call.
Some predefined functions are:

@table @code
@item custom-initialize-set
Use the @code{:set} method to initialize the variable.  Do not
initialize it if already bound.  This is the default @code{:initialize}
method. 

@item custom-initialize-default
Always use @code{set-default} to initialize the variable, even if a
@code{:set} method has been specified.

@item custom-initialize-reset
If the variable is already bound, reset it by calling the @code{:set}
method with the value returned by the @code{:get} method.

@item custom-initialize-changed
Like @code{custom-initialize-reset}, but use @code{set-default} to
initialize the variable if it is not bound and has not been set
already. 
@end table

@item :set 
@var{value} should be a function to set the value of the symbol.  It
takes two arguments, the symbol to set and the value to give it.  The
default is @code{set-default}.

@item :get
@var{value} should be a function to extract the value of symbol.  The
function takes one argument, a symbol, and should return the current
value for that symbol.  The default is @code{default-value}.

@item :require
@var{value} should be a feature symbol.  Each feature will be required
when the `defcustom' is evaluated, or when Emacs is started if the user
has saved this option. 

@end table

@xref{Sexp Types,,,widget,The Widget Library}, for information about
widgets to use together with the @code{:type} keyword.
@end defun

Internally, custom uses the symbol property @code{custom-type} to keep
track of the variables type, @code{standard-value} for the program
specified default value, @code{saved-value} for a value saved by the
user, and @code{variable-documentation} for the documentation string.

Use @code{custom-add-option} to specify that a specific function is
useful as an member of a hook.

@defun custom-add-option symbol option
To the variable @var{symbol} add @var{option}.

If @var{symbol} is a hook variable, @var{option} should be a hook
member.  For other types variables, the effect is undefined."
@end defun

@node Declaring Faces, Usage for Package Authors, Declaring Variables, Top
@comment  node-name,  next,  previous,  up
@section Declaring Faces

Faces are declared with @code{defface}.

@defun defface face spec doc [keyword value]... 

Declare @var{face} as a customizable face that defaults to @var{spec}.
@var{face} does not need to be quoted.

If @var{face} has been set with `custom-set-face', set the face attributes
as specified by that function, otherwise set the face attributes
according to @var{spec}.

@var{doc} is the face documentation.

@var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.

@var{atts} is a list of face attributes and their values.  The possible
attributes are defined in the variable `custom-face-attributes'.

The @var{atts} of the first entry in @var{spec} where the @var{display}
matches the frame should take effect in that frame.  @var{display} can
either be the symbol `t', which will match all frames, or an alist of
the form @samp{((@var{req} @var{item}...)...)}@refill

For the @var{display} to match a FRAME, the @var{req} property of the
frame must match one of the @var{item}.  The following @var{req} are
defined:@refill

@table @code
@item type
(the value of (window-system))@*
Should be one of @code{x} or @code{tty}.

@item class
(the frame's color support)@*
Should be one of @code{color}, @code{grayscale}, or @code{mono}.

@item background
(what color is used for the background text)@*
Should be one of @code{light} or @code{dark}.
@end table
  
Internally, custom uses the symbol property @code{face-defface-spec} for
the program specified default face properties, @code{saved-face} for
properties saved by the user, and @code{face-documentation} for the
documentation string.@refill

@end defun

@node Usage for Package Authors, Utilities, Declaring Faces, Top
@comment  node-name,  next,  previous,  up
@section Usage for Package Authors

The recommended usage for the author of a typical emacs lisp package is
to create one group identifying the package, and make all user options
and faces members of that group.  If the package has more than around 20
such options, they should be divided into a number of subgroups, with
each subgroup being member of the top level group.

The top level group for the package should itself be member of one or
more of the standard customization groups.  There exists a group for
each @emph{finder} keyword.  Press @kbd{C-h p} to see a list of finder
keywords, and add you group to each of them, using the @code{:group}
keyword. 

@node  Utilities, The Init File, Usage for Package Authors, Top
@comment  node-name,  next,  previous,  up
@section Utilities

These utilities can come in handy when adding customization support. 

@deffn Widget custom-manual
Widget type for specifying the info manual entry for a customization
option.  It takes one argument, an info address.
@end deffn

@defun custom-add-to-group group member widget
To existing @var{group} add a new @var{member} of type @var{widget},
If there already is an entry for that member, overwrite it.
@end defun

@defun custom-add-link symbol widget
To the custom option @var{symbol} add the link @var{widget}.
@end defun

@defun custom-add-load symbol load
To the custom option @var{symbol} add the dependency @var{load}.
@var{load} should be either a library file name, or a feature name.
@end defun

@defun customize-menu-create symbol &optional name
Create menu for customization group @var{symbol}.
If optional @var{name} is given, use that as the name of the menu. 
Otherwise the menu will be named `Customize'.
The menu is in a format applicable to @code{easy-menu-define}.
@end defun

@node The Init File, Wishlist, Utilities, Top
@comment  node-name,  next,  previous,  up
@section The Init File

When you save the customizations, call to @code{custom-set-variables},
@code{custom-set-faces} are inserted into the file specified by
@code{custom-file}.  By default @code{custom-file} is your @file{.emacs}
file.  If you use another file, you must explicitly load it yourself.
The two functions will initialize variables and faces as you have
specified.

@node Wishlist,  , The Init File, Top
@comment  node-name,  next,  previous,  up
@section Wishlist

@itemize @bullet
@item 
Better support for keyboard operations in the customize buffer.

@item
Integrate with @file{w3} so you can get customization buffers with much
better formatting.  I'm thinking about adding a <custom>name</custom>
tag.  The latest w3 have some support for this, so come up with a
convincing example.

@item
Add an `examples' section, with explained examples of custom type
definitions. 

@item
Support selectable color themes.  I.e., change many faces by setting one
variable.

@item
Support undo using lmi's @file{gnus-undo.el}.


@item
Make it possible to append to `choice', `radio', and `set' options.

@item
Ask whether set or modified variables should be saved in
@code{kill-buffer-hook}. 

Ditto for @code{kill-emacs-query-functions}.

@item
Command to check if there are any customization options that
does not belong to an existing group. 

@item
Optionally disable the point-cursor and instead highlight the selected
item in XEmacs.  This is like the *Completions* buffer in XEmacs.
Suggested by Jens Lautenbacher
@samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill

@item
Explain why it is necessary that all choices have different default
values.

@item
Make it possible to include a comment/remark/annotation when saving an
option.

@item
Add some direct support for meta variables, i.e. make it possible to
specify that this variable should be reset when that variable is
changed. 

@item
Add tutorial.

@item
Describe the @code{:type} syntax in this manual.

@item
Find a place is this manual for the following text:

@strong{Radio vs. Buttons}

Use a radio if you can't find a good way to describe the item in the
choice menu text.  I.e. it is better to use a radio if you expect the
user would otherwise manually select each item from the choice menu in
turn to see what it expands too.

Avoid radios if some of the items expands to complex structures.

I mostly use radios when most of the items are of type
@code{function-item} or @code{variable-item}.

@item
Update customize buffers when @code{custom-set-variable} or
@code{custom-save-customized} is called.

@item
Better handling of saved but uninitialized items.

@item
Detect when faces have been changed outside customize.

@item
Enable mouse help in Emacs by default.

@item
Add an easy way to display the standard settings when an item is modified.

@item
See if it is feasible to scan files for customization information
instead of loading them, 

@item
Add hint message when user push a non-pushable tag.

Suggest that the user unhide if hidden, and edit the value directly
otherwise.

@item
Use checkboxes and radio buttons in the state menus.

@item
Add option to hide @samp{[hide]} for short options.  Default, on.

@item 
Add option to hide @samp{[state]} for options with their standard
settings.

@item 
There should be a way to specify site defaults for user options.

@item
There should be more buffer styles.  The default `nested style, the old
`outline' style, a `numeric' style with numbers instead of stars, an
`empty' style with just the group name, and `compact' with only one line
per item.

@item
Newline and tab should be displayed as @samp{^J} and @samp{^I} in the
@code{regexp} and @code{file} widgets.  I think this can be done in
XEmacs by adding a display table to the face.

@item
Use glyphs to draw the @code{customize-browse} tree.

Add echo and balloon help.  You should be able to read the documentation
simply by moving the mouse pointer above the name.

Add parent links.

Add colors.

@end itemize

@contents
@bye
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.