Child frames are objects halfway between windows (see Windows) and “normal” frames. Like windows, they are attached to an owning frame. Unlike windows, they may overlap each other—changing the size or position of one child frame does not change the size or position of any of its sibling child frames.
By design, operations to make or modify child frames are implemented with the help of frame parameters (see Frame Parameters) without any specialized functions or customizable variables. Note that child frames are meaningful on graphical terminals only.
To create a new child frame or to convert a normal frame into a child
frame, set that frame’s parent-frame parameter (see Frame Interaction Parameters) to that of an already existing frame. The
frame specified by that parameter will then be the frame’s parent frame
as long as the parameter is not changed or reset. Technically, this
makes the child frame’s window-system window a child window of the
parent frame’s window-system window.
The parent-frame parameter can be changed at any time.
Setting it to another frame reparents the child frame. Setting
it to another child frame makes the frame a nested child frame.
Setting it to nil restores the frame’s status as a top-level
frame—a frame whose window-system window is a child of its display’s
root window.22
Since child frames can be arbitrarily nested, a frame can be both a child and a parent frame. Also, the relative roles of child and parent frame may be reversed at any time (though it’s usually a good idea to keep the size of a child frame sufficiently smaller than that of its parent). An error will be signaled for the attempt to make a frame an ancestor of itself.
Most window-systems clip a child frame at the native edges
(see Frame Geometry) of its parent frame—everything outside these
edges is usually invisible. A child frame’s left and top
parameters specify a position relative to the top-left corner of its
parent’s native frame. When the parent frame is resized, this position
remains conceptually unaltered.
NS builds do not clip child frames at the parent frame’s edges, allowing them to be positioned so they do not obscure the parent frame while still being visible themselves.
Usually, moving a parent frame moves along all its child frames and
their descendants as well, keeping their relative positions unaltered.
Note that the hook move-frame-functions (see Frame Position)
is run for a child frame only when the position of the child frame
relative to its parent frame changes.
When a parent frame is resized, its child frames conceptually retain
their previous sizes and their positions relative to the left upper
corner of the parent. This means that a child frame may become
(partially) invisible when its parent frame shrinks. The parameter
keep-ratio (see Frame Interaction Parameters) can be used to
resize and reposition a child frame proportionally whenever its parent
frame is resized. This may avoid obscuring parts of a frame when its
parent frame is shrunk.
A visible child frame always appears on top of its parent frame thus obscuring parts of it, except on NS builds where it may be positioned beneath the parent. This is comparable to the window-system window of a top-level frame which also always appears on top of its parent window—the desktop’s root window. When a parent frame is iconified or made invisible (see Visibility of Frames), its child frames are made invisible. When a parent frame is deiconified or made visible, its child frames are made visible.
When a parent frame is about to be deleted (see Deleting Frames), its child frames are recursively deleted before it. There is one exception to this rule: When the child frame serves as a surrogate minibuffer frame (see Minibuffers and Frames) for another frame, it is retained until the parent frame has been deleted. If, at this time, no remaining frame uses the child frame as its minibuffer frame, Emacs will try to delete the child frame too. If that deletion fails for whatever reason, the child frame is made a top-level frame.
Whether a child frame can have a menu or tool bar is window-system or window manager dependent. Most window-systems explicitly disallow menu bars for child frames. It seems advisable to disable both, menu and tool bars, via the frame’s initial parameters settings.
Usually, child frames do not exhibit window manager decorations like a title bar or external borders (see Frame Geometry). When the child frame does not show a menu or tool bar, any other of the frame’s borders (see Layout Parameters) can be used instead of the external borders.
In particular, under X (but not when building with GTK+), the frame’s
outer border can be used. On MS-Windows, specifying a non-zero outer
border width will show a one-pixel wide external border. Under all
window-systems, the internal border can be used. In either case, it’s
advisable to disable a child frame’s window manager decorations with the
undecorated frame parameter (see Window Management Parameters).
To resize or move an undecorated child frame with the mouse, special
frame parameters (see Mouse Dragging Parameters) have to be used.
The internal border of a child frame, if present, can be used to resize
the frame with the mouse, provided that frame has a non-nil
drag-internal-border parameter. If set, the snap-width
parameter indicates the number of pixels where the frame snaps at
the respective edge or corner of its parent frame.
There are two ways to drag an entire child frame with the mouse: The
drag-with-mode-line parameter, if non-nil, allows to drag
a frame without minibuffer window (see Minibuffer Windows) via the
mode line area of its bottommost window. The
drag-with-header-line parameter, if non-nil, allows to
drag the frame via the header line area of its topmost window.
In order to give a child frame a draggable header or mode line, the
window parameters mode-line-format and header-line-format
are handy (see Window Parameters). These allow to remove an
unwanted mode line (when drag-with-header-line is chosen) and to
remove mouse-sensitive areas which might interfere with frame dragging.
When the user drags a frame with a mouse and overshoots, it’s easy
to drag a frame out of the screen area of its parent. Retrieving such
a frame can be hairy once the mouse button has been released. To
prevent such a situation, it is advisable to set the frame’s
top-visible or bottom-visible parameter (see Mouse Dragging Parameters).
Set the top-visible parameter of a child frame to a number
when you intend to allow the user dragging that frame by its header
line. Setting top-visible to a number inhibits dragging the
top edge of the child frame above the top edge of its parent. Set the
bottom-visible parameter to a number when you intend to drag
that frame via its mode line; this inhibits dragging the bottom edge
of the child frame beneath the bottom edge of its parent. In either
case, that number also specifies width and height (in pixels) of the
area of the child frame that remains visible during dragging.
When a child frame is used for displaying a buffer via
display-buffer-in-child-frame (see Action Functions for Buffer Display), the frame’s auto-hide-function parameter
(see Frame Interaction Parameters) can be set to a function, in
order to appropriately deal with the frame when the window displaying
the buffer shall be quit.
When a child frame is used during minibuffer interaction, for example,
to display completions in a separate window, the minibuffer-exit
parameter (see Frame Interaction Parameters) is useful in order to
deal with the frame when the minibuffer is exited.
The behavior of child frames deviates from that of top-level frames in a number of other ways as well. Here we sketch a few of them:
iconify-frame on a child frame will try to iconify the top-level
frame corresponding to that child frame instead. To obtain a different
behavior, users may customize the option iconify-child-frame
described below.
z-group (see Position Parameters)
of a child frame changes only the stacking order of child frames with
the same parent.
mouse-autoselect-window can
help in this regard (see Mouse Window Auto-selection).
The following two functions can be useful when working with child and parent frames:
This function returns the parent frame of frame. The parent frame of frame is the Emacs frame whose window-system window is the parent window of frame’s window-system window. If such a frame exists, frame is considered a child frame of that frame.
This function returns nil if frame has no parent frame.
This functions returns non-nil if ancestor is an ancestor
of descendant. ancestor is an ancestor of descendant
when it is either descendant’s parent frame or it is an ancestor
of descendant’s parent frame. Both, ancestor and
descendant must specify live frames.
Note also the function window-largest-empty-rectangle
(see Coordinates and Windows) which can be used to inscribe a child
frame in the largest empty area of an existing window. This can be
useful to avoid that a child frame obscures any text shown in that
window.
Customizing the following option can be useful to tweak the behavior of
iconify-frame for child frames.
This option tells Emacs how to proceed when it is asked to iconify a
child frame. If it is nil, iconify-frame will do nothing
when invoked on a child frame. If it is iconify-top-level, Emacs
will try to iconify the top-level frame that is the ancestor of this
child frame instead. If it is make-invisible, Emacs will try to
make this child frame invisible instead of iconifying it.
Any other value means to try iconifying the child frame. Since such an attempt may not be honored by all window managers and can even lead to making the child frame unresponsive to user actions, the default is to iconify the top level frame instead.
On Haiku, child frames are only visible when a parent frame is active, owing to a limitation of the Haiku windowing system. Owing to the same limitation, child frames are only guaranteed to appear above their top-level parent; that is to say, the top-most frame in the hierarchy, which does not have a parent frame.