39. Frames

A frame is a rectangle on the screen that contains one or more XEmacs windows (see section 38. 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 33.3 Modeline Format), and optionally two scrollbars (see section 31. Scrollbars). By default the vertical scrollbar is on, the horizontal scrollbar is off.

The frame may also contain menubars (see section 27.3 Menubar), toolbars (see section 29.1 Toolbar Intro), and gutters (see section 30.1 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.

Function: framep object

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

See section 52. Emacs Display, for related information.

39.1 Creating Frames

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

Command: make-frame &optional props device

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 40. 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 39.2.3 X Window Frame Properties, for documentation of individual properties you can specify when creating an X window frame.

39.2 Frame Properties

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

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

Function: frame-properties &optional frame

This function returns a plist listing all the properties of frame and their values.

Function: frame-property frame property &optional default

This function returns frame's value for the property property, or default if there is no such property.

Function: set-frame-properties frame plist

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.

Function: set-frame-property frame property value

This function sets the property property of frame frame to the value value.

39.2.2 Initial Frame Properties

You can specify the properties for the initial startup frame by setting initial-frame-plist in your `.emacs' file.

Variable: initial-frame-plist

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

Variable: minibuffer-frame-plist

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.

Variable: default-frame-plist

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 38.8 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 section `Command Arguments' in The XEmacs User's Manual.

39.2.3 X Window Frame Properties

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 39.2.4 Frame Size And Position.)

width

The width of the frame contents, in characters. (To get the height in pixels, call frame-pixel-width; see 39.2.4 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.

39.2.4 Frame Size And Position

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:

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

39.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 properties. See section 39.2 Frame Properties.

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.

39.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 XEmacs computes the title automatically.

XEmacs 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. See section 33.3.1 The Data Structure of the Modeline.

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). See section 50. Glyphs.

39.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 force

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

Function: frame-live-p frame

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

39.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 39.9 Visibility of Frames. (TTY frames always count as "visible", even though only the selected one is actually displayed.)

Function: next-frame &optional frame which-frames which-devices

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.

window

Consider only the window window's frame and any frame now using window as the minibuffer.

any other value

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.

device

Consider only the one device device.

console

Consider all devices on console.

device-type

Consider all devices with device type device-type.

window-system

Consider all devices on window system consoles.

anything else

Consider all devices without restriction.

Function: previous-frame &optional frame which-frames which-devices

Like next-frame, but cycles through all frames in the opposite direction.

See also next-window and previous-window, in 38.5 Cyclic Ordering of Windows.

39.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-highest-window &optional frame position

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.

Function: frame-lowest-window &optional frame position

This function returns the lowest window on frame which is at position.

Function: frame-leftmost-window &optional frame position

This function returns the leftmost window on frame which is at position.

Function: frame-rightmost-window &optional frame 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.

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. See section 38.4 Selecting Windows.

Another function that (usually) returns one of the windows in a frame is minibuffer-window. See section 24.9 Minibuffer Miscellany.

39.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 (see section 24.9 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.

Variable: default-minibuffer-frame

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

39.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 `XEmacs' (see section 33.3.2 Variables Used in the Modeline).

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

Function: focus-frame 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.

Macro: save-selected-frame forms...

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.

Macro: with-selected-frame frame forms...

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.

39.9 Visibility of Frames

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.

Function: make-frame-visible &optional frame

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

Function: make-frame-invisible &optional frame force

This function makes frame frame invisible.

Command: iconify-frame &optional frame

This function iconifies frame frame.

Function: Command deiconify-frame &optional frame

This function de-iconifies frame frame. Under a window system, this is equivalent to make-frame-visible.

Function: frame-visible-p &optional 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 &optional 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 &optional frame

This returns whether frame is not obscured by any other X windows. On TTY frames, this is the same as frame-visible-p.

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

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

39.11 Frame Configurations

A frame configuration records the current arrangement of frames, all their properties, and the window configuration of each one.

Function: current-frame-configuration

This function returns a frame configuration list that describes the current arrangement of frames and their contents.

Function: set-frame-configuration configuration &optional nodelete

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.

39.12 Hooks for Customizing Frame Behavior

XEmacs provides many hooks that are called at various times during a frame's lifetime. See section 33.4 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 39.10 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 39.10 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.