274 |
but this is not required. Such a mode should use |
but this is not required. Such a mode should use |
275 |
@code{delay-mode-hooks} around its entire body, including the call to |
@code{delay-mode-hooks} around its entire body, including the call to |
276 |
the parent mode command and the final call to @code{run-mode-hooks}. |
the parent mode command and the final call to @code{run-mode-hooks}. |
277 |
(Using @code{define-derived-mode} does this automatically.) |
(Using @code{define-derived-mode} does this automatically.) |
278 |
|
|
279 |
@item |
@item |
280 |
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 |
1101 |
@end smallexample |
@end smallexample |
1102 |
|
|
1103 |
@node Mode Line Format |
@node Mode Line Format |
1104 |
@section Mode Line Format |
@section Mode-Line Format |
1105 |
@cindex mode line |
@cindex mode line |
1106 |
|
|
1107 |
Each Emacs window (aside from minibuffer windows) typically has a mode |
Each Emacs window (aside from minibuffer windows) typically has a mode |
1166 |
|
|
1167 |
@node Mode Line Data |
@node Mode Line Data |
1168 |
@subsection The Data Structure of the Mode Line |
@subsection The Data Structure of the Mode Line |
1169 |
@cindex mode line construct |
@cindex mode-line construct |
1170 |
|
|
1171 |
The mode line contents are controlled by a data structure of lists, |
The mode-line contents are controlled by a data structure of lists, |
1172 |
strings, symbols, and numbers kept in buffer-local variables. The data |
strings, symbols, and numbers kept in buffer-local variables. The data |
1173 |
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 |
1174 |
recursive fashion out of simpler mode line constructs. The same data |
recursive fashion out of simpler mode-line constructs. The same data |
1175 |
structure is used for constructing frame titles (@pxref{Frame Titles}) |
structure is used for constructing frame titles (@pxref{Frame Titles}) |
1176 |
and header lines (@pxref{Header Lines}). |
and header lines (@pxref{Header Lines}). |
1177 |
|
|
1178 |
@defvar mode-line-format |
@defvar mode-line-format |
1179 |
The value of this variable is a mode line construct with overall |
The value of this variable is a mode-line construct with overall |
1180 |
responsibility for the mode line format. The value of this variable |
responsibility for the mode-line format. The value of this variable |
1181 |
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 |
1182 |
where they appear. |
where they appear. |
1183 |
|
|
1184 |
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 |
1185 |
have a mode line. (This feature was added in Emacs 21.) |
have a mode line. (This feature was added in Emacs 21.) |
1186 |
@end defvar |
@end defvar |
1187 |
|
|
1188 |
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 |
1189 |
it usually specifies how to use other variables to construct the text. |
it usually specifies how to use other variables to construct the text. |
1190 |
Many of these variables are themselves defined to have mode line |
Many of these variables are themselves defined to have mode-line |
1191 |
constructs as their values. |
constructs as their values. |
1192 |
|
|
1193 |
The default value of @code{mode-line-format} incorporates the values |
The default value of @code{mode-line-format} incorporates the values |
1194 |
of variables such as @code{mode-name} and @code{minor-mode-alist}. |
of variables such as @code{mode-line-position} and |
1195 |
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 |
1196 |
itself. For most purposes, it is sufficient to alter some of the |
variables @code{mode-name} and @code{minor-mode-alist}). Because of |
1197 |
variables that @code{mode-line-format} refers to. |
this, very few modes need to alter @code{mode-line-format} itself. For |
1198 |
|
most purposes, it is sufficient to alter some of the variables that |
1199 |
|
@code{mode-line-format} either directly or indirectly refers to. |
1200 |
|
|
1201 |
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 |
1202 |
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. |
1203 |
|
|
1204 |
The mode line can display various faces, if the strings that control |
The mode line can display various faces, if the strings that control |
1209 |
@table @code |
@table @code |
1210 |
@cindex percent symbol in mode line |
@cindex percent symbol in mode line |
1211 |
@item @var{string} |
@item @var{string} |
1212 |
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 |
1213 |
except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%} |
except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%} |
1214 |
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 |
1215 |
is left justified). @xref{%-Constructs}. |
is left justified). @xref{%-Constructs}. |
1216 |
|
|
1217 |
@item @var{symbol} |
@item @var{symbol} |
1218 |
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 |
1219 |
@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}. |
1220 |
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 |
1221 |
symbol whose value is void. |
symbol whose value is void. |
1222 |
|
|
1226 |
@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{}) |
1227 |
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 |
1228 |
elements recursively and concatenate the results. This is the most |
elements recursively and concatenate the results. This is the most |
1229 |
common form of mode line construct. |
common form of mode-line construct. |
1230 |
|
|
1231 |
@item (:eval @var{form}) |
@item (:eval @var{form}) |
1232 |
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 |
1233 |
@var{form}, and use the result as a string to display. |
@var{form}, and use the result as a string to display. |
1234 |
(This feature is new as of Emacs 21.) |
(This feature is new as of Emacs 21.) |
1235 |
|
|
1236 |
|
@item (:propertize @var{elt} @var{props}@dots{}) |
1237 |
|
A list whose first element is the symbol @code{:propertize} says to |
1238 |
|
process the mode-line construct @var{elt} recursively and add the text |
1239 |
|
properties specified by @var{props} to the result. The argument |
1240 |
|
@var{props} should consist of zero or more pairs @var{text-property} |
1241 |
|
@var{value}. (This feature is new as of Emacs 21.4.) |
1242 |
|
@c FIXME: This might be Emacs 21.5. |
1243 |
|
|
1244 |
@item (@var{symbol} @var{then} @var{else}) |
@item (@var{symbol} @var{then} @var{else}) |
1245 |
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 |
1246 |
conditional. Its meaning depends on the value of @var{symbol}. If the |
conditional. Its meaning depends on the value of @var{symbol}. If the |
1247 |
value is non-@code{nil}, the second element, @var{then}, is processed |
value is non-@code{nil}, the second element, @var{then}, is processed |
1248 |
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 |
1249 |
@code{nil}, the third element, @var{else}, is processed recursively. |
@code{nil}, the third element, @var{else}, is processed recursively. |
1250 |
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 |
1251 |
the value of @var{symbol} is @code{nil}. |
the value of @var{symbol} is @code{nil}. |
1252 |
|
|
1253 |
@item (@var{width} @var{rest}@dots{}) |
@item (@var{width} @var{rest}@dots{}) |
1254 |
A list whose first element is an integer specifies truncation or |
A list whose first element is an integer specifies truncation or |
1255 |
padding of the results of @var{rest}. The remaining elements |
padding of the results of @var{rest}. The remaining elements |
1256 |
@var{rest} are processed recursively as mode line constructs and |
@var{rest} are processed recursively as mode-line constructs and |
1257 |
concatenated together. Then the result is space filled (if |
concatenated together. Then the result is space filled (if |
1258 |
@var{width} is positive) or truncated (to @minus{}@var{width} columns, |
@var{width} is positive) or truncated (to @minus{}@var{width} columns, |
1259 |
if @var{width} is negative) on the right. |
if @var{width} is negative) on the right. |
1285 |
@end group |
@end group |
1286 |
@group |
@group |
1287 |
;; @r{Note that this is evaluated while making the list.} |
;; @r{Note that this is evaluated while making the list.} |
1288 |
;; @r{It makes a mode line construct which is just a string.} |
;; @r{It makes a mode-line construct which is just a string.} |
1289 |
(getenv "HOST") |
(getenv "HOST") |
1290 |
@end group |
@end group |
1291 |
":" |
":" |
1342 |
|
|
1343 |
@defvar mode-line-frame-identification |
@defvar mode-line-frame-identification |
1344 |
This variable identifies the current frame. The default value is |
This variable identifies the current frame. The default value is |
1345 |
@code{" "} if you are using a window system which can show multiple |
@code{" "} if you are using a window system which can show multiple |
1346 |
frames, or @code{"-%F "} on an ordinary terminal which shows only one |
frames, or @code{"-%F "} on an ordinary terminal which shows only one |
1347 |
frame at a time. |
frame at a time. |
1348 |
@end defvar |
@end defvar |
1349 |
|
|
1353 |
with spaces to at least 12 columns. |
with spaces to at least 12 columns. |
1354 |
@end defvar |
@end defvar |
1355 |
|
|
1356 |
@defvar global-mode-string |
@defvar mode-line-position |
1357 |
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 |
1358 |
default, just after the buffer name. The command @code{display-time} |
simplified version of its default value. The actual default value |
1359 |
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. |
|
1360 |
|
|
1361 |
The @samp{%M} construct substitutes the value of |
@example |
1362 |
@code{global-mode-string}, but that is obsolete, since the variable is |
@group |
1363 |
included in the mode line from @code{mode-line-format}. |
((-3 . "%p") |
1364 |
|
(size-indication-mode (8 " of %I")) |
1365 |
|
@end group |
1366 |
|
@group |
1367 |
|
(line-number-mode |
1368 |
|
((column-number-mode |
1369 |
|
(10 " (%l,%c)") |
1370 |
|
(6 " L%l"))) |
1371 |
|
((column-number-mode |
1372 |
|
(5 " C%c"))))) |
1373 |
|
@end group |
1374 |
|
@end example |
1375 |
|
|
1376 |
|
This means that @code{mode-line-position} displays at least the buffer |
1377 |
|
percentage and possibly the buffer size, the line number and the column |
1378 |
|
number. |
1379 |
@end defvar |
@end defvar |
1380 |
|
|
1381 |
|
@defvar vc-mode |
1382 |
|
The variable @code{vc-mode}, buffer-local in each buffer, records |
1383 |
|
whether the buffer's visited file is maintained with version control, |
1384 |
|
and, if so, which kind. Its value is a string that appears in the mode |
1385 |
|
line, or @code{nil} for no version control. |
1386 |
|
@end defvar |
1387 |
|
|
1388 |
|
@defvar mode-line-modes |
1389 |
|
This variable displays the buffer's major and minor modes. Here is a |
1390 |
|
simplified version of its default value. The real default value also |
1391 |
|
specifies addition of text properties. |
1392 |
|
|
1393 |
|
@example |
1394 |
|
@group |
1395 |
|
("%[(" mode-name |
1396 |
|
mode-line-process minor-mode-alist |
1397 |
|
"%n" ")%]--") |
1398 |
|
@end group |
1399 |
|
@end example |
1400 |
|
|
1401 |
|
So @code{mode-line-modes} normally also displays the recursive editing |
1402 |
|
level, information on the process status and whether narrowing is in |
1403 |
|
effect. |
1404 |
|
@end defvar |
1405 |
|
|
1406 |
|
The following three variables are used in @code{mode-line-modes}: |
1407 |
|
|
1408 |
@defvar mode-name |
@defvar mode-name |
1409 |
This buffer-local variable holds the ``pretty'' name of the current |
This buffer-local variable holds the ``pretty'' name of the current |
1410 |
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 |
1411 |
mode name will appear in the mode line. |
mode name will appear in the mode line. |
1412 |
@end defvar |
@end defvar |
1413 |
|
|
1414 |
|
@defvar mode-line-process |
1415 |
|
This buffer-local variable contains the mode-line information on process |
1416 |
|
status in modes used for communicating with subprocesses. It is |
1417 |
|
displayed immediately following the major mode name, with no intervening |
1418 |
|
space. For example, its value in the @samp{*shell*} buffer is |
1419 |
|
@code{(":%s")}, which allows the shell to display its status along |
1420 |
|
with the major mode as: @samp{(Shell:run)}. Normally this variable |
1421 |
|
is @code{nil}. |
1422 |
|
@end defvar |
1423 |
|
|
1424 |
@defvar minor-mode-alist |
@defvar minor-mode-alist |
1425 |
This variable holds an association list whose elements specify how the |
This variable holds an association list whose elements specify how the |
1426 |
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 |
1430 |
(@var{minor-mode-variable} @var{mode-line-string}) |
(@var{minor-mode-variable} @var{mode-line-string}) |
1431 |
@end example |
@end example |
1432 |
|
|
1433 |
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 |
1434 |
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} |
1435 |
non-@code{nil}, and not otherwise. These strings should begin with |
is non-@code{nil}, and not otherwise. These strings should begin with |
1436 |
spaces so that they don't run together. Conventionally, the |
spaces so that they don't run together. Conventionally, the |
1437 |
@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 |
1438 |
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 |
|
1439 |
|
|
1440 |
@code{minor-mode-alist} itself is not buffer-local. Each variable |
@code{minor-mode-alist} itself is not buffer-local. Each variable |
1441 |
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 |
1442 |
enabled separately in each buffer. |
enabled separately in each buffer. |
1443 |
@end defvar |
@end defvar |
1444 |
|
|
1445 |
@defvar mode-line-process |
@defvar global-mode-string |
1446 |
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 |
1447 |
status in modes used for communicating with subprocesses. It is |
default, just after the buffer name. The command @code{display-time} |
1448 |
displayed immediately following the major mode name, with no intervening |
sets @code{global-mode-string} to refer to the variable |
1449 |
space. For example, its value in the @samp{*shell*} buffer is |
@code{display-time-string}, which holds a string containing the time and |
1450 |
@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: |
|
1451 |
|
|
1452 |
@defvar vc-mode |
The @samp{%M} construct substitutes the value of |
1453 |
The variable @code{vc-mode}, buffer-local in each buffer, records |
@code{global-mode-string}, but that is obsolete, since the variable is |
1454 |
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. |
|
1455 |
@end defvar |
@end defvar |
1456 |
|
|
1457 |
The variable @code{default-mode-line-format} is where |
The variable @code{default-mode-line-format} is where |
1462 |
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 |
1463 |
'mode-line-format)}. |
'mode-line-format)}. |
1464 |
|
|
1465 |
The default value of @code{default-mode-line-format} is this list: |
Here is a simplified version of the default value of |
1466 |
|
@code{default-mode-line-format}. The real default value also |
1467 |
|
specifies addition of text properties. |
1468 |
|
|
1469 |
@example |
@example |
1470 |
@group |
@group |
1475 |
mode-line-buffer-identification |
mode-line-buffer-identification |
1476 |
@end group |
@end group |
1477 |
" " |
" " |
1478 |
global-mode-string |
mode-line-position |
1479 |
@group |
(vc-mode vc-mode) |
1480 |
" %[(" |
" " |
|
;; @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 |
|
1481 |
@group |
@group |
1482 |
|
mode-line-modes |
1483 |
(which-func-mode ("" which-func-format "--")) |
(which-func-mode ("" which-func-format "--")) |
1484 |
(line-number-mode "L%l--") |
(global-mode-string ("--" global-mode-string)) |
|
(column-number-mode "C%c--") |
|
|
(-3 . "%p") |
|
1485 |
"-%-") |
"-%-") |
1486 |
@end group |
@end group |
1487 |
@end example |
@end example |
1593 |
|
|
1594 |
@node Properties in Mode |
@node Properties in Mode |
1595 |
@subsection Properties in the Mode Line |
@subsection Properties in the Mode Line |
1596 |
|
@cindex text properties in the mode line |
1597 |
|
|
1598 |
Starting in Emacs 21, certain text properties are meaningful in the |
Starting in Emacs 21, certain text properties are meaningful in the |
1599 |
mode line. The @code{face} property affects the appearance of text; the |
mode line. The @code{face} property affects the appearance of text; the |
1600 |
@code{help-echo} property associate help strings with the text, and |
@code{help-echo} property associate help strings with the text, and |
1601 |
@code{local-map} can make the text mouse-sensitive. |
@code{local-map} can make the text mouse-sensitive. |
1602 |
|
|
1603 |
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 |
1604 |
line: |
line: |
1605 |
|
|
1606 |
@enumerate |
@enumerate |
1607 |
@item |
@item |
1608 |
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 |
1609 |
mode-line data structure. |
structure. |
1610 |
|
|
1611 |
|
@item |
1612 |
|
Put a text property on a mode-line %-construct such as @samp{%12b}; then |
1613 |
|
the expansion of the %-construct will have that same text property. |
1614 |
|
|
1615 |
@item |
@item |
1616 |
Put a @code{local-map} property on a mode-line %-construct |
Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to |
1617 |
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. |
|
1618 |
|
|
1619 |
@item |
@item |
1620 |
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 |
1621 |
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 |
1622 |
@code{local-map} property. |
property. |
1623 |
@end enumerate |
@end enumerate |
1624 |
|
|
1625 |
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 |
1634 |
|
|
1635 |
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 |
1636 |
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 |
1637 |
feature works just like the mode line feature, except that it's |
feature works just like the mode-line feature, except that it's |
1638 |
controlled by different variables. |
controlled by different variables. |
1639 |
|
|
1640 |
@tindex header-line-format |
@tindex header-line-format |
1654 |
@end defvar |
@end defvar |
1655 |
|
|
1656 |
@node Emulating Mode Line |
@node Emulating Mode Line |
1657 |
@subsection Emulating Mode Line Formatting |
@subsection Emulating Mode-Line Formatting |
1658 |
|
|
1659 |
You can use the function @code{format-mode-line} to compute |
You can use the function @code{format-mode-line} to compute |
1660 |
the text that would appear in a mode line or header line |
the text that would appear in a mode line or header line |
1661 |
based on certain mode line specification. |
based on certain mode-line specification. |
1662 |
|
|
1663 |
@defun format-mode-line &optional format window no-props |
@defun format-mode-line &optional format window no-props |
1664 |
This function formats a line of text according to @var{format} as if |
This function formats a line of text according to @var{format} as if |
2247 |
@code{font-lock-face} (@pxref{Special Properties}). This property |
@code{font-lock-face} (@pxref{Special Properties}). This property |
2248 |
acts just like the explicit @code{face} property, but its activation |
acts just like the explicit @code{face} property, but its activation |
2249 |
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 |
2250 |
@code{font-lock-face} is especially conveninent for special modes |
@code{font-lock-face} is especially convenient for special modes |
2251 |
which construct their text programmatically, such as |
which construct their text programmatically, such as |
2252 |
@code{list-buffers} and @code{occur}. |
@code{list-buffers} and @code{occur}. |
2253 |
|
|