#pragma section-numbers on
<<TableOfContents(3)>>

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.

= Enabling and Disabling the Mode Line =
== Interactively ==

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

{{{
M-x mode-line-mode
}}}


== 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 [[ConkerorRC|rc]].

{{{
mode_line_mode(false);
}}}


= 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);
}}}


== Widgets ==
=== 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);
}}}


=== 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));
}}}


=== 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);
}}}


=== 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]].


=== 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.

{{attachment:conkeror-buttons.png}}

To enable it:

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


=== 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));
}}}


=== 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));
}}}