--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1997, 1998 Free Software Foundation, Inc.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../info/customize
+@node Customization, , , Top
+@chapter Writing Customization Definitions
+
+ This chapter describes how to declare user options for customization,
+and also customization groups for classifying them. We use the term
+@dfn{customization item} to include both kinds of customization
+definitions---as well as face definitions.
+
+@menu
+* Common Keywords::
+* Group Definitions::
+* Variable Definitions::
+* Customization Types::
+@end menu
+
+@node Common Keywords
+@section Common Keywords for All Kinds of Items
+
+ 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.
+
+@table @code
+@item :tag @var{name}
+Use @var{name}, a string, instead of the item's name, to label the item
+in customization menus and buffers.
+
+@item :group @var{group}
+Put this customization item in group @var{group}. When you use
+@code{:group} in a @code{defgroup}, it makes the new group a subgroup of
+@var{group}.
+
+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. Be careful not to overdo this!
+
+@item :link @var{link-data}
+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 three alternatives you can use for @var{link-data}:
+
+@table @code
+@item (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
+@samp{[manual]} in the customization buffer.
+
+@item (info-link @var{info-node})
+Like @code{custom-manual} except that the link appears
+in the customization buffer with the Info node name.
+
+@item (url-link @var{url})
+Link to a web page; @var{url} is a string which specifies the @sc{url}.
+The link appears in the customization buffer as @var{url}.
+@end table
+
+You can specify the text to use in the customization buffer by adding
+@code{: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.
+
+@item :load @var{file}
+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.
+
+@item :require @var{feature}
+Require feature @var{feature} (a symbol) when installing a value for
+this item (an option or a face) that was saved using the customization
+feature. This is done by calling @code{require}.
+
+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.
+@end table
+
+@node Group Definitions
+@section Defining Custom Groups
+
+ 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}.
+
+@tindex defgroup
+@defmac defgroup group members doc [keyword value]...
+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
+@var{members} 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,
+@code{custom-face} for a face, and @code{custom-group} for a group.
+
+In addition to the common keywords (@pxref{Common Keywords}), you can
+use this keyword in @code{defgroup}:
+
+@table @code
+@item :prefix @var{prefix}
+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.
+@end table
+@end defmac
+
+@c Doesn't apply to XEmacs
+@c
+@c The prefix-discarding feature is currently turned off, which means
+@c that @code{:prefix} currently has no effect. We did this because we
+@c found that discarding the specified prefixes often led to confusing
+@c names for options. This happened because the people who wrote the
+@c @code{defgroup} definitions for various groups added @code{:prefix}
+@c keywords whenever they make logical sense---that is, whenever the
+@c variables in the library have a common prefix.
+
+@c In order to obtain good results with @code{:prefix}, it would be
+@c necessary to check the specific effects of discarding a particular
+@c prefix, given the specific items in a group and their names and
+@c documentation. If the resulting text is not clear, then @code{:prefix}
+@c should not be used in that case.
+
+@c It should be possible to recheck all the customization groups, delete
+@c the @code{:prefix} specifications which give unclear results, and then
+@c turn this feature back on, if someone would like to do the work.
+
+@node Variable Definitions
+@section Defining Customization Variables
+
+ Use @code{defcustom} to declare user-editable variables.
+
+@tindex defcustom
+@defmac defcustom option default doc [keyword value]...
+Declare @var{option} as a customizable user option variable. Do not
+quote @var{option}. The argument @var{doc} specifies the documentation
+string for the variable.
+
+If @var{option} is void, @code{defcustom} initializes it to
+@var{default}. @var{default} should be an expression to compute the
+value; be careful in writing it, because it can be evaluated on more
+than one occasion.
+
+The following additional keywords are defined:
+
+@table @code
+@item :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.
+@xref{Customization Types}, for more information.
+
+@item :options @var{list}
+Specify @var{list} as the list of reasonable values for use in this
+option.
+
+Currently this is meaningful only when the type is @code{hook}. In that
+case, the elements of @var{list} should be functions that are useful as
+elements of the hook value. The user is not restricted to using only
+these functions, but they are offered as convenient alternatives.
+
+@item :version @var{version}
+This option specifies that the variable was first introduced, or its
+default value was changed, in Emacs version @var{version}. The value
+@var{version} must be a string. For example,
+
+@example
+(defcustom foo-max 34
+ "*Maximum number of foo's allowed."
+ :type 'integer
+ :group 'foo
+ :version "20.3")
+@end example
+
+@item :set @var{setfunction}
+Specify @var{setfunction} as the way to change the value of this option.
+The function @var{setfunction} should take two arguments, a symbol 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 @var{setfunction} is
+@code{set-default}.
+
+@item :get @var{getfunction}
+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 the ``current value'' for that symbol (which
+need not be the symbol's Lisp value). The default is
+@code{default-value}.
+
+@item :initialize @var{function}
+@var{function} should be a function used to initialize the variable when
+the @code{defcustom} is evaluated. It should take two arguments, the
+symbol and value. Here are some predefined functions meant for use in
+this way:
+
+@table @code
+@item 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. This is the default
+@code{:initialize} function.
+
+@item custom-initialize-default
+Like @code{custom-initialize-set}, but use the function
+@code{set-default} to set the variable, instead of the variable's
+@code{:set} function. This is the usual choice for a variable whose
+@code{: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.
+
+@item 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).
+
+@item custom-initialize-changed
+Use the @code{:set} function to initialize the variable, if it is
+already set or has been customized; otherwise, just use
+@code{set-default}.
+@end table
+@end table
+@end defmac
+
+ The @code{:require} option 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{paren.el}:
+
+@example
+(defcustom show-paren-mode nil
+ "Toggle Show Paren mode@enddots{}"
+ :set (lambda (symbol value)
+ (show-paren-mode (or value 0)))
+ :initialize 'custom-initialize-default
+ :type 'boolean
+ :group 'paren-showing
+ :require 'paren)
+@end example
+
+@ignore
+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
+@end ignore
+
+Internally, @code{defcustom} uses the symbol property
+@code{standard-value} to record the expression for the default value,
+and @code{saved-value} to record the value saved by the user with the
+customization buffer. The @code{saved-value} property is actually a
+list whose car is an expression which evaluates to the value.
+
+@node Customization Types
+@section 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.
+
+ You specify the customization type in @code{defcustom} with the
+@code{:type} keyword. The argument of @code{:type} is evaluated; since
+types that vary at run time are rarely useful, normally you use a quoted
+constant. For example:
+
+@example
+(defcustom diff-command "diff"
+ "*The command to use to run diff."
+ :type '(string)
+ :group 'diff)
+@end 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
+@dfn{simple 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)}.
+
+@menu
+* Simple Types::
+* Composite Types::
+* Splicing into Lists::
+* Type Keywords::
+@end menu
+
+@node Simple Types
+@subsection Simple Types
+
+ This section describes all the simple customization types.
+
+@table @code
+@item 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.
+
+@item integer
+The value must be an integer, and is represented textually
+in the customization buffer.
+
+@item number
+The value must be a number, and is represented textually in the
+customization buffer.
+
+@item string
+The value must be a string, and the customization buffer shows just the
+contents, with no delimiting @samp{"} characters and no quoting with
+@samp{\}.
+
+@item regexp
+Like @code{string} except that the string must be a valid regular
+expression.
+
+@item 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.
+
+@item file
+The value must be a file name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item (file :must-match t)
+The value must be a file name for an existing file, and you can do
+completion with @kbd{M-@key{TAB}}.
+
+@item directory
+The value must be a directory name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item symbol
+The value must be a symbol. It appears in the customization buffer as
+the name of the symbol.
+
+@item function
+The value must be either a lambda expression or a function name. When
+it is a function name, you can do completion with @kbd{M-@key{TAB}}.
+
+@item variable
+The value must be a variable name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item face
+The value must be a symbol which is a face name.
+
+@item 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.
+@end table
+
+@node Composite Types
+@subsection Composite Types
+
+ When none of the simple types is appropriate, you can use composite
+types, which build new types from other types. Here are several ways of
+doing that:
+
+@table @code
+@item (restricted-sexp :match-alternatives @var{criteria})
+The value may be any Lisp object that satisfies one of @var{criteria}.
+@var{criteria} should be a list, and each elements should be
+one of these possibilities:
+
+@itemize @bullet
+@item
+A predicate---that is, a function of one argument that returns non-@code{nil}
+if the argument fits a certain type. This means that objects of that type
+are acceptable.
+
+@item
+A quoted constant---that is, @code{'@var{object}}. This means that
+@var{object} itself is an acceptable value.
+@end itemize
+
+For example,
+
+@example
+(restricted-sexp :match-alternatives (integerp 't 'nil))
+@end example
+
+@noindent
+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.
+
+@item (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
+@code{("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.
+
+@item (list @var{element-types}@dots{})
+The value must be a list with exactly as many elements as the
+@var{element-types} you have specified; 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, the each element is displayed and edited
+separately, according to the type specified for it.
+
+@item (vector @var{element-types}@dots{})
+Like @code{list} except that the value must be a vector instead of a
+list. The elements work the same as in @code{list}.
+
+@item (choice @var{alternative-types}...)
+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 one of the alternatives
+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,
+
+@smallexample
+(choice (integer :tag "Number of spaces")
+ (string :tag "Literal text"))
+@end smallexample
+
+@noindent
+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}.
+
+@item (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,
+@code{(choice integer (const nil))} allows either an integer or
+@code{nil}.
+
+@code{:tag} is often used with @code{const}, inside of @code{choice}.
+For example,
+
+@smallexample
+(choice (const :tag "Yes" t)
+ (const :tag "No" nil)
+ (const :tag "Ask" foo))
+@end smallexample
+
+@item (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
+@code{:doc}, or @var{function}'s own documentation string.
+
+@item (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
+@var{variable}'s own documentation string.
+
+@item (set @var{elements}@dots{})
+The value must be a list and each element of the list must be one of the
+@var{elements} specified. This appears in the customization buffer as a
+checklist.
+
+@item (repeat @var{element-type})
+The value must be a list and each element of the list must fit the type
+@var{element-type}. 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.
+@end table
+
+@node Splicing into Lists
+@subsection 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
+@code{set}, @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{t}
+and whose remaining arguments should be zero or more of @code{foo} and
+@code{bar}, use this customization type:
+
+@example
+(list (const t) (set :inline t foo bar))
+@end example
+
+@noindent
+This matches values such as @code{(t)}, @code{(t foo)}, @code{(t bar)}
+and @code{(t 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
+@code{choice}. 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:
+
+@example
+(list file
+ (choice (const t)
+ (list :inline t string string)))
+@end example
+
+@noindent
+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.
+
+@node Type Keywords
+@subsection 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:
+
+@table @code
+@item :value @var{default}
+This is used for a type that appears as an alternative inside of
+@code{choice}; 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}.
+
+@item :format @var{format-string}
+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}:
+
+@table @samp
+@item %[@var{button}%]
+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.
+
+@item %@{@var{sample}%@}
+Show @var{sample} in a special face specified by @code{:sample-face}.
+
+@item %v
+Substitute the item's value. How the value is represented depends on
+the kind of item, and (for variables) on the customization type.
+
+@item %d
+Substitute the item's documentation string.
+
+@item %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.
+
+@item %t
+Substitute the tag here. You specify the tag with the @code{:tag}
+keyword.
+
+@item %%
+Display a literal @samp{%}.
+@end table
+
+@item :action @var{action}
+Perform @var{action} if the user clicks on a button.
+
+@item :button-face @var{face}
+Use the face @var{face} (a face name or a list of face names) for button
+text displayed with @samp{%[@dots{}%]}.
+
+@item :button-prefix @var{prefix}
+@itemx :button-suffix @var{suffix}
+These specify the text to display before and after a button.
+Each can be:
+
+@table @asis
+@item @code{nil}
+No text is inserted.
+
+@item a string
+The string is inserted literally.
+
+@item a symbol
+The symbol's value is used.
+@end table
+
+@item :tag @var{tag}
+Use @var{tag} (a string) as the tag for the value (or part of the value)
+that corresponds to this type.
+
+@item :doc @var{doc}
+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
+@code{:choice} type or the parts of some other composite type.
+
+@item :help-echo @var{motion-doc}
+When you move to this item with @code{widget-forward} or
+@code{widget-backward}, it will display the string @var{motion-doc}
+in the echo area.
+
+@item :match @var{function}
+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 non-@code{nil} if
+the value is acceptable.
+
+@ignore
+@item :indent @var{columns}
+Indent this item by @var{columns} columns. The indentation is used for
+@samp{%n}, 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.
+
+@item :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.
+
+@item :extra-offset
+An integer indicating how many extra spaces to add to this item's
+indentation, compared to its parent.
+
+@item :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.
+
+@item :menu-tag
+Tag used in the menu when the widget is used as an option in a
+@code{menu-choice} widget.
+
+@item :menu-tag-get
+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
+@code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
+representation of the @code{:value} property if not.
+
+@item :validate
+A function which takes a widget as an argument, and returns @code{nil} if the
+widgets current value is valid for the widget. Otherwise, it should
+return the widget containing the invalid data, and set that widgets
+@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.
+
+@item :tab-order
+Specify the order in which widgets are traversed with
+@code{widget-forward} or @code{widget-backward}. This is only partially
+implemented.
+
+@enumerate a
+@item
+Widgets with tabbing order @code{-1} are ignored.
+
+@item
+(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.
+
+@item
+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}
+@end enumerate
+
+@item :parent
+The parent of a nested widget (e.g. a @code{menu-choice} item or an
+element of an @code{editable-list} widget).
+
+@item :sibling-args
+This keyword is only used for members of a @code{radio-button-choice} or
+@code{checklist}. The value should be a list of extra keyword
+arguments, which will be used when creating the @code{radio-button} or
+@code{checkbox} associated with this item.
+@end ignore
+@end table
projects / chise / xemacs-chise.git- / blobdiff