[ << ] | [ < ] | [ 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 XEmacs runs on a text-only terminal, it starts with one TTY frame. If you create additional ones, XEmacs displays one and only one at any given time—on the terminal screen, of course.
When XEmacs communicates directly with an X server, it does not have a TTY frame; instead, it starts with a single X window frame. It can display multiple X window frames at the same time, each in its own X window.
This predicate returns t
if object is a frame, and
nil
otherwise.
1.1 Creating Frames | Creating additional frames. | |
1.2 Frame Parameters | Controlling frame size, position, font, etc. | |
1.3 Frame Titles | Automatic updating of frame titles. | |
1.4 Deleting Frames | Frames last until explicitly deleted. | |
1.5 Finding All Frames | How to examine all existing frames. | |
1.6 Frames and Windows | A frame contains windows; display of text always works through windows. | |
1.7 Minibuffers and Frames | How a frame finds the minibuffer to use. | |
1.8 Input Focus | Specifying the selected frame. | |
1.9 Visibility of Frames | Frames may be visible or invisible, or icons. | |
1.10 Raising and Lowering Frames | Raising a frame makes it hide other X windows; lowering it makes the others hide them. | |
1.11 Hooks for Customizing Frame Behavior | Hooks for customizing frame behavior. |
@xref{Display}, for related information.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To create a new frame, call the function make-frame
.
This function creates a new frame on device, if device permits creation of frames. (An X server does; an ordinary terminal does not.) device defaults to the selected device if omitted. @xref{Devices}.
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
. For X devices, parameters not
specified in default-frame-alist
default in turn from
default-x-frame-alist
and, if not specified there, from the X
resources. For TTY devices, default-tty-frame-alist
is
consulted as well as default-frame-alist
.
The set of possible parameters depends in principle on what kind of window system XEmacs uses to display its frames. See section X Window Frame Parameters, for documentation of individual parameters you can specify when creating an X window frame.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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, mostly for compatibility’s sake; only the height,
width and buffer-predicate
parameters really do something.
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 | List of frame parameters. | |
1.2.4 Frame Size And Position | Changing the size and position of a frame. | |
1.2.5 The Name of a Frame (As Opposed to Its Title) | The name of a frame (as opposed to its title). |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions let you read and change the parameter values of a frame.
The function frame-parameters
returns an alist listing all the
parameters of frame and their values.
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 used when creating the initial X window frame. Each element has the form:
(parameter . value)
Emacs creates the initial frame before it reads your ‘~/.emacs’
file. After reading that file, Emacs checks initial-frame-alist
,
and applies the parameter settings in the altered value to the already
created initial frame.
If these settings affect the frame geometry and appearance, you’ll see the frame appear with the wrong ones and then change to the specified ones. If that bothers you, you can specify the same geometry and appearance with X resources; those do take affect before the frame is created. See X Resources in The GNU Emacs Manual.
X resource settings typically apply to all frames. If you want to
specify some X resources solely for the sake of the initial frame, and
you don’t want them to apply to subsequent frames, here’s how to achieve
this. Specify parameters in default-frame-alist
to override the
X resources for subsequent frames; then, to prevent these from affecting
the initial frame, specify the same parameters in
initial-frame-alist
with values that match the X resources.
This is an alist specifying default values of frame parameters for subsequent Emacs frames (not the initial ones).
See also special-display-frame-alist
, in @ref{Choosing Window}.
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 the specified position to
initial-frame-alist
instead. See Command Arguments in The GNU Emacs Manual.
[ << ] | [ < ] | [ 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; of these,
name
, height
, width
, and buffer-predicate
provide meaningful information in non-X frames.
name
The name of the frame. Most window managers display the frame’s name in the frame’s border, at the top of the frame. If you don’t specify a name, and you have more than one frame, Emacs sets the frame name based on the buffer displayed in the frame’s selected window.
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.
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.
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. If the parameter is a negative
integer -pos then pos is positive!
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. If the parameter is a negative
integer -pos then pos is positive!
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
Non-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
The height of the frame contents, in characters. (To get the height in
pixels, call frame-pixel-height
; see Frame Size And Position.)
width
The width of the frame contents, in characters. (To get the height in
pixels, call frame-pixel-width
; see Frame Size And Position.)
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. If the value is a minibuffer window (in some other frame),
the new frame uses that minibuffer. (Minibuffer-only and minibuffer-less
frames are not yet implemented in XEmacs.)
scroll-bar-width
The width of the vertical scroll bar, in pixels.
cursor-color
The color for the cursor that shows point.
border-color
The color for the border of the frame.
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.
inter-line-space
The space in pixels between adjacent lines of text. (Not currently implemented.)
modeline
Whether the frame has a modeline.
[ << ] | [ < ] | [ 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
. 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, and count from the top left corner of the screen. Negative parameter values count up or rightward from the top left corner of the screen.
These functions return the height and width of frame, measured in lines and columns. 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.
This function sets the size of frame, measured in characters; cols and rows specify the new width and height. (If pretend is non-nil, it means that redisplay should act as if the frame’s size is cols by rows, but the actual size of the frame should not be changed. You should not normally use this option.)
You can also use the functions set-frame-height
and
set-frame-width
to set the height and width individually.
The frame is the first argument and the size (in rows or columns)
is the second. (There is an optional third argument, pretend,
which has the same purpose as the corresponding argument in
set-frame-size
.)
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Under X, every frame has a name, which is not the same as the title of the frame. A frame’s name is used to look up its resources and does not normally change over the lifetime of a frame. It is perfectly allowable, and quite common, for multiple frames to have the same name.
This function returns the name of frame, which defaults to the selected frame if not specified. The name of a frame can also be obtained from the frame’s parameters. See section Frame Parameters.
This variable holds the default name to assign to newly-created frames.
This can be overridden by arguments to make-frame
. This
must be a string.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Every frame has a title; most window managers display the frame title at
the top of the frame. You can specify an explicit title with the
name
frame property. But normally you don’t specify this
explicitly, and Emacs computes the title automatically.
Emacs computes the frame title based on a template stored in the
variable frame-title-format
.
This variable specifies how to compute a title for a frame when you have not explicitly specified one.
The variable’s value is actually a modeline construct, just like
modeline-format
. @xref{Modeline Data}.
This variable specifies how to compute the title for an iconified frame, when you have not explicitly specified the frame title. This title appears in the icon itself.
This function sets the icon of the given frame to the given image
instance, which should be an image instance object (as returned by
make-image-instance
), a glyph object (as returned by
make-glyph
), or nil
. If a glyph object is given, the
glyph will be instantiated on the frame to produce an image instance
object.
If the given image instance has a mask, that will be used as the icon mask; however, not all window managers support this.
The window manager is also not required to support color pixmaps, only bitmaps (one plane deep).
If the image instance does not have a mask, then the optional third argument may be the image instance to use as the mask (it must be one plane deep). @xref{Glyphs}.
[ << ] | [ < ] | [ 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.
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 XEmacs.
This function returns a list of all frames on device. If
device is nil
, the selected device will be used.
This function returns a list of just the currently visible frames. If device is specified only frames on that device will be returned. See section Visibility of Frames. (TTY frames always count as “visible”, even though only the selected one is actually displayed.)
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.
visible
Consider all visible frames.
Consider all visible or iconified frames.
Consider only the frames using that particular window as their minibuffer.
visible
Include all visible frames.
0
Include all visible and iconified frames.
Consider all frames.
Like next-frame
, but cycles through all frames in the opposite
direction.
See also next-window
and previous-window
, in @ref{Cyclic
Window Ordering}.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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. frame defaults to the selected frame if not specified.
This function returns the frame that window is on. window defaults to the selected window if omitted.
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.
This returns the topmost, leftmost window of frame frame.
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 that is selected within frame. frame defaults to the selected frame if not specified.
Conversely, selecting a window for XEmacs with select-window
also
makes that window selected within its frame. @xref{Selecting Windows}.
Another function that (usually) returns one of the windows in a frame is
minibuffer-window
. @xref{Minibuffer Misc}.
[ << ] | [ < ] | [ 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 (this is not
implemented as of 19.13, but will be in 19.14). Such a frame must use
the minibuffer window of some other frame. When you create the frame,
you can specify explicitly the minibuffer window to use (in some other
frame). 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.
This variable specifies the frame to use for the minibuffer window, by default.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
At any time, one frame in XEmacs is the selected frame. The selected window always resides on the selected frame. As the focus moves from device to device, the selected frame on each device is remembered and restored when the focus moves back to that device.
This function returns the selected frame on device. If
device is not specified, the selected device will be used. If no
frames exist on the device, nil
is returned.
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.
When using a text-only terminal, there is no window manager; therefore,
select-frame
is the only way to switch frames, and the effect
lasts until overridden by a subsequent call to select-frame
.
Only the selected terminal frame is actually displayed on the terminal.
Each terminal screen except for the initial one has a number, and the
number of the selected frame appears in the mode line after the word
‘Emacs’ (@pxref{Modeline Variables}).
This function selects frame frame, temporarily disregarding the focus of the X server if any. 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.
Note that this does not actually cause the window-system focus to be set
to this frame, or the select-frame-hook
or
deselect-frame-hook
to be run, until the next time that XEmacs is
waiting for an event.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An X window 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 on the screen, not even as an icon.
Visibility is meaningless for TTY frames, since only the selected one is actually displayed in any case.
This function makes frame frame visible. If you omit frame, it makes the selected frame visible.
This function makes frame frame invisible.
This function iconifies frame frame.
This function de-iconifies frame frame. Under X, this is
equivalent to make-frame-visible
.
This returns whether frame is currently “visible” (actually in use for display). A frame that is not visible is not updated, and, if it works through a window system, may not show at all.
This returns whether frame is iconified. Not all window managers
use icons; some merely unmap the window, so this function is not the
inverse of frame-visible-p
. It is possible for a frame to not
be visible and not be iconified either. However, if the frame is
iconified, it will not be visible. (Under FSF Emacs, the functionality
of this function is obtained through frame-visible-p
.)
This returns whether frame is not obscured by any other X
windows. This function always returns y
on TTY frames.
[ << ] | [ < ] | [ 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 XEmacs’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).
Under X, most ICCCM-compliant window managers will have an option to do
this for you, but the following variables are provided in case you’re
using a broken WM. (Under FSF Emacs, the same functionality is
provided through the auto-raise
and auto-lower
frame parameters.)
This variable’s value is t
if frames will be raised to the top
when selected.
This variable’s value is t
if frames will be lowered to the bottom
when no longer selected.
Auto-raising and auto-lowering is implemented through functions attached
to select-frame-hook
and deselect-frame-hook
(see section Hooks for Customizing Frame Behavior). Under normal circumstances, you should not call
these functions directly.
This hook function implements the auto-raise-frame
variable; it is
for use as the value of select-frame-hook
.
This hook function implements the auto-lower-frame
variable; it is
for use as the value of deselect-frame-hook
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
XEmacs provides many hooks that are called at various times during a frame’s lifetime. @xref{Hooks}.
This hook is called each time a frame is created. The functions are called with one argument, the newly-created frame.
This hook is called each time a frame is deleted. The functions are called with one argument, the about-to-be-deleted frame.
This is a normal hook that is run just after a frame is selected. The
function default-select-frame-hook
, which implements auto-raising
(see section Raising and Lowering Frames), is normally attached to this hook.
Note that calling select-frame
does not necessarily set the
focus: The actual window-system focus will not be changed until the next
time that XEmacs is waiting for an event, and even then, the window
manager may refuse the focus-change request.
This is a normal hook that is run just before a frame is deselected
(and another frame is selected). The function
default-deselect-frame-hook
, which implements auto-lowering
(see section Raising and Lowering Frames), is normally attached to this hook.
This hook is called each time a frame is mapped (i.e. made visible). The functions are called with one argument, the newly mapped frame.
This hook is called each time a frame is unmapped (i.e. made invisible or iconified). The functions are called with one argument, the newly unmapped frame.
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on December 6, 2024 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 December 6, 2024 using texi2html 5.0.