7.3 Window and Frame Configuration

On a non-windowing display, Ediff sets things up in one frame, splitting it between a small control window and the windows for buffers A, B, and C. The split between these windows can be horizontal or vertical, which can be changed interactively by typing | while the cursor is in the control window.

On a window display, Ediff sets up a dedicated frame for Ediff Control Panel and then it chooses windows as follows: If one of the buffers is invisible, it is displayed in the currently selected frame. If a buffer is visible, it is displayed in the frame where it is visible. If, according to the above criteria, the two buffers fall into the same frame, then so be it--the frame will be shared by the two. The same algorithm works when you type C-l (ediff-recenter), p (ediff-previous-difference), n (ediff-next-difference), etc.

The above behavior also depends on whether the current frame is splittable, dedicated, etc. Unfortunately, the margin is too small to present this remarkable algorithm.

The bottom line of all this is that you can compare buffers in one frame or in different frames. The former is done by default, while the latter can be achieved by arranging buffers A, B (and C, if applicable) to be seen in different frames. Ediff respects these arrangements, automatically adapting itself to the multi-frame mode.

Ediff uses the following variables to set up its control panel (a.k.a. control buffer, a.k.a. quick help window):

ediff-control-frame-parameters

You can change or augment this variable including the font, color, etc. The X resource name of Ediff Control Panel frames is `Ediff'. Under X-windows, you can use this name to set up preferences in your `~/.Xdefaults', `~/.xrdb', or whatever X resource file is in use. Usually this is preferable to changing ediff-control-frame-parameters directly. For instance, you can specify in `~/.Xdefaults' the color of the control frame using the resource `Ediff*background'.

In general, any X resource pertaining the control frame can be reached via the prefix Ediff*.

ediff-control-frame-position-function

The preferred way of specifying the position of the control frame is by setting the variable ediff-control-frame-position-function to an appropriate function. The default value of this variable is ediff-make-frame-position. This function places the control frame in the vicinity of the North-East corner of the frame displaying buffer A.

The following variables can be used to adjust the location produced by ediff-make-frame-position and for related customization.

ediff-narrow-control-frame-leftward-shift

Specifies the number of characters for shifting the control frame from the rightmost edge of frame A when the control frame is displayed as a small window.

ediff-wide-control-frame-rightward-shift

Specifies the rightward shift of the control frame from the left edge of frame A when the control frame shows the full menu of options.

ediff-control-frame-upward-shift

Specifies the number of pixels for the upward shift of the control frame.

ediff-prefer-iconified-control-frame

If this variable is t, the control frame becomes iconified automatically when you toggle the quick help message off. This saves valuable real estate on the screen. Toggling help back will deiconify the control frame.

To start Ediff with an iconified Control Panel, you should set this variable to t and ediff-prefer-long-help-message to nil (see section 7.2 Quick Help). This behavior is useful only if the window manager is TWM or a derivative. Also, this doesn't work under XEmacs, since this editor ignores input from icons.

To make more creative changes in the way Ediff sets up windows, you can rewrite the function ediff-setup-windows. However, we believe that detaching Ediff Control Panel from the rest and making it into a separate frame offers an important opportunity by allowing you to iconify that frame. Under Emacs, the icon will usually accept all of the Ediff commands, but will free up valuable real estate on your screen (this may depend on the window manager, though). Iconifying won't do any good under XEmacs since XEmacs icons are not sensitive to keyboard input. The saving grace is that, even if not iconified, the control frame is very small, smaller than some icons, so it does not take much space in any case.

The following variable controls how windows are set up:

ediff-window-setup-function

The multiframe setup is done by the ediff-setup-windows-multiframe function, which is the default on windowing displays. The plain setup, one where all windows are always in one frame, is done by ediff-setup-windows-plain, which is the default on a non-windowing display (or in an xterm window). In fact, under Emacs, you can switch freely between these two setups by executing the command ediff-toggle-multiframe using the Minibuffer.

If you don't like any of these setups, write your own function. See the documentation for ediff-window-setup-function for the basic guidelines. However, writing window setups is not easy, so you should first take a close look at ediff-setup-windows-plain and ediff-setup-windows-multiframe.

You can run multiple Ediff sessions at once, by invoking Ediff several times without exiting previous Ediff sessions. Different sessions may even operate on the same pair of files.

Each session has its own Ediff Control Panel and all the regarding a particular session is local to the associated control panel buffer. You can switch between sessions by suspending one session and then switching to another control panel. (Different control panel buffers are distinguished by a numerical suffix, e.g., `Ediff Control Panel<3>'.)