Freeware (IRIX) » Info Pages
find in page
elisp : Customization
table of contents
Introduction
Coding Conventions
Lisp Data Types
Numbers
Strings and Characters
Lists
Sequences Arrays Vectors
Hash Tables
Symbols
Evaluation
Control Structures
Variables
Functions
Macros
Customization
Loading
Byte Compilation
Advising Functions
Debugging
Read and Print
Minibuffers
Command Loop
Keymaps
Modes
Documentation
Files
Backups and Auto-Saving
Buffers
Windows
Frames
Positions
Markers
Text
Non-ASCII Characters
Searching and Matching
Syntax Tables
Abbrevs
Processes
Display
Calendar
System Interface
Antinews
GNU Free Documentation License
GPL
Tips
GNU Emacs Internals
Standard Errors
Standard Buffer-Local Variables
Standard Keymaps
Standard Hooks
Index
New Symbols
Caveats
Lisp History
Conventions
Acknowledgements
Some Terms
nil and t
Evaluation Notation
Printing Notation
Error Messages
Buffer Text Notation
Format of Descriptions
Coding Conventions
Compilation Tips
Documentation Tips
Comment Tips
Library Headers
A Sample Function Description
A Sample Variable Description
Printed Representation
Comments
Programming Types
Editing Types
Type Predicates
Equality Predicates
Integer Type
Floating Point Type
Character Type
Sequence Type
Cons Cell Type
Array Type
String Type
Vector Type
Symbol Type
Function Type
Macro Type
Primitive Function Type
Byte-Code Type
Autoload Type
Dotted Pair Notation
Association List Type
Buffer Type
Window Type
Window Configuration Type
Marker Type
Process Type
Stream Type
Keymap Type
Overlay Type
Integer Basics
Float Basics
Predicates on Numbers
Comparison of Numbers
Arithmetic Operations
Bitwise Operations
Numeric Conversions
Math Functions
Random Numbers
String Basics
Predicates for Strings
Creating Strings
Text Comparison
String Conversion
Formatting Strings
Case Conversion
Cons Cells
Lists as Boxes
List-related Predicates
List Elements
Building Lists
Modifying Lists
Sets And Lists
Association Lists
Setcar
Setcdr
Rearrangement
Sequence Functions
Arrays
Array Functions
Vectors
Symbol Components
Definitions
Creating Symbols
Property Lists
Intro Eval
Eval
Forms
Quoting
Self-Evaluating Forms
Symbol Forms
Classifying Lists
Function Forms
Macro Forms
Special Forms
Autoloading
Sequencing
Conditionals
Combining Conditions
Iteration
Nonlocal Exits
Catch and Throw
Examples of Catch
Errors
Cleanups
Signaling Errors
Processing of Errors
Handling Errors
Error Symbols
Global Variables
Constant Variables
Local Variables
Void Variables
Defining Variables
Accessing Variables
Setting Variables
Variable Scoping
Buffer-Local Variables
Scope
Extent
Impl of Scope
Using Scoping
Intro to Buffer-Local
Creating Buffer-Local
Default Value
What Is a Function
Lambda Expressions
Function Names
Defining Functions
Calling Functions
Mapping Functions
Anonymous Functions
Function Cells
Related Topics
Lambda Components
Simple Lambda
Argument List
Function Documentation
Simple Macro
Expansion
Compiling Macros
Defining Macros
Backquote
Problems with Macros
How Programs Do Loading
Autoload
Named Features
Repeated Loading
Compilation Functions
Disassembly
Simple Advice
Defining Advice
Computed Advice
Activation of Advice
Enabling Advice
Preactivation
Argument Access in Advice
Subr Arguments
Combined Definition
Debugger
Syntax Errors
Compilation Errors
Edebug
Error Debugging
Function Debugging
Explicit Debug
Using Debugger
Debugger Commands
Invoking the Debugger
Internals of Debugger
Excess Open
Excess Close
Streams Intro
Input Streams
Input Functions
Output Streams
Output Functions
Intro to Minibuffers
Text from Minibuffer
Object from Minibuffer
Completion
Yes-or-No Queries
Minibuffer Misc
Basic Completion
Minibuffer Completion
Completion Commands
High-Level Completion
Reading File Names
Programmed Completion
Command Overview
Defining Commands
Interactive Call
Command Loop Info
Input Events
Reading Input
Waiting
Quitting
Prefix Command Arguments
Recursive Editing
Disabling Commands
Command History
Keyboard Macros
Using Interactive
Interactive Codes
Interactive Examples
Keymap Terminology
Format of Keymaps
Creating Keymaps
Inheritance and Keymaps
Prefix Keys
Menu Keymaps
Active Keymaps
Key Lookup
Functions for Key Lookup
Changing Key Bindings
Key Binding Commands
Scanning Keymaps
Major Modes
Minor Modes
Mode Line Format
Hooks
Major Mode Conventions
Example Major Modes
Auto Major Mode
Mode Help
Minor Mode Conventions
Keymaps and Minor Modes
Mode Line Data
Mode Line Variables
%-Constructs
Documentation Basics
Accessing Documentation
Keys in Documentation
Describing Characters
Help Functions
Visiting Files
Saving Buffers
Reading from Files
Writing to Files
File Locks
Information about Files
Contents of Directories
Changing Files
File Names
Visiting Functions
Subroutines of Visiting
Testing Accessibility
Kinds of Files
File Attributes
File Name Components
Directory Names
Relative File Names
File Name Expansion
Unique File Names
File Name Completion
Backup Files
Auto-Saving
Reverting
Making Backups
Rename or Copy
Numbered Backups
Backup Names
Buffer Basics
Buffer Names
Buffer File Name
Buffer Modification
Modification Time
Read Only Buffers
The Buffer List
Creating Buffers
Killing Buffers
Current Buffer
Basic Windows
Splitting Windows
Deleting Windows
Selecting Windows
Cyclic Window Ordering
Buffers and Windows
Displaying Buffers
Window Point
Window Start
Vertical Scrolling
Horizontal Scrolling
Size of Window
Resizing Windows
Window Configurations
Creating Frames
Multiple Displays
Frame Parameters
Frame Titles
Deleting Frames
Finding All Frames
Frames and Windows
Minibuffers and Frames
Input Focus
Visibility of Frames
Raising and Lowering
Frame Configurations
Mouse Tracking
Mouse Position
Pop-Up Menus
Dialog Boxes
Pointer Shapes
Window System Selections
Color Names
Resources
Display Feature Testing
Point
Motion
Excursions
Narrowing
Character Motion
Word Motion
Buffer End Motion
Text Lines
Screen Lines
List Motion
Skipping Characters
Overview of Markers
Predicates on Markers
Creating Markers
Information from Markers
Moving Markers
The Mark
The Region
Near Point
Buffer Contents
Insertion
Commands for Insertion
Deletion
User-Level Deletion
The Kill Ring
Undo
Auto Filling
Filling
Margins
Sorting
Indentation
Columns
Case Changes
Text Properties
Substitution
Transposition
Registers
Change Hooks
Kill Ring Concepts
Kill Functions
Yank Commands
Low-Level Kill Ring
Internals of Kill Ring
Primitive Indent
Mode-Specific Indent
Region Indent
Relative Indent
Indent Tabs
Motion by Indent
Examining Properties
Changing Properties
Property Search
Special Properties
Format Properties
Sticky Properties
Saving Properties
Lazy Properties
Clickable Text
Fields
Not Intervals
Text Representations
Converting Representations
Selecting a Representation
Character Codes
Character Sets
Chars and Bytes
Splitting Characters
Scanning Charsets
Translation of Characters
Coding Systems
Input Methods
Locales
String Search
Regular Expressions
Regexp Search
Match Data
Saving Match Data
Standard Regexps
Searching and Case
Syntax of Regexps
Regexp Example
Syntax Descriptors
Syntax Table Functions
Parsing Expressions
Standard Syntax Tables
Syntax Table Internals
Syntax Class Table
Syntax Flags
Abbrev Mode
Abbrev Tables
Defining Abbrevs
Abbrev Files
Abbrev Expansion
Standard Abbrev Tables
Subprocess Creation
Synchronous Processes
Asynchronous Processes
Deleting Processes
Process Information
Input to Processes
Signals to Processes
Output from Processes
Sentinels
Network
Process Buffers
Filter Functions
Accepting Output
Starting Up
Getting Out
System Environment
Terminal Input
Terminal Output
Flow Control
Batch Mode
Startup Summary
Init File
Terminal-Specific
Command-Line Arguments
Killing Emacs
Suspending Emacs
Refresh Screen
Truncation
The Echo Area
Selective Display
Overlay Arrow
Temporary Displays
Waiting
Blinking
Usual Display
Beeping
Window Systems
Building Emacs
Pure Storage
Garbage Collection
Object Internals
Writing Emacs Primitives
Buffer Internals
Window Internals
Process Internals
Writing Customization Definitions
*********************************
This chapter describes how to declare user options for customization,
and also customization groups for classifying them. We use the term
"customization item" to include both kinds of customization
definitions--as well as face definitions (*note Defining Faces::).
* Menu:
* Common Keywords::
* Group Definitions::
* Variable Definitions::
* Customization Types::
back to top
Common Item 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 `:tag', can be used more than once in
a given item. Each use of the keyword has an independent effect. The
keyword `:tag' is an exception because any given item can only display
one name.
`:tag LABEL'
Use LABEL, a string, instead of the item's name, to label the item
in customization menus and buffers.
`:group GROUP'
Put this customization item in group GROUP. When you use `:group'
in a `defgroup', it makes the new group a subgroup of 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. Please don't overdo this, since the result would
be annoying.
`:link 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 LINK-DATA:
`(custom-manual INFO-NODE)'
Link to an Info node; INFO-NODE is a string which specifies
the node name, as in `"(emacs)Top"'. The link appears as
`[manual]' in the customization buffer.
`(info-link INFO-NODE)'
Like `custom-manual' except that the link appears in the
customization buffer with the Info node name.
`(url-link URL)'
Link to a web page; URL is a string which specifies the URL.
The link appears in the customization buffer as URL.
`(emacs-commentary-link LIBRARY)'
Link to the commentary section of a library; LIBRARY is a
string which specifies the library name.
You can specify the text to use in the customization buffer by
adding `:tag NAME' after the first element of the LINK-DATA; for
example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
Emacs manual which appears in the buffer as `foo'.
An item can have more than one external link; however, most items
have none at all.
`:load FILE'
Load file FILE (a string) before displaying this customization
item. Loading is done with `load-library', and only if the file is
not already loaded.
`:require FEATURE'
Require feature 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 `require'.
The most common reason to use `: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.
back to top
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 `M-x customize'.) Choose one or more of them (but not too many),
and add your group to each of them using the `:group' keyword.
The way to declare new customization groups is with `defgroup'.
- Macro: defgroup group members doc [keyword value]...
Declare GROUP as a customization group containing MEMBERS. Do not
quote the symbol GROUP. The argument DOC specifies the
documentation string for the group. It should not start with a
`*' as in `defcustom'; that convention is for variables only.
The argument MEMBERS is a list specifying an initial set of
customization items to be members of the group. However, most
often MEMBERS is `nil', and you specify the group's members by
using the `:group' keyword when defining those members.
If you want to specify group members through MEMBERS, each element
should have the form `(NAME WIDGET)'. Here NAME is a symbol, and
WIDGET is a widget type for editing that symbol. Useful widgets
are `custom-variable' for a variable, `custom-face' for a face,
and `custom-group' for a group.
When a new group is introduced into Emacs, use this keyword in
`defgroup':
`:version VERSION'
This option specifies that the group was first introduced in
Emacs version VERSION. The value VERSION must be a string.
Tag the group with a version like this when it is introduced,
rather than the individual members (*note Variable Definitions::).
In addition to the common keywords (*note Common Keywords::), you
can also use this keyword in `defgroup':
`:prefix PREFIX'
If the name of an item in the group starts with PREFIX, then
the tag for that item is constructed (by default) by omitting
PREFIX.
One group can have any number of prefixes.
The prefix-discarding feature is currently turned off, which means
that `: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 `defgroup'
definitions for various groups added `: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 `: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 `:prefix'
should not be used in that case.
It should be possible to recheck all the customization groups, delete
the `:prefix' specifications which give unclear results, and then turn
this feature back on, if someone would like to do the work.
back to top
Defining Customization Variables
================================
Use `defcustom' to declare user-editable variables.
- Macro: defcustom option default doc [keyword value]...
Declare OPTION as a customizable user option variable. Do not
quote OPTION. The argument DOC specifies the documentation string
for the variable. It should often start with a `*' to mark it as
a "user option" (*note Defining Variables::). Do not start the
documentation string with `*' for options which cannot or normally
should not be set with `set-variable'; examples of the former are
global minor mode options such as `global-font-lock-mode' and
examples of the latter are hooks.
If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT
should be an expression to compute the value; be careful in
writing it, because it can be evaluated on more than one occasion.
You should normally avoid using backquotes in DEFAULT because
they are not expanded when editing the value, causing list values
to appear to have the wrong structure.
When you evaluate a `defcustom' form with `C-M-x' in Emacs Lisp
mode (`eval-defun'), a special feature of `eval-defun' arranges to
set the variable unconditionally, without testing whether its
value is void. (The same feature applies to `defvar'.) *Note
Defining Variables::.
`defcustom' accepts the following additional keywords:
`:type TYPE'
Use TYPE as the data type for this option. It specifies which
values are legitimate, and how to display the value. *Note
Customization Types::, for more information.
`:options LIST'
Specify LIST as 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
`hook', `plist' and `alist'. See the definition of the individual
types for a description of how to use `:options'.
`:version VERSION'
This option specifies that the variable was first introduced, or
its default value was changed, in Emacs version VERSION. The value
VERSION must be a string. For example,
(defcustom foo-max 34
"*Maximum number of foo's allowed."
:type 'integer
:group 'foo
:version "20.3")
`:set SETFUNCTION'
Specify SETFUNCTION as the way to change the value of this option.
The function 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 SETFUNCTION is
`set-default'.
`:get GETFUNCTION'
Specify GETFUNCTION as the way to extract the value of this
option. The function 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
`default-value'.
`:initialize FUNCTION'
FUNCTION should be a function used to initialize the variable when
the `defcustom' is evaluated. It should take two arguments, the
symbol and value. Here are some predefined functions meant for
use in this way:
`custom-initialize-set'
Use the variable's `:set' function to initialize the
variable, but do not reinitialize it if it is already
non-void. This is the default `:initialize' function.
`custom-initialize-default'
Like `custom-initialize-set', but use the function
`set-default' to set the variable, instead of the variable's
`:set' function. This is the usual choice for a variable
whose `: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.
`custom-initialize-reset'
Always use the `:set' function to initialize the variable.
If the variable is already non-void, reset it by calling the
`:set' function using the current value (returned by the
`:get' method).
`custom-initialize-changed'
Use the `:set' function to initialize the variable, if it is
already set or has been customized; otherwise, just use
`set-default'.
`:set-after VARIABLES'
When setting variables according to saved customizations, make
sure to set the variables VARIABLES before this one; in other
words, delay setting this variable until after those others have
been handled. Use `:set-after' if setting this variable won't
work properly unless those other variables already have their
intended values.
The `: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 `:require'. *Note Common
Keywords::. Here is an example, from the library `paren.el':
(defcustom show-paren-mode nil
"Toggle Show Paren mode..."
:set (lambda (symbol value)
(show-paren-mode (or value 0)))
:initialize 'custom-initialize-default
:type 'boolean
:group 'paren-showing
:require 'paren)
If a customization item has a type such as `hook' or `alist', which
supports `:options', you can add additional options to the item,
outside the `defcustom' declaration, by calling `custom-add-option'.
For example, if you define a function `my-lisp-mode-initialization'
intended to be called from `emacs-lisp-mode-hook', you might want to
add that to the list of options for `emacs-lisp-mode-hook', but not by
editing its definition. You can do it thus:
(custom-add-option 'emacs-lisp-mode-hook
'my-lisp-mode-initialization)
- Function: custom-add-option symbol option
To the customization SYMBOL, add OPTION.
The precise effect of adding OPTION depends on the customization
type of SYMBOL.
Internally, `defcustom' uses the symbol property `standard-value' to
record the expression for the default value, and `saved-value' to
record the value saved by the user with the customization buffer. The
`saved-value' property is actually a list whose car is an expression
which evaluates to the value.
back to top
Customization Types
===================
When you define a user option with `defcustom', you must specify its
"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 `defcustom' with the `:type'
keyword. The argument of `:type' is evaluated; since types that vary
at run time are rarely useful, normally you use a quoted constant. For
example:
(defcustom diff-command "diff"
"*The command to use to run diff."
:type '(string)
:group 'diff)
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 (*note Type Keywords::).
Some of the type symbols do not use any arguments; those are called
"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 `string' as a customization type is equivalent to
`(string)'.
* Menu:
* Simple Types::
* Composite Types::
* Splicing into Lists::
* Type Keywords::
back to top
Simple Types
------------
This section describes all the simple customization types.
`sexp'
The value may be any Lisp object that can be printed and read
back. You can use `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.
`integer'
The value must be an integer, and is represented textually in the
customization buffer.
`number'
The value must be a number, and is represented textually in the
customization buffer.
`string'
The value must be a string, and the customization buffer shows
just the contents, with no delimiting `"' characters and no
quoting with `\'.
`regexp'
Like `string' except that the string must be a valid regular
expression.
`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.
`file'
The value must be a file name, and you can do completion with
`M-'.
`(file :must-match t)'
The value must be a file name for an existing file, and you can do
completion with `M-'.
`directory'
The value must be a directory name, and you can do completion with
`M-'.
`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 `:options' keyword in a hook variable's
`defcustom' to specify a list of functions recommended for use in
the hook; see *Note Variable Definitions::.
`alist'
The value must be a list of cons-cells, the CAR of each cell
representing a key, and the 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:
(alist :key-type KEY-TYPE :value-type VALUE-TYPE)
where KEY-TYPE and VALUE-TYPE are customization type
specifications. The default key type is `sexp', and the default
value type is `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 `:options' (see *Note 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 `:options'
keyword argument.
The argument to the `:options' keywords should be a list of option
specifications. Ordinarily, the options are simply atoms, which
are the specified keys. For example:
:options '("foo" "bar" "baz")
specifies that there are three "known" keys, namely `"foo"',
`"bar"' and `"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 `"bar"' key can only be an
integer. You can specify this by using a list instead of an atom
in the option specification. The first element will specify the
key, like before, while the second element will specify the value
type.
:options '("foo" ("bar" integer) "baz")
Finally, you may want to change how the key is presented. By
default, the key is simply shown as a `const', since the user
cannot change the special keys specified with the `:options'
keyword. However, you may want to use a more specialized type for
presenting the key, like `function-item' 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.
:options '("foo" ((function-item some-function) integer) "baz")
Many alists use lists with two elements, instead of cons cells.
For example,
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE).")
instead of
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
"Each element is a cons-cell (KEY . VALUE).")
Because of the way lists are implemented on top of cons cells, you
can treat `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.
(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)))
The `group' widget is used here instead of `list' only because the
formatting is better suited for the purpose.
Similarily, you can have alists with more values associated with
each key, using variations of this trick:
(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 age 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)))
`plist'
The `plist' custom type is similar to the `alist' (see above),
except that the information is stored as a property list, i.e. a
list of this form:
(KEY VALUE KEY VALUE KEY VALUE ...)
The default `:key-type' for `plist' is `symbol', rather than
`sexp'.
`symbol'
The value must be a symbol. It appears in the customization
buffer as the name of the symbol.
`function'
The value must be either a lambda expression or a function name.
When it is a function name, you can do completion with `M-'.
`variable'
The value must be a variable name, and you can do completion with
`M-'.
`face'
The value must be a symbol which is a face name, and you can do
completion with `M-'.
`boolean'
The value is boolean--either `nil' or `t'. Note that by using
`choice' and `const' together (see the next section), you can
specify that the value must be `nil' or `t', but also specify the
text to describe each value in a way that fits the specific
meaning of the alternative.
`coding-system'
The value must be a coding-system name, and you can do completion
with `M-'.
`color'
The value must be a valid color name, and you can do completion
with `M-'. A sample is provided,
back to top
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:
`(restricted-sexp :match-alternatives CRITERIA)'
The value may be any Lisp object that satisfies one of CRITERIA.
CRITERIA should be a list, and each element should be one of these
possibilities:
* A predicate--that is, a function of one argument that has no
side effects, and returns either `nil' or non-`nil' according
to the argument. Using a predicate in the list says that
objects for which the predicate returns non-`nil' are
acceptable.
* A quoted constant--that is, `'OBJECT'. This sort of element
in the list says that OBJECT itself is an acceptable value.
For example,
(restricted-sexp :match-alternatives
(integerp 't 'nil))
allows integers, `t' and `nil' as legitimate values.
The customization buffer shows all legitimate values using their
read syntax, and the user edits them textually.
`(cons CAR-TYPE CDR-TYPE)'
The value must be a cons cell, its CAR must fit CAR-TYPE, and its
CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a
customization type which matches values such as `("foo" . foo)'.
In the customization buffer, the CAR and the CDR are displayed and
edited separately, each according to the type that you specify for
it.
`(list ELEMENT-TYPES...)'
The value must be a list with exactly as many elements as the
ELEMENT-TYPES you have specified; and each element must fit the
corresponding ELEMENT-TYPE.
For example, `(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.
`(vector ELEMENT-TYPES...)'
Like `list' except that the value must be a vector instead of a
list. The elements work the same as in `list'.
`(choice ALTERNATIVE-TYPES...)'
The value must fit at least one of ALTERNATIVE-TYPES. For
example, `(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 `: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,
(choice (integer :tag "Number of spaces")
(string :tag "Literal text"))
so that the menu offers `Number of spaces' and `Literal Text'.
In any alternative for which `nil' is not a valid value, other than
a `const', you should specify a valid default for that alternative
using the `:value' keyword. *Note Type Keywords::.
`(radio ELEMENT-TYPES...)'
This is similar to `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
(`function-item' customization types).
`(const VALUE)'
The value must be VALUE--nothing else is allowed.
The main use of `const' is inside of `choice'. For example,
`(choice integer (const nil))' allows either an integer or `nil'.
`:tag' is often used with `const', inside of `choice'. For
example,
(choice (const :tag "Yes" t)
(const :tag "No" nil)
(const :tag "Ask" foo))
describes a variable for which `t' means yes, `nil' means no, and
`foo' means "ask."
`(other VALUE)'
This alternative can match any Lisp value, but if the user chooses
this alternative, that selects the value VALUE.
The main use of `other' is as the last element of `choice'. For
example,
(choice (const :tag "Yes" t)
(const :tag "No" nil)
(other :tag "Ask" foo))
describes a variable for which `t' means yes, `nil' means no, and
anything else means "ask." If the user chooses `Ask' from the
menu of alternatives, that specifies the value `foo'; but any
other value (not `t', `nil' or `foo') displays as `Ask', just like
`foo'.
`(function-item FUNCTION)'
Like `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
`:doc', or FUNCTION's own documentation string.
`(variable-item VARIABLE)'
Like `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
`:doc', or VARIABLE's own documentation string.
`(set TYPES...)'
The value must be a list, and each element of the list must match
one of the TYPES specified.
This appears in the customization buffer as a checklist, so that
each of TYPES may have either one corresponding element or none.
It is not possible to specify two different elements that match
the same one of TYPES. For example, `(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 `integer' in a `set'.
Most often, the TYPES in a `set' are `const' types, as shown here:
(set (const :bold) (const :italic))
Sometimes they describe possible elements in an alist:
(set (cons :tag "Height" (const height) integer)
(cons :tag "Width" (const width) integer))
That lets the user specify a height value optionally and a width
value optionally.
`(repeat ELEMENT-TYPE)'
The value must be a list and each element of the list must fit the
type ELEMENT-TYPE. This appears in the customization buffer as a
list of elements, with `[INS]' and `[DEL]' buttons for adding more
elements or removing elements.
back to top
Splicing into Lists
-------------------
The `:inline' feature lets you splice a variable number of elements
into the middle of a list or vector. You use it in a `set', `choice'
or `repeat' type which appears among the element-types of a `list' or
`vector'.
Normally, each of the element-types in a `list' or `vector'
describes one and only one element of the list or vector. Thus, if an
element-type is a `repeat', that specifies a list of unspecified length
which appears as one element.
But when the element-type uses `: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 `,@' in the backquote
construct.
For example, to specify a list whose first element must be `t' and
whose remaining arguments should be zero or more of `foo' and `bar',
use this customization type:
(list (const t) (set :inline t foo bar))
This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
bar)'.
When the element-type is a `choice', you use `:inline' not in the
`choice' itself, but in (some of) the alternatives of the `choice'.
For example, to match a list which must start with a file name,
followed either by the symbol `t' or two strings, use this
customization type:
(list file
(choice (const t)
(list :inline t string string)))
If the user chooses the first alternative in the choice, then the
overall list has two elements and the second element is `t'. If the
user chooses the second alternative, then the overall list has three
elements and the second and third must be strings.
back to top
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:
`:value DEFAULT'
This is used for a type that appears as an alternative inside of
`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 DEFAULT.
If `nil' is not a valid value for the alternative, then it is
essential to specify a valid default with `:value'.
`:format FORMAT-STRING'
This string will be inserted in the buffer to represent the value
corresponding to the type. The following `%' escapes are available
for use in FORMAT-STRING:
`%[BUTTON%]'
Display the text BUTTON marked as a button. The `: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.
`%{SAMPLE%}'
Show SAMPLE in a special face specified by `:sample-face'.
`%v'
Substitute the item's value. How the value is represented
depends on the kind of item, and (for variables) on the
customization type.
`%d'
Substitute the item's documentation string.
`%h'
Like `%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.
`%t'
Substitute the tag here. You specify the tag with the `:tag'
keyword.
`%%'
Display a literal `%'.
`:action ACTION'
Perform ACTION if the user clicks on a button.
`:button-face FACE'
Use the face FACE (a face name or a list of face names) for button
text displayed with `%[...%]'.
`:button-prefix PREFIX'
`:button-suffix SUFFIX'
These specify the text to display before and after a button. Each
can be:
`nil'
No text is inserted.
a string
The string is inserted literally.
a symbol
The symbol's value is used.
`:tag TAG'
Use TAG (a string) as the tag for the value (or part of the value)
that corresponds to this type.
`:doc DOC'
Use 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 `:format', and use `%d' or `%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 `:choice' type or the parts of some other composite type.
`:help-echo MOTION-DOC'
When you move to this item with `widget-forward' or
`widget-backward', it will display the string MOTION-DOC in the
echo area. In addition, MOTION-DOC is used as the mouse
`help-echo' string and may actually be a function or form evaluated
to yield a help string as for `help-echo' text properties.
`:match FUNCTION'
Specify how to decide whether a value matches the type. The
corresponding value, FUNCTION, should be a function that accepts
two arguments, a widget and a value; it should return non-`nil' if
the value is acceptable.
back to top
elisp : Customization
table of contents
Introduction
Coding Conventions
Lisp Data Types
Numbers
Strings and Characters
Lists
Sequences Arrays Vectors
Hash Tables
Symbols
Evaluation
Control Structures
Variables
Functions
Macros
Customization
Loading
Byte Compilation
Advising Functions
Debugging
Read and Print
Minibuffers
Command Loop
Keymaps
Modes
Documentation
Files
Backups and Auto-Saving
Buffers
Windows
Frames
Positions
Markers
Text
Non-ASCII Characters
Searching and Matching
Syntax Tables
Abbrevs
Processes
Display
Calendar
System Interface
Antinews
GNU Free Documentation License
GPL
Tips
GNU Emacs Internals
Standard Errors
Standard Buffer-Local Variables
Standard Keymaps
Standard Hooks
Index
New Symbols
Caveats
Lisp History
Conventions
Acknowledgements
Some Terms
nil and t
Evaluation Notation
Printing Notation
Error Messages
Buffer Text Notation
Format of Descriptions
Coding Conventions
Compilation Tips
Documentation Tips
Comment Tips
Library Headers
A Sample Function Description
A Sample Variable Description
Printed Representation
Comments
Programming Types
Editing Types
Type Predicates
Equality Predicates
Integer Type
Floating Point Type
Character Type
Sequence Type
Cons Cell Type
Array Type
String Type
Vector Type
Symbol Type
Function Type
Macro Type
Primitive Function Type
Byte-Code Type
Autoload Type
Dotted Pair Notation
Association List Type
Buffer Type
Window Type
Window Configuration Type
Marker Type
Process Type
Stream Type
Keymap Type
Overlay Type
Integer Basics
Float Basics
Predicates on Numbers
Comparison of Numbers
Arithmetic Operations
Bitwise Operations
Numeric Conversions
Math Functions
Random Numbers
String Basics
Predicates for Strings
Creating Strings
Text Comparison
String Conversion
Formatting Strings
Case Conversion
Cons Cells
Lists as Boxes
List-related Predicates
List Elements
Building Lists
Modifying Lists
Sets And Lists
Association Lists
Setcar
Setcdr
Rearrangement
Sequence Functions
Arrays
Array Functions
Vectors
Symbol Components
Definitions
Creating Symbols
Property Lists
Intro Eval
Eval
Forms
Quoting
Self-Evaluating Forms
Symbol Forms
Classifying Lists
Function Forms
Macro Forms
Special Forms
Autoloading
Sequencing
Conditionals
Combining Conditions
Iteration
Nonlocal Exits
Catch and Throw
Examples of Catch
Errors
Cleanups
Signaling Errors
Processing of Errors
Handling Errors
Error Symbols
Global Variables
Constant Variables
Local Variables
Void Variables
Defining Variables
Accessing Variables
Setting Variables
Variable Scoping
Buffer-Local Variables
Scope
Extent
Impl of Scope
Using Scoping
Intro to Buffer-Local
Creating Buffer-Local
Default Value
What Is a Function
Lambda Expressions
Function Names
Defining Functions
Calling Functions
Mapping Functions
Anonymous Functions
Function Cells
Related Topics
Lambda Components
Simple Lambda
Argument List
Function Documentation
Simple Macro
Expansion
Compiling Macros
Defining Macros
Backquote
Problems with Macros
How Programs Do Loading
Autoload
Named Features
Repeated Loading
Compilation Functions
Disassembly
Simple Advice
Defining Advice
Computed Advice
Activation of Advice
Enabling Advice
Preactivation
Argument Access in Advice
Subr Arguments
Combined Definition
Debugger
Syntax Errors
Compilation Errors
Edebug
Error Debugging
Function Debugging
Explicit Debug
Using Debugger
Debugger Commands
Invoking the Debugger
Internals of Debugger
Excess Open
Excess Close
Streams Intro
Input Streams
Input Functions
Output Streams
Output Functions
Intro to Minibuffers
Text from Minibuffer
Object from Minibuffer
Completion
Yes-or-No Queries
Minibuffer Misc
Basic Completion
Minibuffer Completion
Completion Commands
High-Level Completion
Reading File Names
Programmed Completion
Command Overview
Defining Commands
Interactive Call
Command Loop Info
Input Events
Reading Input
Waiting
Quitting
Prefix Command Arguments
Recursive Editing
Disabling Commands
Command History
Keyboard Macros
Using Interactive
Interactive Codes
Interactive Examples
Keymap Terminology
Format of Keymaps
Creating Keymaps
Inheritance and Keymaps
Prefix Keys
Menu Keymaps
Active Keymaps
Key Lookup
Functions for Key Lookup
Changing Key Bindings
Key Binding Commands
Scanning Keymaps
Major Modes
Minor Modes
Mode Line Format
Hooks
Major Mode Conventions
Example Major Modes
Auto Major Mode
Mode Help
Minor Mode Conventions
Keymaps and Minor Modes
Mode Line Data
Mode Line Variables
%-Constructs
Documentation Basics
Accessing Documentation
Keys in Documentation
Describing Characters
Help Functions
Visiting Files
Saving Buffers
Reading from Files
Writing to Files
File Locks
Information about Files
Contents of Directories
Changing Files
File Names
Visiting Functions
Subroutines of Visiting
Testing Accessibility
Kinds of Files
File Attributes
File Name Components
Directory Names
Relative File Names
File Name Expansion
Unique File Names
File Name Completion
Backup Files
Auto-Saving
Reverting
Making Backups
Rename or Copy
Numbered Backups
Backup Names
Buffer Basics
Buffer Names
Buffer File Name
Buffer Modification
Modification Time
Read Only Buffers
The Buffer List
Creating Buffers
Killing Buffers
Current Buffer
Basic Windows
Splitting Windows
Deleting Windows
Selecting Windows
Cyclic Window Ordering
Buffers and Windows
Displaying Buffers
Window Point
Window Start
Vertical Scrolling
Horizontal Scrolling
Size of Window
Resizing Windows
Window Configurations
Creating Frames
Multiple Displays
Frame Parameters
Frame Titles
Deleting Frames
Finding All Frames
Frames and Windows
Minibuffers and Frames
Input Focus
Visibility of Frames
Raising and Lowering
Frame Configurations
Mouse Tracking
Mouse Position
Pop-Up Menus
Dialog Boxes
Pointer Shapes
Window System Selections
Color Names
Resources
Display Feature Testing
Point
Motion
Excursions
Narrowing
Character Motion
Word Motion
Buffer End Motion
Text Lines
Screen Lines
List Motion
Skipping Characters
Overview of Markers
Predicates on Markers
Creating Markers
Information from Markers
Moving Markers
The Mark
The Region
Near Point
Buffer Contents
Insertion
Commands for Insertion
Deletion
User-Level Deletion
The Kill Ring
Undo
Auto Filling
Filling
Margins
Sorting
Indentation
Columns
Case Changes
Text Properties
Substitution
Transposition
Registers
Change Hooks
Kill Ring Concepts
Kill Functions
Yank Commands
Low-Level Kill Ring
Internals of Kill Ring
Primitive Indent
Mode-Specific Indent
Region Indent
Relative Indent
Indent Tabs
Motion by Indent
Examining Properties
Changing Properties
Property Search
Special Properties
Format Properties
Sticky Properties
Saving Properties
Lazy Properties
Clickable Text
Fields
Not Intervals
Text Representations
Converting Representations
Selecting a Representation
Character Codes
Character Sets
Chars and Bytes
Splitting Characters
Scanning Charsets
Translation of Characters
Coding Systems
Input Methods
Locales
String Search
Regular Expressions
Regexp Search
Match Data
Saving Match Data
Standard Regexps
Searching and Case
Syntax of Regexps
Regexp Example
Syntax Descriptors
Syntax Table Functions
Parsing Expressions
Standard Syntax Tables
Syntax Table Internals
Syntax Class Table
Syntax Flags
Abbrev Mode
Abbrev Tables
Defining Abbrevs
Abbrev Files
Abbrev Expansion
Standard Abbrev Tables
Subprocess Creation
Synchronous Processes
Asynchronous Processes
Deleting Processes
Process Information
Input to Processes
Signals to Processes
Output from Processes
Sentinels
Network
Process Buffers
Filter Functions
Accepting Output
Starting Up
Getting Out
System Environment
Terminal Input
Terminal Output
Flow Control
Batch Mode
Startup Summary
Init File
Terminal-Specific
Command-Line Arguments
Killing Emacs
Suspending Emacs
Refresh Screen
Truncation
The Echo Area
Selective Display
Overlay Arrow
Temporary Displays
Waiting
Blinking
Usual Display
Beeping
Window Systems
Building Emacs
Pure Storage
Garbage Collection
Object Internals
Writing Emacs Primitives
Buffer Internals
Window Internals
Process Internals
home/search |
what's new |
help
