diff options
Diffstat (limited to 'devdocs/elisp/mode-line-variables.html')
| -rw-r--r-- | devdocs/elisp/mode-line-variables.html | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/devdocs/elisp/mode-line-variables.html b/devdocs/elisp/mode-line-variables.html new file mode 100644 index 00000000..7ca33f58 --- /dev/null +++ b/devdocs/elisp/mode-line-variables.html @@ -0,0 +1,70 @@ + <h4 class="subsection">Variables Used in the Mode Line</h4> <p>This section describes variables incorporated by the standard value of <code>mode-line-format</code> into the text of the mode line. There is nothing inherently special about these variables; any other variables could have the same effects on the mode line if the value of <code>mode-line-format</code> is changed to use them. However, various parts of Emacs set these variables on the understanding that they will control parts of the mode line; therefore, practically speaking, it is essential for the mode line to use them. Also see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Optional-Mode-Line.html#Optional-Mode-Line">Optional Mode Line</a> in <cite>The GNU Emacs Manual</cite>. </p> <dl> <dt id="mode-line-mule-info">Variable: <strong>mode-line-mule-info</strong> +</dt> <dd><p>This variable holds the value of the mode line construct that displays information about the language environment, buffer coding system, and current input method. See <a href="non_002dascii-characters">Non-ASCII Characters</a>. </p></dd> +</dl> <dl> <dt id="mode-line-modified">Variable: <strong>mode-line-modified</strong> +</dt> <dd> +<p>This variable holds the value of the mode line construct that displays whether the current buffer is modified. Its default value displays ‘<samp>**</samp>’ if the buffer is modified, ‘<samp>--</samp>’ if the buffer is not modified, ‘<samp>%%</samp>’ if the buffer is read only, and ‘<samp>%*</samp>’ if the buffer is read only and modified. </p> <p>Changing this variable does not force an update of the mode line. </p> +</dd> +</dl> <dl> <dt id="mode-line-frame-identification">Variable: <strong>mode-line-frame-identification</strong> +</dt> <dd><p>This variable identifies the current frame. Its default value displays <code>" "</code> if you are using a window system which can show multiple frames, or <code>"-%F "</code> on an ordinary terminal which shows only one frame at a time. </p></dd> +</dl> <dl> <dt id="mode-line-buffer-identification">Variable: <strong>mode-line-buffer-identification</strong> +</dt> <dd><p>This variable identifies the buffer being displayed in the window. Its default value displays the buffer name, padded with spaces to at least 12 columns. </p></dd> +</dl> <dl> <dt id="mode-line-position">Variable: <strong>mode-line-position</strong> +</dt> <dd><p>This variable indicates the position in the buffer. Its default value displays the buffer percentage and, optionally, the buffer size, the line number and the column number. </p></dd> +</dl> <dl> <dt id="mode-line-percent-position">User Option: <strong>mode-line-percent-position</strong> +</dt> <dd><p>This option is used in <code>mode-line-position</code>. Its value specifies both the buffer percentage to display (one of <code>nil</code>, <code>"%o"</code>, <code>"%p"</code>, <code>"%P"</code> or <code>"%q"</code>, see <a href="_0025_002dconstructs">%-Constructs</a>) and a width to space-fill or truncate to. You are recommended to set this option with the <code>customize-variable</code> facility. </p></dd> +</dl> <dl> <dt id="vc-mode">Variable: <strong>vc-mode</strong> +</dt> <dd><p>The variable <code>vc-mode</code>, 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</code> for no version control. </p></dd> +</dl> <dl> <dt id="mode-line-modes">Variable: <strong>mode-line-modes</strong> +</dt> <dd><p>This variable displays the buffer’s major and minor modes. Its default value also displays the recursive editing level, information on the process status, and whether narrowing is in effect. </p></dd> +</dl> <dl> <dt id="mode-line-remote">Variable: <strong>mode-line-remote</strong> +</dt> <dd><p>This variable is used to show whether <code>default-directory</code> for the current buffer is remote. </p></dd> +</dl> <dl> <dt id="mode-line-client">Variable: <strong>mode-line-client</strong> +</dt> <dd><p>This variable is used to identify <code>emacsclient</code> frames. </p></dd> +</dl> <p>The following three variables are used in <code>mode-line-modes</code>: </p> <dl> <dt id="mode-name">Variable: <strong>mode-name</strong> +</dt> <dd><p>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. The value does not have to be a string, but can use any of the data types valid in a mode-line construct (see <a href="mode-line-data">Mode Line Data</a>). To compute the string that will identify the mode name in the mode line, use <code>format-mode-line</code> (see <a href="emulating-mode-line">Emulating Mode Line</a>). </p></dd> +</dl> <dl> <dt id="mode-line-process">Variable: <strong>mode-line-process</strong> +</dt> <dd><p>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*</samp> buffer is <code>(":%s")</code>, which allows the shell to display its status along with the major mode as: ‘<samp>(Shell:run)</samp>’. Normally this variable is <code>nil</code>. </p></dd> +</dl> <dl> <dt id="mode-line-front-space">Variable: <strong>mode-line-front-space</strong> +</dt> <dd><p>This variable is displayed at the front of the mode line. By default, this construct is displayed right at the beginning of the mode line, except that if there is a memory-full message, it is displayed first. </p></dd> +</dl> <dl> <dt id="mode-line-end-spaces">Variable: <strong>mode-line-end-spaces</strong> +</dt> <dd><p>This variable is displayed at the end of the mode line. </p></dd> +</dl> <dl> <dt id="mode-line-misc-info">Variable: <strong>mode-line-misc-info</strong> +</dt> <dd><p>Mode line construct for miscellaneous information. By default, this shows the information specified by <code>global-mode-string</code>. </p></dd> +</dl> <dl> <dt id="mode-line-position-line-format">Variable: <strong>mode-line-position-line-format</strong> +</dt> <dd><p>The format used to display line numbers when <code>line-number-mode</code> (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Optional-Mode-Line.html#Optional-Mode-Line">Optional Mode Line</a> in <cite>The GNU Emacs Manual</cite>) is switched on. ‘<samp>%l</samp>’ in the format will be replaced with the line number. </p></dd> +</dl> <dl> <dt id="mode-line-position-column-format">Variable: <strong>mode-line-position-column-format</strong> +</dt> <dd><p>The format used to display column numbers when <code>column-number-mode</code> (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Optional-Mode-Line.html#Optional-Mode-Line">Optional Mode Line</a> in <cite>The GNU Emacs Manual</cite>) is switched on. ‘<samp>%c</samp>’ in the format will be replaced with a zero-based column number, and ‘<samp>%C</samp>’ will be replaced with a one-based column number. </p></dd> +</dl> <dl> <dt id="mode-line-position-column-line-format">Variable: <strong>mode-line-position-column-line-format</strong> +</dt> <dd><p>The format used to display column numbers when both <code>line-number-mode</code> and <code>column-number-mode</code> are switched on. See the previous two variables for the meaning of the ‘<samp>%l</samp>’, ‘<samp>%c</samp>’ and ‘<samp>%C</samp>’ format specs. </p></dd> +</dl> <dl> <dt id="minor-mode-alist">Variable: <strong>minor-mode-alist</strong> +</dt> <dd> +<p>This variable holds an association list whose elements specify how the mode line should indicate that a minor mode is active. Each element of the <code>minor-mode-alist</code> should be a two-element list: </p> <div class="example"> <pre class="example">(<var>minor-mode-variable</var> <var>mode-line-string</var>) +</pre> +</div> <p>More generally, <var>mode-line-string</var> can be any mode line construct. It appears in the mode line when the value of <var>minor-mode-variable</var> is non-<code>nil</code>, and not otherwise. These strings should begin with spaces so that they don’t run together. Conventionally, the <var>minor-mode-variable</var> for a specific mode is set to a non-<code>nil</code> value when that minor mode is activated. </p> <p><code>minor-mode-alist</code> itself is not buffer-local. Each variable mentioned in the alist should be buffer-local if its minor mode can be enabled separately in each buffer. </p> +</dd> +</dl> <dl> <dt id="global-mode-string">Variable: <strong>global-mode-string</strong> +</dt> <dd> +<p>This variable holds a mode line construct that, by default, appears in the mode line just after the <code>which-function-mode</code> minor mode if set, else after <code>mode-line-modes</code>. Elements that are added to this construct should normally end in a space (to ensure that consecutive <code>global-mode-string</code> elements display properly). For instance, the command <code>display-time</code> sets <code>global-mode-string</code> to refer to the variable <code>display-time-string</code>, which holds a string containing the time and load information. </p> <p>The ‘<samp>%M</samp>’ construct substitutes the value of <code>global-mode-string</code>, but that is obsolete, since the variable is included in the mode line from <code>mode-line-format</code>. </p> +</dd> +</dl> <p>Here is a simplified version of the default value of <code>mode-line-format</code>. The real default value also specifies addition of text properties. </p> <div class="example"> <pre class="example">("-" + mode-line-mule-info + mode-line-modified + mode-line-frame-identification + mode-line-buffer-identification +</pre> +<pre class="example"> " " + mode-line-position + (vc-mode vc-mode) + " " +</pre> +<pre class="example"> mode-line-modes + (which-function-mode ("" which-func-format "--")) + (global-mode-string ("--" global-mode-string)) + "-%-") +</pre> +</div><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Variables.html</a> + </p> +</div> |