[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Frames

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.

Function: framep object

This predicate returns t if object is a frame, and nil otherwise.

@xref{Display}, for related information.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Creating Frames

To create a new frame, call the function make-frame.

Function: make-frame &optional alist device

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] [ ? ]

1.2 Frame Parameters

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.1 Access to Frame Parameters

These functions let you read and change the parameter values of a frame.

Function: frame-parameters frame

The function frame-parameters returns an alist listing all the parameters of frame and their values.

Function: modify-frame-parameters frame alist

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] [ ? ]

1.2.2 Initial Frame Parameters

You can specify the parameters for the initial startup frame by setting initial-frame-alist in your ‘.emacs’ file.

Variable: initial-frame-alist

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.

Variable: default-frame-alist

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] [ ? ]

1.2.3 X Window Frame Parameters

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] [ ? ]

1.2.4 Frame Size And Position

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:

Function: set-frame-position frame left top

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.

Function: frame-height &optional frame
Function: frame-width &optional frame

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.

Function: frame-pixel-height &optional frame
Function: frame-pixel-width &optional frame

These functions return the height and width of frame, measured in pixels. If you don’t supply frame, they use the selected frame.

Function: set-frame-size frame cols rows &optional pretend

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] [ ? ]

1.2.5 The Name of a Frame (As Opposed to Its Title)

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.

Function: frame-name &optional frame

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.

Variable: default-frame-name

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] [ ? ]

1.3 Frame Titles

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.

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}.

Variable: frame-icon-title-format

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.

Function: x-set-frame-icon-pixmap frame pixmap &optional mask

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] [ ? ]

1.4 Deleting Frames

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.

Command: delete-frame &optional frame

This function deletes the frame frame. By default, frame is the selected frame.

Function: frame-live-p frame

The function frame-live-p returns non-nil if the frame frame has not been deleted.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Finding All Frames

Function: frame-list

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.

Function: device-frame-list &optional device

This function returns a list of all frames on device. If device is nil, the selected device will be used.

Function: visible-frame-list &optional device

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.)

Function: next-frame &optional frame minibuf

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.

0

Consider all visible or iconified frames.

a window

Consider only the frames using that particular window as their minibuffer.

the symbol visible

Include all visible frames.

0

Include all visible and iconified frames.

anything else

Consider all frames.

Function: previous-frame &optional frame minibuf

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] [ ? ]

1.6 Frames and Windows

Each window is part of one and only one frame; you can get the frame with window-frame.

Function: frame-root-window &optional frame

This returns the root window of frame frame. frame defaults to the selected frame if not specified.

Function: window-frame &optional window

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.

Function: frame-top-window frame

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.

Function: frame-selected-window &optional frame

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] [ ? ]

1.7 Minibuffers and Frames

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.

Variable: default-minibuffer-frame

This variable specifies the frame to use for the minibuffer window, by default.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 Input Focus

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.

Function: selected-frame &optional 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}).

Function: select-frame frame

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] [ ? ]

1.9 Visibility of Frames

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.

Command: make-frame-visible &optional frame

This function makes frame frame visible. If you omit frame, it makes the selected frame visible.

Command: make-frame-invisible &optional frame

This function makes frame frame invisible.

Command: iconify-frame &optional frame

This function iconifies frame frame.

Command: deiconify-frame &optional frame

This function de-iconifies frame frame. Under X, this is equivalent to make-frame-visible.

Function: frame-visible-p frame

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.

Function: frame-iconified-p frame

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.)

Function: frame-totally-visible-p frame

This returns whether frame is not obscured by any other X windows. This function always returns y on TTY frames.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.10 Raising and Lowering Frames

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:

Command: raise-frame &optional frame

This function raises frame frame.

Command: lower-frame &optional 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.)

Variable: auto-raise-frame

This variable’s value is t if frames will be raised to the top when selected.

Variable: auto-lower-frame

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.

Function: default-select-frame-hook

This hook function implements the auto-raise-frame variable; it is for use as the value of select-frame-hook.

Function: default-deselect-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] [ ? ]

1.11 Hooks for Customizing Frame Behavior

XEmacs provides many hooks that are called at various times during a frame’s lifetime. @xref{Hooks}.

Variable: create-frame-hook

This hook is called each time a frame is created. The functions are called with one argument, the newly-created frame.

Variable: delete-frame-hook

This hook is called each time a frame is deleted. The functions are called with one argument, the about-to-be-deleted frame.

Variable: select-frame-hook

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.

Variable: deselect-frame-hook

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.

Variable: map-frame-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.

Variable: unmap-frame-hook

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] [ ? ]

About This Document

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.