From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Lute Kamstra Newsgroups: gmane.emacs.devel Subject: Update of Mode Line Format in the Lisp Reference Manual. Date: Thu, 25 Sep 2003 17:45:18 +0200 Organization: CWI, Amsterdam Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1064506392 27200 80.91.224.253 (25 Sep 2003 16:13:12 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 25 Sep 2003 16:13:12 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Thu Sep 25 18:13:09 2003 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1A2Yjt-0000mK-00 for ; Thu, 25 Sep 2003 18:13:09 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1A2Yr7-0002kx-00 for ; Thu, 25 Sep 2003 18:20:37 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.22) id 1A2YeC-0003Jd-So for emacs-devel@quimby.gnus.org; Thu, 25 Sep 2003 12:07:16 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.22) id 1A2YJ4-0007Wq-Iq for emacs-devel@gnu.org; Thu, 25 Sep 2003 11:45:26 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.22) id 1A2YIz-0007Vk-Q6 for emacs-devel@gnu.org; Thu, 25 Sep 2003 11:45:23 -0400 Original-Received: from [192.16.191.8] (helo=hera.cwi.nl) by monty-python.gnu.org with esmtp (Exim 4.22) id 1A2YIy-0007VO-GH for emacs-devel@gnu.org; Thu, 25 Sep 2003 11:45:20 -0400 Original-Received: from occarina.pna.cwi.nl (occarina.pna.cwi.nl [192.16.184.200]) by hera.cwi.nl with ESMTP id h8PFjJJS002479 for ; Thu, 25 Sep 2003 17:45:19 +0200 (MEST) Original-Received: (from lute@localhost) by occarina.pna.cwi.nl (8.12.8/8.12.5) id h8PFjIXF007052; Thu, 25 Sep 2003 17:45:18 +0200 X-Authentication-Warning: occarina.pna.cwi.nl: lute set sender to Lute.Kamstra@cwi.nl using -f Original-To: emacs-devel@gnu.org User-Agent: Gnus/5.1003 (Gnus v5.10.3) Emacs/21.3.50 (gnu/linux) Original-Lines: 472 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:16632 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:16632 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}.