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' (Note:%-Constructs). This is normally the case when Emacs is not
using a window system, and can only display one frame at a time.
Note: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
(Note: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 Note:Size and
Position.)
`width'
The width of the frame contents, in characters. (To get the
height in pixels, call `frame-pixel-width'; see Note:Size and
Position.)
`window-id'
The number of the window-system window used by the frame to
contain the actual Emacs windows.
`outer-window-id'
The number of the outermost window-system window used for the
whole 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 (Note:Fontsets). Changing this frame parameter
on a frame also changes the font-related attributes of the default
face on that frame.
`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. Changing
this parameter is equivalent to changing the foreground color of
the face `default' on the frame in question.
`background-color'
The color to use for the background of characters. Changing this
parameter is equivalent to changing the foreground color of the
face `default' on the frame in question.
`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. Changing this parameter is
equivalent to changing the background color of face `mouse'.
`cursor-color'
The color for the cursor that shows point. Changing this parameter
is equivalent to changing the background color of face `cursor'.
`border-color'
The color for the border of the frame. Changing this parameter is
equivalent to changing the background color of face `border'.
`scroll-bar-foreground'
If non-`nil', the color for the foreground of scroll bars.
Changing this parameter is equivalent to setting the foreground
color of face `scroll-bar'.
`scroll-bar-background'
If non-`nil', the color for the background of scroll bars.
Changing this parameter is equivalent to setting the foreground
color of face `scroll-bar'.
`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.
The buffer-local variable `cursor-type' overrides the value of the
`cursor-type' frame parameter, and can in addition have values `t'
(use the cursor specified for the frame) and `nil' (don't display
a cursor).
`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. Note: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. Note: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.)
`screen-gamma'
If this is a number, Emacs performs "gamma correction" on colors.
The value should be the screen gamma of your display, a floating
point number. Usual PC monitors have a screen gamma of 2.2, so
the default is to display for that gamma value. Specifying a
smaller value results in darker colors, which is desirable for a
monitor that tends to display colors too light. A screen gamma
value of 1.5 may give good results for LCD color displays.
`tool-bar-lines'
The number of lines to use for the toolbar. A value of `nil' means
don't display a tool bar.
`line-spacing'
Additional space put below text lines in pixels (a positive
integer).