[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A frame is a rectangle on the screen that contains one or more XEmacs windows (see section Windows). A frame initially contains a single main window (plus perhaps an echo area), which you can subdivide vertically or horizontally into smaller windows. Each window is associated with a modeline (see section Modeline Format), and optionally two scrollbars (see section Scrollbars). By default the vertical scrollbar is on, the horizontal scrollbar is off.
The frame may also contain menubars (see section Menubar), toolbars (see section Toolbar Intro), and gutters (see section Gutter Intro). By default there is one of each at the top of the frame, with menubar topmost, toolbar next, and gutter lowest, immediately above the windows. (Warning: the gutter is a new, experimental, and unstable feature of XEmacs version 21.2.)
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.
39.1 Creating Frames | Creating additional frames. | |
39.2 Frame Properties | Controlling frame size, position, font, etc. | |
39.3 Frame Titles | Automatic updating of frame titles. | |
39.4 Deleting Frames | Frames last until explicitly deleted. | |
39.5 Finding All Frames | How to examine all existing frames. | |
39.6 Frames and Windows | A frame contains windows; display of text always works through windows. | |
39.7 Minibuffers and Frames | How a frame finds the minibuffer to use. | |
39.8 Input Focus | Specifying the selected frame. | |
39.9 Visibility of Frames | Frames may be visible or invisible, or icons. | |
39.10 Raising and Lowering Frames | Raising a frame makes it hide other X windows; lowering it makes the others hide them. | |
39.11 Frame Configurations | Saving the state of all frames. | |
39.12 Hooks for Customizing Frame Behavior | Hooks for customizing frame behavior. |
See section 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 on device, if device permits creation of frames. (An X server does; an ordinary terminal does not (yet).) device defaults to the selected device if omitted. See section Consoles and Devices.
The argument props is a property list (a list of alternating
keyword-value specifications) of properties for the new frame. (An alist
is accepted for backward compatibility but should not be passed in.) Any
properties not mentioned in props default according to the value
of the variable default-frame-plist
. For X devices, properties
not specified in default-frame-plist
default in turn from
default-x-frame-plist
and, if not specified there, from the X
resources. For TTY devices, default-tty-frame-plist
is consulted
as well as default-frame-plist
.
The set of possible properties depends in principle on what kind of window system XEmacs uses to display its frames. See section X Window Frame Properties, for documentation of individual properties you can specify when creating an X window frame.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A frame has many properties that control its appearance and behavior. Just what properties a frame has depends on which display mechanism it uses.
Frame properties exist for the sake of window systems. A terminal frame
has few properties, mostly for compatibility’s sake; only the height,
width and buffer-predicate
properties really do something.
39.2.1 Access to Frame Properties | How to change a frame’s properties. | |
39.2.2 Initial Frame Properties | Specifying frame properties when you make a frame. | |
39.2.3 X Window Frame Properties | List of frame properties. | |
39.2.4 Frame Size And Position | Changing the size and position of a frame. | |
39.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 properties of a frame.
This function returns a plist listing all the properties of frame and their values.
This function returns frame’s value for the property property, or default if there is no such property.
This function alters the properties of frame frame based on the elements of property list plist. If you don’t mention a property in plist, its value doesn’t change.
This function sets the property property of frame frame to the value value.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can specify the properties for the initial startup frame by setting
initial-frame-plist
in your ‘.emacs’ file.
This variable’s value is a plist of alternating property-value pairs used when creating the initial X window frame.
XEmacs creates the initial frame before it reads your ‘~/.emacs’
file. After reading that file, XEmacs checks initial-frame-plist
,
and applies the property 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 (xemacs)Resources X section ‘X Resources’ in The XEmacs User’s 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 properties in default-frame-plist
to override the X
resources for subsequent frames; then, to prevent these from affecting
the initial frame, specify the same properties in
initial-frame-plist
with values that match the X resources.
If these properties specify a separate minibuffer-only frame via a
minibuffer
property of nil
, and you have not yet created
one, XEmacs creates one for you.
This variable’s value is a plist of properties used when creating an initial minibuffer-only frame—if such a frame is needed, according to the properties for the main initial frame.
This is a plist specifying default values of frame properties for subsequent XEmacs frames (not the initial ones).
See also special-display-frame-plist
, in Choosing a Window for Display.
If you use options that specify window appearance when you invoke XEmacs,
they take effect by adding elements to default-frame-plist
. One
exception is ‘-geometry’, which adds the specified position to
initial-frame-plist
instead. See (xemacs)Command Arguments section ‘Command Arguments’ in The XEmacs User’s Manual.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Just what properties a frame has depends on what display mechanism it
uses. Here is a table of the properties 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, XEmacs 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 XEmacs 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 property 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 property 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 property non-nil
; it is up to
Lisp programs that call make-frame
to specify this property as
well as specifying the left
and top
properties.
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.)
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 arg, a buffer, once for
each buffer; if the predicate returns a non-nil
value, it
considers that buffer.
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 properties left
, top
, height
, and
width
. Whatever geometry properties 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 property 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 properties. See section Frame Properties.
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 XEmacs computes the title automatically.
XEmacs 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
. See section The Data Structure of the Modeline.
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). See section 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.
A frame may not be deleted if its minibuffer is used by other frames.
Normally, you cannot delete the last non-minibuffer-only frame (you must
use save-buffers-kill-emacs
or kill-emacs
). However, if
optional second argument force is non-nil
, you can delete
the last frame. (This will automatically call
save-buffers-kill-emacs
.)
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 defaults to the
selected frame.
The second argument, which-frames, says which frames to consider:
visible
Consider only frames that are visible.
iconic
Consider only frames that are iconic.
invisible
Consider only frames that are invisible (this is different from iconic).
visible-iconic
Consider frames that are visible or iconic.
invisible-iconic
Consider frames that are invisible or iconic.
nomini
Consider all frames except minibuffer-only ones.
visible-nomini
Like visible
but omits minibuffer-only frames.
iconic-nomini
Like iconic
but omits minibuffer-only frames.
invisible-nomini
Like invisible
but omits minibuffer-only frames.
visible-iconic-nomini
Like visible-iconic
but omits minibuffer-only frames.
invisible-iconic-nomini
Like invisible-iconic
but omits minibuffer-only frames.
nil
Identical to nomini
.
Consider only the window window’s frame and any frame now using window as the minibuffer.
Consider all frames.
The optional argument which-devices further clarifies on which devices to search for frames as specified by which-frames.
nil
Consider all devices on the selected console.
Consider only the one device device.
Consider all devices on console.
Consider all devices with device type device-type.
window-system
Consider all devices on window system consoles.
Consider all devices without restriction.
Like next-frame
, but cycles through all frames in the opposite
direction.
See also next-window
and previous-window
, in Cyclic Ordering of Windows.
[ < ] | [ > ] | [ << ] | [ 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 function returns the topmost, leftmost window of frame frame at position position.
If omitted, frame defaults to the currently selected frame.
position is used to distinguish between multiple windows that abut
the top of the frame: 0 means the leftmost window abutting the top of
the frame, 1 the next-leftmost, etc. position can also be less
than zero: -1 means the rightmost window abutting the top of the frame,
-2 the next-rightmost, etc. If omitted, position defaults to 0,
i.e. the leftmost highest window. If there is no window at the given
position, nil
is returned.
The following three functions work similarly.
This function returns the lowest window on frame which is at position.
This function returns the leftmost window on frame which is at position.
This function returns the rightmost window on frame which is at position.
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. See section Selecting Windows.
Another function that (usually) returns one of the windows in a frame is
minibuffer-window
. See section Minibuffer Miscellany.
[ < ] | [ > ] | [ << ] | [ 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
(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 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
‘XEmacs’ (see section Variables Used in the Modeline).
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 select-frame
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.
Also note that when the variable focus-follows-mouse
is
non-nil
, the frame selection is temporary and is reverted when
the current command terminates, much like the buffer selected by
set-buffer
. In order to effect a permanent focus change use
focus-frame
.
This function selects frame and gives it the window system focus.
The operation of focus-frame
is not affected by the value of
focus-follows-mouse
.
This macro records the selected frame, executes forms in sequence, then restores the earlier selected frame. The value returned is the value of the last form.
This macro records the selected frame, then selects frame and executes forms in sequence. After the last form is finished, the earlier selected frame is restored. The value returned is the value of the last form.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An frame on a window system 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 a window system,
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. On TTY frames, this is the same as frame-visible-p
.
[ < ] | [ > ] | [ << ] | [ 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 properties.)
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] | [ ? ] |
A frame configuration records the current arrangement of frames, all their properties, and the window configuration of each one.
This function returns a frame configuration list that describes the current arrangement of frames and their contents.
This function restores the state of frames described by
configuration, which should be the return value from a previous
call to current-frame-configuration
.
Each frame listed in configuration has its position, size, window configuration, and other properties set as specified in configuration.
Ordinarily, this function deletes all existing frames not listed in
configuration. But if optional second argument nodelete is
non-nil
, the unwanted frames are iconified instead.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.