10.5 Window Layout

No, there’s nothing here about X, so be quiet.

If gnus-use-full-window non-nil, Gnus will delete all other windows and occupy the entire Emacs screen by itself. It is t by default.

Setting this variable to nil kinda works, but there are glitches. Use at your own peril.

gnus-buffer-configuration describes how much space each Gnus buffer should be given. Here’s an excerpt of this variable:

((group (vertical 1.0 (group 1.0 point)))
 (article (vertical 1.0 (summary 0.25 point)
                        (article 1.0))))

This is an alist. The key is a symbol that names some action or other. For instance, when displaying the group buffer, the window configuration function will use group as the key. A full list of possible names is listed below.

The value (i.e., the split) says how much space each buffer should occupy. To take the article split as an example:

(article (vertical 1.0 (summary 0.25 point)
                       (article 1.0)))

This split says that the summary buffer should occupy 25% of upper half of the screen, and that it is placed over the article buffer. As you may have noticed, 100% + 25% is actually 125% (yup, I saw y’all reaching for that calculator there). However, the special number 1.0 is used to signal that this buffer should soak up all the rest of the space available after the rest of the buffers have taken whatever they need. There should be only one buffer with the 1.0 size spec per split.

Point will be put in the buffer that has the optional third element point. In a frame split, the last subsplit having a leaf split where the tag frame-focus is a member (i.e., is the third or fourth element in the list, depending on whether the point tag is present) gets focus.

Here’s a more complicated example:

(article (vertical 1.0 (group 4)
                       (summary 0.25 point)
                       (article 1.0)))

If the size spec is an integer instead of a floating point number, then that number will be used to say how many lines a buffer should occupy, not a percentage.

If the split looks like something that can be evaled (to be precise—if the car of the split is a function or a subr), this split will be evaled. If the result is non-nil, it will be used as a split.

Not complicated enough for you? Well, try this on for size:

(article (horizontal 1.0
             (vertical 0.5
                 (group 1.0))
             (vertical 1.0
                 (summary 0.25 point)
                 (article 1.0))))

Whoops. Two buffers with the mystery 100% tag. And what’s that horizontal thingie?

If the first element in one of the split is horizontal, Gnus will split the window horizontally, giving you two windows side-by-side. Inside each of these strips you may carry on all you like in the normal fashion. The number following horizontal says what percentage of the screen is to be given to this strip.

For each split, there must be one element that has the 100% tag. The splitting is never accurate, and this buffer will eat any leftover lines from the splits.

To be slightly more formal, here’s a definition of what a valid split may look like:

split      = frame | horizontal | vertical | buffer | form
frame      = "(frame " size *split ")"
horizontal = "(horizontal " size *split ")"
vertical   = "(vertical " size *split ")"
buffer     = "(" buf-name " " size *[ "point" ] *[ "frame-focus"] ")"
size       = number | frame-params
buf-name   = group | article | summary ...

The limitations are that the frame split can only appear as the top-level split. form should be an Emacs Lisp form that should return a valid split. We see that each split is fully recursive, and may contain any number of vertical and horizontal splits.

Finding the right sizes can be a bit complicated. No window may be less than gnus-window-min-height (default 1) characters high, and all windows must be at least gnus-window-min-width (default 1) characters wide. Gnus will try to enforce this before applying the splits. If you want to use the normal Emacs window width/height limit, you can just set these two variables to nil.

If you’re not familiar with Emacs terminology, horizontal and vertical splits may work the opposite way of what you’d expect. Windows inside a horizontal split are shown side-by-side, and windows within a vertical split are shown above each other.

If you want to experiment with window placement, a good tip is to call gnus-configure-frame directly with a split. This is the function that does all the real work when splitting buffers. Below is a pretty nonsensical configuration with 5 windows; two for the group buffer and three for the article buffer. (I said it was nonsensical.) If you eval the statement below, you can get an idea of how that would look straight away, without going through the normal Gnus channels. Play with it until you’re satisfied, and then use gnus-add-configuration to add your new creation to the buffer configuration list.

