@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002,
-@c 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
@node Modes, Documentation, Keymaps, Top
elements of the form @code{(@var{interpreter} . @var{mode})}; for
example, @code{("perl" . perl-mode)} is one element present by
default. The element says to use mode @var{mode} if the file
-specifies an interpreter which matches @var{interpreter}. The value
-of @var{interpreter} is actually a regular expression. @xref{Regular
-Expressions}.
+specifies an interpreter which matches @var{interpreter}.
@end defvar
@defvar magic-mode-alist
@end deffn
@defvar major-mode
-This variable holds the symbol for the current buffer's major mode.
-This symbol should have a function definition that is the command to
-switch to that major mode. The @code{describe-mode} function uses the
-documentation string of the function as the documentation of the major
-mode.
+This buffer-local variable holds the symbol for the current buffer's
+major mode. This symbol should have a function definition that is the
+command to switch to that major mode. The @code{describe-mode}
+function uses the documentation string of the function as the
+documentation of the major mode.
@end defvar
@node Derived Modes
@var{hookvars}.
@end defun
-@defmac delay-mode-hooks body...
+@defmac delay-mode-hooks body@dots{}
This macro executes @var{body} like @code{progn}, but all calls to
@code{run-mode-hooks} inside @var{body} delay running their hooks.
They will be run by the first call to @code{run-mode-hooks} after exit
There are conventions for writing minor modes just as there are for
major modes. Several of the major mode conventions apply to minor
modes as well: those regarding the name of the mode initialization
-function, the names of global symbols, and the use of keymaps and
-other tables.
+function, the names of global symbols, the use of a hook at the end of
+the initialization function, and the use of keymaps and other tables.
In addition, there are several conventions that are specific to
minor modes. (The easiest way to follow all the conventions is to use
"Toggle msb-mode.
Setting this variable directly does not take effect;
use either \\[customize] or the function `msb-mode'."
- :set (lambda (symbol value)
- (msb-mode (or value 0)))
+ :set 'custom-set-minor-mode
:initialize 'custom-initialize-default
:version "20.4"
:type 'boolean
The macro @code{define-minor-mode} offers a convenient way of
implementing a mode in one self-contained definition.
-@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args... body...
+@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
@tindex define-minor-mode
This macro defines a new minor mode whose name is @var{mode} (a
symbol). It defines a command named @var{mode} to toggle the minor
@end defmac
The initial value must be @code{nil} except in cases where (1) the
-mode is preloaded in Emacs, or (2) it is painless to for loading to
+mode is preloaded in Emacs, or (2) it is painless for loading to
enable the mode even though the user did not request it. For
instance, if the mode has no effect unless something else is enabled,
and will always be loaded by that time, enabling it by default is
:group 'hunger)
@end smallexample
-@defmac define-global-minor-mode global-mode mode turn-on keyword-args...
+@defmac define-global-minor-mode global-mode mode turn-on keyword-args@dots{}
This defines a global minor mode named @var{global-mode} whose meaning
is to enable the buffer-local minor mode @var{mode} in every buffer.
To turn on the minor mode in a buffer, it uses the function
minor modes.
@menu
-* Mode Line Basics::
-* Mode Line Data:: The data structure that controls the mode line.
+* Base: Mode Line Basics. Basic ideas of mode line control.
+* Data: Mode Line Data. The data structure that controls the mode line.
+* Top: Mode Line Top. The top level variable, mode-line-format.
* Mode Line Variables:: Variables used in that data structure.
* %-Constructs:: Putting information into a mode line.
* Properties in Mode:: Using text properties in the mode line.
@subsection Mode Line Basics
@code{mode-line-format} is a buffer-local variable that holds a
-template used to display the mode line of the current buffer. All
-windows for the same buffer use the same @code{mode-line-format}, so
-their mode lines appear the same---except for scrolling percentages, and
-line and column numbers, since those depend on point and on how the
-window is scrolled. @code{header-line-format} is used likewise for
-header lines.
+@dfn{mode line construct}, a kind of template, which controls the
+display the mode line of the current buffer. All windows for the same
+buffer use the same @code{mode-line-format}, so their mode lines
+appear the same---except for scrolling percentages, and line and
+column numbers, since those depend on point and on how the window is
+scrolled. The value of @code{header-line-format} specifies the
+buffer's header line in the same way, with a mode line construct.
For efficiency, Emacs does not recompute the mode line and header
line of a window in every redisplay. It does so when circumstances
color using the face @code{mode-line}. Other windows' mode lines
appear in the face @code{mode-line-inactive} instead. @xref{Faces}.
- A window that is just one line tall does not display either a mode
-line or a header line, even if the variables call for one. A window
-that is two lines tall cannot display both a mode line and a header
-line at once; if the variables call for both, only the mode line
-actually appears.
-
@node Mode Line Data
@subsection The Data Structure of the Mode Line
@cindex mode-line construct
- The mode-line contents are controlled by a data structure of lists,
-strings, symbols, and numbers kept in buffer-local variables. The data
-structure is called a @dfn{mode-line construct}, and it is built in
-recursive fashion out of simpler mode-line constructs. The same data
-structure is used for constructing frame titles (@pxref{Frame Titles})
-and header lines (@pxref{Header Lines}).
-
-@defvar mode-line-format
-The value of this variable is a mode-line construct with overall
-responsibility for the mode-line format. The value of this variable
-controls which other variables are used to form the mode-line text, and
-where they appear.
+ The mode-line contents are controlled by a data structure called a
+@dfn{mode-line construct}, made up of lists, strings, symbols, and
+numbers kept in buffer-local variables. Each data type has a specific
+meaning for the mode-line appearance, as described below. The same
+data structure is used for constructing frame titles (@pxref{Frame
+Titles}) and header lines (@pxref{Header Lines}).
-If you set this variable to @code{nil} in a buffer, that buffer does not
-have a mode line.
-@end defvar
+ A mode-line construct may be as simple as a fixed string of text,
+but it usually specifies how to combine fixed strings with variables'
+values to construct the text. Many of these variables are themselves
+defined to have mode-line constructs as their values.
- A mode-line construct may be as simple as a fixed string of text, but
-it usually specifies how to use other variables to construct the text.
-Many of these variables are themselves defined to have mode-line
-constructs as their values.
-
- The default value of @code{mode-line-format} incorporates the values
-of variables such as @code{mode-line-position} and
-@code{mode-line-modes} (which in turn incorporates the values of the
-variables @code{mode-name} and @code{minor-mode-alist}). Because of
-this, very few modes need to alter @code{mode-line-format} itself. For
-most purposes, it is sufficient to alter some of the variables that
-@code{mode-line-format} either directly or indirectly refers to.
-
- A mode-line construct may be a list, a symbol, or a string. If the
-value is a list, each element may be a list, a symbol, or a string.
-
- The mode line can display various faces, if the strings that control
-it have the @code{face} property. @xref{Properties in Mode}. In
-addition, the face @code{mode-line} is used as a default for the whole
-mode line (@pxref{Standard Faces}).
+ Here are the meanings of various data types as mode-line constructs:
@table @code
@cindex percent symbol in mode line
@item @var{string}
-A string as a mode-line construct is displayed verbatim in the mode line
-except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
-specify the field width for space filling on the right (i.e., the data
-is left justified). @xref{%-Constructs}.
+A string as a mode-line construct appears verbatim in the mode line
+except for @dfn{@code{%}-constructs} in it. These stand for
+substitution of other data; see @ref{%-Constructs}.
+
+If the string has @code{face} properties, they are copied into the
+mode line contents too (@pxref{Properties in Mode}). Any characters
+in the mode line which have no @code{face} properties are displayed,
+by default, in the face @code{mode-line} or @code{mode-line-inactive}
+(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}).
@item @var{symbol}
A symbol as a mode-line construct stands for its value. The value of
displayed verbatim: the @code{%}-constructs are not recognized.
Unless @var{symbol} is marked as ``risky'' (i.e., it has a
-non-@code{nil} @code{risky-local-variable} property), all properties in
-any strings, as well as all @code{:eval} and @code{:propertize} forms in
-the value of that symbol will be ignored.
+non-@code{nil} @code{risky-local-variable} property), all text
+properties specified in @var{symbol}'s value are ignored. This
+includes the text properties of strings in @var{symbol}'s value, as
+well as all @code{:eval} and @code{:propertize} forms in it.
-@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
+@item (@var{string} @var{rest}@dots{})
+@itemx (@var{list} @var{rest}@dots{})
A list whose first element is a string or list means to process all the
elements recursively and concatenate the results. This is the most
common form of mode-line construct.
@item (:propertize @var{elt} @var{props}@dots{})
A list whose first element is the symbol @code{:propertize} says to
-process the mode-line construct @var{elt} recursively and add the text
+process the mode-line construct @var{elt} recursively, then add the text
properties specified by @var{props} to the result. The argument
@var{props} should consist of zero or more pairs @var{text-property}
@var{value}. (This feature is new as of Emacs 22.1.)
the top of the window is to use a list like this: @code{(-3 "%p")}.
@end table
+@node Mode Line Top
+@subsection The Top Level of Mode Line Control
+
+ The variable in overall control of the mode line is
+@code{mode-line-format}.
+
+@defvar mode-line-format
+The value of this variable is a mode-line construct that controls the
+contents of the mode-line. It is always buffer-local in all buffers.
+
+If you set this variable to @code{nil} in a buffer, that buffer does
+not have a mode line. (A window that is just one line tall never
+displays a mode line.)
+@end defvar
+
+ The default value of @code{mode-line-format} is designed to use the
+values of other variables such as @code{mode-line-position} and
+@code{mode-line-modes} (which in turn incorporates the values of the
+variables @code{mode-name} and @code{minor-mode-alist}). Very few
+modes need to alter @code{mode-line-format} itself. For most
+purposes, it is sufficient to alter some of the variables that
+@code{mode-line-format} either directly or indirectly refers to.
+
If you do alter @code{mode-line-format} itself, the new value should
use the same variables that appear in the default value (@pxref{Mode
Line Variables}), rather than duplicating their contents or displaying
@node Mode Line Variables
@subsection Variables Used in the Mode Line
- This section describes variables incorporated by the
-standard value of @code{mode-line-format} into the text of the mode
-line. There is nothing inherently special about these variables; any
-other variables could have the same effects on the mode line if
-@code{mode-line-format} were changed to use them.
+ This section describes variables incorporated by the standard value
+of @code{mode-line-format} into the text of the mode line. There is
+nothing inherently special about these variables; any other variables
+could have the same effects on the mode line if
+@code{mode-line-format}'s value were changed to use them. However,
+various parts of Emacs set these variables on the understanding that
+they will control parts of the mode line; therefore, practically
+speaking, it is essential for the mode line to use them.
@defvar mode-line-mule-info
This variable holds the value of the mode-line construct that displays
@node %-Constructs
@subsection @code{%}-Constructs in the Mode Line
- The following table lists the recognized @code{%}-constructs and what
-they mean. In any construct except @samp{%%}, you can add a decimal
-integer after the @samp{%} to specify a minimum field width. If the
-width is less, the field is padded with spaces to the right.
+ Strings used as mode-line constructs can use certain
+@code{%}-constructs to substitute various kinds of data. Here is a
+list of the defined @code{%}-constructs, and what they mean. In any
+construct except @samp{%%}, you can add a decimal integer after the
+@samp{%} to specify a minimum field width. If the width is less, the
+field is padded with spaces to the right.
@table @code
@item %b
The value of @code{mode-name}.
@item %M
-The value of @code{global-mode-string}. Currently, only
-@code{display-time} modifies the value of @code{global-mode-string}.
+The value of @code{global-mode-string}.
@end table
@node Properties in Mode
It is normally @code{nil}, so that ordinary buffers have no header line.
@end defvar
+ A window that is just one line tall never displays a header line. A
+window that is two lines tall cannot display both a mode line and a
+header line at once; if it has a mode line, then it does not display a
+header line.
+
@node Emulating Mode Line
@subsection Emulating Mode-Line Formatting
finds the next ``definition'' to put in the buffer index, scanning
backward in the buffer from point. It should return @code{nil} if it
doesn't find another ``definition'' before point. Otherwise it should
-leave point at the place it finds a ``definition,'' and return any
+leave point at the place it finds a ``definition'' and return any
non-@code{nil} value.
Setting this variable makes it buffer-local in the current buffer.
* Font Lock Basics:: Overview of customizing Font Lock.
* Search-based Fontification:: Fontification based on regexps.
* Customizing Keywords:: Customizing search-based fontification.
+* Region to Fontify:: Controlling which region gets refontified
+ after a buffer change.
* Other Font Lock Variables:: Additional customization facilities.
* Levels of Font Lock:: Each mode can define alternative levels
so that the user can select more or less.
search-based fontification rules to a major mode, and
@code{font-lock-remove-keywords} to removes rules.
-@defun font-lock-add-keywords mode keywords &optional append
+@defun font-lock-add-keywords mode keywords &optional how
This function adds highlighting @var{keywords}, for the current buffer
or for major mode @var{mode}. The argument @var{keywords} should be a
list with the same format as the variable @code{font-lock-keywords}.
@code{font-lock-add-keywords} is usually used in mode hook functions.
By default, @var{keywords} are added at the beginning of
-@code{font-lock-keywords}. If the optional argument @var{append} is
+@code{font-lock-keywords}. If the optional argument @var{how} is
@code{set}, they are used to replace the value of
-@code{font-lock-keywords}. If @var{append} is any other
-non-@code{nil} value, they are added at the end of
-@code{font-lock-keywords}.
+@code{font-lock-keywords}. If @var{how} is any other non-@code{nil}
+value, they are added at the end of @code{font-lock-keywords}.
Some modes provide specialized support you can use in additional
highlighting patterns. See the variables
This function removes @var{keywords} from @code{font-lock-keywords}
for the current buffer or for major mode @var{mode}. As in
@code{font-lock-add-keywords}, @var{mode} should be a major mode
-command name or @code{nil}. All the caveats and requirments for
+command name or @code{nil}. All the caveats and requirements for
@code{font-lock-add-keywords} apply here too.
@end defun
font-lock-keyword-face)))))
@end smallexample
+@node Region to Fontify
+@subsection Region to Fontify after a Buffer Change
+
+ When a buffer is changed, the region that Font Lock refontifies is by
+default the smallest sequence of whole lines that spans the change.
+While this works well most of the time, sometimes it doesn't---for
+example, when a buffer change has changed the syntactic meaning of text
+on an earlier line.
+
+You can enlarge (or even reduce) the region to fontify by setting either
+of the following variables:
+
+@defvar font-lock-extend-region-function
+This buffer-local variable is either @code{nil} or is a function that
+determines the region to fontify, which Emacs then calls after each
+buffer change.
+
+The function is given three parameters, the standard @var{beg},
+@var{end}, and @var{old-len} from after-change-functions (@pxref{Change
+Hooks}). It should return either a cons of the beginning and end buffer
+positions (in that order) of the region to fontify, or @code{nil} (which
+directs the caller to fontify the default region). This function need
+not preserve point or the match-data, but must preserve the current
+restriction. The region it returns may start or end in the middle of a
+line.
+
+Since this function is called after every buffer change, it should be
+reasonably fast.
+@end defvar
+
@node Other Font Lock Variables
@subsection Other Font Lock Variables
@code{font-lock-default-unfontify-region}.
@end defvar
-@defvar font-lock-lines-before
-This variable specifies the number of extra lines to consider when
-refontifying the buffer after each text change. Font lock begins
-refontifying from that number of lines before the changed region. The
-default is 1, but using a larger value can be useful for coping with
-multi-line patterns.
-@end defvar
-
@ignore
@defvar font-lock-inhibit-thing-lock
List of Font Lock mode related modes that should not be turned on.