[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to customize.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to customize.texi |
|
Date: |
Thu, 06 Sep 2007 04:10:18 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:10:18
Index: customize.texi
===================================================================
RCS file: customize.texi
diff -N customize.texi
--- customize.texi 7 Apr 2007 02:04:36 -0000 1.69
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,1253 +0,0 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
address@hidden 2005, 2006, 2007 Free Software Foundation, Inc.
address@hidden See the file elisp.texi for copying conditions.
address@hidden ../info/customize
address@hidden Customization, Loading, Macros, Top
address@hidden Writing Customization Definitions
-
address@hidden customization definitions
- This chapter describes how to declare user options for customization,
-and also customization groups for classifying them. We use the term
address@hidden item} to include both kinds of customization
-definitions---as well as face definitions (@pxref{Defining Faces}).
-
address@hidden
-* Common Keywords:: Common keyword arguments for all kinds of
- customization declarations.
-* Group Definitions:: Writing customization group definitions.
-* Variable Definitions:: Declaring user options.
-* Customization Types:: Specifying the type of a user option.
address@hidden menu
-
address@hidden Common Keywords
address@hidden Common Item Keywords
-
address@hidden customization keywords
- All kinds of customization declarations (for variables and groups, and
-for faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all kinds.
-
- All of these keywords, except @code{:tag}, can be used more than once
-in a given item. Each use of the keyword has an independent effect.
-The keyword @code{:tag} is an exception because any given item can only
-display one name.
-
address@hidden @code
address@hidden :tag @var{label}
address@hidden address@hidden, customization keyword}
-Use @var{label}, a string, instead of the item's name, to label the
-item in customization menus and buffers. @strong{Don't use a tag
-which is substantially different from the item's real name; that would
-cause confusion.} One legitimate case for use of @code{:tag} is to
-specify a dash where normally a hyphen would be converted to a space:
-
address@hidden
-(defcustom cursor-in-non-selected-windows @dots{}
- :tag "Cursor In Non-selected Windows"
address@hidden example
-
address@hidden address@hidden, customization keyword}
address@hidden :group @var{group}
-Put this customization item in group @var{group}. When you use
address@hidden:group} in a @code{defgroup}, it makes the new group a subgroup of
address@hidden
-
-If you use this keyword more than once, you can put a single item into
-more than one group. Displaying any of those groups will show this
-item. Please don't overdo this, since the result would be annoying.
-
address@hidden :link @var{link-data}
address@hidden address@hidden, customization keyword}
-Include an external link after the documentation string for this item.
-This is a sentence containing an active field which references some
-other documentation.
-
-There are several alternatives you can use for @var{link-data}:
-
address@hidden @code
address@hidden (custom-manual @var{info-node})
-Link to an Info node; @var{info-node} is a string which specifies the
-node name, as in @code{"(emacs)Top"}. The link appears as
address@hidden in the customization buffer and enters the built-in
-Info reader on @var{info-node}.
-
address@hidden (info-link @var{info-node})
-Like @code{custom-manual} except that the link appears
-in the customization buffer with the Info node name.
-
address@hidden (url-link @var{url})
-Link to a web page; @var{url} is a string which specifies the
address@hidden The link appears in the customization buffer as
address@hidden and invokes the WWW browser specified by
address@hidden
-
address@hidden (emacs-commentary-link @var{library})
-Link to the commentary section of a library; @var{library} is a string
-which specifies the library name.
-
address@hidden (emacs-library-link @var{library})
-Link to an Emacs Lisp library file; @var{library} is a string which
-specifies the library name.
-
address@hidden (file-link @var{file})
-Link to a file; @var{file} is a string which specifies the name of the
-file to visit with @code{find-file} when the user invokes this link.
-
address@hidden (function-link @var{function})
-Link to the documentation of a function; @var{function} is a string
-which specifies the name of the function to describe with
address@hidden when the user invokes this link.
-
address@hidden (variable-link @var{variable})
-Link to the documentation of a variable; @var{variable} is a string
-which specifies the name of the variable to describe with
address@hidden when the user invokes this link.
-
address@hidden (custom-group-link @var{group})
-Link to another customization group. Invoking it creates a new
-customization buffer for @var{group}.
address@hidden table
-
-You can specify the text to use in the customization buffer by adding
address@hidden:tag @var{name}} after the first element of the @var{link-data};
-for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
-the Emacs manual which appears in the buffer as @samp{foo}.
-
-An item can have more than one external link; however, most items have
-none at all.
-
address@hidden :load @var{file}
address@hidden address@hidden, customization keyword}
-Load file @var{file} (a string) before displaying this customization
-item. Loading is done with @code{load-library}, and only if the file is
-not already loaded.
-
address@hidden :require @var{feature}
address@hidden address@hidden, customization keyword}
-Execute @code{(require '@var{feature})} when your saved customizations
-set the value of this item. @var{feature} should be a symbol.
-
-The most common reason to use @code{:require} is when a variable enables
-a feature such as a minor mode, and just setting the variable won't have
-any effect unless the code which implements the mode is loaded.
-
address@hidden :version @var{version}
address@hidden address@hidden, customization keyword}
-This keyword specifies that the item was first introduced in Emacs
-version @var{version}, or that its default value was changed in that
-version. The value @var{version} must be a string.
-
address@hidden :package-version '(@var{package} . @var{version})
address@hidden address@hidden, customization keyword}
-This keyword specifies that the item was first introduced in
address@hidden version @var{version}, or that its meaning or default
-value was changed in that version. The value of @var{package} is a
-symbol and @var{version} is a string.
-
-This keyword takes priority over @code{:version}.
-
address@hidden should be the official name of the package, such as MH-E
-or Gnus. If the package @var{package} is released as part of Emacs,
address@hidden and @var{version} should appear in the value of
address@hidden
address@hidden table
-
-Packages distributed as part of Emacs that use the
address@hidden:package-version} keyword must also update the
address@hidden variable.
-
address@hidden customize-package-emacs-version-alist
-This alist provides a mapping for the versions of Emacs that are
-associated with versions of a package listed in the
address@hidden:package-version} keyword. Its elements look like this:
-
address@hidden
-(@var{package} (@var{pversion} . @var{eversion})@dots{})
address@hidden example
-
-For each @var{package}, which is a symbol, there are one or more
-elements that contain a package version @var{pversion} with an
-associated Emacs version @var{eversion}. These versions are strings.
-For example, the MH-E package updates this alist with the following:
-
address@hidden
-(add-to-list 'customize-package-emacs-version-alist
- '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
- ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
- ("7.4" . "22.1") ("8.0" . "22.1")))
address@hidden smallexample
-
-The value of @var{package} needs to be unique and it needs to match
-the @var{package} value appearing in the @code{:package-version}
-keyword. Since the user might see the value in a error message, a good
-choice is the official name of the package, such as MH-E or Gnus.
address@hidden defvar
-
address@hidden Group Definitions
address@hidden Defining Customization Groups
address@hidden define customization group
address@hidden customization groups, defining
-
- Each Emacs Lisp package should have one main customization group which
-contains all the options, faces and other groups in the package. If the
-package has a small number of options and faces, use just one group and
-put everything in it. When there are more than twelve or so options and
-faces, then you should structure them into subgroups, and put the
-subgroups under the package's main customization group. It is OK to
-put some of the options and faces in the package's main group alongside
-the subgroups.
-
- The package's main or only group should be a member of one or more of
-the standard customization groups. (To display the full list of them,
-use @kbd{M-x customize}.) Choose one or more of them (but not too
-many), and add your group to each of them using the @code{:group}
-keyword.
-
- The way to declare new customization groups is with @code{defgroup}.
-
address@hidden defgroup group members doc [keyword address@hidden
-Declare @var{group} as a customization group containing @var{members}.
-Do not quote the symbol @var{group}. The argument @var{doc} specifies
-the documentation string for the group.
-
-The argument @var{members} is a list specifying an initial set of
-customization items to be members of the group. However, most often
address@hidden is @code{nil}, and you specify the group's members by
-using the @code{:group} keyword when defining those members.
-
-If you want to specify group members through @var{members}, each element
-should have the form @code{(@var{name} @var{widget})}. Here @var{name}
-is a symbol, and @var{widget} is a widget type for editing that symbol.
-Useful widgets are @code{custom-variable} for a variable,
address@hidden for a face, and @code{custom-group} for a group.
-
-When you introduce a new group into Emacs, use the @code{:version}
-keyword in the @code{defgroup}; then you need not use it for
-the individual members of the group.
-
-In addition to the common keywords (@pxref{Common Keywords}), you can
-also use this keyword in @code{defgroup}:
-
address@hidden @code
address@hidden :prefix @var{prefix}
address@hidden address@hidden, @code{defgroup} keyword}
-If the name of an item in the group starts with @var{prefix}, then the
-tag for that item is constructed (by default) by omitting @var{prefix}.
-
-One group can have any number of prefixes.
address@hidden table
address@hidden defmac
-
- The prefix-discarding feature is currently turned off, which means
-that @code{:prefix} currently has no effect. We did this because we
-found that discarding the specified prefixes often led to confusing
-names for options. This happened because the people who wrote the
address@hidden definitions for various groups added @code{:prefix}
-keywords whenever they make logical sense---that is, whenever the
-variables in the library have a common prefix.
-
- In order to obtain good results with @code{:prefix}, it would be
-necessary to check the specific effects of discarding a particular
-prefix, given the specific items in a group and their names and
-documentation. If the resulting text is not clear, then @code{:prefix}
-should not be used in that case.
-
- It should be possible to recheck all the customization groups, delete
-the @code{:prefix} specifications which give unclear results, and then
-turn this feature back on, if someone would like to do the work.
-
address@hidden Variable Definitions
address@hidden Defining Customization Variables
address@hidden define customization options
address@hidden customization variables, how to define
-
- Use @code{defcustom} to declare user-customizable variables.
-
address@hidden defcustom option standard doc [keyword address@hidden
-This construct declares @var{option} as a customizable user option
-variable. You should not quote @var{option}. The argument @var{doc}
-specifies the documentation string for the variable. There is no need
-to start it with a @samp{*}, because @code{defcustom} automatically
-marks @var{option} as a @dfn{user option} (@pxref{Defining
-Variables}).
-
-The argument @var{standard} is an expression that specifies the
-standard value for @var{option}. Evaluating the @code{defcustom} form
-evaluates @var{standard}, but does not necessarily install the
-standard value. If @var{option} already has a default value,
address@hidden does not change it. If the user has saved a
-customization for @var{option}, @code{defcustom} installs the user's
-customized value as @var{option}'s default value. If neither of those
-cases applies, @code{defcustom} installs the result of evaluating
address@hidden as the default value.
-
-The expression @var{standard} can be evaluated at various other times,
-too---whenever the customization facility needs to know @var{option}'s
-standard value. So be sure to use an expression which is harmless to
-evaluate at any time. We recommend avoiding backquotes in
address@hidden, because they are not expanded when editing the value,
-so list values will appear to have the wrong structure.
-
-Every @code{defcustom} should specify @code{:group} at least once.
-
-If you specify the @code{:set} keyword, to make the variable take other
-special actions when set through the customization buffer, the
-variable's documentation string should tell the user specifically how
-to do the same job in hand-written Lisp code.
-
-When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
-mode (@code{eval-defun}), a special feature of @code{eval-defun}
-arranges to set the variable unconditionally, without testing whether
-its value is void. (The same feature applies to @code{defvar}.)
address@hidden Variables}.
address@hidden defmac
-
- @code{defcustom} accepts the following additional keywords:
-
address@hidden @code
address@hidden :type @var{type}
-Use @var{type} as the data type for this option. It specifies which
-values are legitimate, and how to display the value.
address@hidden Types}, for more information.
-
address@hidden :options @var{value-list}
address@hidden address@hidden, @code{defcustom} keyword}
-Specify the list of reasonable values for use in this
-option. The user is not restricted to using only these values, but they
-are offered as convenient alternatives.
-
-This is meaningful only for certain types, currently including
address@hidden, @code{plist} and @code{alist}. See the definition of the
-individual types for a description of how to use @code{:options}.
-
address@hidden :set @var{setfunction}
address@hidden address@hidden, @code{defcustom} keyword}
-Specify @var{setfunction} as the way to change the value of this
-option. The function @var{setfunction} should take two arguments, a
-symbol (the option name) and the new value, and should do whatever is
-necessary to update the value properly for this option (which may not
-mean simply setting the option as a Lisp variable). The default for
address@hidden is @code{set-default}.
-
address@hidden :get @var{getfunction}
address@hidden address@hidden, @code{defcustom} keyword}
-Specify @var{getfunction} as the way to extract the value of this
-option. The function @var{getfunction} should take one argument, a
-symbol, and should return whatever customize should use as the
-``current value'' for that symbol (which need not be the symbol's Lisp
-value). The default is @code{default-value}.
-
-You have to really understand the workings of Custom to use
address@hidden:get} correctly. It is meant for values that are treated in
-Custom as variables but are not actually stored in Lisp variables. It
-is almost surely a mistake to specify @code{getfunction} for a value
-that really is stored in a Lisp variable.
-
address@hidden :initialize @var{function}
address@hidden address@hidden, @code{defcustom} keyword}
address@hidden should be a function used to initialize the variable
-when the @code{defcustom} is evaluated. It should take two arguments,
-the option name (a symbol) and the value. Here are some predefined
-functions meant for use in this way:
-
address@hidden @code
address@hidden custom-initialize-set
-Use the variable's @code{:set} function to initialize the variable, but
-do not reinitialize it if it is already non-void.
-
address@hidden custom-initialize-default
-Like @code{custom-initialize-set}, but use the function
address@hidden to set the variable, instead of the variable's
address@hidden:set} function. This is the usual choice for a variable whose
address@hidden:set} function enables or disables a minor mode; with this choice,
-defining the variable will not call the minor mode function, but
-customizing the variable will do so.
-
address@hidden custom-initialize-reset
-Always use the @code{:set} function to initialize the variable. If
-the variable is already non-void, reset it by calling the @code{:set}
-function using the current value (returned by the @code{:get} method).
-This is the default @code{:initialize} function.
-
address@hidden custom-initialize-changed
-Use the @code{:set} function to initialize the variable, if it is
-already set or has been customized; otherwise, just use
address@hidden
-
address@hidden custom-initialize-safe-set
address@hidden custom-initialize-safe-default
-These functions behave like @code{custom-initialize-set}
-(@code{custom-initialize-default}, respectively), but catch errors.
-If an error occurs during initialization, they set the variable to
address@hidden using @code{set-default}, and throw no error.
-
-These two functions are only meant for options defined in pre-loaded
-files, where some variables or functions used to compute the option's
-value may not yet be defined. The option normally gets updated in
address@hidden, ignoring the previously computed value. Because of
-this typical usage, the value which these two functions compute
-normally only matters when, after startup, one unsets the option's
-value and then reevaluates the defcustom. By that time, the necessary
-variables and functions will be defined, so there will not be an error.
address@hidden table
-
address@hidden :set-after @var{variables}
address@hidden address@hidden, @code{defcustom} keyword}
-When setting variables according to saved customizations, make sure to
-set the variables @var{variables} before this one; in other words, delay
-setting this variable until after those others have been handled. Use
address@hidden:set-after} if setting this variable won't work properly unless
-those other variables already have their intended values.
address@hidden table
-
- The @code{:require} keyword is useful for an option that turns on the
-operation of a certain feature. Assuming that the package is coded to
-check the value of the option, you still need to arrange for the package
-to be loaded. You can do that with @code{:require}. @xref{Common
-Keywords}. Here is an example, from the library @file{saveplace.el}:
-
address@hidden
-(defcustom save-place nil
- "Non-nil means automatically save place in each file..."
- :type 'boolean
- :require 'saveplace
- :group 'save-place)
address@hidden example
-
-If a customization item has a type such as @code{hook} or
address@hidden, which supports @code{:options}, you can add additional
-values to the list from outside the @code{defcustom} declaration by
-calling @code{custom-add-frequent-value}. For example, if you define a
-function @code{my-lisp-mode-initialization} intended to be called from
address@hidden, you might want to add that to the list of
-reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
-its definition. You can do it thus:
-
address@hidden
-(custom-add-frequent-value 'emacs-lisp-mode-hook
- 'my-lisp-mode-initialization)
address@hidden example
-
address@hidden custom-add-frequent-value symbol value
-For the customization option @var{symbol}, add @var{value} to the
-list of reasonable values.
-
-The precise effect of adding a value depends on the customization type
-of @var{symbol}.
address@hidden defun
-
-Internally, @code{defcustom} uses the symbol property
address@hidden to record the expression for the standard value,
-and @code{saved-value} to record the value saved by the user with the
-customization buffer. Both properties are actually lists whose car is
-an expression which evaluates to the value.
-
address@hidden Customization Types
address@hidden Customization Types
-
address@hidden customization types
- When you define a user option with @code{defcustom}, you must specify
-its @dfn{customization type}. That is a Lisp object which describes (1)
-which values are legitimate and (2) how to display the value in the
-customization buffer for editing.
-
address@hidden address@hidden, @code{defcustom} keyword}
- You specify the customization type in @code{defcustom} with the
address@hidden:type} keyword. The argument of @code{:type} is evaluated, but
-only once when the @code{defcustom} is executed, so it isn't useful
-for the value to vary. Normally we use a quoted constant. For
-example:
-
address@hidden
-(defcustom diff-command "diff"
- "The command to use to run diff."
- :type '(string)
- :group 'diff)
address@hidden example
-
- In general, a customization type is a list whose first element is a
-symbol, one of the customization type names defined in the following
-sections. After this symbol come a number of arguments, depending on
-the symbol. Between the type symbol and its arguments, you can
-optionally write keyword-value pairs (@pxref{Type Keywords}).
-
- Some of the type symbols do not use any arguments; those are called
address@hidden types}. For a simple type, if you do not use any
-keyword-value pairs, you can omit the parentheses around the type
-symbol. For example just @code{string} as a customization type is
-equivalent to @code{(string)}.
-
address@hidden
-* Simple Types::
-* Composite Types::
-* Splicing into Lists::
-* Type Keywords::
-* Defining New Types::
address@hidden menu
-
-All customization types are implemented as widgets; see @ref{Top, ,
-Introduction, widget, The Emacs Widget Library}, for details.
-
address@hidden Simple Types
address@hidden Simple Types
-
- This section describes all the simple customization types.
-
address@hidden @code
address@hidden sexp
-The value may be any Lisp object that can be printed and read back. You
-can use @code{sexp} as a fall-back for any option, if you don't want to
-take the time to work out a more specific type to use.
-
address@hidden integer
-The value must be an integer, and is represented textually
-in the customization buffer.
-
address@hidden number
-The value must be a number (floating point or integer), and is
-represented textually in the customization buffer.
-
address@hidden float
-The value must be a floating point number, and is represented
-textually in the customization buffer.
-
address@hidden string
-The value must be a string, and the customization buffer shows just the
-contents, with no delimiting @samp{"} characters and no quoting with
address@hidden
-
address@hidden regexp
-Like @code{string} except that the string must be a valid regular
-expression.
-
address@hidden character
-The value must be a character code. A character code is actually an
-integer, but this type shows the value by inserting the character in the
-buffer, rather than by showing the number.
-
address@hidden file
-The value must be a file name, and you can do completion with
address@hidden@key{TAB}}.
-
address@hidden (file :must-match t)
-The value must be a file name for an existing file, and you can do
-completion with @address@hidden
-
address@hidden directory
-The value must be a directory name, and you can do completion with
address@hidden@key{TAB}}.
-
address@hidden hook
-The value must be a list of functions (or a single function, but that is
-obsolete usage). This customization type is used for hook variables.
-You can use the @code{:options} keyword in a hook variable's
address@hidden to specify a list of functions recommended for use in
-the hook; see @ref{Variable Definitions}.
-
address@hidden alist
-The value must be a list of cons-cells, the @sc{car} of each cell
-representing a key, and the @sc{cdr} of the same cell representing an
-associated value. The user can add and delete key/value pairs, and
-edit both the key and the value of each pair.
-
-You can specify the key and value types like this:
-
address@hidden
-(alist :key-type @var{key-type} :value-type @var{value-type})
address@hidden smallexample
-
address@hidden
-where @var{key-type} and @var{value-type} are customization type
-specifications. The default key type is @code{sexp}, and the default
-value type is @code{sexp}.
-
-The user can add any key matching the specified key type, but you can
-give some keys a preferential treatment by specifying them with the
address@hidden:options} (see @ref{Variable Definitions}). The specified keys
-will always be shown in the customize buffer (together with a suitable
-value), with a checkbox to include or exclude or disable the key/value
-pair from the alist. The user will not be able to edit the keys
-specified by the @code{:options} keyword argument.
-
-The argument to the @code{:options} keywords should be a list of
-specifications for reasonable keys in the alist. Ordinarily, they are
-simply atoms, which stand for themselves as. For example:
-
address@hidden
-:options '("foo" "bar" "baz")
address@hidden smallexample
-
address@hidden
-specifies that there are three ``known'' keys, namely @code{"foo"},
address@hidden"bar"} and @code{"baz"}, which will always be shown first.
-
-You may want to restrict the value type for specific keys, for
-example, the value associated with the @code{"bar"} key can only be an
-integer. You can specify this by using a list instead of an atom in
-the list. The first element will specify the key, like before, while
-the second element will specify the value type. For example:
-
address@hidden
-:options '("foo" ("bar" integer) "baz")
address@hidden smallexample
-
-Finally, you may want to change how the key is presented. By default,
-the key is simply shown as a @code{const}, since the user cannot change
-the special keys specified with the @code{:options} keyword. However,
-you may want to use a more specialized type for presenting the key, like
address@hidden if you know it is a symbol with a function binding.
-This is done by using a customization type specification instead of a
-symbol for the key.
-
address@hidden
-:options '("foo" ((function-item some-function) integer)
- "baz")
address@hidden smallexample
-
-Many alists use lists with two elements, instead of cons cells. For
-example,
-
address@hidden
-(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
- "Each element is a list of the form (KEY VALUE).")
address@hidden smallexample
-
address@hidden
-instead of
-
address@hidden
-(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
- "Each element is a cons-cell (KEY . VALUE).")
address@hidden smallexample
-
-Because of the way lists are implemented on top of cons cells, you can
-treat @code{list-alist} in the example above as a cons cell alist, where
-the value type is a list with a single element containing the real
-value.
-
address@hidden
-(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
- "Each element is a list of the form (KEY VALUE)."
- :type '(alist :value-type (group integer)))
address@hidden smallexample
-
-The @code{group} widget is used here instead of @code{list} only because
-the formatting is better suited for the purpose.
-
-Similarly, you can have alists with more values associated with each
-key, using variations of this trick:
-
address@hidden
-(defcustom person-data '(("brian" 50 t)
- ("dorith" 55 nil)
- ("ken" 52 t))
- "Alist of basic info about people.
-Each element has the form (NAME AGE MALE-FLAG)."
- :type '(alist :value-type (group integer boolean)))
-
-(defcustom pets '(("brian")
- ("dorith" "dog" "guppy")
- ("ken" "cat"))
- "Alist of people's pets.
-In an element (KEY . VALUE), KEY is the person's name,
-and the VALUE is a list of that person's pets."
- :type '(alist :value-type (repeat string)))
address@hidden smallexample
-
address@hidden plist
-The @code{plist} custom type is similar to the @code{alist} (see above),
-except that the information is stored as a property list, i.e. a list of
-this form:
-
address@hidden
-(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
address@hidden smallexample
-
-The default @code{:key-type} for @code{plist} is @code{symbol},
-rather than @code{sexp}.
-
address@hidden symbol
-The value must be a symbol. It appears in the customization buffer as
-the name of the symbol.
-
address@hidden function
-The value must be either a lambda expression or a function name. When
-it is a function name, you can do completion with @address@hidden
-
address@hidden variable
-The value must be a variable name, and you can do completion with
address@hidden@key{TAB}}.
-
address@hidden face
-The value must be a symbol which is a face name, and you can do
-completion with @address@hidden
-
address@hidden boolean
-The value is boolean---either @code{nil} or @code{t}. Note that by
-using @code{choice} and @code{const} together (see the next section),
-you can specify that the value must be @code{nil} or @code{t}, but also
-specify the text to describe each value in a way that fits the specific
-meaning of the alternative.
-
address@hidden coding-system
-The value must be a coding-system name, and you can do completion with
address@hidden@key{TAB}}.
-
address@hidden color
-The value must be a valid color name, and you can do completion with
address@hidden@key{TAB}}. A sample is provided.
address@hidden table
-
address@hidden Composite Types
address@hidden Composite Types
address@hidden Composite Types (customization)
-
- When none of the simple types is appropriate, you can use composite
-types, which build new types from other types or from specified data.
-The specified types or data are called the @dfn{arguments} of the
-composite type. The composite type normally looks like this:
-
address@hidden
-(@var{constructor} @address@hidden)
address@hidden example
-
address@hidden
-but you can also add keyword-value pairs before the arguments, like
-this:
-
address@hidden
-(@var{constructor} @address@hidden@var{keyword} @address@hidden@address@hidden
@address@hidden)
address@hidden example
-
- Here is a table of constructors and how to use them to write
-composite types:
-
address@hidden @code
address@hidden (cons @var{car-type} @var{cdr-type})
-The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
-its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
-symbol)} is a customization type which matches values such as
address@hidden("foo" . foo)}.
-
-In the customization buffer, the @sc{car} and the @sc{cdr} are
-displayed and edited separately, each according to the type
-that you specify for it.
-
address@hidden (list @address@hidden)
-The value must be a list with exactly as many elements as the
address@hidden given; and each element must fit the
-corresponding @var{element-type}.
-
-For example, @code{(list integer string function)} describes a list of
-three elements; the first element must be an integer, the second a
-string, and the third a function.
-
-In the customization buffer, each element is displayed and edited
-separately, according to the type specified for it.
-
address@hidden (vector @address@hidden)
-Like @code{list} except that the value must be a vector instead of a
-list. The elements work the same as in @code{list}.
-
address@hidden (choice @address@hidden)
-The value must fit at least one of @var{alternative-types}.
-For example, @code{(choice integer string)} allows either an
-integer or a string.
-
-In the customization buffer, the user selects an alternative
-using a menu, and can then edit the value in the usual way for that
-alternative.
-
-Normally the strings in this menu are determined automatically from the
-choices; however, you can specify different strings for the menu by
-including the @code{:tag} keyword in the alternatives. For example, if
-an integer stands for a number of spaces, while a string is text to use
-verbatim, you might write the customization type this way,
-
address@hidden
-(choice (integer :tag "Number of spaces")
- (string :tag "Literal text"))
address@hidden example
-
address@hidden
-so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
-
-In any alternative for which @code{nil} is not a valid value, other than
-a @code{const}, you should specify a valid default for that alternative
-using the @code{:value} keyword. @xref{Type Keywords}.
-
-If some values are covered by more than one of the alternatives,
-customize will choose the first alternative that the value fits. This
-means you should always list the most specific types first, and the
-most general last. Here's an example of proper usage:
-
address@hidden
-(choice (const :tag "Off" nil)
- symbol (sexp :tag "Other"))
address@hidden example
-
address@hidden
-This way, the special value @code{nil} is not treated like other
-symbols, and symbols are not treated like other Lisp expressions.
-
address@hidden (radio @address@hidden)
-This is similar to @code{choice}, except that the choices are displayed
-using `radio buttons' rather than a menu. This has the advantage of
-displaying documentation for the choices when applicable and so is often
-a good choice for a choice between constant functions
-(@code{function-item} customization types).
-
address@hidden (const @var{value})
-The value must be @var{value}---nothing else is allowed.
-
-The main use of @code{const} is inside of @code{choice}. For example,
address@hidden(choice integer (const nil))} allows either an integer or
address@hidden
-
address@hidden:tag} is often used with @code{const}, inside of @code{choice}.
-For example,
-
address@hidden
-(choice (const :tag "Yes" t)
- (const :tag "No" nil)
- (const :tag "Ask" foo))
address@hidden example
-
address@hidden
-describes a variable for which @code{t} means yes, @code{nil} means no,
-and @code{foo} means ``ask.''
-
address@hidden (other @var{value})
-This alternative can match any Lisp value, but if the user chooses this
-alternative, that selects the value @var{value}.
-
-The main use of @code{other} is as the last element of @code{choice}.
-For example,
-
address@hidden
-(choice (const :tag "Yes" t)
- (const :tag "No" nil)
- (other :tag "Ask" foo))
address@hidden example
-
address@hidden
-describes a variable for which @code{t} means yes, @code{nil} means no,
-and anything else means ``ask.'' If the user chooses @samp{Ask} from
-the menu of alternatives, that specifies the value @code{foo}; but any
-other value (not @code{t}, @code{nil} or @code{foo}) displays as
address@hidden, just like @code{foo}.
-
address@hidden (function-item @var{function})
-Like @code{const}, but used for values which are functions. This
-displays the documentation string as well as the function name.
-The documentation string is either the one you specify with
address@hidden:doc}, or @var{function}'s own documentation string.
-
address@hidden (variable-item @var{variable})
-Like @code{const}, but used for values which are variable names. This
-displays the documentation string as well as the variable name. The
-documentation string is either the one you specify with @code{:doc}, or
address@hidden's own documentation string.
-
address@hidden (set @address@hidden)
-The value must be a list, and each element of the list must match one of
-the @var{types} specified.
-
-This appears in the customization buffer as a checklist, so that each of
address@hidden may have either one corresponding element or none. It is
-not possible to specify two different elements that match the same one
-of @var{types}. For example, @code{(set integer symbol)} allows one
-integer and/or one symbol in the list; it does not allow multiple
-integers or multiple symbols. As a result, it is rare to use
-nonspecific types such as @code{integer} in a @code{set}.
-
-Most often, the @var{types} in a @code{set} are @code{const} types, as
-shown here:
-
address@hidden
-(set (const :bold) (const :italic))
address@hidden example
-
-Sometimes they describe possible elements in an alist:
-
address@hidden
-(set (cons :tag "Height" (const height) integer)
- (cons :tag "Width" (const width) integer))
address@hidden example
-
address@hidden
-That lets the user specify a height value optionally
-and a width value optionally.
-
address@hidden (repeat @var{element-type})
-The value must be a list and each element of the list must fit the type
address@hidden This appears in the customization buffer as a
-list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
-more elements or removing elements.
-
address@hidden (restricted-sexp :match-alternatives @var{criteria})
-This is the most general composite type construct. The value may be
-any Lisp object that satisfies one of @var{criteria}. @var{criteria}
-should be a list, and each element should be one of these
-possibilities:
-
address@hidden @bullet
address@hidden
-A predicate---that is, a function of one argument that has no side
-effects, and returns either @code{nil} or address@hidden according to
-the argument. Using a predicate in the list says that objects for which
-the predicate returns address@hidden are acceptable.
-
address@hidden
-A quoted constant---that is, @code{'@var{object}}. This sort of element
-in the list says that @var{object} itself is an acceptable value.
address@hidden itemize
-
-For example,
-
address@hidden
-(restricted-sexp :match-alternatives
- (integerp 't 'nil))
address@hidden example
-
address@hidden
-allows integers, @code{t} and @code{nil} as legitimate values.
-
-The customization buffer shows all legitimate values using their read
-syntax, and the user edits them textually.
address@hidden table
-
- Here is a table of the keywords you can use in keyword-value pairs
-in a composite type:
-
address@hidden @code
address@hidden :tag @var{tag}
-Use @var{tag} as the name of this alternative, for user communication
-purposes. This is useful for a type that appears inside of a
address@hidden
-
address@hidden :match-alternatives @var{criteria}
address@hidden address@hidden, customization keyword}
-Use @var{criteria} to match possible values. This is used only in
address@hidden
-
address@hidden :args @var{argument-list}
address@hidden address@hidden, customization keyword}
-Use the elements of @var{argument-list} as the arguments of the type
-construct. For instance, @code{(const :args (foo))} is equivalent to
address@hidden(const foo)}. You rarely need to write @code{:args} explicitly,
-because normally the arguments are recognized automatically as
-whatever follows the last keyword-value pair.
address@hidden table
-
address@hidden Splicing into Lists
address@hidden Splicing into Lists
-
- The @code{:inline} feature lets you splice a variable number of
-elements into the middle of a list or vector. You use it in a
address@hidden, @code{choice} or @code{repeat} type which appears among the
-element-types of a @code{list} or @code{vector}.
-
- Normally, each of the element-types in a @code{list} or @code{vector}
-describes one and only one element of the list or vector. Thus, if an
-element-type is a @code{repeat}, that specifies a list of unspecified
-length which appears as one element.
-
- But when the element-type uses @code{:inline}, the value it matches is
-merged directly into the containing sequence. For example, if it
-matches a list with three elements, those become three elements of the
-overall sequence. This is analogous to using @samp{,@@} in the backquote
-construct.
-
- For example, to specify a list whose first element must be @code{baz}
-and whose remaining arguments should be zero or more of @code{foo} and
address@hidden, use this customization type:
-
address@hidden
-(list (const baz) (set :inline t (const foo) (const bar)))
address@hidden example
-
address@hidden
-This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
-and @code{(baz foo bar)}.
-
- When the element-type is a @code{choice}, you use @code{:inline} not
-in the @code{choice} itself, but in (some of) the alternatives of the
address@hidden For example, to match a list which must start with a
-file name, followed either by the symbol @code{t} or two strings, use
-this customization type:
-
address@hidden
-(list file
- (choice (const t)
- (list :inline t string string)))
address@hidden example
-
address@hidden
-If the user chooses the first alternative in the choice, then the
-overall list has two elements and the second element is @code{t}. If
-the user chooses the second alternative, then the overall list has three
-elements and the second and third must be strings.
-
address@hidden Type Keywords
address@hidden Type Keywords
-
-You can specify keyword-argument pairs in a customization type after the
-type name symbol. Here are the keywords you can use, and their
-meanings:
-
address@hidden @code
address@hidden :value @var{default}
-This is used for a type that appears as an alternative inside of
address@hidden; it specifies the default value to use, at first, if and
-when the user selects this alternative with the menu in the
-customization buffer.
-
-Of course, if the actual value of the option fits this alternative, it
-will appear showing the actual value, not @var{default}.
-
-If @code{nil} is not a valid value for the alternative, then it is
-essential to specify a valid default with @code{:value}.
-
address@hidden :format @var{format-string}
address@hidden address@hidden, customization keyword}
-This string will be inserted in the buffer to represent the value
-corresponding to the type. The following @samp{%} escapes are available
-for use in @var{format-string}:
-
address@hidden @samp
address@hidden address@hidden
-Display the text @var{button} marked as a button. The @code{:action}
-attribute specifies what the button will do if the user invokes it;
-its value is a function which takes two arguments---the widget which
-the button appears in, and the event.
-
-There is no way to specify two different buttons with different
-actions.
-
address@hidden address@hidden@address@hidden
-Show @var{sample} in a special face specified by @code{:sample-face}.
-
address@hidden %v
-Substitute the item's value. How the value is represented depends on
-the kind of item, and (for variables) on the customization type.
-
address@hidden %d
-Substitute the item's documentation string.
-
address@hidden %h
-Like @samp{%d}, but if the documentation string is more than one line,
-add an active field to control whether to show all of it or just the
-first line.
-
address@hidden %t
-Substitute the tag here. You specify the tag with the @code{:tag}
-keyword.
-
address@hidden %%
-Display a literal @samp{%}.
address@hidden table
-
address@hidden :action @var{action}
address@hidden address@hidden, customization keyword}
-Perform @var{action} if the user clicks on a button.
-
address@hidden :button-face @var{face}
address@hidden address@hidden, customization keyword}
-Use the face @var{face} (a face name or a list of face names) for button
-text displayed with @address@hidden
-
address@hidden :button-prefix @var{prefix}
address@hidden :button-suffix @var{suffix}
address@hidden address@hidden, customization keyword}
address@hidden address@hidden, customization keyword}
-These specify the text to display before and after a button.
-Each can be:
-
address@hidden @asis
address@hidden @code{nil}
-No text is inserted.
-
address@hidden a string
-The string is inserted literally.
-
address@hidden a symbol
-The symbol's value is used.
address@hidden table
-
address@hidden :tag @var{tag}
-Use @var{tag} (a string) as the tag for the value (or part of the value)
-that corresponds to this type.
-
address@hidden :doc @var{doc}
address@hidden address@hidden, customization keyword}
-Use @var{doc} as the documentation string for this value (or part of the
-value) that corresponds to this type. In order for this to work, you
-must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
-in that value.
-
-The usual reason to specify a documentation string for a type is to
-provide more information about the meanings of alternatives inside a
address@hidden:choice} type or the parts of some other composite type.
-
address@hidden :help-echo @var{motion-doc}
address@hidden address@hidden, customization keyword}
-When you move to this item with @code{widget-forward} or
address@hidden, it will display the string @var{motion-doc} in
-the echo area. In addition, @var{motion-doc} is used as the mouse
address@hidden string and may actually be a function or form evaluated
-to yield a help string. If it is a function, it is called with one
-argument, the widget.
-
address@hidden :match @var{function}
address@hidden address@hidden, customization keyword}
-Specify how to decide whether a value matches the type. The
-corresponding value, @var{function}, should be a function that accepts
-two arguments, a widget and a value; it should return address@hidden if
-the value is acceptable.
-
address@hidden
address@hidden :indent @var{columns}
-Indent this item by @var{columns} columns. The indentation is used for
address@hidden, and automatically for group names, for checklists and radio
-buttons, and for editable lists. It affects the whole of the
-item except for the first line.
-
address@hidden :offset @var{columns}
-An integer indicating how many extra spaces to indent the subitems of
-this item. By default, subitems are indented the same as their parent.
-
address@hidden :extra-offset
-An integer indicating how many extra spaces to add to this item's
-indentation, compared to its parent.
-
address@hidden :notify
-A function called each time the item or a subitem is changed. The
-function is called with two or three arguments. The first argument is
-the item itself, the second argument is the item that was changed, and
-the third argument is the event leading to the change, if any.
-
address@hidden :menu-tag
-A tag used in the menu when the widget is used as an option in a
address@hidden widget.
-
address@hidden :menu-tag-get
-A function used for finding the tag when the widget is used as an option
-in a @code{menu-choice} widget. By default, the tag used will be either the
address@hidden:menu-tag} or @code{:tag} property if present, or the @code{princ}
-representation of the @code{:value} property if not.
-
address@hidden :validate
-A function which takes a widget as an argument, and return @code{nil}
-if the widget's current value is valid for the widget. Otherwise, it
-should return the widget containing the invalid data, and set that
-widget's @code{:error} property to a string explaining the error.
-
-You can use the function @code{widget-children-validate} for this job;
-it tests that all children of @var{widget} are valid.
-
address@hidden :tab-order
-Specify the order in which widgets are traversed with
address@hidden or @code{widget-backward}. This is only partially
-implemented.
-
address@hidden a
address@hidden
-Widgets with tabbing order @code{-1} are ignored.
-
address@hidden
-(Unimplemented) When on a widget with tabbing order @var{n}, go to the
-next widget in the buffer with tabbing order @var{n+1} or @code{nil},
-whichever comes first.
-
address@hidden
-When on a widget with no tabbing order specified, go to the next widget
-in the buffer with a positive tabbing order, or @code{nil}
address@hidden enumerate
-
address@hidden :parent
-The parent of a nested widget (e.g., a @code{menu-choice} item or an
-element of a @code{editable-list} widget).
-
address@hidden :sibling-args
-This keyword is only used for members of a @code{radio-button-choice} or
address@hidden The value should be a list of extra keyword
-arguments, which will be used when creating the @code{radio-button} or
address@hidden associated with this item.
address@hidden ignore
address@hidden table
-
address@hidden Defining New Types
address@hidden Defining New Types
-
-In the previous sections we have described how to construct elaborate
-type specifications for @code{defcustom}. In some cases you may want
-to give such a type specification a name. The obvious case is when
-you are using the same type for many user options: rather than repeat
-the specification for each option, you can give the type specification
-a name, and use that name each @code{defcustom}. The other case is
-when a user option's value is a recursive data structure. To make it
-possible for a datatype to refer to itself, it needs to have a name.
-
-Since custom types are implemented as widgets, the way to define a new
-customize type is to define a new widget. We are not going to describe
-the widget interface here in details, see @ref{Top, , Introduction,
-widget, The Emacs Widget Library}, for that. Instead we are going to
-demonstrate the minimal functionality needed for defining new customize
-types by a simple example.
-
address@hidden
-(define-widget 'binary-tree-of-string 'lazy
- "A binary tree made of cons-cells and strings."
- :offset 4
- :tag "Node"
- :type '(choice (string :tag "Leaf" :value "")
- (cons :tag "Interior"
- :value ("" . "")
- binary-tree-of-string
- binary-tree-of-string)))
-
-(defcustom foo-bar ""
- "Sample variable holding a binary tree of strings."
- :type 'binary-tree-of-string)
address@hidden example
-
-The function to define a new widget is called @code{define-widget}. The
-first argument is the symbol we want to make a new widget type. The
-second argument is a symbol representing an existing widget, the new
-widget is going to be defined in terms of difference from the existing
-widget. For the purpose of defining new customization types, the
address@hidden widget is perfect, because it accepts a @code{:type} keyword
-argument with the same syntax as the keyword argument to
address@hidden with the same name. The third argument is a
-documentation string for the new widget. You will be able to see that
-string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
address@hidden command.
-
-After these mandatory arguments follow the keyword arguments. The most
-important is @code{:type}, which describes the data type we want to match
-with this widget. Here a @code{binary-tree-of-string} is described as
-being either a string, or a cons-cell whose car and cdr are themselves
-both @code{binary-tree-of-string}. Note the reference to the widget
-type we are currently in the process of defining. The @code{:tag}
-attribute is a string to name the widget in the user interface, and the
address@hidden:offset} argument is there to ensure that child nodes are
-indented four spaces relative to the parent node, making the tree
-structure apparent in the customization buffer.
-
-The @code{defcustom} shows how the new widget can be used as an ordinary
-customization type.
-
-The reason for the name @code{lazy} is that the other composite
-widgets convert their inferior widgets to internal form when the
-widget is instantiated in a buffer. This conversion is recursive, so
-the inferior widgets will convert @emph{their} inferior widgets. If
-the data structure is itself recursive, this conversion is an infinite
-recursion. The @code{lazy} widget prevents the recursion: it convert
-its @code{:type} argument only when needed.
-
address@hidden
- arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
address@hidden ignore
- [Emacs-diffs] Changes to customize.texi,
Glenn Morris <=