(gnus-configure-frame
 '(horizontal 1.0
    (vertical 10
      (group 1.0)
      (article 0.3 point))
    (vertical 1.0
      (article 1.0)
      (horizontal 4
        (group 1.0)
        (article 10)))))

You might want to have several frames as well. No prob—just use the frame split:

(gnus-configure-frame
 '(frame 1.0
         (vertical 1.0
                   (summary 0.25 point frame-focus)
                   (article 1.0))
         (vertical ((height . 5) (width . 15)
                    (user-position . t)
                    (left . -1) (top . 1))
                   (picon 1.0))))

This split will result in the familiar summary/article window configuration in the first (or “main”) frame, while a small additional frame will be created where picons will be shown. As you can see, instead of the normal 1.0 top-level spec, each additional split should have a frame parameter alist as the size spec. See Frame Parameters in The GNU Emacs Lisp Reference Manual. The list of all possible keys for gnus-buffer-configuration can be found in its default value.

Note that the message key is used for both gnus-group-mail and gnus-summary-mail-other-window. If it is desirable to distinguish between the two, something like this might be used:

(message (horizontal 1.0
                     (vertical 1.0 (message 1.0 point))
                     (vertical 0.24
                               (if (buffer-live-p gnus-summary-buffer)
                                   '(summary 0.5))
                               (group 1.0))))

One common desire for a multiple frame split is to have a separate frame for composing mail and news while leaving the original frame intact. To accomplish that, something like the following can be done:

(message
  (frame 1.0
         (if (not (buffer-live-p gnus-summary-buffer))
             (car (cdr (assoc 'group gnus-buffer-configuration)))
           (car (cdr (assoc 'summary gnus-buffer-configuration))))
         (vertical ((user-position . t) (top . 1) (left . 1)
                    (name . "Message"))
                   (message 1.0 point))))

Since the gnus-buffer-configuration variable is so long and complicated, there’s a function you can use to ease changing the config of a single setting: gnus-add-configuration. If, for instance, you want to change the article setting, you could say:

(gnus-add-configuration
 '(article (vertical 1.0
               (group 4)
               (summary .25 point)
               (article 1.0))))

You’d typically stick these gnus-add-configuration calls in your ~/.gnus.el file or in some startup hook—they should be run after Gnus has been loaded.

If all windows mentioned in the configuration are already visible, Gnus won’t change the window configuration. If you always want to force the “right” window configuration, you can set gnus-always-force-window-configuration to non-nil.

If you’re using tree displays (see Tree Display), and the tree window is displayed vertically next to another window, you may also want to fiddle with gnus-tree-minimize-window to avoid having the windows resized.

Lastly, it’s possible to make Gnus window layouts “atomic” (see Atomic Windows in The GNU Emacs Lisp Reference Manual) by setting gnus-use-atomic-windows to t. This will ensure that pop-up buffers (e.g. help or completion buffers), will appear below or to the side of the entire Gnus window layout and not, for example, squashed between the summary and article buffers.

10.5.1 Window Configuration Names

Here’s a list of most of the currently known window configurations, and when they’re used:

group

The group buffer.

summary

Entering a group and showing only the summary.

article

Selecting an article.

server

The server buffer.

browse

Browsing groups from the server buffer.

message

Composing a (new) message.

only-article

Showing only the article buffer.

edit-article

Editing an article.

edit-form

Editing group parameters and the like.

edit-score

Editing a server definition.

post

Composing a news message.

reply

Replying or following up an article without yanking the text.

forward

Forwarding a message.

reply-yank

Replying or following up an article with yanking the text.

mail-bound

Bouncing a message.

pipe

Sending an article to an external process.

bug

Sending a bug report.

score-trace

Displaying the score trace.

score-words

Displaying the score words.

split-trace

Displaying the split trace.

compose-bounce

Composing a bounce message.

mml-preview

Previewing a MIME part.

10.5.2 Example Window Configurations