A frame is a rectangle on the screen that contains one or more Emacs windows. A frame initially contains a single main window (plus perhaps a minibuffer window) which you can subdivide vertically or horizontally into smaller windows.
When Emacs runs on a text-only terminal, it has just one frame, a terminal frame. There is no way to create another terminal frame after startup. If Emacs has an X display, it does not have a terminal frame; instead, it starts with a single X window frame. You can create more; see section Creating Frames.
t if object is a frame, and
nil otherwise.
See section Emacs Display, for related information.
To create a new frame, call the function make-frame.
The argument is an alist specifying frame parameters. Any parameters
not mentioned in alist default according to the value of the
variable default-frame-alist; parameters not specified there
either default from the standard X defaults file and X resources.
The set of possible parameters depends in principle on what kind of window system Emacs uses to display its the frames. See section X Window Frame Parameters, for documentation of individual parameters you can specify when creating an X window frame.
(parameter . value)
Emacs creates the initial X frame before it reads the user's init file, which is the first occasion that the user has to set this variable. So after reading the init file, Emacs modifies the parameters according to the value of this variable. In most cases, that is good enough. However, for window position parameters, it may be inconvenient that the window initially appears in the wrong place or the wrong size. The way to overcome this annoyance is to specify the initial frame's geometry with an X resource.
If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to default-frame-alist. One
exception is `-geometry', which adds to initial-frame-alist
instead. See section `Command Arguments' in The GNU Emacs Manual.
make-frame before it actually creates the
frame.
make-frame after it creates the frame.
A frame has many parameters that control its appearance and behavior. Just what parameters a frame has depends on what display mechanism it uses.
Frame parameters exist for the sake of window systems. A terminal frame has a few parameters, for compatibility's sake only. You can't change these parameters directly; the only ones that ever change are the height and width.
These functions let you read and change the parameter values of a frame.
frame-parameters returns an alist listing all the
parameters of frame and their values.
(parm . value), where parm is a symbol naming a
parameter. If you don't mention a parameter in alist, its value
doesn't change.
You can specify the parameters for the initial startup 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.
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:
name
left
- instead of a number; that represents `-0' in a geometry
specification.
top
- instead of a number; that represents `-0' in a geometry
specification.
user-position
nil if the screen position of the frame was explicitly
requested by the user (for example, with the `-geometry' option).
Nothing automatically makes this parameter non-nil; it is up to
Lisp programs that call make-frame to specify this parameter as
well as specifying the left and top parameters.
height
frame-pixel-height; see section Frame Size And Position.)
width
frame-pixel-width; see section Frame Size And Position.)
window-id
minibuffer
t means
yes, nil means no, only means this frame is just a
minibuffer, a minibuffer window (in some other frame) means the new
frame uses that minibuffer.
font
auto-raise
nil means yes).
auto-lower
nil means yes).
vertical-scroll-bars
nil means yes).
horizontal-scroll-bars
nil means yes). (Horizontal scroll bars are not currently
implemented.)
icon-type
nil specifies a bitmap icon, nil a text icon.
foreground-color
background-color
mouse-color
cursor-color
border-color
cursor-type
bar and box. The symbol bar specifies a vertical
bar between characters as the cursor. The symbol box specifies
an ordinary black box overlaying the character after point; that is the
default.
border-width
internal-border-width
unsplittable
nil, this frame's window is never split automatically.
visibility
nil for invisible, t for visible, and icon for
iconified. See section Visibility of Frames.
menu-bar-lines
parent-id
You can read or change the size and position of a frame using the
frame parameters left, top, height and
width. Whatever geometry parameters you don't specify are chosen
by the window manager in its usual fashion.
Here are some special features for working with sizes and positions:
To set the size based on values measured in pixels, use
frame-char-height and frame-char-width to convert
them to units of characters.
The old-fashioned functions set-screen-height and
set-screen-width, which were used to specify the height and width
of the screen in Emacs versions that did not support multiple frames,
are still usable. They apply to the selected frame. See section Screen Size.
x-parse-geometry converts a standard X windows
geometry string to an alist which you can use as part of the argument to
make-frame.
The alist describes which parameters were specified in geom, and
gives the values specified for them. Each element looks like
(parameter . value). The possible parameter
values are left, top, width, and height.
(x-parse-geometry "35x70+0-0")
=> ((width . 35) (height . 70) (left . 0) (top . -1))
Frames remain potentially visible until you explicitly delete them. A deleted frame cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a frame aside from restoring a saved frame configuration (see section Frame Configurations); this is similar to the way windows behave.
frame-live-p returns non-nil if the frame
frame has not been deleted.
frame-list returns a list of all the frames that
have not been deleted. It is analogous to buffer-list for
buffers. The list that you get is newly created, so modifying the list
doesn't have any effect on the internals of Emacs.
next-frame lets you cycle conveniently through all
the frames from an arbitrary starting point. It returns the "next"
frame after frame in the cycle. If frame is omitted or
nil, it defaults to the selected frame.
The second argument, minibuf, says which frames to consider:
nil
visible
next-frame, but cycles through all frames in the opposite
direction.
Each window is part of one and only one frame; you can get the frame
with window-frame.
All the non-minibuffer windows in a frame are arranged in a cyclic order. The order runs from the frame's top window, which is at the upper left corner, down and to the right, until it reaches the window at the lower right corner (always the minibuffer window, if the frame has one), and then it moves back to the top.
At any time, exactly one window on any frame is selected within the
frame. The significance of this designation is that selecting the
frame also selects this window. You can get the frame's current
selected window with frame-selected-window.
Conversely, selecting a window for Emacs with select-window also
makes that window selected within its frame. See section Selecting Windows.
Normally, each frame has its own minibuffer window at the bottom, which
is used whenever that frame is selected. If the frame has a minibuffer,
you can get it with minibuffer-window (see section Minibuffer Miscellany).
However, you can also create a frame with no minibuffer. Such a frame
must use the minibuffer window of some other frame. When you create the
frame, you can specify explicitly the frame on which to find the
minibuffer to use. If you don't, then the minibuffer is found in the
frame which is the value of the variable
default-minibuffer-frame. Its value should be a frame which does
have a minibuffer.
If you use a minibuffer-only frame, you might want that frame to raise
when you enter the minibuffer. If so, set the variable
minibuffer-auto-raise to t. See section Raising and Lowering Frames.
At any time, one frame in Emacs is the selected frame. The selected window always resides on 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.
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
handle-select-frame. See section Focus Events.
Focus events normally do their job by invoking this command. Don't call it for any other reason.
last-event-frame will be focus-frame. Also, switch-frame
events specifying frame will instead select focus-frame.
If focus-frame is nil, that cancels any existing
redirection for frame, which therefore once again receives its own
events.
One use of focus redirection is for frames that don't have minibuffers. These frames use minibuffers on other frames. Activating a minibuffer on another frame redirects focus to that frame. This puts the focus on the minibuffer's frame, where it belongs, even though the mouse remains in the frame which activated the minibuffer.
Selecting a frame can also change focus redirections. Selecting frame
bar, when foo had been selected, changes any redirections
pointing to foo so that they point to bar instead. This
allows focus redirection to work properly when the user switches from
one frame to another using select-window.
This means that a frame whose focus is redirected to itself is treated
differently from a frame whose focus is not redirected.
select-frame affects the former but not the latter.
The redirection lasts until redirect-frame-focus is called to
change it.
A frame may be visible, invisible, or iconified. If it is visible, you can see its contents. If it is iconified, the frame's contents do not appear on the screen, but an icon does. If the frame is invisible, it doesn't show in the screen, not even as an icon.
t if frame is visible, nil if it is invisible, and
icon if it is iconified.
The visibility status of a frame is also available as a frame parameter. You can read or change it as such. See section X Window Frame Parameters.
The X Window System uses a desktop metaphor. Part of this metaphor is the idea that windows are stacked in a notional third dimension perpendicular to the screen surface, and thus ordered from "highest" to "lowest". Where two windows overlap, the one higher up covers the one underneath. Even a window at the bottom of the stack can be seen if no other window overlaps it.
A window's place in this ordering is not fixed; in fact, users tend to change the order frequently. Raising a window means moving it "up", to the top of the stack. Lowering a window means moving it to the bottom of the stack. This motion is in the notional third dimension only, and does not change the position of the window on the screen.
You can raise and lower Emacs's X windows with these functions:
nil, activation of the minibuffer raises the frame
that the minibuffer window is in.
You can also enable auto-raise (raising automatically when a frame is selected) or auto-lower (lowering automatically when it is deselected) for any frame using frame parameters. See section X Window Frame Parameters.
A frame configuration records the current arrangement of frames, all their properties, and the window configuration of each one.
Sometimes it is useful to track the mouse, which means, to display something to indicate where the mouse is and move the indicator as the mouse moves. For efficient mouse tracking, you need a way to wait until the mouse actually moves.
The convenient way to track the mouse is to ask for events to represent mouse motion. Then you can wait for motion by waiting for an event. In addition, you can easily handle any other sorts of events that may occur. That is useful, because normally you don't want to track the mouse forever--only until some other event, such as the release of a button.
read-event or
read-key-sequence. See section Motion Events, for the format of mouse
motion events.
The value of track-mouse is that of the last form in body.
The usual purpose of tracking mouse motion is to indicate on the screen the consequences of pushing or releasing a button at the current position.
The functions mouse-position and set-mouse-position
give access to the current position of the mouse.
(frame x . y), where x
and y are integers giving the position in characters relative to
the top left corner of the inside of frame.
mouse-position except that it returns
coordinates in units of pixels rather than units of characters.
set-mouse-position except that
x and y are in units of pixels rather than units of
characters. These coordinates are not required to be within the frame.
The argument position specifies where on the screen to put the menu. It can be either a mouse button event (which says to put the menu where the user actuated the button) or a list of this form:
((xoffset yoffset) window)
where xoffset and yoffset are coordinates, measured in pixels, counting from the top left corner of window's frame.
If position is t, it means to use the current mouse
position. If position is nil, it means to precompute the
key binding equivalents for the keymaps specified in menu,
without actually displaying or popping up the menu.
The argument menu says what to display in the menu. It can be a keymap or a list of keymaps (see section Menu Keymaps). Alternatively, it can have the following form:
(title pane1 pane2...)
where each pane is a list of form
(title (line item)...)
Each line should be a string, and each item should be the value to return if that line is chosen.
Usage note: Don't use x-popup-menu to display a menu if
a prefix key with a menu keymap would do the job. If you use a menu
keymap to implement a menu, C-h c and C-h a can see the
individual items in that menu and provide help for them. If instead you
implement the menu by defining a command that calls x-popup-menu,
the help facilities cannot know what happens inside that command, so
they cannot give any help for the menu's items. This is the reason why
all the menu bar items except `Buffers' are implemented with menu
keymaps (see section Menu Keymaps).
A dialog box is a variant of a pop-up menu. It looks a little
different (if Emacs uses an X toolkit), it always appears in the center
of a frame, and it has just one level and one pane. The main use of
dialog boxes is for asking questions that the user can answer with
"yes", "no", and a few other alternatives. The functions
y-or-n-p and yes-or-no-p use dialog boxes instead of the
keyboard, when called from commands invoked by mouse clicks.
(title (string . value)...)
which looks like the list that specifies a single pane for
x-popup-menu.
The return value is value from the chosen alternative.
An element of the list may be just a string instead of a cons cell
(string . value). That makes a box that cannot
be selected.
If nil appears in the list, it separates the left-hand items from
the right-hand items; items that precede the nil appear on the
left, and items that follow the nil appear on the right. If you
don't include a nil in the list, then approximately half the
items appear on each side.
Dialog boxes always appear in the center of a frame; the argument
position specifies which frame. The possible values are as in
x-popup-menu, but the precise coordinates don't matter; only the
frame matters.
If your Emacs executable does not use an X toolkit, then it cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the frame.
The X server records a set of selections which permit transfer of data between application programs. The various selections are distinguished by selection types, represented in Emacs by symbols. X clients including Emacs can read or set the selection for any given type.
nil, it means to clear out the
selection. Otherwise, data may be a string, a symbol, an integer
(or a cons of two integers or list of two integers), an overlay, or a
cons of two markers pointing to the same buffer. An overlay or a pair
of markers stands for text in the overlay or between the markers.
The data may also be a vector of valid non-vector selection values.
Each possible type has its own selection value, which changes
independently. The usual values of type are PRIMARY and
SECONDARY; these are symbols with upper-case names, in accord
with X Window System conventions. The default is PRIMARY.
PRIMARY.
The data-type argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into Lisp
data. Meaningful values include TEXT, STRING,
TARGETS, LENGTH, DELETE, FILE_NAME,
CHARACTER_POSITION, LINE_NUMBER, COLUMN_NUMBER,
OWNER_OS, HOST_NAME, USER, CLASS,
NAME, ATOM, and INTEGER. (These are symbols with
upper-case names in accord with X conventions.) The default for
data-type is STRING.
The X server also has a set of numbered cut buffers which can store text or other data being moved between applications. Cut buffers are considered obsolete, but Emacs supports them for the sake of X clients that still use them.
You can close the connection with the X server with the function
x-close-current-connection, and open a new one with
x-open-connection (perhaps with a different server and display).
The optional argument resource-string is a string of resource names and values, in the same format used in the `.Xresources' file. The values you specify override the resource values recorded in the X server itself. Here's an example of what this string might look like:
"*BorderWidth: 3\n*InternalBorder: 2\n"
See section X Resources.
t if the connected X display has color, and
nil otherwise.
t if the display
supports that color; otherwise, nil.
Black-and-white displays support just two colors, "black" or
"white". Color displays support many other colors.
x-synchronize enables or disables synchronous
communication with the X server. It enables synchronous communication
if flag is non-nil, and disables it if flag is
nil.
In synchronous mode, Emacs waits for a response to each X protocol command before doing anything else. This is useful for debugging Emacs, because protocol errors are reported right away, which helps you find the erroneous command. Synchronous mode is not the default because it is much slower.
x-get-resource retrieves a resource value from the X
Windows defaults database.
Resources are indexed by a combination of a key and a class. This function searches using a key of the form `instance.attribute', using the name under which Emacs was invoked as instance, and using `Emacs' as the class.
The optional arguments component and subclass add to the key and the class, respectively. You must specify both of them or neither. If you specify them, the key is `instance.component.attribute', and the class is `Emacs.subclass'.
See section `Resources X' in The GNU Emacs Manual.
This section describes functions and a variable that you can use to get information about the capabilities and origin of the X server that Emacs is displaying its frames on.
always, when-mapped, or
not-useful.
nil if this X screen supports the
SaveUnder feature.
static-gray, gray-scale,
static-color, pseudo-color, true-color, and
direct-color.
t if the X screen in use is a color
screen.