Go to the first, previous, next, last section, table of contents.


Emacs now supports multiple X windows via a new data type known as a frame.

A frame is a rectangle on the screen that contains one or more Emacs windows. Subdividing a frame works just like subdividing the screen in earlier versions of Emacs.

There are two kinds of frames: terminal frames and X window frames. Emacs creates one terminal frame when it starts up with no X display; it uses Termcap or Terminfo to display using characters. There is no way to create another terminal frame after startup. If Emacs has an X display, it does not make a terminal frame, and there is none.

When you are using X windows, Emacs starts out with a single X window frame. You can create any number of X window frames using make-frame.

Use the predicate framep to determine whether a given Lisp object is a frame.

The function redraw-frame redisplays the entire contents of a given frame.

Creating and Deleting Frames

Use make-frame to create a new frame. This is the only primitive for creating frames. In principle it could work under any window system which Emacs understands; the only one we support is X.

make-frame takes just one argument, which is an alist specifying frame parameters. Any parameters not mentioned in the argument alist default based on the value of default-frame-alist; parameters not specified there default from the standard X defaults file and X resources.

When you invoke Emacs, if you specify arguments for window appearance and so forth, these go into default-frame-alist and that is how they have their effect.

You can specify the parameters for the initial startup X window frame by setting initial-frame-alist in your `.emacs' file. If these parameters specify a separate minibuffer-only frame, and you have not created one, Emacs creates one for you, using the parameter values specified in minibuffer-frame-alist.

You can specify the size and position of a frame using the frame parameters left, top, height and width. You must specify either both size parameters or neither. You must specify either both position parameters or neither. The geometry parameters that you don't specify are chosen by the window manager in its usual fashion.

The function x-parse-geometry converts a standard X-style geometry string to an alist which you can use as part of the argument to make-frame.

Use the function delete-frame to eliminate a frame. Frames are like buffers where deletion is concerned; a frame actually continues to exist as a Lisp object until it is deleted and there are no references to it, but once it is deleted, it has no further effect on the screen.

The function frame-live-p returns non-nil if the argument (a frame) has not been deleted.

Finding All Frames

The function frame-list returns a list of all the frames that have not been deleted. It is analogous to buffer-list. The list that you get is newly created, so modifying the list doesn't have any effect on the internals of Emacs. The function visible-frame-list returns the list of just the frames that are visible.

next-frame lets you cycle conveniently through all the frames from an arbitrary starting point. Its first argument is a frame. Its second argument minibuf says what to do about minibuffers:

Exclude minibuffer-only frames.
a window
Consider only the frames using that particular window as their minibuffer.
anything else
Consider all frames.

Frames and Windows

All the non-minibuffer windows in a frame are arranged in a tree of subdivisions; the root of this tree is available via the function frame-root-window. Each window is part of one and only one frame; you can get the frame with window-frame.

At any time, exactly one window on any frame is selected within the frame. You can get the frame's current selected window with frame-selected-window. The significance of this designation is that selecting the frame selects for Emacs as a whole the window currently selected within that frame.

Conversely, selecting a window for Emacs with select-window also makes that window selected within its frame.

Frame Visibility

A frame may be visible, invisible, or iconified. If it is invisible, it doesn't show in the screen, not even as an icon. You can set the visibility status of a frame with make-frame-visible, make-frame-invisible, and iconify-frame. You can examine the visibility status with frame-visible-p---it returns t for a visible frame, nil for an invisible frame, and icon for an iconified frame.

Selected Frame

At any time, one frame in Emacs is the selected frame. The selected window always resides on the selected frame.

Function: selected-frame
This function returns the selected frame.

The X server normally directs keyboard input to the X window that the mouse is in. Some window managers use mouse clicks or keyboard events to shift the focus to various X windows, overriding the normal behavior of the server.

Lisp programs can switch frames "temporarily" by calling the function select-frame. This does not override the window manager; rather, it escapes from the window manager's control until that control is somehow reasserted. The function takes one argument, a frame, and selects that frame. The selection lasts until the next time the user does something to select a different frame, or until the next time this function is called.

Emacs cooperates with the X server and the window managers by arranging to select frames according to what the server and window manager ask for. It does so by generating a special kind of input event, called a focus event. The command loop handles a focus event by calling internal-select-frame.

Frame Size and Position

The new functions frame-height and frame-width return the height and width of a specified frame (or of the selected frame), measured in characters.

The new functions frame-pixel-height and frame-pixel-width return the height and width of a specified frame (or of the selected frame), measured in pixels.

The new functions frame-char-height and frame-char-width return the height and width of a character in a specified frame (or in the selected frame), measured in pixels.

set-frame-size sets the size of a frame, measured in characters; its arguments are frame, cols and rows. To set the size with values measured in pixels, you can use modify-frame-parameters.

The function set-frame-position sets the position of the top left corner of a frame. Its arguments are frame, left and top.

Frame Parameters

A frame has many parameters that affect how it displays. Use the function frame-parameters to get an alist of all the parameters of a given frame. To alter parameters, use modify-frame-parameters, which takes two arguments: the frame to modify, and an alist of parameters to change and their new values. Each element of alist has the form (parm . value), where parm is a symbol. Parameters that aren't meaningful are ignored. If you don't mention a parameter in alist, its value doesn't change.

Just what parameters a frame has depends on what display mechanism it uses. Here is a table of the parameters of an X window frame:

The name of the frame.
The screen position of the left edge.
The screen position of the top edge.
The height of the frame contents, in pixels.
The width of the frame contents, in pixels.
The number of the X window for the frame.
Whether this frame has its own minibuffer. t means yes, none means no, only means this frame is just a minibuffer, a minibuffer window (in some other frame) means the new frame uses that minibuffer.
The name of the font for the text.
The color to use for the inside of a character. Use strings to designate colors; the X server defines the meaningful color names.
The color to use for the background of text.
The color for the mouse cursor.
The color for the cursor that shows point.
The color for the border of the frame.
The way to display the cursor. There are two legitimate values: bar and box. The value bar specifies a vertical bar between characters as the cursor. The value box specifies an ordinary black box overlaying the character after point; that is the default.
Non-nil for a bitmap icon, nil for a text icon.
The width in pixels of the window border.
The distance in pixels between text and border.
Non-nil means selecting the frame raises it.
Non-nil means deselecting the frame lowers it.
Non-nil gives the frame a scroll bar for vertical scrolling.

Minibufferless Frames

Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. However, you can also create frames with no minibuffers. These frames must use the minibuffer window of some other frame.

The variable default-minibuffer-frame specifies where to find a minibuffer for frames created without minibuffers of their own. Its value should be a frame which does have a minibuffer.

You can also specify a minibuffer window explicitly when you create a frame; then default-minibuffer-frame is not used.

Go to the first, previous, next, last section, table of contents.