Mercurial > emacs
view lispref/customize.texi @ 21602:c774fc879d96
(LINK_TYPE): Do not include debug info in optimized
binary.
(LIBS): Include mpr.lib.
(clean): Delete patch generated files, optimized build directory.
author | Geoff Voelker <voelker@cs.washington.edu> |
---|---|
date | Fri, 17 Apr 1998 05:05:40 +0000 |
parents | 00022857f529 |
children | 90da2489c498 |
line wrap: on
line source
@c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1997, 1998 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/customize @node Customization, Loading, Macros, Top @chapter Writing Customization Definitions This chapter describes how to declare customization groups, variables, and faces. We use the term @dfn{customization item} to include all three of those. This has few examples, but please look at the file @file{cus-edit.el}, which contains many declarations you can learn from. @menu * Common Keywords:: * Group Definitions:: * Variable Definitions:: * Face Definitions:: * Customization Types:: @end menu @node Common Keywords @section Common Keywords for All Kinds of Items All three kinds of customization declarations (for groups, variables, and faces) accept keyword arguments for specifying various information. This section describes some keywords that apply to all three. 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 item. @table @code @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 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. @item :tag @var{name} Use @var{name}, a string, instead of the item's name, to label the item in customization menus and buffers. @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 have 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. Type press @kbd{C-h p} to display a list of finder keywords; them choose some of them 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 arguments @var{members} can be an alist whose elements specify members of the group; however, normally @var{members} is @code{nil}, and you specify the group's members by using the @code{:group} keyword when defining those members. @ignore @code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and @var{widget} is a widget for editing that symbol. Useful widgets are @code{custom-variable} for editing variables, @code{custom-face} for editing faces, and @code{custom-group} for editing groups. @end ignore 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 The @code{:prefix} 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 @code{defgroup} definitions for various groups added @code{:prefix} keywords whenever they make logical sense---that is, whenever they say that there was a common prefix for the option names in a library. In order to obtain good results with @code{:prefix}, it is 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. @node Variable Definitions @section Defining Customization Variables Use @code{defcustom} to declare user editable variables. @tindex defcustom @defmac defcustom option value doc [keyword value]... Declare @var{option} as a customizable user option variable that defaults to @var{value}. Do not quote @var{option}. @var{value} should be an expression to compute the value; it will be be evaluated on more than one occasion. If @var{option} is void, @code{defcustom} initializes it to @var{value}. The argument @var{doc} specifies the documentation string for the variable. 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 type is @code{hook}. The elements of @var{list} are functions that you might likely want to use as elements of the hook value. The user is not actually restricted to using only these functions, but they are offered as convenient alternatives. @item :version @var{version} This option specifies that the variable's default value was changed in Emacs version @var{version}. 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. Do not reinitialize it if it is already non-void. This is the default @code{:initialize} function. @item custom-initialize-default Always use @code{set-default} to initialize the variable, even if some other @code{:set} function has been specified. @item custom-initialize-reset Even 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 Like @code{custom-initialize-reset}, except use @code{set-default} (rather than the @code{:set} function) to initialize the variable if it is not bound and has not been set already. @end table @item :require @var{feature} If the user saves a customized value for this item, them Emacs should do @code{(require @var{feature})} after installing the saved value. The place to use this feature is 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. That is what @code{:require} is for. @end table @end defmac @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 Face Definitions @section Defining Faces Faces are declared with @code{defface}. @tindex defface @defmac defface face spec doc [keyword value]... Declare @var{face} as a customizable face that defaults according to @var{spec}. Do not quote the symbol @var{face}. @var{doc} is the face documentation. @var{spec} should be an alist whose elements have the form @code{(@var{display} @var{atts})} (see below). When @code{defface} executes, it defines the face according to @var{spec}, then uses any customizations saved in the @file{.emacs} file to override that specification. In each element of @var{spec}, @var{atts} is a list of face attributes and their values. The possible attributes are defined in the variable @code{custom-face-attributes}. The @var{display} part of an element of @var{spec} determines which frames the element applies to. If more than one element of @var{spec} matches a given frame, the first matching element is the only one used for that frame. If @var{display} is @code{t} in a @var{spec} element, that element matches all frames. (This means that any subsequent elements of @var{spec} are never used.) Alternatively, @var{display} can be an alist whose elements have the form @code{(@var{characteristic} @var{value}@dots{})}. Here @var{characteristic} specifies a way of classifying frames, and the @var{value}s are possible classifications which @var{display} should apply to. Here are the possible values of @var{characteristic}: @table @code @item type The kind of window system the frame uses---either @code{x}, @code{pc} (for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or @code{tty}. @item class What kinds of colors the frame supports---either @code{color}, @code{grayscale}, or @code{mono}. @item background The kind of background--- either @code{light} or @code{dark}. @end table If an element of @var{display} specifies more than one @var{value} for a given @var{characteristic}, any of those values is acceptable. If an element of @var{display} has elements for more than one @var{characteristic}, then @var{each} characteristic of the frame must match one of the values specified for it. @end defmac Internally, @code{defface} uses the symbol property @code{face-defface-spec} to record the face attributes specified in @code{defface}, @code{saved-face} for the attributes saved by the user with the customization buffer, and @code{face-documentation} for the documentation string. @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 indictaes (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 it is 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 appears 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. Some of the type symbols do not use any arguments; those are called @dfn{simple types}. In between the type symbol and its arguments, you can optionally write keyword-value pairs. @xref{Type Keywords}. For a simple type, if you do not use any keyword-value pairs, you can omit the parentheses around the type symbol. The above example does this, using just @code{string} as the customization type. But @code{(string)} would mean the same thing. @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 @samp{"} characters or quoting with @samp{\}. @item regexp The value must be a string which is 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 boolean The value is boolean---either @code{nil} or @code{t}. @end table @node Composite Types @subsection Composite Types When none of the simple types is appropriate, you can use composite types, which build from simple 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} 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{(const string symbol)} is a customization type which matches values such as @code{("foo" . foo)}. In the customization buffeer, 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 buffeer, 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}. @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}. @item (function-item @var{function}) Like @code{const}, but used for values which are functions. This displays the documentation string of the function @var{function} as well as its name. @item (variable-item @var{variable}) Like @code{const}, but used for values which are variable names. This displays the documentation string of the variable @var{variable} as well as its name. @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}. @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 @ignore @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; but perhaps there is no need for one. @end ignore @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 :button-face @var{face} Use face @var{face} for text displayed with @samp{%[@dots{}%]}. @item :button-prefix @itemx :button-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 :doc @var{doc} Use @var{doc} as the documentation string for this item. @item :tag @var{tag} Use @var{tag} (a string) as the tag for this item. @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. @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 return 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 a @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