@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/frames.info
@node Frames, Devices, Windows, Top
@chapter Frames
@cindex frame

  A @var{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.

@cindex terminal frame
@cindex X window frame
  When XEmacs runs on a text-only terminal, it has just one frame, a
@dfn{terminal frame}.  There is no way to create another terminal frame
after startup.  If XEmacs has an X display, it does not make a terminal
frame; instead, it initially creates a single @dfn{X window frame}.  You
can create more; see @ref{Creating Frames}.

@defun framep object
This predicate returns @code{t} if @var{object} is a frame, and
@code{nil} otherwise.
@end defun

@menu
* Creating Frames::		Creating additional X Window frames.
* Frame Parameters::		Controlling frame size, position, font, etc.
* Deleting Frames::		Frames last until explicitly deleted.
* Finding All Frames::		How to examine all existing frames.
* Frames and Windows::		A frame contains windows;
				  display of text always works through windows.
* Minibuffers and Frames::	How a frame finds the minibuffer to use.
* Input Focus::			Which frame receives keyboard events.
* Visibility of Frames::	Frames may be visible or invisible, or icons.
* Raising and Lowering::	Raising a frame makes it hide other X windows;
				  lowering it makes the others hide them.
* Frame Titles and Icons::     Changing the way the frame's title or icon
                                  appears.
* Frame Hooks::                Hooks for customizing frame behavior.
@end menu

  @xref{Display}, for related information.

@node Creating Frames
@section Creating Frames

To create a new frame, call the function @code{make-frame}.

@defun make-frame &optional alist device
This function creates a new frame on @var{device}, if @var{device} permits
creation of frames.  (An X server does; an ordinary terminal does not.)
@var{device} defaults to the selected device if omitted.  @xref{Devices}.

The argument is an alist specifying frame parameters.  Any parameters
not mentioned in @var{alist} default according to the value of the
variable @code{default-frame-alist}.  For X devices, parameters not
specified in @code{default-frame-alist} default in turn from
@code{default-x-frame-alist} and, if not specified there, from the X
resources.  For TTY devices, @code{default-tty-frame-alist} is
consulted as well as @code{default-frame-alist}.

The set of possible parameters depends in principle on what kind of
window system XEmacs uses to display its the frames.  @xref{X Frame
Parameters}, for documentation of individual parameters you can specify
when creating an X window frame.
@end defun

@defvar default-frame-alist
An alist specifying default values of frame parameters.  Each element
has the form:

@example
(@var{parameter} . @var{value})
@end example

If you use options that specify window appearance when you invoke XEmacs,
they take effect by adding elements to @code{default-frame-alist}.
@end defvar

@node Frame Parameters
@section Frame Parameters

A frame has many parameters that control how it displays.

@menu
* Parameter Access::       How to change a frame's parameters.
* Initial Parameters::	   Specifying frame parameters when you make a frame.
* X Frame Parameters::     Individual parameters documented.
* Size And Position::      Changing the size and position of a frame.
* Frame Name::            The name of a frame (as opposed to its title).
@end menu

@node Parameter Access
@subsection Access to Frame Parameters

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

@defun frame-parameters frame
The function @code{frame-parameters} returns an alist of all the
parameters of @var{frame}.
@end defun

@defun modify-frame-parameters frame alist
This function alters the parameters of frame @var{frame} based on the
elements of @var{alist}.  Each element of @var{alist} has the form
@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
parameter.  If you don't mention a parameter in @var{alist}, its value
doesn't change.
@end defun

@node Initial Parameters
@subsection Initial Frame Parameters

You can specify the parameters for the initial startup frame
by setting @code{initial-frame-alist} in your @file{.emacs} file.

@defvar initial-frame-alist
This variable's value is an alist of parameter values to when creating
the initial X window frame.
@end defvar

@ignore  @c Not yet working in XEmacs
If these parameters specify a separate minibuffer-only frame,
and you have not created one, XEmacs creates one for you.

@defvar minibuffer-frame-alist
This variable's value is an alist of parameter values to when creating
an initial minibuffer-only frame---if such a frame is needed, according
to the parameters for the main initial frame.
@end defvar
@end ignore

@node X Frame Parameters
@subsection 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:

@table @code
@item name
The name of the frame.

@item left
The screen position of the left edge, in pixels.

@item top
The screen position of the top edge, in pixels.

@item height
The height of the frame contents, in lines.  (This differs from FSF
Emacs, which measures the value in pixels.)

@item width
The width of the frame contents, in characters.  (This differs from FSF
Emacs, which measures the value in pixels.)

@item window-id
The number of the X window for the frame.

@item minibuffer
The minibuffer window for the frame, or @code{nil} if this frame has
no minibuffer.

@item cursor-color
The color for the cursor that shows point.

@item border-color
The color for the border of the frame.

@item border-width
The width in pixels of the window border.

@item internal-border-width
The distance in pixels between text and border.

@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.

@item inter-line-space
The space in pixels between adjacent lines of text. (Not currently
implemented.)

@item modeline
Whether the frame has a modeline. (Currently always @code{t}.)
@end table

@node Size And Position
@subsection Frame Size And Position
@cindex size of frame
@cindex frame size
@cindex display lines
@cindex display columns
@cindex resize redisplay
@cindex frame position
@cindex position of frame

  You can read or change the size and position of a frame using the
frame parameters @code{left}, @code{top}, @code{height} and
@code{width}.  When you create a frame, you must specify either both
size parameters or neither.  Likewise, you must specify either both
position parameters or neither.  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:

@defun set-frame-position frame xoffset yoffset
This function sets the position of the top left corner of
@var{frame}---to @var{xoffset} and @var{yoffset}.  These arguments are
measured in pixels, counting from the top left corner of the screen.  If
@var{xoffset} or @var{yoffset} is negative, it is interpreted relative
to the leftmost or bottommost position @var{frame} could occupy without
going off the frame.
@end defun

@defun frame-height &optional frame
@defunx frame-width &optional frame
These functions return the height and width of @var{frame}, measured in
lines and columns.  If you don't supply @var{frame}, they use the selected
frame.
@end defun

@defun frame-pixel-height &optional frame
@defunx frame-pixel-width &optional frame
These functions return the height and width of @var{frame}, measured in
pixels.  If you don't supply @var{frame}, they use the selected frame.
@end defun

@defun set-frame-size frame cols rows &optional pretend
This function sets the size of @var{frame}, measured in characters;
@var{cols} and @var{rows} specify the new width and height.  (If
@var{pretend} is non-nil, it means that redisplay should act as if
the frame's size is @var{cols} by @var{rows}, but the actual size
of the frame should not be changed.  You should not normally use
this option.)
@end defun

  You can also use the functions @code{set-frame-height} and
@code{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, @var{pretend},
which has the same purpose as the corresponding argument in
@code{set-frame-size}.)

@ignore  @c Not in XEmacs
@defun x-parse-geometry geom
@cindex geometry specification
The function @code{x-parse-geometry} converts a standard X windows
geometry string to an alist which you can use as part of the argument to
@code{x-create-frame}.

The alist describes which parameters were specified in @var{geom}, and
gives the values specified for them.  Each element looks like
@code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
values are @code{left}, @code{top}, @code{width}, and @code{height}.

@smallexample
(x-geometry "35x70+0-0")
     @result{} ((width . 35) (height . 70) (left . 0) (top . -1))
@end smallexample
@end defun
@end ignore

@node Frame Name
@subsection The Name of a Frame (As Opposed to Its Title)
@cindex frame name

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.

@defun frame-name &optional frame
This function returns the name of @var{frame}, which defaults to the
selected frame if not specified.  The name of a frame can also be
obtained from the frame's parameters.  @xref{Frame Parameters}.
@end defun

@defvar default-frame-name
This variable holds the default name to assign to newly-created frames.
This can be overridden by arguments to @code{x-create-frame}.  This
must be a string.
@end defvar

@node Deleting Frames
@section Deleting Frames
@cindex deletion of frames

Frames remain potentially visible until you explicitly @dfn{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.

@deffn Command delete-frame &optional frame
This function deletes the frame @var{frame}.  By default, @var{frame} is
the selected frame.
@end deffn

@defun frame-live-p frame
The function @code{frame-live-p} returns non-@code{nil} if the frame
@var{frame} has not been deleted.
@end defun

@node Finding All Frames
@section Finding All Frames

@defun frame-list
The function @code{frame-list} returns a list of all the frames that
have not been deleted.  It is analogous to @code{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.
@end defun

@defun device-frame-list &optional device
This function returns a list of all frames on @var{device}.  If
@var{device} is @code{nil}, the selected device will be used.
@end defun

@defun visible-frame-list &optional device
This function returns a list of just the currently visible frames.
If @var{device} is specified only frames on that device will be returned.
@end defun

@defun next-frame &optional frame minibuf
The function @code{next-frame} lets you cycle conveniently through all
the frames from an arbitrary starting point.  It returns the ``next''
frame after @var{frame} in the cycle.  If @var{frame} is omitted or
@code{nil}, it defaults to the selected frame.

The second argument, @var{minibuf}, says which frames to consider:

@table @asis
@item @code{nil}
Exclude minibuffer-only frames.
@item a window
Consider only the frames using that particular window as their
minibuffer.
@item the symbol @code{visible}
Include all visible frames.
@item @code{0}
Include all visible and iconified frames.
@item anything else
Consider all frames.
@end table
@end defun

@defun previous-frame &optional frame minibuf
Like @code{next-frame}, but cycles through all frames in the opposite
direction.
@end defun

@node Frames and Windows
@section Frames and Windows

All the non-minibuffer windows in a frame are arranged in a tree of
subdivisions; the root of this tree is available via the function
@code{frame-root-window}.  Each window is part of one and
only one frame; you can get the frame with @code{window-frame}.

@defun frame-root-window &optional frame
This returns the root window of frame @var{frame}.  @var{frame}
defaults to the selected frame if not specified.
@end defun

@defun window-frame &optional window
This function returns the frame that @var{window} is on.  @var{window}
defaults to the selected window if omitted.
@end defun

At any time, exactly one window on any frame is @dfn{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 @code{frame-selected-window}.

@defun frame-selected-window &optional frame
This function returns the window on @var{frame} which is selected
within @var{frame}.  @var{frame} defaults to the selected frame if not
specified.
@end defun

Conversely, selecting a window for XEmacs with @code{select-window} also
makes that window selected within its frame.  @xref{Selecting Windows}.

@node Minibuffers and Frames
@section 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 @code{minibuffer-window} (@pxref{Minibuffer Misc}).

Currently it is not possible for a frame not to have a minibuffer.  This
feature will appear in later versions of XEmacs.

However, you can also create a frame with no minibuffer (this is not
implemented as of 19.12, but will be in 19.13).  Such a frame must use
the minibuffer window of some other frame.  When you create the frame,
you can specify explicitly the frame on which to find the minibuffer to
use.  If you don't, then the minibuffer is found in the frame which is
the value of the variable @code{default-minibuffer-frame}.  Its value
should be a frame which does have a minibuffer.

@node Input Focus
@section Input Focus
@cindex input focus
@cindex selected frame

At any time, one frame in XEmacs is the @dfn{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.

@defun selected-frame &optional device
This function returns the selected frame on @var{device}.  If
@var{device} is not specified, the selected device will be used.  If no
frames exist on the device, @code{nil} is returned.
@end defun

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 @dfn{shift the focus} to various X windows, overriding the normal
behavior of the server.

@ignore  @c I decided we need not do this one.
Lisp programs can override the window manager and the user by forcing
the focus to a particular frame.

@c ??? This is not yet implemented properly.
@defun focus-frame frame
This function sets the input focus on frame @var{frame} until explicitly
overridden.  If @var{frame} is @code{nil}, it abolishes the explicit
focus, so that control of the focus returns to the window manager
program.
@end defun
@end ignore

Lisp programs can switch frames ``temporarily'' by calling
the function @code{select-frame}.  This does not override the window
manager; rather, it escapes from the window manager's control until
that control is somehow reasserted.

@defun select-frame frame
This function selects the frame @var{frame}.  Subsequent editing
commands apply to its selected window.  The selection of @var{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 @code{select-frame-hook} or
@code{deselect-frame-hook} to be run, until the next time that XEmacs is
waiting for an event.
@end defun

@node Visibility of Frames
@section Visibility of Frames
@cindex visible frame
@cindex invisible frame
@cindex iconified frame
@cindex frame visibility

A frame may be @dfn{visible}, @dfn{invisible}, or @dfn{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 in the screen, not even as an icon.

@defun make-frame-visible &optional frame
This function makes frame @var{frame} visible.
@end defun

@defun make-frame-invisible &optional frame
This function makes frame @var{frame} invisible.
@end defun

@defun iconify-frame &optional frame
This function iconifies frame @var{frame}.
@end defun

@defun deiconify-frame &optional frame
This function de-iconifies frame @var{frame}.  Under X, this is
equivalent to @code{make-frame-visible}.
@end defun

@defun frame-visible-p frame
This returns whether @var{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.
@end defun

@defun frame-iconified-p frame
This returns whether @var{frame} is iconified.  Not all window managers
use icons; some merely unmap the window, so this function is not the
inverse of @code{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 @code{frame-visible-p}.)
@end defun

@defun frame-totally-visible-p frame
This returns whether @var{frame} is not obscured by any other X
windows.  This function always returns @code{y} on TTY frames.
@end defun

@ignore  @c Not in XEmacs.
  The visibility status of a frame is also available as a frame
parameter.  You can read or change it as such.  @xref{X Frame
Parameters}.
@end ignore

@node Raising and Lowering
@section 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.

@cindex raising a frame
@cindex lowering a frame
A window's place in this ordering is not fixed; in fact, users tend to
change the order frequently.  @dfn{Raising} a window means moving it
``up'', to the top of the stack.  @dfn{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:

@defun raise-frame &optional frame
This function raises frame @var{frame}.
@end defun

@defun lower-frame &optional frame
This function lowers frame @var{frame}.
@end defun

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 @code{auto-raise} and @code{auto-lower}
frame parameters.)

@defvar auto-raise-frame
This variable's value is @code{t} if frames will be raised to the top
when selected.
@end defvar

@defvar auto-lower-frame
This variable's value is @code{t} if frames will be lowered to the bottom
when no longer selected.
@end defvar

Auto-raising and auto-lowering is implemented through functions attached
to @code{select-frame-hook} and @code{deselect-frame-hook}
(@pxref{Frame Hooks}).  Under normal circumstances, you should not call
these functions directly.

@defun default-select-frame-hook
This hook function implements the @code{auto-raise-frame} variable; it is
for use as the value of @code{select-frame-hook}.
@end defun

@defun default-deselect-frame-hook
This hook function implements the @code{auto-lower-frame} variable; it is
for use as the value of @code{deselect-frame-hook}.
@end defun

@ignore  @c Not in XEmacs.
@node Frame Configurations
@section Frame Configurations
@cindex frame configuration

@defun current-frame-configuration
This function returns a @dfn{frame configuration} list which describes
the current arrangement of frames, all their properties, and the window
configuration of each one.
@end defun

@defun set-frame-configuration configuration
This function restores the state of frames described in
@var{configuration}.
@end defun
@end ignore

@node Frame Titles and Icons
@section Changing the Way a Frame's Title or Icon Appears
@cindex frame title
@cindex icon pixmap

Under the X Window System, the title of the X window corresponding to a
frame and the title and pixmap of the corresponding icon can be set
from E-Lisp.

@defvar frame-title-format
This variable controls how the title of the X window corresponding to a
frame appears.  The format is the same as in @code{modeline-format}.
@xref{Modeline Format}.
@end defvar

@defvar frame-icon-title-format
This variable is similar to @code{frame-title-format} but controls the title
of a frame's icon, when the frame is iconified.
@end defvar

@defun 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
@code{make-image-instance}), a glyph object (as returned by
@code{make-glyph}), or @code{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}.
@end defun

@node Frame Hooks
@section Hooks for Customizing Frame Behavior
@cindex frame hooks

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

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

@defvar 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.
@end defvar

@defvar select-frame-hook
This is a normal hook that is run just after a frame is selected.  The
function @code{default-select-frame-hook}, which implements auto-raising
(@pxref{Raising and Lowering}), is normally attached to this hook.

Note that calling @code{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.
@end defvar

@defvar deselect-frame-hook
This is a normal hook that is run just before a frame is deselected
(and another frame is selected).  The function
@code{default-deselect-frame-hook}, which implements auto-lowering
(@pxref{Raising and Lowering}), is normally attached to this hook.
@end defvar

@defvar 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.
@end defvar

@defvar 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.
@end defvar
