1 |
@c -*-texinfo-*- |
@c -*-texinfo-*- |
2 |
@c This is part of the GNU Emacs Lisp Reference Manual. |
@c This is part of the GNU Emacs Lisp Reference Manual. |
3 |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003 |
4 |
@c Free Software Foundation, Inc. |
@c Free Software Foundation, Inc. |
5 |
@c See the file elisp.texi for copying conditions. |
@c See the file elisp.texi for copying conditions. |
6 |
@setfilename ../info/modes |
@setfilename ../info/modes |
7 |
@node Modes, Documentation, Keymaps, Top |
@node Modes, Documentation, Keymaps, Top |
8 |
@chapter Major and Minor Modes |
@chapter Major and Minor Modes |
9 |
@cindex mode |
@cindex mode |
10 |
|
|
236 |
@item |
@item |
237 |
The mode should specify how Imenu should find the definitions or |
The mode should specify how Imenu should find the definitions or |
238 |
sections of a buffer, by setting up a buffer-local value for the |
sections of a buffer, by setting up a buffer-local value for the |
239 |
variable @code{imenu-generic-expression} or |
variable @code{imenu-generic-expression}, for the pair of variables |
240 |
|
@code{imenu-prev-index-position-function} and |
241 |
|
@code{imenu-extract-index-name-function}, or for the variable |
242 |
@code{imenu-create-index-function} (@pxref{Imenu}). |
@code{imenu-create-index-function} (@pxref{Imenu}). |
243 |
|
|
244 |
@item |
@item |
265 |
@cindex major mode hook |
@cindex major mode hook |
266 |
Each major mode should have a @dfn{mode hook} named |
Each major mode should have a @dfn{mode hook} named |
267 |
@code{@var{modename}-mode-hook}. The major mode command should run that |
@code{@var{modename}-mode-hook}. The major mode command should run that |
268 |
hook, with @code{run-hooks}, as the very last thing it |
hook, with @code{run-mode-hooks}, as the very last thing it |
269 |
does. @xref{Hooks}. |
does. @xref{Hooks}. |
270 |
|
|
271 |
@item |
@item |
272 |
The major mode command may also run the hooks of some more basic modes. |
The major mode command may start by calling some other major mode |
273 |
For example, @code{indented-text-mode} runs @code{text-mode-hook} as |
command (called the @dfn{parent mode}) and then alter some of its |
274 |
well as @code{indented-text-mode-hook}. It may run these other hooks |
settings. A mode that does this is called a @dfn{derived mode}. The |
275 |
immediately before the mode's own hook (that is, after everything else), |
recommended way to define one is to use @code{define-derived-mode}, |
276 |
or it may run them earlier. |
but this is not required. Such a mode should use |
277 |
|
@code{delay-mode-hooks} around its entire body, including the call to |
278 |
|
the parent mode command and the final call to @code{run-mode-hooks}. |
279 |
|
(Using @code{define-derived-mode} does this automatically.) |
280 |
|
|
281 |
@item |
@item |
282 |
If something special should be done if the user switches a buffer from |
If something special should be done if the user switches a buffer from |
288 |
major mode command symbol should have a property named @code{mode-class} |
major mode command symbol should have a property named @code{mode-class} |
289 |
with value @code{special}, put on as follows: |
with value @code{special}, put on as follows: |
290 |
|
|
291 |
@cindex @code{mode-class} property |
@kindex mode-class @r{(property)} |
292 |
@cindex @code{special} |
@cindex @code{special} |
293 |
@example |
@example |
294 |
(put 'funny-mode 'mode-class 'special) |
(put 'funny-mode 'mode-class 'special) |
364 |
@end group |
@end group |
365 |
@end smallexample |
@end smallexample |
366 |
|
|
367 |
Here is the complete major mode function definition for Text mode: |
This was formerly the complete major mode function definition for Text mode: |
368 |
|
|
369 |
@smallexample |
@smallexample |
370 |
@group |
@group |
393 |
@group |
@group |
394 |
(setq mode-name "Text") |
(setq mode-name "Text") |
395 |
(setq major-mode 'text-mode) |
(setq major-mode 'text-mode) |
396 |
(run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} |
(run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} |
397 |
; @r{customize the mode with a hook.} |
; @r{customize the mode with a hook.} |
398 |
@end group |
@end group |
399 |
@end smallexample |
@end smallexample |
548 |
@group |
@group |
549 |
(setq imenu-case-fold-search t) |
(setq imenu-case-fold-search t) |
550 |
(set-syntax-table lisp-mode-syntax-table) |
(set-syntax-table lisp-mode-syntax-table) |
551 |
(run-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} |
(run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} |
552 |
; @r{hook to customize the mode.} |
; @r{hook to customize the mode.} |
553 |
@end group |
@end group |
554 |
@end smallexample |
@end smallexample |
824 |
way to insert the necessary hook into the rest of Emacs. Minor mode |
way to insert the necessary hook into the rest of Emacs. Minor mode |
825 |
keymaps make this easier than it used to be. |
keymaps make this easier than it used to be. |
826 |
|
|
827 |
|
@defvar minor-mode-list |
828 |
|
The value of this variable is a list of all minor mode commands. |
829 |
|
@end defvar |
830 |
|
|
831 |
@menu |
@menu |
832 |
* Minor Mode Conventions:: Tips for writing a minor mode. |
* Minor Mode Conventions:: Tips for writing a minor mode. |
833 |
* Keymaps and Minor Modes:: How a minor mode can have its own keymap. |
* Keymaps and Minor Modes:: How a minor mode can have its own keymap. |
873 |
Its job is to enable and disable the mode by setting the variable. |
Its job is to enable and disable the mode by setting the variable. |
874 |
|
|
875 |
The command should accept one optional argument. If the argument is |
The command should accept one optional argument. If the argument is |
876 |
@code{nil}, it should toggle the mode (turn it on if it is off, and off |
@code{nil}, it should toggle the mode (turn it on if it is off, and |
877 |
if it is on). Otherwise, it should turn the mode on if the argument is |
off if it is on). It should turn the mode on if the argument is a |
878 |
a positive integer, a symbol other than @code{nil} or @code{-}, or a |
positive integer, the symbol @code{t}, or a list whose @sc{car} is one |
879 |
list whose @sc{car} is such an integer or symbol; it should turn the |
of those. It should turn the mode off if the argument is a negative |
880 |
mode off otherwise. |
integer or zero, the symbol @code{-}, or a list whose @sc{car} is one |
881 |
|
of those. The meaning of other arguments is not specified. |
882 |
|
|
883 |
Here is an example taken from the definition of @code{transient-mark-mode}. |
Here is an example taken from the definition of @code{transient-mark-mode}. |
884 |
It shows the use of @code{transient-mark-mode} as a variable that enables or |
It shows the use of @code{transient-mark-mode} as a variable that enables or |
990 |
implementing a mode in one self-contained definition. It supports only |
implementing a mode in one self-contained definition. It supports only |
991 |
buffer-local minor modes, not global ones. |
buffer-local minor modes, not global ones. |
992 |
|
|
993 |
@defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body... |
@defmac define-minor-mode mode doc [init-value [lighter [keymap keyword-args... body...]]] |
994 |
@tindex define-minor-mode |
@tindex define-minor-mode |
995 |
This macro defines a new minor mode whose name is @var{mode} (a symbol). |
This macro defines a new minor mode whose name is @var{mode} (a |
996 |
It defines a command named @var{mode} to toggle the minor |
symbol). It defines a command named @var{mode} to toggle the minor |
997 |
mode, with @var{doc} as its documentation string. It also defines a |
mode, with @var{doc} as its documentation string. It also defines a |
998 |
variable named @var{mode}, which is set to @code{t} or @code{nil} by |
variable named @var{mode}, which is set to @code{t} or @code{nil} by |
999 |
enabling or disabling the mode. The variable is initialized to |
enabling or disabling the mode. The variable is initialized to |
1000 |
@var{init-value}. |
@var{init-value}. |
1001 |
|
|
1002 |
The command named @var{mode} finishes by executing the @var{body} forms, |
The string @var{lighter} says what to display in the mode line |
|
if any, after it has performed the standard actions such as setting |
|
|
the variable named @var{mode}. |
|
|
|
|
|
The string @var{mode-indicator} says what to display in the mode line |
|
1003 |
when the mode is enabled; if it is @code{nil}, the mode is not displayed |
when the mode is enabled; if it is @code{nil}, the mode is not displayed |
1004 |
in the mode line. |
in the mode line. |
1005 |
|
|
1010 |
@example |
@example |
1011 |
(@var{key-sequence} . @var{definition}) |
(@var{key-sequence} . @var{definition}) |
1012 |
@end example |
@end example |
1013 |
|
|
1014 |
|
The @var{keyword-args} consist of keywords followed by corresponding |
1015 |
|
values. A few keywords have special meanings: |
1016 |
|
|
1017 |
|
@table @code |
1018 |
|
@item :global @var{global} |
1019 |
|
If non-@code{nil} specifies that the minor mode should be global. |
1020 |
|
By default, minor modes are buffer-local. |
1021 |
|
|
1022 |
|
@item :init-value @var{init-value} |
1023 |
|
This is equivalent to specifying @var{init-value} positionally. |
1024 |
|
|
1025 |
|
@item :lighter @var{lighter} |
1026 |
|
This is equivalent to specifying @var{lighter} positionally. |
1027 |
|
|
1028 |
|
@item :keymap @var{keymap} |
1029 |
|
This is equivalent to specifying @var{keymap} positionally. |
1030 |
|
@end table |
1031 |
|
|
1032 |
|
Any other keyword arguments are passed passed directly to the |
1033 |
|
@code{defcustom} generated for the variable @var{mode}. |
1034 |
|
|
1035 |
|
The command named @var{mode} finishes by executing the @var{body} forms, |
1036 |
|
if any, after it has performed the standard actions such as setting |
1037 |
|
the variable named @var{mode}. |
1038 |
@end defmac |
@end defmac |
1039 |
|
|
1040 |
|
@findex easy-mmode-define-minor-mode |
1041 |
|
The name @code{easy-mmode-define-minor-mode} is an alias |
1042 |
|
for this macro. |
1043 |
|
|
1044 |
Here is an example of using @code{define-minor-mode}: |
Here is an example of using @code{define-minor-mode}: |
1045 |
|
|
1046 |
@smallexample |
@smallexample |
1062 |
("\C-\M-\^?" |
("\C-\M-\^?" |
1063 |
. (lambda () |
. (lambda () |
1064 |
(interactive) |
(interactive) |
1065 |
(hungry-electric-delete t))))) |
(hungry-electric-delete t)))) |
1066 |
|
:group 'hunger) |
1067 |
@end smallexample |
@end smallexample |
1068 |
|
|
1069 |
@noindent |
@noindent |
1072 |
which indicates whether the mode is enabled, and a variable named |
which indicates whether the mode is enabled, and a variable named |
1073 |
@code{hungry-mode-map} which holds the keymap that is active when the |
@code{hungry-mode-map} which holds the keymap that is active when the |
1074 |
mode is enabled. It initializes the keymap with key bindings for |
mode is enabled. It initializes the keymap with key bindings for |
1075 |
@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}. |
@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}. It puts the variable |
1076 |
|
@code{hungry-mode} into custom group @code{hunger}. There are no |
1077 |
|
@var{body} forms---many minor modes don't need any. |
1078 |
|
|
1079 |
|
Here's an equivalent way to write it: |
1080 |
|
|
1081 |
@findex easy-mmode-define-minor-mode |
@smallexample |
1082 |
The name @code{easy-mmode-define-minor-mode} is an alias |
(define-minor-mode hungry-mode |
1083 |
for this macro. |
"Toggle Hungry mode. |
1084 |
|
With no argument, this command toggles the mode. |
1085 |
|
Non-null prefix argument turns on the mode. |
1086 |
|
Null prefix argument turns off the mode. |
1087 |
|
|
1088 |
|
When Hungry mode is enabled, the control delete key |
1089 |
|
gobbles all preceding whitespace except the last. |
1090 |
|
See the command \\[hungry-electric-delete]." |
1091 |
|
;; The initial value. |
1092 |
|
:initial-value nil |
1093 |
|
;; The indicator for the mode line. |
1094 |
|
:lighter " Hungry" |
1095 |
|
;; The minor mode bindings. |
1096 |
|
:keymap |
1097 |
|
'(("\C-\^?" . hungry-electric-delete) |
1098 |
|
("\C-\M-\^?" |
1099 |
|
. (lambda () |
1100 |
|
(interactive) |
1101 |
|
(hungry-electric-delete t)))) |
1102 |
|
:group 'hunger) |
1103 |
|
@end smallexample |
1104 |
|
|
1105 |
@node Mode Line Format |
@node Mode Line Format |
1106 |
@section Mode Line Format |
@section Mode-Line Format |
1107 |
@cindex mode line |
@cindex mode line |
1108 |
|
|
1109 |
Each Emacs window (aside from minibuffer windows) typically has a mode |
Each Emacs window (aside from minibuffer windows) typically has a mode |
1163 |
* %-Constructs:: Putting information into a mode line. |
* %-Constructs:: Putting information into a mode line. |
1164 |
* Properties in Mode:: Using text properties in the mode line. |
* Properties in Mode:: Using text properties in the mode line. |
1165 |
* Header Lines:: Like a mode line, but at the top. |
* Header Lines:: Like a mode line, but at the top. |
1166 |
|
* Emulating Mode Line:: Formatting text as the mode line would. |
1167 |
@end menu |
@end menu |
1168 |
|
|
1169 |
@node Mode Line Data |
@node Mode Line Data |
1170 |
@subsection The Data Structure of the Mode Line |
@subsection The Data Structure of the Mode Line |
1171 |
@cindex mode line construct |
@cindex mode-line construct |
1172 |
|
|
1173 |
The mode line contents are controlled by a data structure of lists, |
The mode-line contents are controlled by a data structure of lists, |
1174 |
strings, symbols, and numbers kept in buffer-local variables. The data |
strings, symbols, and numbers kept in buffer-local variables. The data |
1175 |
structure is called a @dfn{mode line construct}, and it is built in |
structure is called a @dfn{mode-line construct}, and it is built in |
1176 |
recursive fashion out of simpler mode line constructs. The same data |
recursive fashion out of simpler mode-line constructs. The same data |
1177 |
structure is used for constructing frame titles (@pxref{Frame Titles}) |
structure is used for constructing frame titles (@pxref{Frame Titles}) |
1178 |
and header lines (@pxref{Header Lines}). |
and header lines (@pxref{Header Lines}). |
1179 |
|
|
1180 |
@defvar mode-line-format |
@defvar mode-line-format |
1181 |
The value of this variable is a mode line construct with overall |
The value of this variable is a mode-line construct with overall |
1182 |
responsibility for the mode line format. The value of this variable |
responsibility for the mode-line format. The value of this variable |
1183 |
controls which other variables are used to form the mode line text, and |
controls which other variables are used to form the mode-line text, and |
1184 |
where they appear. |
where they appear. |
1185 |
|
|
1186 |
If you set this variable to @code{nil} in a buffer, that buffer does not |
If you set this variable to @code{nil} in a buffer, that buffer does not |
1187 |
have a mode line. (This feature was added in Emacs 21.) |
have a mode line. (This feature was added in Emacs 21.) |
1188 |
@end defvar |
@end defvar |
1189 |
|
|
1190 |
A mode line construct may be as simple as a fixed string of text, but |
A mode-line construct may be as simple as a fixed string of text, but |
1191 |
it usually specifies how to use other variables to construct the text. |
it usually specifies how to use other variables to construct the text. |
1192 |
Many of these variables are themselves defined to have mode line |
Many of these variables are themselves defined to have mode-line |
1193 |
constructs as their values. |
constructs as their values. |
1194 |
|
|
1195 |
The default value of @code{mode-line-format} incorporates the values |
The default value of @code{mode-line-format} incorporates the values |
1196 |
of variables such as @code{mode-name} and @code{minor-mode-alist}. |
of variables such as @code{mode-line-position} and |
1197 |
Because of this, very few modes need to alter @code{mode-line-format} |
@code{mode-line-modes} (which in turn incorporates the values of the |
1198 |
itself. For most purposes, it is sufficient to alter some of the |
variables @code{mode-name} and @code{minor-mode-alist}). Because of |
1199 |
variables that @code{mode-line-format} refers to. |
this, very few modes need to alter @code{mode-line-format} itself. For |
1200 |
|
most purposes, it is sufficient to alter some of the variables that |
1201 |
|
@code{mode-line-format} either directly or indirectly refers to. |
1202 |
|
|
1203 |
A mode line construct may be a list, a symbol, or a string. If the |
A mode-line construct may be a list, a symbol, or a string. If the |
1204 |
value is a list, each element may be a list, a symbol, or a string. |
value is a list, each element may be a list, a symbol, or a string. |
1205 |
|
|
1206 |
The mode line can display various faces, if the strings that control |
The mode line can display various faces, if the strings that control |
1211 |
@table @code |
@table @code |
1212 |
@cindex percent symbol in mode line |
@cindex percent symbol in mode line |
1213 |
@item @var{string} |
@item @var{string} |
1214 |
A string as a mode line construct is displayed verbatim in the mode line |
A string as a mode-line construct is displayed verbatim in the mode line |
1215 |
except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%} |
except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%} |
1216 |
specify the field width for space filling on the right (i.e., the data |
specify the field width for space filling on the right (i.e., the data |
1217 |
is left justified). @xref{%-Constructs}. |
is left justified). @xref{%-Constructs}. |
1218 |
|
|
1219 |
@item @var{symbol} |
@item @var{symbol} |
1220 |
A symbol as a mode line construct stands for its value. The value of |
A symbol as a mode-line construct stands for its value. The value of |
1221 |
@var{symbol} is used as a mode line construct, in place of @var{symbol}. |
@var{symbol} is used as a mode-line construct, in place of @var{symbol}. |
1222 |
However, the symbols @code{t} and @code{nil} are ignored, as is any |
However, the symbols @code{t} and @code{nil} are ignored, as is any |
1223 |
symbol whose value is void. |
symbol whose value is void. |
1224 |
|
|
1225 |
There is one exception: if the value of @var{symbol} is a string, it is |
There is one exception: if the value of @var{symbol} is a string, it is |
1226 |
displayed verbatim: the @code{%}-constructs are not recognized. |
displayed verbatim: the @code{%}-constructs are not recognized. |
1227 |
|
|
1228 |
|
Unless @var{symbol} is marked as ``risky'' (i.e., it has a |
1229 |
|
non-@code{nil} @code{risky-local-variable} property), all properties in |
1230 |
|
any strings, as well as all @code{:eval} and @code{:propertize} forms in |
1231 |
|
the value of that symbol will be ignored. |
1232 |
|
|
1233 |
@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{}) |
@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{}) |
1234 |
A list whose first element is a string or list means to process all the |
A list whose first element is a string or list means to process all the |
1235 |
elements recursively and concatenate the results. This is the most |
elements recursively and concatenate the results. This is the most |
1236 |
common form of mode line construct. |
common form of mode-line construct. |
1237 |
|
|
1238 |
@item (:eval @var{form}) |
@item (:eval @var{form}) |
1239 |
A list whose first element is the symbol @code{:eval} says to evaluate |
A list whose first element is the symbol @code{:eval} says to evaluate |
1240 |
@var{form}, and use the result as a string to display. |
@var{form}, and use the result as a string to display. |
1241 |
(This feature is new as of Emacs 21.) |
(This feature is new as of Emacs 21.) |
1242 |
|
|
1243 |
|
@item (:propertize @var{elt} @var{props}@dots{}) |
1244 |
|
A list whose first element is the symbol @code{:propertize} says to |
1245 |
|
process the mode-line construct @var{elt} recursively and add the text |
1246 |
|
properties specified by @var{props} to the result. The argument |
1247 |
|
@var{props} should consist of zero or more pairs @var{text-property} |
1248 |
|
@var{value}. (This feature is new as of Emacs 21.4.) |
1249 |
|
@c FIXME: This might be Emacs 21.5. |
1250 |
|
|
1251 |
@item (@var{symbol} @var{then} @var{else}) |
@item (@var{symbol} @var{then} @var{else}) |
1252 |
A list whose first element is a symbol that is not a keyword specifies a |
A list whose first element is a symbol that is not a keyword specifies a |
1253 |
conditional. Its meaning depends on the value of @var{symbol}. If the |
conditional. Its meaning depends on the value of @var{symbol}. If the |
1254 |
value is non-@code{nil}, the second element, @var{then}, is processed |
value is non-@code{nil}, the second element, @var{then}, is processed |
1255 |
recursively as a mode line element. But if the value of @var{symbol} is |
recursively as a mode-line element. But if the value of @var{symbol} is |
1256 |
@code{nil}, the third element, @var{else}, is processed recursively. |
@code{nil}, the third element, @var{else}, is processed recursively. |
1257 |
You may omit @var{else}; then the mode line element displays nothing if |
You may omit @var{else}; then the mode-line element displays nothing if |
1258 |
the value of @var{symbol} is @code{nil}. |
the value of @var{symbol} is @code{nil}. |
1259 |
|
|
1260 |
@item (@var{width} @var{rest}@dots{}) |
@item (@var{width} @var{rest}@dots{}) |
1261 |
A list whose first element is an integer specifies truncation or |
A list whose first element is an integer specifies truncation or |
1262 |
padding of the results of @var{rest}. The remaining elements |
padding of the results of @var{rest}. The remaining elements |
1263 |
@var{rest} are processed recursively as mode line constructs and |
@var{rest} are processed recursively as mode-line constructs and |
1264 |
concatenated together. Then the result is space filled (if |
concatenated together. Then the result is space filled (if |
1265 |
@var{width} is positive) or truncated (to @minus{}@var{width} columns, |
@var{width} is positive) or truncated (to @minus{}@var{width} columns, |
1266 |
if @var{width} is negative) on the right. |
if @var{width} is negative) on the right. |
1292 |
@end group |
@end group |
1293 |
@group |
@group |
1294 |
;; @r{Note that this is evaluated while making the list.} |
;; @r{Note that this is evaluated while making the list.} |
1295 |
;; @r{It makes a mode line construct which is just a string.} |
;; @r{It makes a mode-line construct which is just a string.} |
1296 |
(getenv "HOST") |
(getenv "HOST") |
1297 |
@end group |
@end group |
1298 |
":" |
":" |
1309 |
'(which-func-mode ("" which-func-format "--")) |
'(which-func-mode ("" which-func-format "--")) |
1310 |
'(line-number-mode "L%l--") |
'(line-number-mode "L%l--") |
1311 |
'(column-number-mode "C%c--") |
'(column-number-mode "C%c--") |
1312 |
'(-3 . "%p") |
'(-3 "%p") |
1313 |
"-%-")) |
"-%-")) |
1314 |
@end group |
@end group |
1315 |
@end example |
@end example |
1349 |
|
|
1350 |
@defvar mode-line-frame-identification |
@defvar mode-line-frame-identification |
1351 |
This variable identifies the current frame. The default value is |
This variable identifies the current frame. The default value is |
1352 |
@code{" "} if you are using a window system which can show multiple |
@code{" "} if you are using a window system which can show multiple |
1353 |
frames, or @code{"-%F "} on an ordinary terminal which shows only one |
frames, or @code{"-%F "} on an ordinary terminal which shows only one |
1354 |
frame at a time. |
frame at a time. |
1355 |
@end defvar |
@end defvar |
1356 |
|
|
1360 |
with spaces to at least 12 columns. |
with spaces to at least 12 columns. |
1361 |
@end defvar |
@end defvar |
1362 |
|
|
1363 |
@defvar global-mode-string |
@defvar mode-line-position |
1364 |
This variable holds a mode line spec that appears in the mode line by |
This variable indicates the position in the buffer. Here is a |
1365 |
default, just after the buffer name. The command @code{display-time} |
simplified version of its default value. The actual default value |
1366 |
sets @code{global-mode-string} to refer to the variable |
also specifies addition of the @code{help-echo} text property. |
|
@code{display-time-string}, which holds a string containing the time and |
|
|
load information. |
|
1367 |
|
|
1368 |
The @samp{%M} construct substitutes the value of |
@example |
1369 |
@code{global-mode-string}, but that is obsolete, since the variable is |
@group |
1370 |
included in the mode line from @code{mode-line-format}. |
((-3 "%p") |
1371 |
|
(size-indication-mode (8 " of %I")) |
1372 |
|
@end group |
1373 |
|
@group |
1374 |
|
(line-number-mode |
1375 |
|
((column-number-mode |
1376 |
|
(10 " (%l,%c)") |
1377 |
|
(6 " L%l"))) |
1378 |
|
((column-number-mode |
1379 |
|
(5 " C%c"))))) |
1380 |
|
@end group |
1381 |
|
@end example |
1382 |
|
|
1383 |
|
This means that @code{mode-line-position} displays at least the buffer |
1384 |
|
percentage and possibly the buffer size, the line number and the column |
1385 |
|
number. |
1386 |
@end defvar |
@end defvar |
1387 |
|
|
1388 |
|
@defvar vc-mode |
1389 |
|
The variable @code{vc-mode}, buffer-local in each buffer, records |
1390 |
|
whether the buffer's visited file is maintained with version control, |
1391 |
|
and, if so, which kind. Its value is a string that appears in the mode |
1392 |
|
line, or @code{nil} for no version control. |
1393 |
|
@end defvar |
1394 |
|
|
1395 |
|
@defvar mode-line-modes |
1396 |
|
This variable displays the buffer's major and minor modes. Here is a |
1397 |
|
simplified version of its default value. The real default value also |
1398 |
|
specifies addition of text properties. |
1399 |
|
|
1400 |
|
@example |
1401 |
|
@group |
1402 |
|
("%[(" mode-name |
1403 |
|
mode-line-process minor-mode-alist |
1404 |
|
"%n" ")%]--") |
1405 |
|
@end group |
1406 |
|
@end example |
1407 |
|
|
1408 |
|
So @code{mode-line-modes} normally also displays the recursive editing |
1409 |
|
level, information on the process status and whether narrowing is in |
1410 |
|
effect. |
1411 |
|
@end defvar |
1412 |
|
|
1413 |
|
The following three variables are used in @code{mode-line-modes}: |
1414 |
|
|
1415 |
@defvar mode-name |
@defvar mode-name |
1416 |
This buffer-local variable holds the ``pretty'' name of the current |
This buffer-local variable holds the ``pretty'' name of the current |
1417 |
buffer's major mode. Each major mode should set this variable so that the |
buffer's major mode. Each major mode should set this variable so that the |
1418 |
mode name will appear in the mode line. |
mode name will appear in the mode line. |
1419 |
@end defvar |
@end defvar |
1420 |
|
|
1421 |
|
@defvar mode-line-process |
1422 |
|
This buffer-local variable contains the mode-line information on process |
1423 |
|
status in modes used for communicating with subprocesses. It is |
1424 |
|
displayed immediately following the major mode name, with no intervening |
1425 |
|
space. For example, its value in the @samp{*shell*} buffer is |
1426 |
|
@code{(":%s")}, which allows the shell to display its status along |
1427 |
|
with the major mode as: @samp{(Shell:run)}. Normally this variable |
1428 |
|
is @code{nil}. |
1429 |
|
@end defvar |
1430 |
|
|
1431 |
@defvar minor-mode-alist |
@defvar minor-mode-alist |
1432 |
This variable holds an association list whose elements specify how the |
This variable holds an association list whose elements specify how the |
1433 |
mode line should indicate that a minor mode is active. Each element of |
mode line should indicate that a minor mode is active. Each element of |
1437 |
(@var{minor-mode-variable} @var{mode-line-string}) |
(@var{minor-mode-variable} @var{mode-line-string}) |
1438 |
@end example |
@end example |
1439 |
|
|
1440 |
More generally, @var{mode-line-string} can be any mode line spec. It |
More generally, @var{mode-line-string} can be any mode-line spec. It |
1441 |
appears in the mode line when the value of @var{minor-mode-variable} is |
appears in the mode line when the value of @var{minor-mode-variable} |
1442 |
non-@code{nil}, and not otherwise. These strings should begin with |
is non-@code{nil}, and not otherwise. These strings should begin with |
1443 |
spaces so that they don't run together. Conventionally, the |
spaces so that they don't run together. Conventionally, the |
1444 |
@var{minor-mode-variable} for a specific mode is set to a non-@code{nil} |
@var{minor-mode-variable} for a specific mode is set to a |
1445 |
value when that minor mode is activated. |
non-@code{nil} value when that minor mode is activated. |
|
|
|
|
The default value of @code{minor-mode-alist} is: |
|
|
|
|
|
@example |
|
|
@group |
|
|
minor-mode-alist |
|
|
@result{} ((vc-mode vc-mode) |
|
|
(abbrev-mode " Abbrev") |
|
|
(overwrite-mode overwrite-mode) |
|
|
(auto-fill-function " Fill") |
|
|
(defining-kbd-macro " Def") |
|
|
(isearch-mode isearch-mode)) |
|
|
@end group |
|
|
@end example |
|
1446 |
|
|
1447 |
@code{minor-mode-alist} itself is not buffer-local. Each variable |
@code{minor-mode-alist} itself is not buffer-local. Each variable |
1448 |
mentioned in the alist should be buffer-local if its minor mode can be |
mentioned in the alist should be buffer-local if its minor mode can be |
1449 |
enabled separately in each buffer. |
enabled separately in each buffer. |
1450 |
@end defvar |
@end defvar |
1451 |
|
|
1452 |
@defvar mode-line-process |
@defvar global-mode-string |
1453 |
This buffer-local variable contains the mode line information on process |
This variable holds a mode-line spec that appears in the mode line by |
1454 |
status in modes used for communicating with subprocesses. It is |
default, just after the buffer name. The command @code{display-time} |
1455 |
displayed immediately following the major mode name, with no intervening |
sets @code{global-mode-string} to refer to the variable |
1456 |
space. For example, its value in the @samp{*shell*} buffer is |
@code{display-time-string}, which holds a string containing the time and |
1457 |
@code{(":%s")}, which allows the shell to display its status along |
load information. |
|
with the major mode as: @samp{(Shell:run)}. Normally this variable |
|
|
is @code{nil}. |
|
|
@end defvar |
|
|
|
|
|
Some variables are used by @code{minor-mode-alist} to display |
|
|
a string for various minor modes when enabled. This is a typical |
|
|
example: |
|
1458 |
|
|
1459 |
@defvar vc-mode |
The @samp{%M} construct substitutes the value of |
1460 |
The variable @code{vc-mode}, buffer-local in each buffer, records |
@code{global-mode-string}, but that is obsolete, since the variable is |
1461 |
whether the buffer's visited file is maintained with version control, |
included in the mode line from @code{mode-line-format}. |
|
and, if so, which kind. Its value is a string that appears in the mode |
|
|
line, or @code{nil} for no version control. |
|
1462 |
@end defvar |
@end defvar |
1463 |
|
|
1464 |
The variable @code{default-mode-line-format} is where |
The variable @code{default-mode-line-format} is where |
1469 |
that do not override it. This is the same as @code{(default-value |
that do not override it. This is the same as @code{(default-value |
1470 |
'mode-line-format)}. |
'mode-line-format)}. |
1471 |
|
|
1472 |
The default value of @code{default-mode-line-format} is this list: |
Here is a simplified version of the default value of |
1473 |
|
@code{default-mode-line-format}. The real default value also |
1474 |
|
specifies addition of text properties. |
1475 |
|
|
1476 |
@example |
@example |
1477 |
@group |
@group |
1482 |
mode-line-buffer-identification |
mode-line-buffer-identification |
1483 |
@end group |
@end group |
1484 |
" " |
" " |
1485 |
global-mode-string |
mode-line-position |
1486 |
@group |
(vc-mode vc-mode) |
1487 |
" %[(" |
" " |
|
;; @r{@code{mode-line-mode-name} is a function} |
|
|
;; @r{that copies the mode name and adds text} |
|
|
;; @r{properties to make it mouse-sensitive.} |
|
|
(:eval (mode-line-mode-name)) |
|
|
mode-line-process |
|
|
minor-mode-alist |
|
|
"%n" |
|
|
")%]--" |
|
|
@end group |
|
1488 |
@group |
@group |
1489 |
|
mode-line-modes |
1490 |
(which-func-mode ("" which-func-format "--")) |
(which-func-mode ("" which-func-format "--")) |
1491 |
(line-number-mode "L%l--") |
(global-mode-string ("--" global-mode-string)) |
|
(column-number-mode "C%c--") |
|
|
(-3 . "%p") |
|
1492 |
"-%-") |
"-%-") |
1493 |
@end group |
@end group |
1494 |
@end example |
@end example |
1517 |
The title (only on a window system) or the name of the selected frame. |
The title (only on a window system) or the name of the selected frame. |
1518 |
@xref{Window Frame Parameters}. |
@xref{Window Frame Parameters}. |
1519 |
|
|
1520 |
|
@item %i |
1521 |
|
The size of the accessible part of the current buffer; basically |
1522 |
|
@code{(- (point-max) (point-min))}. |
1523 |
|
|
1524 |
|
@item %I |
1525 |
|
Like @samp{%i}, but the size is printed in a more readable way by using |
1526 |
|
@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to |
1527 |
|
abbreviate. |
1528 |
|
|
1529 |
@item %l |
@item %l |
1530 |
The current line number of point, counting within the accessible portion |
The current line number of point, counting within the accessible portion |
1531 |
of the buffer. |
of the buffer. |
1600 |
|
|
1601 |
@node Properties in Mode |
@node Properties in Mode |
1602 |
@subsection Properties in the Mode Line |
@subsection Properties in the Mode Line |
1603 |
|
@cindex text properties in the mode line |
1604 |
|
|
1605 |
Starting in Emacs 21, certain text properties are meaningful in the |
Starting in Emacs 21, certain text properties are meaningful in the |
1606 |
mode line. The @code{face} property affects the appearance of text; the |
mode line. The @code{face} property affects the appearance of text; the |
1607 |
@code{help-echo} property associate help strings with the text, and |
@code{help-echo} property associate help strings with the text, and |
1608 |
@code{local-map} can make the text mouse-sensitive. |
@code{local-map} can make the text mouse-sensitive. |
1609 |
|
|
1610 |
There are three ways to specify text properties for text in the mode |
There are four ways to specify text properties for text in the mode |
1611 |
line: |
line: |
1612 |
|
|
1613 |
@enumerate |
@enumerate |
1614 |
@item |
@item |
1615 |
Put a string with the @code{local-map} property directly into the |
Put a string with a text property directly into the mode-line data |
1616 |
mode-line data structure. |
structure. |
1617 |
|
|
1618 |
|
@item |
1619 |
|
Put a text property on a mode-line %-construct such as @samp{%12b}; then |
1620 |
|
the expansion of the %-construct will have that same text property. |
1621 |
|
|
1622 |
@item |
@item |
1623 |
Put a @code{local-map} property on a mode-line %-construct |
Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to |
1624 |
such as @samp{%12b}; then the expansion of the %-construct |
give @var{elt} a text property specified by @var{props}. |
|
will have that same text property. |
|
1625 |
|
|
1626 |
@item |
@item |
1627 |
Use a list containing @code{:eval @var{form}} in the mode-line data |
Use a list containing @code{:eval @var{form}} in the mode-line data |
1628 |
structure, and make @var{form} evaluate to a string that has a |
structure, and make @var{form} evaluate to a string that has a text |
1629 |
@code{local-map} property. |
property. |
1630 |
@end enumerate |
@end enumerate |
1631 |
|
|
1632 |
You use the @code{local-map} property to specify a keymap. Like any |
You use the @code{local-map} property to specify a keymap. Like any |
1641 |
|
|
1642 |
Starting in Emacs 21, a window can have a @dfn{header line} at the |
Starting in Emacs 21, a window can have a @dfn{header line} at the |
1643 |
top, just as it can have a mode line at the bottom. The header line |
top, just as it can have a mode line at the bottom. The header line |
1644 |
feature works just like the mode line feature, except that it's |
feature works just like the mode-line feature, except that it's |
1645 |
controlled by different variables. |
controlled by different variables. |
1646 |
|
|
1647 |
@tindex header-line-format |
@tindex header-line-format |
1660 |
It is normally @code{nil}, so that ordinary buffers have no header line. |
It is normally @code{nil}, so that ordinary buffers have no header line. |
1661 |
@end defvar |
@end defvar |
1662 |
|
|
1663 |
|
@node Emulating Mode Line |
1664 |
|
@subsection Emulating Mode-Line Formatting |
1665 |
|
|
1666 |
|
You can use the function @code{format-mode-line} to compute |
1667 |
|
the text that would appear in a mode line or header line |
1668 |
|
based on certain mode-line specification. |
1669 |
|
|
1670 |
|
@defun format-mode-line &optional format window no-props |
1671 |
|
This function formats a line of text according to @var{format} as if |
1672 |
|
it were generating the mode line for @var{window}, but instead of |
1673 |
|
displaying the text in the mode line or the header line, it returns |
1674 |
|
the text as a string. |
1675 |
|
|
1676 |
|
If @var{format} is @code{nil}, that means to use |
1677 |
|
@code{mode-line-format} and return the text that would appear in the |
1678 |
|
mode line. If @var{format} is @code{t}, that means to use |
1679 |
|
@code{header-line-format} so as to return the text that would appear |
1680 |
|
in the header line (@code{""} if the window has no header line). |
1681 |
|
The argument @var{window} defaults to the selected window. |
1682 |
|
|
1683 |
|
The value string normally has text properties that correspond to the |
1684 |
|
faces, keymaps, etc., that the mode line would have. If |
1685 |
|
@var{no-props} is non-@code{nil}, the value has no text properties. |
1686 |
|
@end defun |
1687 |
|
|
1688 |
@node Imenu |
@node Imenu |
1689 |
@section Imenu |
@section Imenu |
1690 |
|
|
1691 |
@cindex Imenu |
@cindex Imenu |
1692 |
@dfn{Imenu} is a feature that lets users select a definition or |
@dfn{Imenu} is a feature that lets users select a definition or |
1693 |
section in the buffer, from a menu which lists all of them, to go |
section in the buffer, from a menu which lists all of them, to go |
1694 |
directly to that location in the buffer. Imenu works by constructing a |
directly to that location in the buffer. Imenu works by constructing |
1695 |
buffer index which lists the names and buffer positions of the |
a buffer index which lists the names and buffer positions of the |
1696 |
definitions, or other named portions of the buffer; then the user can |
definitions, or other named portions of the buffer; then the user can |
1697 |
choose one of them and move point to it. This section explains how to |
choose one of them and move point to it. The user-level commands for |
1698 |
customize how Imenu finds the definitions or buffer portions for a |
using Imenu are described in the Emacs Manual (@pxref{Imenu,, Imenu, |
1699 |
|
emacs, the Emacs Manual}). This section explains how to customize |
1700 |
|
Imenu's method of finding definitions or buffer portions for a |
1701 |
particular major mode. |
particular major mode. |
1702 |
|
|
1703 |
The usual and simplest way is to set the variable |
The usual and simplest way is to set the variable |
1704 |
@code{imenu-generic-expression}: |
@code{imenu-generic-expression}: |
1705 |
|
|
1706 |
@defvar imenu-generic-expression |
@defvar imenu-generic-expression |
1707 |
This variable, if non-@code{nil}, specifies regular expressions for |
This variable, if non-@code{nil}, is a list that specifies regular |
1708 |
finding definitions for Imenu. In the simplest case, elements should |
expressions for finding definitions for Imenu. Simple elements of |
1709 |
look like this: |
@code{imenu-generic-expression} look like this: |
1710 |
|
|
1711 |
@example |
@example |
1712 |
(@var{menu-title} @var{regexp} @var{subexp}) |
(@var{menu-title} @var{regexp} @var{index}) |
1713 |
@end example |
@end example |
1714 |
|
|
1715 |
Here, if @var{menu-title} is non-@code{nil}, it says that the matches |
Here, if @var{menu-title} is non-@code{nil}, it says that the matches |
1719 |
in the top level of the buffer index. |
in the top level of the buffer index. |
1720 |
|
|
1721 |
The second item in the list, @var{regexp}, is a regular expression |
The second item in the list, @var{regexp}, is a regular expression |
1722 |
(@pxref{Regular Expressions}); anything in the buffer that it matches is |
(@pxref{Regular Expressions}); anything in the buffer that it matches |
1723 |
considered a definition, something to mention in the buffer index. The |
is considered a definition, something to mention in the buffer index. |
1724 |
third item, @var{subexp}, indicates which subexpression in @var{regexp} |
The third item, @var{index}, is a non-negative integer that indicates |
1725 |
matches the definition's name. |
which subexpression in @var{regexp} matches the definition's name. |
1726 |
|
|
1727 |
An element can also look like this: |
An element can also look like this: |
1728 |
|
|
1730 |
(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{}) |
(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{}) |
1731 |
@end example |
@end example |
1732 |
|
|
1733 |
Each match for this element creates a special index item which, if |
Like in the previous case, each match for this element creates an |
1734 |
selected by the user, calls @var{function} with arguments consisting of |
index item. However, if this index item is selected by the user, it |
1735 |
the item name, the buffer position, and @var{arguments}. |
calls @var{function} with arguments consisting of the item name, the |
1736 |
|
buffer position, and @var{arguments}. |
1737 |
|
|
1738 |
For Emacs Lisp mode, @var{pattern} could look like this: |
For Emacs Lisp mode, @code{imenu-generic-expression} could look like |
1739 |
|
this: |
1740 |
|
|
1741 |
@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+] |
@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+] |
1742 |
@example |
@example |
1760 |
@end defvar |
@end defvar |
1761 |
|
|
1762 |
@defvar imenu-case-fold-search |
@defvar imenu-case-fold-search |
1763 |
This variable controls whether matching against |
This variable controls whether matching against the regular |
1764 |
@var{imenu-generic-expression} is case-sensitive: @code{t}, the default, |
expressions in the value of @code{imenu-generic-expression} is |
1765 |
means matching should ignore case. |
case-sensitive: @code{t}, the default, means matching should ignore |
1766 |
|
case. |
1767 |
|
|
1768 |
Setting this variable makes it buffer-local in the current buffer. |
Setting this variable makes it buffer-local in the current buffer. |
1769 |
@end defvar |
@end defvar |
1788 |
For example, Fortran mode uses it this way: |
For example, Fortran mode uses it this way: |
1789 |
|
|
1790 |
@example |
@example |
1791 |
(setq imenu-syntax-alist '(("_$" . "w"))) |
(setq imenu-syntax-alist '(("_$" . "w"))) |
1792 |
@end example |
@end example |
1793 |
|
|
1794 |
The @code{imenu-generic-expression} patterns can then use @samp{\\sw+} |
The @code{imenu-generic-expression} regular expressions can then use |
1795 |
instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this technique may be |
@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this |
1796 |
inconvenient when the mode needs to limit the initial character |
technique may be inconvenient when the mode needs to limit the initial |
1797 |
of a name to a smaller set of characters than are allowed in the rest |
character of a name to a smaller set of characters than are allowed in |
1798 |
of a name. |
the rest of a name. |
1799 |
|
|
1800 |
Setting this variable makes it buffer-local in the current buffer. |
Setting this variable makes it buffer-local in the current buffer. |
1801 |
@end defvar |
@end defvar |
1828 |
variable @code{imenu-create-index-function}: |
variable @code{imenu-create-index-function}: |
1829 |
|
|
1830 |
@defvar imenu-create-index-function |
@defvar imenu-create-index-function |
1831 |
This variable specifies the function to use for creating a buffer index. |
This variable specifies the function to use for creating a buffer |
1832 |
The function should take no arguments, and return an index for the |
index. The function should take no arguments, and return an index |
1833 |
current buffer. It is called within @code{save-excursion}, so where it |
alist for the current buffer. It is called within |
1834 |
leaves point makes no difference. |
@code{save-excursion}, so where it leaves point makes no difference. |
|
|
|
|
The default value is a function that uses |
|
|
@code{imenu-generic-expression} to produce the index alist. If you |
|
|
specify a different function, then @code{imenu-generic-expression} is |
|
|
not used. |
|
1835 |
|
|
1836 |
Setting this variable makes it buffer-local in the current buffer. |
The index alist can have three types of elements. Simple elements |
1837 |
@end defvar |
look like this: |
1838 |
|
|
1839 |
@defvar imenu-index-alist |
@example |
1840 |
This variable holds the index alist for the current buffer. |
(@var{index-name} . @var{index-position}) |
1841 |
Setting it makes it buffer-local in the current buffer. |
@end example |
1842 |
|
|
1843 |
Simple elements in the alist look like @code{(@var{index-name} |
Selecting a simple element has the effect of moving to position |
1844 |
. @var{index-position})}. Selecting a simple element has the effect of |
@var{index-position} in the buffer. Special elements look like this: |
|
moving to position @var{index-position} in the buffer. |
|
1845 |
|
|
1846 |
Special elements look like @code{(@var{index-name} @var{position} |
@example |
1847 |
@var{function} @var{arguments}@dots{})}. Selecting a special element |
(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{}) |
1848 |
performs |
@end example |
1849 |
|
|
1850 |
|
Selecting a special element performs: |
1851 |
|
|
1852 |
@example |
@example |
1853 |
(funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{}) |
(funcall @var{function} |
1854 |
|
@var{index-name} @var{index-position} @var{arguments}@dots{}) |
1855 |
@end example |
@end example |
1856 |
|
|
1857 |
A nested sub-alist element looks like @code{(@var{index-name} |
A nested sub-alist element looks like this: |
1858 |
@var{sub-alist})}. |
|
1859 |
|
@example |
1860 |
|
(@var{menu-title} @var{sub-alist}) |
1861 |
|
@end example |
1862 |
|
|
1863 |
|
It creates the submenu @var{menu-title} specified by @var{sub-alist}. |
1864 |
|
|
1865 |
|
The default value of @code{imenu-create-index-function} is |
1866 |
|
@code{imenu-default-create-index-function}. This function uses |
1867 |
|
@code{imenu-prev-index-position-function} and |
1868 |
|
@code{imenu-extract-index-name-function} to produce the index alist. |
1869 |
|
However, if either of these two variables is @code{nil}, the default |
1870 |
|
function uses @code{imenu-generic-expression} instead. |
1871 |
|
|
1872 |
|
Setting this variable makes it buffer-local in the current buffer. |
1873 |
@end defvar |
@end defvar |
1874 |
|
|
1875 |
@node Font Lock Mode |
@node Font Lock Mode |
2032 |
("fubar" . fubar-face) |
("fubar" . fubar-face) |
2033 |
@end example |
@end example |
2034 |
|
|
2035 |
|
The value of @var{facename} is usually a face name (a symbol), but it |
2036 |
|
can also be a list of the form |
2037 |
|
|
2038 |
|
@example |
2039 |
|
(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) |
2040 |
|
@end example |
2041 |
|
|
2042 |
|
to specify various text properties to put on the text that matches. |
2043 |
|
If you do this, be sure to add the other text property names that you |
2044 |
|
set in this way to the value of @code{font-lock-extra-managed-props} |
2045 |
|
so that the properties will also be cleared out when they are no longer |
2046 |
|
appropriate. |
2047 |
|
|
2048 |
@item (@var{matcher} . @var{highlighter}) |
@item (@var{matcher} . @var{highlighter}) |
2049 |
In this kind of element, @var{highlighter} is a list |
In this kind of element, @var{highlighter} is a list |
2050 |
which specifies how to highlight matches found by @var{matcher}. |
which specifies how to highlight matches found by @var{matcher}. |
2059 |
subelement, @var{facename}, specifies the face, as described above. |
subelement, @var{facename}, specifies the face, as described above. |
2060 |
|
|
2061 |
The last two values in @var{highlighter}, @var{override} and |
The last two values in @var{highlighter}, @var{override} and |
2062 |
@var{laxmatch}, are flags. If @var{override} is @code{t}, this element |
@var{laxmatch}, are flags. If @var{override} is @code{t}, this |
2063 |
can override existing fontification made by previous elements of |
element can override existing fontification made by previous elements |
2064 |
@code{font-lock-keywords}. If it is @code{keep}, then each character is |
of @code{font-lock-keywords}. If it is @code{keep}, then each |
2065 |
fontified if it has not been fontified already by some other element. |
character is fontified if it has not been fontified already by some |
2066 |
If it is @code{prepend}, the face @var{facename} is added to the |
other element. If it is @code{prepend}, the face @var{facename} is |
2067 |
beginning of the @code{face} property. If it is @code{append}, the face |
added to the beginning of the @code{font-lock-face} property. If it |
2068 |
@var{facename} is added to the end of the @code{face} property. |
is @code{append}, the face @var{facename} is added to the end of the |
2069 |
|
@code{font-lock-face} property. |
2070 |
|
|
2071 |
If @var{laxmatch} is non-@code{nil}, it means there should be no error |
If @var{laxmatch} is non-@code{nil}, it means there should be no error |
2072 |
if there is no subexpression numbered @var{subexp} in @var{matcher}. |
if there is no subexpression numbered @var{subexp} in @var{matcher}. |
2221 |
textual modes. |
textual modes. |
2222 |
@end defvar |
@end defvar |
2223 |
|
|
2224 |
|
@defvar font-lock-extra-managed-props |
2225 |
|
Additional properties (other than @code{font-lock-face}) that are |
2226 |
|
being managed by Font Lock mode. Font Lock mode normally manages only |
2227 |
|
the @code{font-lock-face} property; if you want it to manage others as |
2228 |
|
well, you must specify them in a @var{facename} in |
2229 |
|
@code{font-lock-keywords} as well as adding them to this list. |
2230 |
|
@end defvar |
2231 |
|
|
2232 |
@node Levels of Font Lock |
@node Levels of Font Lock |
2233 |
@subsection Levels of Font Lock |
@subsection Levels of Font Lock |
2234 |
|
|
2268 |
@code{font-lock-face} (@pxref{Special Properties}). This property |
@code{font-lock-face} (@pxref{Special Properties}). This property |
2269 |
acts just like the explicit @code{face} property, but its activation |
acts just like the explicit @code{face} property, but its activation |
2270 |
is toggled when the user calls @kbd{M-x font-lock-mode}. Using |
is toggled when the user calls @kbd{M-x font-lock-mode}. Using |
2271 |
@code{font-lock-face} is especially conveninent for special modes |
@code{font-lock-face} is especially convenient for special modes |
2272 |
which construct their text programmatically, such as |
which construct their text programmatically, such as |
2273 |
@code{list-buffers} and @code{occur}. |
@code{list-buffers} and @code{occur}. |
2274 |
|
|
2275 |
If your mode does not use any of the other machinery of Font Lock |
If your mode does not use any of the other machinery of Font Lock |
2276 |
(i.e. it only uses the @code{font-lock-face} property), you can tell |
(i.e. it only uses the @code{font-lock-face} property), you can tell |
2277 |
Emacs not to load all of font-lock.el (unless it's already loaded), by |
Emacs not to load all of font-lock.el (unless it's already loaded), by |
2278 |
setting the variable @code{font-lock-core-only} to non-nil as part of |
setting the variable @code{font-lock-core-only} to non-@code{nil} as |
2279 |
the @code{font-lock-defaults} settings. Here is the canonical way to |
part of the @code{font-lock-defaults} settings. Here is the canonical |
2280 |
do this: |
way to do this: |
2281 |
|
|
2282 |
@example |
@example |
2283 |
(set (make-local-variable 'font-lock-defaults) |
(set (make-local-variable 'font-lock-defaults) |
2332 |
@vindex font-lock-constant-face |
@vindex font-lock-constant-face |
2333 |
Used (typically) for constant names. |
Used (typically) for constant names. |
2334 |
|
|
2335 |
|
@item font-lock-preprocessor-face |
2336 |
|
@vindex font-lock-preprocessor-face |
2337 |
|
Used (typically) for preprocessor commands. |
2338 |
|
|
2339 |
@item font-lock-warning-face |
@item font-lock-warning-face |
2340 |
@vindex font-lock-warning-face |
@vindex font-lock-warning-face |
2341 |
Used (typically) for constructs that are peculiar, or that greatly |
Used (typically) for constructs that are peculiar, or that greatly |
2352 |
table by itself is not sufficient. |
table by itself is not sufficient. |
2353 |
|
|
2354 |
@defvar font-lock-syntactic-keywords |
@defvar font-lock-syntactic-keywords |
2355 |
This variable enables and controls syntactic Font Lock. Its value |
This variable enables and controls syntactic Font Lock. It is |
2356 |
should be a list of elements of this form: |
normally set via @code{font-lock-defaults}. Its value should be a |
2357 |
|
list of elements of this form: |
2358 |
|
|
2359 |
@example |
@example |
2360 |
(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch}) |
(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch}) |
2368 |
@end example |
@end example |
2369 |
|
|
2370 |
However, instead of specifying the value @var{facename} to use for the |
However, instead of specifying the value @var{facename} to use for the |
2371 |
@code{face} property, it specifies the value @var{syntax} to use for the |
@code{face} property, it specifies the value @var{syntax} to use for |
2372 |
@code{syntax-table} property. Here, @var{syntax} can be a variable |
the @code{syntax-table} property. Here, @var{syntax} can be a string |
2373 |
whose value is a syntax table, a syntax entry of the form |
(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell |
2374 |
@code{(@var{syntax-code} . @var{matching-char})}, or an expression whose |
(as returned by @code{string-to-syntax}), or an expression whose value |
2375 |
value is one of those two types. |
is one of those two types. @var{override} cannot be @code{prepend} or |
2376 |
|
@code{append}. |
2377 |
|
|
2378 |
|
For example, an element of the form: |
2379 |
|
|
2380 |
|
@example |
2381 |
|
("\\$\\(#\\)" 1 ".") |
2382 |
|
@end example |
2383 |
|
|
2384 |
|
highlights syntactically a hash character when following a dollar |
2385 |
|
character, with a SYNTAX of @code{"."} (meaning punctuation syntax). |
2386 |
|
Assuming that the buffer syntax table specifies hash characters to |
2387 |
|
have comment start syntax, the element will only highlight hash |
2388 |
|
characters that do not follow dollar characters as comments |
2389 |
|
syntactically. |
2390 |
|
|
2391 |
|
An element of the form: |
2392 |
|
|
2393 |
|
@example |
2394 |
|
("\\('\\).\\('\\)" |
2395 |
|
(1 "\"") |
2396 |
|
(2 "\"")) |
2397 |
|
@end example |
2398 |
|
|
2399 |
|
highlights syntactically both single quotes which surround a single |
2400 |
|
character, with a SYNTAX of @code{"\""} (meaning string quote syntax). |
2401 |
|
Assuming that the buffer syntax table does not specify single quotes |
2402 |
|
to have quote syntax, the element will only highlight single quotes of |
2403 |
|
the form @samp{'@var{c}'} as strings syntactically. Other forms, such |
2404 |
|
as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as |
2405 |
|
strings. |
2406 |
|
|
2407 |
@end defvar |
@end defvar |
2408 |
|
|
2409 |
@node Hooks |
@node Hooks |
2433 |
|
|
2434 |
The recommended way to add a hook function to a normal hook is by |
The recommended way to add a hook function to a normal hook is by |
2435 |
calling @code{add-hook} (see below). The hook functions may be any of |
calling @code{add-hook} (see below). The hook functions may be any of |
2436 |
the valid kinds of functions that @code{funcall} accepts (@pxref{What Is |
the valid kinds of functions that @code{funcall} accepts (@pxref{What |
2437 |
a Function}). Most normal hook variables are initially void; |
Is a Function}). Most normal hook variables are initially void; |
2438 |
@code{add-hook} knows how to deal with this. |
@code{add-hook} knows how to deal with this. You can add hooks either |
2439 |
|
globally or buffer-locally with @code{add-hook}. |
2440 |
|
|
2441 |
@cindex abnormal hook |
@cindex abnormal hook |
2442 |
If the hook variable's name does not end with @samp{-hook}, that |
If the hook variable's name does not end with @samp{-hook}, that |
2467 |
been added with @code{add-hook}. |
been added with @code{add-hook}. |
2468 |
|
|
2469 |
@defun run-hooks &rest hookvars |
@defun run-hooks &rest hookvars |
2470 |
This function takes one or more hook variable names as arguments, and |
This function takes one or more normal hook variable names as |
2471 |
runs each hook in turn. Each argument should be a symbol that is a hook |
arguments, and runs each hook in turn. Each argument should be a |
2472 |
variable. These arguments are processed in the order specified. |
symbol that is a normal hook variable. These arguments are processed |
2473 |
|
in the order specified. |
2474 |
|
|
2475 |
If a hook variable has a non-@code{nil} value, that value may be a |
If a hook variable has a non-@code{nil} value, that value may be a |
2476 |
function or a list of functions. If the value is a function (either a |
function or a list of functions. (The former option is considered |
2477 |
lambda expression or a symbol with a function definition), it is called. |
obsolete.) If the value is a function (either a lambda expression or |
2478 |
If it is a list, the elements are called, in order. The hook functions |
a symbol with a function definition), it is called. If it is a list |
2479 |
are called with no arguments. Nowadays, storing a single function in |
that isn't a function, its elements are called, consecutively. All |
2480 |
the hook variable is semi-obsolete; you should always use a list of |
the hook functions are called with no arguments. |
|
functions. |
|
2481 |
|
|
2482 |
For example, here's how @code{emacs-lisp-mode} runs its mode hook: |
For example, here's how @code{emacs-lisp-mode} runs its mode hook: |
2483 |
|
|
2486 |
@end example |
@end example |
2487 |
@end defun |
@end defun |
2488 |
|
|
2489 |
|
@defun run-mode-hooks &rest hookvars |
2490 |
|
Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks} |
2491 |
|
macro. |
2492 |
|
@end defun |
2493 |
|
|
2494 |
|
@defmac delay-mode-hooks body... |
2495 |
|
This macro executes the @var{body} forms but defers all calls to |
2496 |
|
@code{run-mode-hooks} within them until the end of @var{body}. |
2497 |
|
This macro enables a derived mode to arrange not to run |
2498 |
|
its parent modes' mode hooks until the end. |
2499 |
|
@end defmac |
2500 |
|
|
2501 |
@defun run-hook-with-args hook &rest args |
@defun run-hook-with-args hook &rest args |
2502 |
This function is the way to run an abnormal hook which passes arguments |
This function is the way to run an abnormal hook and always call all |
2503 |
to the hook functions. It calls each of the hook functions, passing |
of the hook functions. It calls each of the hook functions one by |
2504 |
each of them the arguments @var{args}. |
one, passing each of them the arguments @var{args}. |
2505 |
@end defun |
@end defun |
2506 |
|
|
2507 |
@defun run-hook-with-args-until-failure hook &rest args |
@defun run-hook-with-args-until-failure hook &rest args |
2508 |
This function is the way to run an abnormal hook which passes arguments |
This function is the way to run an abnormal hook until one of the hook |
2509 |
to the hook functions, and stops as soon as any hook function fails. It |
functions fails. It calls each of the hook functions, passing each of |
2510 |
calls each of the hook functions, passing each of them the arguments |
them the arguments @var{args}, until some hook function returns |
2511 |
@var{args}, until some hook function returns @code{nil}. Then it stops, |
@code{nil}. It then stops and returns @code{nil}. If none of the |
2512 |
and returns @code{nil} if some hook function returned @code{nil}. |
hook functions return @code{nil}, it returns a non-@code{nil} value. |
|
Otherwise it returns a non-@code{nil} value. |
|
2513 |
@end defun |
@end defun |
2514 |
|
|
2515 |
@defun run-hook-with-args-until-success hook &rest args |
@defun run-hook-with-args-until-success hook &rest args |
2516 |
This function is the way to run an abnormal hook which passes arguments |
This function is the way to run an abnormal hook until a hook function |
2517 |
to the hook functions, and stops as soon as any hook function succeeds. |
succeeds. It calls each of the hook functions, passing each of them |
2518 |
It calls each of the hook functions, passing each of them the arguments |
the arguments @var{args}, until some hook function returns |
2519 |
@var{args}, until some hook function returns non-@code{nil}. Then it |
non-@code{nil}. Then it stops, and returns whatever was returned by |
2520 |
stops, and returns whatever was returned by the last hook function |
the last hook function that was called. If all hook functions return |
2521 |
that was called. |
@code{nil}, it returns @code{nil} as well. |
2522 |
@end defun |
@end defun |
2523 |
|
|
2524 |
@defun add-hook hook function &optional append local |
@defun add-hook hook function &optional append local |
2525 |
This function is the handy way to add function @var{function} to hook |
This function is the handy way to add function @var{function} to hook |
2526 |
variable @var{hook}. The argument @var{function} may be any valid Lisp |
variable @var{hook}. You can use it for abnormal hooks as well as for |
2527 |
function with the proper number of arguments. For example, |
normal hooks. @var{function} can be any Lisp function that can accept |
2528 |
|
the proper number of arguments for @var{hook}. For example, |
2529 |
|
|
2530 |
@example |
@example |
2531 |
(add-hook 'text-mode-hook 'my-text-hook-function) |
(add-hook 'text-mode-hook 'my-text-hook-function) |
2534 |
@noindent |
@noindent |
2535 |
adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. |
adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. |
2536 |
|
|
2537 |
You can use @code{add-hook} for abnormal hooks as well as for normal |
If @var{function} is already present in @var{hook} (comparing using |
2538 |
hooks. |
@code{equal}), then @code{add-hook} does not add it a second time. |
2539 |
|
|
2540 |
It is best to design your hook functions so that the order in which they |
It is best to design your hook functions so that the order in which they |
2541 |
are executed does not matter. Any dependence on the order is ``asking |
are executed does not matter. Any dependence on the order is ``asking |
2542 |
for trouble.'' However, the order is predictable: normally, |
for trouble''. However, the order is predictable: normally, |
2543 |
@var{function} goes at the front of the hook list, so it will be |
@var{function} goes at the front of the hook list, so it will be |
2544 |
executed first (barring another @code{add-hook} call). If the optional |
executed first (barring another @code{add-hook} call). If the optional |
2545 |
argument @var{append} is non-@code{nil}, the new hook function goes at |
argument @var{append} is non-@code{nil}, the new hook function goes at |
2546 |
the end of the hook list and will be executed last. |
the end of the hook list and will be executed last. |
2547 |
|
|
2548 |
If @var{local} is non-@code{nil}, that says to add @var{function} |
If @var{local} is non-@code{nil}, that says to add @var{function} to |
2549 |
to the buffer-local hook list instead of to the global hook list. |
the buffer-local hook list instead of to the global hook list. If |
2550 |
|
needed, this makes the hook buffer-local and adds @code{t} to the |
2551 |
|
buffer-local value. The latter acts as a flag to run the hook |
2552 |
|
functions in the default value as well as in the local value. |
2553 |
@end defun |
@end defun |
2554 |
|
|
2555 |
@defun remove-hook hook function &optional local |
@defun remove-hook hook function &optional local |
2556 |
This function removes @var{function} from the hook variable @var{hook}. |
This function removes @var{function} from the hook variable |
2557 |
|
@var{hook}. It compares @var{function} with elements of @var{hook} |
2558 |
|
using @code{equal}, so it works for both symbols and lambda |
2559 |
|
expressions. |
2560 |
|
|
2561 |
If @var{local} is non-@code{nil}, that says to remove @var{function} |
If @var{local} is non-@code{nil}, that says to remove @var{function} |
2562 |
from the buffer-local hook list instead of from the global hook list. |
from the buffer-local hook list instead of from the global hook list. |
2563 |
@end defun |
@end defun |
2564 |
|
|
2565 |
|
@ignore |
2566 |
|
arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e |
2567 |
|
@end ignore |