Window Frame Parameters

Just what parameters a frame has depends on what display mechanism it uses. Here is a table of the parameters that have special meanings in a window frame; of these, name, title, height, width, buffer-list and buffer-predicate provide meaningful information in terminal frames.

display

The display on which to open this frame. It should be a string of the form "host:dpy.screen", just like the DISPLAY environment variable.

title

If a frame has a non-nil title, it appears in the window system's border for the frame, and also in the mode line of windows in that frame if mode-line-frame-identification uses `%F' (see section %-Constructs in the Mode Line). This is normally the case when Emacs is not using a window system, and can only display one frame at a time. See section Frame Titles.

name

The name of the frame. The frame name serves as a default for the frame title, if the title parameter is unspecified or nil. If you don't specify a name, Emacs sets the frame name automatically (see section Frame Titles). If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame.

left

The screen position of the left edge, in pixels, with respect to the left edge of the screen. The value may be a positive number pos, or a list of the form (+ pos) which permits specifying a negative pos value. A negative number -pos, or a list of the form (- pos), actually specifies the position of the right edge of the window with respect to the right edge of the screen. A positive value of pos counts toward the left. Reminder: if the parameter is a negative integer -pos, then pos is positive. Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as well.

top

The screen position of the top edge, in pixels, with respect to the top edge of the screen. The value may be a positive number pos, or a list of the form (+ pos) which permits specifying a negative pos value. A negative number -pos, or a list of the form (- pos), actually specifies the position of the bottom edge of the window with respect to the bottom edge of the screen. A positive value of pos counts toward the top. Reminder: if the parameter is a negative integer -pos, then pos is positive. Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as well.

icon-left

The screen position of the left edge of the frame's icon, in pixels, counting from the left edge of the screen. This takes effect if and when the frame is iconified.

icon-top

The screen position of the top edge of the frame's icon, in pixels, counting from the top edge of the screen. This takes effect if and when the frame is iconified.

user-position

When you create a frame and specify its screen position with the left and top parameters, use this parameter to say whether the specified position was user-specified (explicitly requested in some way by a human user) or merely program-specified (chosen by a program). A non-nil value says the position was user-specified. Window managers generally heed user-specified positions, and some heed program-specified positions too. But many ignore program-specified positions, placing the window in a default fashion or letting the user place it with the mouse. Some window managers, including twm, let the user specify whether to obey program-specified positions or ignore them. When you call make-frame, you should specify a non-nil value for this parameter if the values of the left and top parameters represent the user's stated preference; otherwise, use nil.

height

The height of the frame contents, in characters. (To get the height in pixels, call frame-pixel-height; see section Frame Size And Position.)

width

The width of the frame contents, in characters. (To get the height in pixels, call frame-pixel-width; see section Frame Size And Position.)

window-id

The number of the window-system window used by the frame.

minibuffer

Whether this frame has its own minibuffer. The value t means yes, nil means no, only means this frame is just a minibuffer. If the value is a minibuffer window (in some other frame), the new frame uses that minibuffer.

buffer-predicate

The buffer-predicate function for this frame. The function other-buffer uses this predicate (from the selected frame) to decide which buffers it should consider, if the predicate is not nil. It calls the predicate with one argument, a buffer, once for each buffer; if the predicate returns a non-nil value, it considers that buffer.

buffer-list

A list of buffers that have been selected in this frame, ordered most-recently-selected first.

font

The name of the font for displaying text in the frame. This is a string, either a valid font name for your system or the name of an Emacs fontset (see section Fontsets).

auto-raise

Whether selecting the frame raises it (non-nil means yes).

auto-lower

Whether deselecting the frame lowers it (non-nil means yes).

vertical-scroll-bars

Whether the frame has scroll bars for vertical scrolling, and which side of the frame they should be on. The possible values are left, right, and nil for no scroll bars.

horizontal-scroll-bars

Whether the frame has scroll bars for horizontal scrolling (non-nil means yes). (Horizontal scroll bars are not currently implemented.)

scroll-bar-width

The width of the vertical scroll bar, in pixels.

icon-type

The type of icon to use for this frame when it is iconified. If the value is a string, that specifies a file containing a bitmap to use. Any other non-nil value specifies the default bitmap icon (a picture of a gnu); nil specifies a text icon.

icon-name

The name to use in the icon for this frame, when and if the icon appears. If this is nil, the frame's title is used.

foreground-color

The color to use for the image of a character. This is a string; the window system defines the meaningful color names. If you set the foreground-color frame parameter, you should call frame-update-face-colors to update faces accordingly.

background-color

The color to use for the background of characters. If you set the background-color frame parameter, you should call frame-update-face-colors to update faces accordingly. See section Functions for Working with Faces.

background-mode

This parameter is either dark or light, according to whether the background color is a light one or a dark one.

mouse-color

The color for the mouse pointer.

cursor-color

The color for the cursor that shows point.

border-color

The color for the border of the frame.

display-type

This parameter describes the range of possible colors that can be used in this frame. Its value is color, grayscale or mono.

cursor-type

The way to display the cursor. The legitimate values are bar, box, and (bar . width). The symbol box specifies an ordinary black box overlaying the character after point; that is the default. The symbol bar specifies a vertical bar between characters as the cursor. (bar . width) specifies a bar width pixels wide.

border-width

The width in pixels of the window border.

internal-border-width

The distance in pixels between text and border.

unsplittable

If non-nil, this frame's window is never split automatically.

visibility

The state of visibility of the frame. There are three possibilities: nil for invisible, t for visible, and icon for iconified. See section Visibility of Frames.

menu-bar-lines

The number of lines to allocate at the top of the frame for a menu bar. The default is 1. See section The Menu Bar. (In Emacs versions that use the X toolkit, there is only one menu bar line; all that matters about the number you specify is whether it is greater than zero.)

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