Buffers in a Conkeror window have both a spatial order and a historical, or last-access, order. Spatial ordering is particularly useful for visualizations of the buffer list such as tabs, but can also be useful for general organization of a session. Conkeror has a flexible system for configuring spatial order to allow for many different styles of using the browser.

1. Position

The buffer ordering system is configured by setting various position variables. A position is either a number, giving the index of insertion into a buffer-list, or it is a function that returns such an index. The position 0 is the front of a buffer-list.

When a position is given as a function, the function takes three arguments and returns an index. The arguments are:

container

the buffer_container being inserted into

buffer

the buffer being inserted

i

the index of another buffer, appropriate to the action taking place.

For example, when you follow a link in a new buffer, the argument i is the index of the buffer containing the link.

Several position functions are provided by Conkeror to cover the most common cases:

buffer_position_before

before the other buffer.

buffer_position_after

after the other buffer.

buffer_position_end

the end of the buffer list.

buffer_position_end_by_type

after the last buffer of the same type.

2. Variables

2.1. new_buffer_position

The position at which to insert a new buffer, when it has no opener, or its opener is not a buffer in the same window.

2.2. new_buffer_with_opener_position

The position at which to insert a new buffer when it has an opener buffer in the same window.

2.3. bury_buffer_position

The position that the bury-buffer command moves buffers to. The value may be null (as it is by default), in which case the buffer will not be moved. When the value of this variable is a function, the "other buffer index" is the index of the buffer that will be selected after having buried the current buffer.

2.4. $position (keyword to buffer constructor)

When the $position keyword is given to a buffer constructor, this value overrides new_buffer_position and new_buffer_with_opener_position.

2.5. buffer.default_position

The buffer property default_position also overrides new_buffer_position and new_buffer_with_opener_position, but is itself overridden by the keyword $position. This property allows you to configure position based on buffer type. For example, if you wanted all special buffers to always be inserted at the end of the list, you could do this:

special_buffer.prototype.default_position = buffer_position_end;

3. Manual Ordering

Buffer order can be manually changed with the commands buffer-move-forward and buffer-move-backward, bound respectively to M-N and M-P (note capital letters).

4. Examples

4.1. end oriented

4.1.1. default

The default ordering inserts new buffers at the end of the list, except when they have an opener in the same window. Then they are inserted to the right of their opener.

new_buffer_position = buffer_position_end;
new_buffer_with_opener_position = buffer_position_after;
bury_buffer_position = null;

4.1.2. end-oriented by-type

This variation is like the default, but buffers are grouped by type.

new_buffer_position = buffer_position_end_by_type;
new_buffer_with_opener_position = buffer_position_after;
bury_buffer_position = null;
special_buffer.prototype.default_position = buffer_position_end_by_type;

In this scenario, it is possible, but rare, that content buffers could end up in the list after special buffers. This would happen if the only buffers in a window were special buffers, and then a content buffer was opened. The user could manually move the new content buffer, or write a custom position function that took content-buffers into account.

4.1.3. left to right hierarchical

This is like the default, except that new buffers with openers appear in left to right order after their opener.

The ordering cannot be strictly maintained; the buffers might be manually moved and any of the buffers may be re-used for any purpose; a link may be followed or an unrelated URL opened. The approximation used here is to place the new buffer to the right of all other descendants of the current buffer (or immediately to the right of the current buffer if it has no other descendants); descendants are tracked by their referrer URL.

function url_ref_trim (uri) {
    try {
        uri = uri.clone().QueryInterface(Ci.nsIURL);
    } catch (e) {
        return uri.spec;
    }
    uri.ref = "";
    return uri.spec;
}

function buffer_position_after_descendants (container, b, i) {
    var refs = [url_ref_trim(container.get_buffer(i).current_uri)];
    var count = container.count;
    var p = i + 1;
    for (i++; i < count; i++) {
        b = container.get_buffer(i);
        if (b.web_navigation &&
            b.web_navigation.referringURI &&
            refs.indexOf(url_ref_trim(b.web_navigation.referringURI)) != -1)
        {
            refs.push(url_ref_trim(b.current_uri));
            p = i + 1;
        }
    }
    return p;
}

new_buffer_with_opener_position = buffer_position_after_descendants;

4.2. front oriented

4.2.1. stackish

Front-oriented configurations treat the front of the list as the "current" area. In a front-oriented configuration, when you load your session, your most recently opened buffer is in front. When a new buffer has an opener in the same window, it is opened to the right of its opener. In this way, although the overall ordering is oriented toward the front of the list, you end up with "subgroups" of related buffers in left-to-right order. In this configuration, the bury-buffer command not only affects a buffer's last-access time, but also sends it to the end of the list, out of the way.

new_buffer_position = 0;
new_buffer_with_opener_position = buffer_position_after;
bury_buffer_position = buffer_position_end;

4.2.2. stackish by-type

This is a variation on the front-oriented configuration, but buffers are grouped by type.

new_buffer_position = 0;
new_buffer_with_opener_position = buffer_position_after;
bury_buffer_position = buffer_position_end_by_type;
special_buffer.prototype.default_position = buffer_position_end_by_type;