[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 make a terminal frame; instead, it initially creates a single X window frame. You can create more; see Creating Frames.
This predicate returns t
if object is a frame, and
nil
otherwise.
1.1 Creating Frames | Creating additional X Window frames. | |
1.2 Frame Parameters | Controlling frame size, position, font, etc. | |
1.3 Deleting Frames | Frames last until explicitly deleted. | |
1.4 Finding All Frames | How to examine all existing frames. | |
1.5 Frames and Windows | A frame contains windows; display of text always works through windows. | |
1.6 Minibuffers and Frames | How a frame finds the minibuffer to use. | |
1.7 Input Focus | What is this?? | |
1.8 Visibility of Frames | Frames may be visible or invisible, or icons. | |
1.9 Raising and Lowering Frames | Raising a frame makes it hide other X windows; lowering it makes the others hide them. | |
1.10 Frame Configurations | Saving the state of all frames. | |
1.11 Mouse Tracking | Getting events that say when the mouse moves. | |
1.12 Mouse Position | Asking where the mouse is, or moving it. | |
1.13 Pop-Up Menus | Displaying a menu for the user to select from. | |
1.14 X Selections | Transferring text to and from other X clients. | |
1.15 X Server |
@xref{Emacs Display}, for related information.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To create a new frame, call the function make-frame
.
This function creates a new frame, if the display mechanism permits creation of frames. (An X server does; an ordinary terminal does not.)
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.
An alist specifying default values of frame parameters. Each element has the form:
(parameter . value)
If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to default-frame-alist
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A frame has many parameters that control how it displays.
1.2.1 Access to Frame Parameters | How to change a frame’s parameters. | |
1.2.2 Initial Frame Parameters | Specifying frame parameters when you make a frame. | |
1.2.3 X Window Frame Parameters | Individual parameters documented. | |
1.2.4 Frame Size And Position | Changing the size and position of a frame. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions let you read and change the parameter values of a frame.
The function frame-parameters
returns an alist of all the
parameters of frame.
This function alters the parameters of frame frame based on the
elements of alist. Each element of alist has the form
(parm . value)
, where parm is a symbol naming a
parameter. If you don’t mention a parameter in alist, its value
doesn’t change.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can specify the parameters for the initial startup frame
by setting initial-frame-alist
in your ‘.emacs’ file.
This variable’s value is an alist of parameter values to when creating the initial X window frame.
If these parameters specify a separate minibuffer-only frame, and you have not created one, Emacs creates one for you.
This variable’s value is an alist of parameter values to when creating an initial minibuffer-only frame—if such a frame is needed, according to the parameters for the main initial frame.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
The name of the frame.
left
The screen position of the left edge, in pixels.
top
The screen position of the top edge, in pixels.
height
The height of the frame contents, in pixels.
width
The width of the frame contents, in pixels.
window-id
The number of the X window for 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, a minibuffer window (in some other frame) means the new
frame uses that minibuffer.
font
The name of the font for text in the frame. This is a string.
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 a scroll bar for vertical scrolling
(non-nil
means yes).
horizontal-scroll-bars
Whether the frame has a scroll bar for horizontal scrolling
(non-nil
means yes). (Horizontal scroll bars are not currently
implemented.)
icon-type
The type of icon to use for this frame when it is iconified.
Non-nil
specifies a bitmap icon, nil
a text icon.
foreground-color
The color to use for the inside of a character. We use strings to designate colors; the X server defines the meaningful color names.
background-color
The color to use for the background of text.
mouse-color
The color for the mouse cursor.
cursor-color
The color for the cursor that shows point.
border-color
The color for the border of the frame.
cursor-type
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.
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 zero. @xref{Menu Bar}.
parent-id
The X Window number of the window that should be the parent of this one. Specifying this lets you create an Emacs window inside some other application’s window. (It is not certain this will be implemented; try it and see if it works.)
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can read or change the size and position of a frame using the
frame parameters left
, top
, height
and
width
. When you create a frame, you must specify either both
size parameters or neither. Likewise, you must specify either both
position parameters or neither. 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:
This function sets the position of the top left corner of frame—to left and top. These arguments are measured in pixels, counting from the top left corner of the screen.
These functions return the height and width of frame, measured in characters. If you don’t supply frame, they use the selected frame.
These functions return the height and width of frame, measured in pixels. If you don’t supply frame, they use the selected frame.
These functions return the height and width, respectively, of a character in frame, measured in pixels. The values depend on the choice of font. If you don’t supply frame, these functions use the selected frame.
This function sets the size of frame, measured in characters; cols and rows specify the new width and height.
To set the size with values measured in pixels, use
modify-frame-parameters
to set the width
and height
parameters. See section X Window Frame Parameters.
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. @xref{Screen
Size}.
The function x-parse-geometry
converts a standard X windows
geometry string to an alist which you can use as part of the argument to
x-create-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-geometry "35x70+0-0") ⇒ ((width . 35) (height . 70) (left . 0) (top . -1))
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
This function deletes the frame frame. By default, frame is the selected frame.
The function frame-live-p
returns non-nil
if the frame
frame has not been deleted.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The function 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.
This function returns a list of just the currently visible frames.
The function 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
Exclude minibuffer-only frames.
Consider only the frames using that particular window as their minibuffer.
Consider all frames.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
.
This returns the root window of frame frame.
This function returns the frame that window is on.
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
.
This function returns the window on frame which is selected within frame.
Conversely, selecting a window for Emacs with select-window
also
makes that window selected within its frame. @xref{Selecting Windows}.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
(@pxref{Minibuffer Misc}).
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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
At any time, one frame in Emacs is the selected frame. The selected window always resides on the 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.
This function selects frame frame, temporarily disregarding the X Windows focus. The selection of frame 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
. @xref{Focus Events}.
This function selects frame frame, assuming that the X server focus already points to frame.
Focus events normally do their job by invoking this command. Don’t call it for any other reason.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
This function makes frame frame visible. If you omit frame, it makes the selected frame visible.
This function makes frame frame invisible. If you omit frame, it makes the selected frame invisible.
This function iconifies frame frame. If you omit frame, it iconifies the selected frame.
This returns the visibility status of frame frame. The value is
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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
This function raises frame frame.
This function lowers frame frame.
You can also specify 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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function returns a frame configuration list which describes the current arrangement of frames, all their properties, and the window configuration of each one.
This function restores the state of frames described in configuration.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
Execute body, meanwhile generating input events for mouse motion.
The code in body can read these events with read-event
or
read-key-sequence
. @xref{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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The new functions mouse-position
and set-mouse-position
give access to the current position of the mouse.
This function returns a description of the position of the mouse. The
value looks like (frame x . y)
, where x
and y are integers giving the position in pixels relative to the
top left corner of the inside of frame.
Thus function warps the mouse to position x, y in frame frame. The arguments x and y are integers, giving the position in pixels relative to the top left corner of the inside of frame.
Warping the mouse means changing the screen position of the mouse as if the user had moved the physical mouse—thus simulating the effect of actual mouse motion.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function displays a pop-up menu and returns an indication of what selection the user makes.
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 positions measured in characters, counting from the top left corner of window’s frame.
The argument menu says what to display in the menu. It can be a keymap or a list of keymaps (@pxref{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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
This function sets a “selection” in the X server.
It takes two arguments: a selection type type, and the value to
assign to it, data. If data is 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),
or a cons of two markers pointing to the same buffer. In the last case,
the selection is considered to be the text 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 Windows conventions. The default is PRIMARY
.
This function accesses selections set up by Emacs or by other X
clients. It takes two optional arguments, type and
data-type. The default for type, the selection type, is
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.
This function returns the contents of cut buffer number n.
This function stores string into the first cut buffer (cut buffer 0), moving the other values down through the series of cut buffers, kill-ring-style.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes how to access and change the overall status of the X server Emacs is using.
1.15.1 X Connections | Opening and closing the X server connection. | |
1.15.2 Resources | Getting resource values from the server. | |
1.15.3 Rebinding X Server Keys | Telling the server what input to send for each keyboard key. | |
1.15.4 Data about the X Server | Getting info about the X server. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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).
This function closes the connection to the X server. It deletes all frames, making Emacs effectively inaccessible to the user; therefore, a Lisp program that closes the connection should open another one.
This function opens a connection to an X server, for use of display 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"
This returns t
if the connected X display has color, and
nil
otherwise.
This function reports whether a color name is meaningful and supported
on the X display Emacs is using. It returns 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.
The function 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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The function 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’, where instance is the name under which Emacs was invoked, and uses ‘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’.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The X server allows each client to specify what sequence of characters
each keyboard key should generate, depending on the set of shift keys
held down. Emacs has functions to redefine these sequences in the X
server. Redefinitions via x-rebind-key
apply only to Emacs.
Other clients using the same X server are not affected.
This function redefines a keyboard key in the X server. keysym is
a string which conforms to the X keysym definitions found in
‘X11/keysymdef.h’, but without the prefix XK_
.
modifiers is either nil
, meaning no modifier keys, or a
list of names of modifier keys, again using the names from
‘X11/keysymdef.h’ but without the XK_
prefix.
The third argument, newstring, is the new definition of the key. It is the sequence of characters that the key should produce as input.
For example,
(x-rebind-key "F1" nil "abc")
causes the F1 function key to generate the string "abc"
. Similarly,
(x-rebind-key "BackSpace" (list "Shift" "Control_L" "c-s-BackSpace")
makes the <BS> key send the string "c-s-BackSpace"
if either
the shift key or the left-hand control key is held down.
This function redefines the complete meaning of a single keyboard key, specifying the behavior for each of the 16 shift masks independently.
The argument keysym specifies the key to rebind, as in
x-rebind-key
.
The argument strings is a list of 16 elements, one for each
possible shift mask value; the nth element says how to redefine
the key keycode with shift mask value n. If element n
is a string, it is the new definition for shift mask n. If
element n is nil
, the definition for shift mask n is
unchanged.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
This function returns the number of screens associated with the current display.
This function returns the list of version numbers of the X server in use.
This function returns the vendor supporting the X server in use.
This function returns the height of this X screen in pixels.
This function returns the height of this X screen in millimeters.
This function returns the width of this X screen in pixels.
This function returns the width of this X screen in millimeters.
This function returns the backing store capability of this screen.
Values can be the symbols always
, when-mapped
, or
not-useful
.
This function returns non-nil
if this X screen supports the
SaveUnder feature.
This function returns the number of planes this display supports.
This function returns the visual class for this X screen. The value is
one of the symbols static-gray
, gray-scale
,
static-color
, pseudo-color
, true-color
, and
direct-color
.
This function returns t
if the X screen in use is a color
screen.
This function returns the number of color cells this X screen supports.
This variable’s value is is t
if no X window manager is in use.
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on January 16, 2023 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on January 16, 2023 using texi2html 5.0.