From: Lute Kamstra <Lute.Kamstra@cwi.nl>
Subject: Update of Mode Line Format in the Lisp Reference Manual.
Date: Thu, 25 Sep 2003 17:45:18 +0200 [thread overview]
Message-ID: <sgdptho7typ.fsf@occarina.pna.cwi.nl> (raw)
I've updated the Mode Line Format node of the Lisp Reference Manual.
I documented a couple of new features like the (:propertize elt
props...) construct and the mode-line-position and mode-line-modes
variables. It would be nice if people involved in their
implementation would look at it before I commit the update.
Lute.
Index: lispref/modes.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/modes.texi,v
retrieving revision 1.63
diff -c -r1.63 modes.texi
*** lispref/modes.texi 8 Sep 2003 07:59:06 -0000 1.63
--- lispref/modes.texi 25 Sep 2003 15:32:13 -0000
***************
*** 274,280 ****
but this is not required. Such a mode should use
@code{delay-mode-hooks} around its entire body, including the call to
the parent mode command and the final call to @code{run-mode-hooks}.
! (Using @code{define-derived-mode} does this automatically.)
@item
If something special should be done if the user switches a buffer from
--- 274,280 ----
but this is not required. Such a mode should use
@code{delay-mode-hooks} around its entire body, including the call to
the parent mode command and the final call to @code{run-mode-hooks}.
! (Using @code{define-derived-mode} does this automatically.)
@item
If something special should be done if the user switches a buffer from
***************
*** 1191,1200 ****
constructs as their values.
The default value of @code{mode-line-format} incorporates the values
! of variables such as @code{mode-name} and @code{minor-mode-alist}.
! Because of this, very few modes need to alter @code{mode-line-format}
! itself. For most purposes, it is sufficient to alter some of the
! variables that @code{mode-line-format} refers to.
A mode line construct may be a list, a symbol, or a string. If the
value is a list, each element may be a list, a symbol, or a string.
--- 1191,1202 ----
constructs as their values.
The default value of @code{mode-line-format} incorporates the values
! of variables such as @code{mode-line-position} and
! @code{mode-line-modes} (which in turn incorporates the values of the
! variables @code{mode-name} and @code{minor-mode-alist}). Because of
! this, very few modes need to alter @code{mode-line-format} itself. For
! most purposes, it is sufficient to alter some of the variables that
! @code{mode-line-format} either directly or indirectly refers to.
A mode line construct may be a list, a symbol, or a string. If the
value is a list, each element may be a list, a symbol, or a string.
***************
*** 1231,1236 ****
--- 1233,1246 ----
@var{form}, and use the result as a string to display.
(This feature is new as of Emacs 21.)
+ @item (:propertize @var{elt} @var{props}@dots{})
+ A list whose first element is the symbol @code{:propertize} says to
+ process the mode line construct @var{elt} recursively and add the text
+ properties specified by @var{props} to the result. The argument
+ @var{props} should consist of zero or more pairs @var{text-property}
+ @var{value}. (This feature is new as of Emacs 21.4.)
+ @c FIXME: This might be Emacs 21.5.
+
@item (@var{symbol} @var{then} @var{else})
A list whose first element is a symbol that is not a keyword specifies a
conditional. Its meaning depends on the value of @var{symbol}. If the
***************
*** 1312,1324 ****
@code{mode-line-format} were changed to use them.
@defvar mode-line-mule-info
! This variable holds the value of the mode-line construct that displays
information about the language environment, buffer coding system, and
current input method. @xref{Non-ASCII Characters}.
@end defvar
@defvar mode-line-modified
! This variable holds the value of the mode-line construct that displays
whether the current buffer is modified.
The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
--- 1322,1334 ----
@code{mode-line-format} were changed to use them.
@defvar mode-line-mule-info
! This variable holds the value of the mode line construct that displays
information about the language environment, buffer coding system, and
current input method. @xref{Non-ASCII Characters}.
@end defvar
@defvar mode-line-modified
! This variable holds the value of the mode line construct that displays
whether the current buffer is modified.
The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
***************
*** 1332,1339 ****
@defvar mode-line-frame-identification
This variable identifies the current frame. The default value is
! @code{" "} if you are using a window system which can show multiple
! frames, or @code{"-%F "} on an ordinary terminal which shows only one
frame at a time.
@end defvar
--- 1342,1349 ----
@defvar mode-line-frame-identification
This variable identifies the current frame. The default value is
! @code{" "} if you are using a window system which can show multiple
! frames, or @code{"-%F "} on an ordinary terminal which shows only one
frame at a time.
@end defvar
***************
*** 1343,1366 ****
with spaces to at least 12 columns.
@end defvar
! @defvar global-mode-string
! This variable holds a mode line spec that appears in the mode line by
! default, just after the buffer name. The command @code{display-time}
! sets @code{global-mode-string} to refer to the variable
! @code{display-time-string}, which holds a string containing the time and
! load information.
! The @samp{%M} construct substitutes the value of
! @code{global-mode-string}, but that is obsolete, since the variable is
! included in the mode line from @code{mode-line-format}.
@end defvar
@defvar mode-name
This buffer-local variable holds the ``pretty'' name of the current
buffer's major mode. Each major mode should set this variable so that the
mode name will appear in the mode line.
@end defvar
@defvar minor-mode-alist
This variable holds an association list whose elements specify how the
mode line should indicate that a minor mode is active. Each element of
--- 1353,1427 ----
with spaces to at least 12 columns.
@end defvar
! @defvar mode-line-position
! This variable indicates the position in the buffer. The default value
! (with text properties omitted) is:
! @example
! @group
! ((-3 . "%p")
! (size-indication-mode (8 " of %I"))
! @end group
! @group
! (line-number-mode
! ((column-number-mode
! (10 " (%l,%c)")
! (6 " L%l")))
! ((column-number-mode
! (5 " C%c")))))
! @end group
! @end example
!
! This means that @code{mode-line-position} displays at least the buffer
! percentage and possibly the buffer size, the line number and the column
! number.
! @end defvar
!
! @defvar vc-mode
! The variable @code{vc-mode}, buffer-local in each buffer, records
! whether the buffer's visited file is maintained with version control,
! and, if so, which kind. Its value is a string that appears in the mode
! line, or @code{nil} for no version control.
! @end defvar
!
! @defvar mode-line-modes
! This variable displays the buffer's major and minor modes. Its default
! value (with text properties omitted) is:
!
! @example
! @group
! ("%[("
! mode-name
! mode-line-process
! minor-mode-alist
! "%n"
! ")%]--")
! @end group
! @end example
!
! So @code{mode-line-modes} normally also displays the recursive editing
! level, information on the process status and whether narrowing is in
! effect.
@end defvar
+ The following three variables are used in @code{mode-line-modes}:
+
@defvar mode-name
This buffer-local variable holds the ``pretty'' name of the current
buffer's major mode. Each major mode should set this variable so that the
mode name will appear in the mode line.
@end defvar
+ @defvar mode-line-process
+ This buffer-local variable contains the mode line information on process
+ status in modes used for communicating with subprocesses. It is
+ displayed immediately following the major mode name, with no intervening
+ space. For example, its value in the @samp{*shell*} buffer is
+ @code{(":%s")}, which allows the shell to display its status along
+ with the major mode as: @samp{(Shell:run)}. Normally this variable
+ is @code{nil}.
+ @end defvar
+
@defvar minor-mode-alist
This variable holds an association list whose elements specify how the
mode line should indicate that a minor mode is active. Each element of
***************
*** 1377,1393 ****
@var{minor-mode-variable} for a specific mode is set to a 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
--- 1438,1461 ----
@var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
value when that minor mode is activated.
! The default value (without text properties) of @code{minor-mode-alist}
! is:
@example
@group
! ((ispell-minor-mode " Spell")
! (checkdoc-minor-mode " CDoc")
! (view-mode " View")
! @end group
! (server-buffer-clients " Server")
! (visible-mode " Vis")
! (flyspell-mode flyspell-mode-line-string)
! (abbrev-mode " Abbrev")
! (overwrite-mode overwrite-mode)
! @group
! (auto-fill-function " Fill")
! (defining-kbd-macro " Def")
! (isearch-mode isearch-mode))
@end group
@end example
***************
*** 1396,1420 ****
enabled separately in each buffer.
@end defvar
! @defvar mode-line-process
! This buffer-local variable contains the mode line information on process
! status in modes used for communicating with subprocesses. It is
! displayed immediately following the major mode name, with no intervening
! space. For example, its value in the @samp{*shell*} buffer is
! @code{(":%s")}, which allows the shell to display its status along
! 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:
! @defvar vc-mode
! The variable @code{vc-mode}, buffer-local in each buffer, records
! whether the buffer's visited file is maintained with version control,
! and, if so, which kind. Its value is a string that appears in the mode
! line, or @code{nil} for no version control.
@end defvar
The variable @code{default-mode-line-format} is where
--- 1464,1479 ----
enabled separately in each buffer.
@end defvar
! @defvar global-mode-string
! This variable holds a mode line spec that appears in the mode line by
! default, just after the buffer name. The command @code{display-time}
! sets @code{global-mode-string} to refer to the variable
! @code{display-time-string}, which holds a string containing the time and
! load information.
! The @samp{%M} construct substitutes the value of
! @code{global-mode-string}, but that is obsolete, since the variable is
! included in the mode line from @code{mode-line-format}.
@end defvar
The variable @code{default-mode-line-format} is where
***************
*** 1425,1431 ****
that do not override it. This is the same as @code{(default-value
'mode-line-format)}.
! The default value of @code{default-mode-line-format} is this list:
@example
@group
--- 1484,1491 ----
that do not override it. This is the same as @code{(default-value
'mode-line-format)}.
! The default value of @code{default-mode-line-format} is this list (text
! properties omitted):
@example
@group
***************
*** 1436,1458 ****
mode-line-buffer-identification
@end group
" "
! global-mode-string
! @group
! " %[("
! ;; @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
@group
(which-func-mode ("" which-func-format "--"))
! (line-number-mode "L%l--")
! (column-number-mode "C%c--")
! (-3 . "%p")
"-%-")
@end group
@end example
--- 1496,1508 ----
mode-line-buffer-identification
@end group
" "
! mode-line-position
! (vc-mode vc-mode)
! " "
@group
+ mode-line-modes
(which-func-mode ("" which-func-format "--"))
! (global-mode-string ("--" global-mode-string))
"-%-")
@end group
@end example
***************
*** 1500,1507 ****
@item %p
The percentage of the buffer text above the @strong{top} of window, or
! @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
! mode-line specification truncates this to three characters.
@item %P
The percentage of the buffer text that is above the @strong{bottom} of
--- 1550,1557 ----
@item %p
The percentage of the buffer text above the @strong{top} of window, or
! @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default mode
! line specification truncates this to three characters.
@item %P
The percentage of the buffer text that is above the @strong{bottom} of
***************
*** 1564,1592 ****
@node Properties in Mode
@subsection Properties in the Mode Line
Starting in Emacs 21, certain text properties are meaningful in the
mode line. The @code{face} property affects the appearance of text; the
@code{help-echo} property associate help strings with the text, and
@code{local-map} can make the text mouse-sensitive.
! There are three ways to specify text properties for text in the mode
line:
@enumerate
@item
! Put a string with the @code{local-map} property directly into the
! mode-line data structure.
@item
! Put a @code{local-map} property on a mode-line %-construct
! such as @samp{%12b}; then the expansion of the %-construct
! will have that same text property.
@item
! Use a list containing @code{:eval @var{form}} in the mode-line data
! structure, and make @var{form} evaluate to a string that has a
! @code{local-map} property.
@end enumerate
You use the @code{local-map} property to specify a keymap. Like any
--- 1614,1646 ----
@node Properties in Mode
@subsection Properties in the Mode Line
+ @cindex text properties in the mode line
Starting in Emacs 21, certain text properties are meaningful in the
mode line. The @code{face} property affects the appearance of text; the
@code{help-echo} property associate help strings with the text, and
@code{local-map} can make the text mouse-sensitive.
! There are four ways to specify text properties for text in the mode
line:
@enumerate
@item
! Put a string with a text property directly into the mode line data
! structure.
!
! @item
! Put a text property on a mode line %-construct such as @samp{%12b}; then
! the expansion of the %-construct will have that same text property.
@item
! Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
! give @var{elt} a text property specified by @var{props}.
@item
! Use a list containing @code{:eval @var{form}} in the mode line data
! structure, and make @var{form} evaluate to a string that has a text
! property.
@end enumerate
You use the @code{local-map} property to specify a keymap. Like any
***************
*** 2214,2220 ****
@code{font-lock-face} (@pxref{Special Properties}). This property
acts just like the explicit @code{face} property, but its activation
is toggled when the user calls @kbd{M-x font-lock-mode}. Using
! @code{font-lock-face} is especially conveninent for special modes
which construct their text programmatically, such as
@code{list-buffers} and @code{occur}.
--- 2268,2274 ----
@code{font-lock-face} (@pxref{Special Properties}). This property
acts just like the explicit @code{face} property, but its activation
is toggled when the user calls @kbd{M-x font-lock-mode}. Using
! @code{font-lock-face} is especially convenient for special modes
which construct their text programmatically, such as
@code{list-buffers} and @code{occur}.
next reply other threads:[~2003-09-25 15:45 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2003-09-25 15:45 Lute Kamstra [this message]
2003-09-27 11:42 ` Update of Mode Line Format in the Lisp Reference Manual Eli Zaretskii
2003-09-28 15:33 ` Richard Stallman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=sgdptho7typ.fsf@occarina.pna.cwi.nl \
--to=lute.kamstra@cwi.nl \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.