7. The Mode Line

The mode line is a bar that runs across either the top or bottom of a head and is used to display information. By default the mode line displays the list of windows, similar to the output C-t w produces.

Alternatively, external panel applications such as the GNOME panel and KDE’s kicker may be used. Simply starting one of these programs is enough to set it as the mode line of the head it would like to be on (if the panel is XRandR aware) or whichever head is available. In order to avoid problems displaying menus, configure your panel application for positioning at the top or bottom of the head rather than relying on *mode-line-position*

The mode line can be turned on and off with the mode-line command or the lisp function stumpwm:toggle-mode-line. Each head has its own mode line. For example:

;; turn on/off the mode line for the current head only.
(stumpwm:toggle-mode-line (stumpwm:current-screen)
                          (stumpwm:current-head))

The mode line is updated after every StumpWM command.

To display the window list and the current date on the modeline, one might do the following:

(setf stumpwm:*screen-mode-line-format*
      (list "%w | "
            '(:eval (stumpwm:run-shell-command "date" t))))

(stumpwm:run-shell-command "date" t) runs the command date and returns its output as a string.

Command: mode-line

A command to toggle the mode line visibility.

Function: toggle-mode-line screen head &optional format

Default Values:

  format  'stumpwm:*screen-mode-line-format*

Toggle the state of the mode line for the specified screen

Variable: *screen-mode-line-format*

This variable describes what will be displayed on the modeline for each screen. Turn it on with the function TOGGLE-MODE-LINE or the mode-line command.

It is a list where each element may be a string, a symbol, or a list.

For a symbol its value is used.

For a list of the form (:eval FORM) FORM is evaluated and the result is used as a mode line element.

If it is a string the string is printed with the following formatting options:

%h

List the number of the head the mode-line belongs to

%w

List all windows in the current group windows using *window-format*

%W

List all windows on the current head of the current group using *window-format*

%g

List the groups using *group-format*

%n

The current group’s name

%u

Using *window-format*, return a 1 line list of the urgent windows, space seperated.

%v

Using *window-format*, return a 1 line list of the windows, space separated. The currently focused window is highlighted with fmt-highlight. Any non-visible windows are colored the *hidden-window-color*.

%d

Using *time-modeline-string*, print the time.

A number of modules have been written that extends the possible formatting strings. See their documentation for details.

Variable: *time-format-string-default*

The default value for ‘echo-date’, (e.g, Thu Mar 3 2005 23:05:25).

Variable: *time-modeline-string*

The default time value to pass to the modeline.

Hook: *new-mode-line-hook*

Called whenever the mode-line is created. It is called with argument, the mode-line

Variable: *screen-mode-line-formatters*

An alist containing format character format function pairs for formatting screen mode-lines. functions are passed the mode line.

Variable: *window-formatters*

an alist containing format character format function pairs for formatting window lists.

Function: bar percent width full empty

Return a progress bar string of WIDTH characters composed of characters FULL and EMPTY at PERCENT complete.

Function: bar-zone-color amount &optional med hi crit reverse

Default Values:

  med      20
  hi       50
  crit     90
  reverse  nil

Return a color command based on the magnitude of the argument. If the limits for the levels aren’t specified, they default to sensible values for a percentage. With reverse, lower numbers are more critical.

Function: add-screen-mode-line-formatter character fmt-fun

Add a format function to a format character (or overwrite an existing one).

Function: enable-mode-line screen head state &optional format

Default Values:

  format  nil

Set the state of SCREEN’s HEAD’s mode-line. If STATE is T and FORMAT is specified, then the mode-line’s format is updated.

The following variables control the color, position, and size of the mode line. See Colors for an explanation of how to set these color variables.

Variable: *mode-line-position*

Specifies where the mode line is displayed. Valid values are :top and :bottom.

Variable: *mode-line-border-width*

Specifies how thick the mode line’s border will be. Integer value.

Variable: *mode-line-highlight-template*

The string passed to FORMAT to highlight things in the mode line.

Variable: *mode-line-pad-x*

Specifies the number of padding pixels between the text and the side of the mode line. Integer value.

Variable: *mode-line-pad-y*

The number of padding pixels between the modeline text and the top/bottom of the modeline. Integer value.

Variable: *mode-line-background-color*

The mode line background color.

Variable: *mode-line-foreground-color*

The mode line foreground color.

Variable: *mode-line-border-color*

The mode line border color.

Variable: *mode-line-timeout*

The modeline updates after each command, when a new window appears or an existing one disappears, and on a timer. This variable controls how many seconds elapse between each update. If this variable is changed while the modeline is visible, you must toggle the modeline to update timer.

This document was generated on February 2, 2024 using texi2html 1.82.