• Appearance

1. Styling Chrome

A window in Conkeror is a XUL document, commonly referred to as "chrome". Chrome includes such visual elements as the mode-line, the minibuffer, and the tab-bar. These elements can be styled with CSS. This page describes the primitive functions that can be used to apply stylesheets to Conkeror's chrome. Conkeror has a higher level system for creating entire themes which is discussed in the following section.

1.1. Registering and Unregistering Sylesheets

Conkeror provides four utility functions for managing stylesheets:

• register_agent_stylesheet

  • This is the correct function for Conkeror modules to register their stylesheets at runtime. Agent sheets can be overridden by User sheets.

• unregister_agent_stylesheet

  • This utility unregisters an agent sheet. A person could use this in their rc in order to unload one of the default stylesheets.

• register_user_stylesheet

  • Use this function to load your stylesheets from your rc.

• unregister_user_stylesheet

  • Use this function to unload stylesheets loaded by register_user_stylesheet.

1.2. Namespaces

Stylesheets loaded by the utility functions described above get applied both to the Conkeror gui chrome, and to content within the browser (web pages). But if you put a namespace declaration in your stylesheet, it will only apply to elements of that namespace.

To make a stylesheet which only affects Conkeror's gui, put the following line before the css rules in your stylesheet. (If the stylesheet contains any @import directives, @namespace must come after all @imports, and before any css rules.)

@namespace url("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");

1.3. Examples

You can use register_user_stylesheet in your rc script to add styles to the chrome:

register_user_stylesheet('file:///path/to/css/file');

You can also include CSS directly in the Javascript file:

register_user_stylesheet(
    "data:text/css,"+
        escape("@namespace url(\"http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul\");\n"+
               "#minibuffer, .mode-line {"+
               " font-size: 16px;"+
               "}\n"+
               "#minibuffer-prompt { color: red; }"));

The above code sets the font-size of the minibuffer and the mode-line to 16px, and sets the font colour of the prompt to red.

1.4. new-tabs

If you use the new-tabs module (require('new-tabs.js');) you may want to style your tab bar. If you want to write a style for new-tabs from scratch, you will want to unregister the default stylesheet:

unregister_agent_stylesheet('chrome://conkeror-gui/skin/tab2-bar.css');

Then use register_user_stylesheet with your css.

2. Theming

In physical terms, a theme is a directory containing a group of .css files, and an index file called theme.json.

theme_load_paths is a variable like load_paths, but it gives chrome directories and file directories that contain themes. Example:

theme_load_paths.unshift("/path/to/my-themes-root/");

Themes require the theme.json index file because it is both simpler implementationally, and faster to load a theme, if Conkeror does not have to search for all of the .css files itself. (Themes can be stored in chrome:// urls, and it is non-trivial to get a list of files in a "chrome directory".)

Example theme.json file:

{ "sheets": [
      "tab-bar.css",
      "new-tabs.css"
  ]
}

The .css files themselves are specially named. The part of the basename before an optional double-hyphen separator is the name of the module that this stylesheet is for. Following the optional double-hyphen is a name for this specific stylesheet.

Multiple themes may be loaded in what we call a "theme stack". Stylesheets from themes higher in the stack override stylesheets of the same name lower in the stack.

To load a theme:

theme_load("my-theme");

To unload a theme:

theme_unload("my-theme");

Conkeror's default theme is called "default".

2.1. How to restore the "blackened" theme

Conkeror included a theme with black colors but it was removed in favor of native theming. You can still extract it from an old version and store it somewhere else as if it were a custom theme written which you can further extend. Instructions:

1. Check out: git clone git://repo.or.cz/conkeror.git

2. Go back in time: cd conkeror && git checkout a38b3a3630ebf85a403207b37220cee9790d3a82

3. Copy styles/blackened somewhere: cp -r styles/blackened /path/to/somewhere
4. Return to the present: git checkout master
5. Add the following to ~/.conkerorrc:
   • theme_load_paths.push("/path/to/somewhere"); theme_load("blackened");

After restarting, conkeror should be blackened.

15th April 2009.

3. Resources

When using CSS to modify chrome or webpage appearance, the obscur rules for precedence in CSS selectors confound even the wise at times. We list particularly good articles on this subject here, which will hopefully help Conkeror hackers have more success in their themes and schemes.

http://www.csarven.ca/css-specificity-and-selectors