Frames
******

A FRAME is a rectangle on the screen that contains one or more XEmacs 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.

See Display, for related information.

Creating Frames
===============

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

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

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.

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.

 -- 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 prop val
     This function sets the property PROP of frame FRAME to the value VAL.

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 X Resources (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 Choosing Window.

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 Command Arguments (The XEmacs User's Manual).

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 Size and Position.)

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

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

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

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

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.

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 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 Cyclic Window Ordering.

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

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

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

However, you can also create a frame with no minibuffer.  Such a frame must use the minibuffer window of some other frame.  When you create the frame, you can specify explicitly the 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.

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

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.

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.  On TTY frames, this is the same as frame-visible-p.

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

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
     This function restores the state of frames described in CONFIGURATION.

Hooks for Customizing Frame Behavior
====================================

XEmacs provides many hooks that are called at various times during a frame's lifetime.  See 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 Raising and Lowering), 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 Raising and Lowering), 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.