/[emacs]/emacs/lispref/modes.texi
ViewVC logotype

Diff of /emacs/lispref/modes.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.63 by lute, Mon Sep 8 07:59:06 2003 UTC revision 1.64 by lute, Fri Sep 26 12:15:32 2003 UTC
# Line 274  recommended way to define one is to use Line 274  recommended way to define one is to use
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
# Line 1101  See the command \\[hungry-electric-delet Line 1101  See the command \\[hungry-electric-delet
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
# Line 1166  actually appears. Line 1166  actually appears.
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
# Line 1207  mode line (@pxref{Standard Faces}). Line 1209  mode line (@pxref{Standard Faces}).
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    
# Line 1224  displayed verbatim: the @code{%}-constru Line 1226  displayed verbatim: the @code{%}-constru
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.
# Line 1275  directory. Line 1285  directory.
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     ":"     ":"
# Line 1332  Changing this variable does not force an Line 1342  Changing this variable does not force an
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    
# Line 1343  default value is @code{("%12b")}, which Line 1353  default value is @code{("%12b")}, which
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
# Line 1370  the @code{minor-mode-alist} should be a Line 1430  the @code{minor-mode-alist} should be a
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
# Line 1425  This variable holds the default @code{mo Line 1462  This variable holds the default @code{mo
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
# Line 1436  The default value of @code{default-mode- Line 1475  The default value of @code{default-mode-
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
# Line 1564  The value of @code{global-mode-string}. Line 1593  The value of @code{global-mode-string}.
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
# Line 1601  keymap can only take real effect for mou Line 1634  keymap can only take real effect for mou
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
# Line 1621  It is normally @code{nil}, so that ordin Line 1654  It is normally @code{nil}, so that ordin
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
# Line 2214  fontification, you may use the special c Line 2247  fontification, you may use the special c
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    

Legend:
Removed from v.1.63  
changed lines
  Added in v.1.64

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26