git.chise.org Git - chise/xemacs-chise.git.1/blob - info/custom.info

   1 This is ../info/custom.info, produced by makeinfo version 4.0 from
   2 custom.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Customizations: (custom).     Customization Library.
   7 END-INFO-DIR-ENTRY
   8
   9 \1f
  10 File: custom.info,  Node: Top,  Next: Declaring Groups,  Prev: (dir),  Up: (dir)
  11
  12 The Customization Library
  13 *************************
  14
  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.
  18
  19 * Menu:
  20
  21 * Declaring Groups::
  22 * Declaring Variables::
  23 * Declaring Faces::
  24 * Usage for Package Authors::
  25 * Utilities::
  26 * The Init File::
  27 * Wishlist::
  28
  29    All the customization declarations can be changes by keyword
  30 arguments.  Groups, variables, and faces all share these common
  31 keywords:
  32
  33 `:group'
  34      VALUE should be a customization group.  Add SYMBOL to that group.
  35
  36 `:link'
  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'.
  40
  41 `:load'
  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
  46      with `require'.
  47
  48 `:tag'
  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.
  52
  53 \1f
  54 File: custom.info,  Node: Declaring Groups,  Next: Declaring Variables,  Prev: Top,  Up: Top
  55
  56 Declaring Groups
  57 ================
  58
  59    Use `defgroup' to declare new customization groups.
  60
  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.
  64
  65      DOC is the group documentation.
  66
  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
  71      groups.
  72
  73      Internally, custom uses the symbol property `custom-group' to keep
  74      track of the group members, and `group-documentation' for the
  75      documentation string.
  76
  77      The following additional KEYWORD's are defined:
  78
  79     `:prefix'
  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.
  83
  84 \1f
  85 File: custom.info,  Node: Declaring Variables,  Next: Declaring Faces,  Prev: Declaring Groups,  Up: Top
  86
  87 Declaring Variables
  88 ===================
  89
  90    Use `defcustom' to declare user editable variables.
  91
  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.
  96
  97      DOC is the variable documentation.
  98
  99      The following additional KEYWORD's are defined:
 100
 101     `:type'
 102           VALUE should be a widget type.
 103
 104     `:options'
 105           VALUE should be a list of possible members of the specified
 106           type.  For hooks, this is a list of function names.
 107
 108     `:initialize'
 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:
 112
 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.
 117
 118          `custom-initialize-default'
 119                Always use `set-default' to initialize the variable,
 120                even if a `:set' method has been specified.
 121
 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'
 125                method.
 126
 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
 130                been set already.
 131
 132     `:set'
 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'.
 136
 137     `:get'
 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
 141           `default-value'.
 142
 143     `:require'
 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.
 147
 148      *Note Sexp Types: (widget)Sexp Types, for information about
 149      widgets to use together with the `:type' keyword.
 150
 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.
 155
 156    Use `custom-add-option' to specify that a specific function is
 157 useful as an member of a hook.
 158
 159  - Function: custom-add-option symbol option
 160      To the variable SYMBOL add OPTION.
 161
 162      If SYMBOL is a hook variable, OPTION should be a hook member.  For
 163      other types variables, the effect is undefined."
 164
 165 \1f
 166 File: custom.info,  Node: Declaring Faces,  Next: Usage for Package Authors,  Prev: Declaring Variables,  Up: Top
 167
 168 Declaring Faces
 169 ===============
 170
 171    Faces are declared with `defface'.
 172
 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.
 176
 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.
 180
 181      DOC is the face documentation.
 182
 183      SPEC should be an alist of the form `((DISPLAY ATTS)...)'.
 184
 185      ATTS is a list of face attributes and their values.  The possible
 186      attributes are defined in the variable `custom-face-attributes'.
 187
 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
 191      `((REQ ITEM...)...)'
 192
 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:
 195
 196     `type'
 197           (the value of (window-system))
 198           Should be one of `x' or `tty'.
 199
 200     `class'
 201           (the frame's color support)
 202           Should be one of `color', `grayscale', or `mono'.
 203
 204     `background'
 205           (what color is used for the background text)
 206           Should be one of `light' or `dark'.
 207
 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.
 212
 213
 214 \1f
 215 File: custom.info,  Node: Usage for Package Authors,  Next: Utilities,  Prev: Declaring Faces,  Up: Top
 216
 217 Usage for Package Authors
 218 =========================
 219
 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.
 225
 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.
 230
 231 \1f
 232 File: custom.info,  Node: Utilities,  Next: The Init File,  Prev: Usage for Package Authors,  Up: Top
 233
 234 Utilities
 235 =========
 236
 237    These utilities can come in handy when adding customization support.
 238
 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.
 242
 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.
 246
 247  - Function: custom-add-link symbol widget
 248      To the custom option SYMBOL add the link WIDGET.
 249
 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.
 253
 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
 258      `easy-menu-define'.
 259
 260 \1f
 261 File: custom.info,  Node: The Init File,  Next: Wishlist,  Prev: Utilities,  Up: Top
 262
 263 The Init File
 264 =============
 265
 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.
 271
 272 \1f
 273 File: custom.info,  Node: Wishlist,  Prev: The Init File,  Up: Top
 274
 275 Wishlist
 276 ========
 277
 278    * Better support for keyboard operations in the customize buffer.
 279
 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.
 284
 285    * Add an `examples' section, with explained examples of custom type
 286      definitions.
 287
 288    * Support selectable color themes.  I.e., change many faces by
 289      setting one variable.
 290
 291    * Support undo using lmi's `gnus-undo.el'.
 292
 293    * Make it possible to append to `choice', `radio', and `set' options.
 294
 295    * Ask whether set or modified variables should be saved in
 296      `kill-buffer-hook'.
 297
 298      Ditto for `kill-emacs-query-functions'.
 299
 300    * Command to check if there are any customization options that does
 301      not belong to an existing group.
 302
 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>'.
 307
 308    * Explain why it is necessary that all choices have different default
 309      values.
 310
 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
 313      changed.
 314
 315    * Add tutorial.
 316
 317    * Describe the `:type' syntax in this manual.
 318
 319    * Find a place is this manual for the following text:
 320
 321      *Radio vs. Buttons*
 322
 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.
 327
 328      Avoid radios if some of the items expands to complex structures.
 329
 330      I mostly use radios when most of the items are of type
 331      `function-item' or `variable-item'.
 332
 333    * Update customize buffers when `custom-set-variable' or
 334      `custom-save-customized' is called.
 335
 336    * Better handling of saved but uninitialized items.
 337
 338    * Detect when faces have been changed outside customize.
 339
 340    * Enable mouse help in Emacs by default.
 341
 342    * Add an easy way to display the standard settings when an item is
 343      modified.
 344
 345    * See if it is feasible to scan files for customization information
 346      instead of loading them,
 347
 348    * Add hint message when user push a non-pushable tag.
 349
 350      Suggest that the user unhide if hidden, and edit the value directly
 351      otherwise.
 352
 353    * Use checkboxes and radio buttons in the state menus.
 354
 355    * Add option to hide `[hide]' for short options.  Default, on.
 356
 357    * Add option to hide `[state]' for options with their standard
 358      settings.
 359
 360    * There should be a way to specify site defaults for user options.
 361
 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.
 366
 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.
 370
 371    * Use glyphs to draw the `customize-browse' tree.
 372
 373      Add echo and balloon help.  You should be able to read the
 374      documentation simply by moving the mouse pointer above the name.
 375
 376      Add parent links.
 377
 378      Add colors.
 379
 380
 381
 382 \1f
 383 Tag Table:
 384 Node: Top\7f204
 385 Node: Declaring Groups\7f1625
 386 Node: Declaring Variables\7f2726
 387 Node: Declaring Faces\7f5817
 388 Node: Usage for Package Authors\7f7515
 389 Node: Utilities\7f8294
 390 Node: The Init File\7f9378
 391 Node: Wishlist\7f9830
 392 \1f
 393 End Tag Table