The mode-line is the bar in Conkeror's gui between the browser and the minibuffer. With a default configuration, it tells the buffer's current url, the scroll position, and the current time. All of this can be customized. You can even disable the mode-line completely.

1. Enabling and Disabling the Mode Line

1.1. Interactively

The mode-line can be toggled on and off with the palindromic interactive command, mode-line-mode.

M-x mode-line-mode

1.2. With JavaScript

You can turn the mode-line on and off in your rc, too. Simply call the function mode_line_mode. If you pass no argument, it toggles the mode-line, as with the interactive command described earlier. If you pass true, it turns the mode line on, and if you pass false, it turns the mode line off. Since the mode-line is on by default, and most people who will come looking here will do so because they want to turn it off, here is the full code to turn off the mode-line in your rc.

mode_line_mode(false);

2. Configuring the Mode Line

The contents of a mode-line are called mode-line widgets. Certain widgets are there by default. Other widgets are available, but not enabled by default. You can even write your own widgets. Widgets can be added and removed from the mode-line by configuring mode_line_hook. Changes to this hook will not affect mode-lines that already exist, only future ones. So if you are configuring the mode-line interactive, you can make your changes take effect by calling:

M-x mode-line-mode
M-x mode-line-mode

or in javascript:

mode_line_mode(false);
mode_line_mode(true);

2.1. Widgets

2.1.1. Buffer Count

This widget shows how many buffers are in the current window, and which one is currently selected. To enable it:

add_hook("mode_line_hook", mode_line_adder(buffer_count_widget), true);

2.1.2. Buffer Name

This is the widget that displays the current url, or for special buffers, their name. To remove it:

remove_hook("mode_line_hook", mode_line_adder(current_buffer_name_widget));

2.1.3. Buffers Loading

This widget shows how many buffers are currently loading. To enable it:

add_hook("mode_line_hook", mode_line_adder(loading_count_widget), true);

2.1.4. Clock

The clock widget is enabled by default. People commonly want to disable it. Here is how:

remove_hook("mode_line_hook", mode_line_adder(clock_widget));

The format of the clock can be configured by setting the variable clock_time_format. The default value is "%R". A reference on the formatting codes can be found at http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html.

2.1.5. Navigation Buttons

This is a row of buttons that call basic navigation commands for the current buffer. Hovering over them tells you the command and the corresponding keystroke. This widget is provided in a module in Conkeror's contrib directory.

To enable it:

load_paths.unshift("chrome://conkeror-contrib/content/");
require("mode-line-buttons.js");
mode_line_add_buttons(standard_mode_line_buttons, true);

2.1.6. Scroll Position

This widget shows the scroll position in parentheses. To remove it:

remove_hook("mode_line_hook", mode_line_adder(current_buffer_scroll_position_widget));

2.1.7. Downloads Status

The downloads-status widget shows the active download count. It may be expanded in the future to do more.

add_hook("mode_line_hook", mode_line_adder(downloads_status_widget));