[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 7cc613d: Describe recent frame and window changes i
|
From: |
Martin Rudalics |
|
Subject: |
[Emacs-diffs] master 7cc613d: Describe recent frame and window changes in manuals |
|
Date: |
Thu, 13 Apr 2017 11:46:24 -0400 (EDT) |
branch: master
commit 7cc613dc68b8c388a7ccd8f79e37a641ad05312c
Author: Martin Rudalics <address@hidden>
Commit: Martin Rudalics <address@hidden>
Describe recent frame and window changes in manuals
* doc/emacs/emacs.texi (Top):
* doc/emacs/cmdargs.texi (Borders X): Clearly separate the terms
"outer border" (for the X border which can be set from within
Emacs) and "external border" (for the border which is added by
the window manager).
* doc/lispref/display.texi (Tooltips): Clarify slightly.
* doc/lispref/elisp.texi (Top): Update node and section names.
* doc/lispref/frames.texi (Frames): Describe difference between
top-level and child frames.
(Frame Layout): Describe outer border. Add more details about
how Emacs obtains the outer size and position of a frame and
about menu bar/tool bar wrapping. Add references to new frame
parameters.
(Size and Position): Remove subsection.
(Frame Position): New subsection excerpted from the earlier Size
and Position subsection. Clarify positioning concepts and
some of their shortcomings. Describe `move-frame-functions'.
(Frame Size): New subsection excerpted from the earlier Size
and Position subsection. Describe how to track frame size
changes and the new function `frame-size-changed-p'.
(Position Parameters): Describe child frame positioning. Warn
about negative offsets. Describe 'z-group' parameter.
(Size Parameters): Describe 'text-pixels' specification
facility and new 'min-width' and 'min-height' parameters.
(Layout Parameters): Clarify description of 'tool-bar-lines' and
'menu-bar-lines' parameters.
(Frame Interaction Parameters): New subsubsection describing
'parent-frame', 'delete-before', 'mouse-wheel-frame' and
'no-other-frame' parameters.
(Management Parameters): Describe 'skip-taskbar',
'no-focus-on-map', 'no-accept-focus', 'undecorated' and
'override-redirect' parameters.
(Deleting Frames): Describe handling of 'delete-before'
parameter and child frames for `delete-frame' and
`delete-other-frames'.
(Finding All Frames): Describe `frame-list-z-order' and handling
of 'no-other-frame' parameter by `next-frame'.
(Minibuffers and Frames): Minor clarifications.
(Input Focus): Document `x-focus-frame'. Clarify descriptions
of `focus-in-hook', `focus-out-hook' and `focus-follows-mouse'.
(Visibility of Frames): Describe mapping and how the visibility
of a parent frame affects that of its child frames.
(Raising and Lowering): Describe restacking of frames and
z-groups.
(Child Frames): New section.
* doc/lispref/windows.texi (Selecting Windows): Describe
additional semantics of NORECORD argument of `select-window' and
how `buffer-list-update-hook' can emulate a "select window
hook".
(Mouse Window Auto-selection): New section.
---
doc/emacs/cmdargs.texi | 26 +-
doc/emacs/emacs.texi | 2 +-
doc/lispref/display.texi | 26 +-
doc/lispref/elisp.texi | 12 +-
doc/lispref/frames.texi | 1091 ++++++++++++++++++++++++++++++++++++----------
doc/lispref/windows.texi | 122 +++++-
6 files changed, 997 insertions(+), 282 deletions(-)
diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index 6c86670..721a2ce 100644
--- a/doc/emacs/cmdargs.texi
+++ b/doc/emacs/cmdargs.texi
@@ -71,7 +71,7 @@ arguments.)
* Font X:: Choosing a font for text, under X.
* Colors X:: Choosing display colors.
* Window Size X:: Start-up window size, under X.
-* Borders X:: Internal and external borders, under X.
+* Borders X:: Internal and outer borders, under X.
* Title X:: Specifying the initial frame's title.
* Icons X:: Choosing what sort of icon to use, under X.
* Misc X:: Other display options.
@@ -1053,15 +1053,15 @@ program-specified and user-specified positions. If
these are set,
Emacs fails to position the window correctly.
@node Borders X
address@hidden Internal and External Borders
address@hidden Internal and Outer Borders
@cindex borders (X Window System)
- An Emacs frame has an internal border and an external border. The
+ An Emacs frame has an internal border and an outer border. The
internal border is an extra strip of the background color around the
-text portion of the frame. Emacs itself draws the internal border.
-The external border is added by the window manager outside the frame;
-depending on the window manager you use, it may contain various boxes
-you can click on to move or iconify the window.
+text portion of the frame. Emacs itself draws the internal border. The
+outer border is drawn by X outside the tool and menu bars of the frame.
+There is also an external border which is drawn by the window manager.
+The size of the external border cannot be set from within Emacs.
@table @samp
@item -ib @var{width}
@@ -1069,15 +1069,15 @@ you can click on to move or iconify the window.
@itemx address@hidden
@opindex --internal-border
@cindex internal border width, command-line argument
-Specify @var{width} as the width of the internal border (between the text
-and the main border), in pixels.
+Specify @var{width} as the width of the internal border (around the
+frame's text area), in pixels.
@item -bw @var{width}
@opindex -bw
@itemx address@hidden
@opindex --border-width
@cindex main border width, command-line argument
-Specify @var{width} as the width of the main border, in pixels.
+Specify @var{width} as the width of the outer border, in pixels.
@end table
When you specify the size of the frame, that does not count the
@@ -1086,9 +1086,9 @@ external border.
Use the @samp{-ib @var{n}} option to specify an internal border
@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to
-specify the width of the external border (though the window manager may
-not pay attention to what you specify). The default width of the
-external border is 2.
+specify the width of the outer border (though the window manager may not
+pay attention to what you specify). The default width of the outer
+border is 2.
@node Title X
@appendixsec Frame Titles
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index a6f2896..599b373 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -1198,7 +1198,7 @@ Command Line Arguments for Emacs Invocation
* Font X:: Choosing a font for text, under X.
* Colors X:: Choosing display colors.
* Window Size X:: Start-up window size, under X.
-* Borders X:: Internal and external borders, under X.
+* Borders X:: Internal and outer borders, under X.
* Title X:: Specifying the initial frame's title.
* Icons X:: Choosing what sort of icon to use, under X.
* Misc X:: Other display options.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 57dd16d..7a6a216 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -7190,20 +7190,22 @@ changing the value of the variable
@code{x-gtk-use-system-tooltips} to
@code{nil}. The rest of this subsection describes how to control
non-GTK+ tooltips, which are presented by Emacs itself.
-Since tooltips are special frames, they have their frame parameters
-(@pxref{Frame Parameters}). Unlike other frames, the frame parameters
-for tooltips are stored in a special variable.
address@hidden tooltip frames
+Tooltips are displayed in special frames called tooltip frames, which
+have their own frame parameters (@pxref{Frame Parameters}). Unlike
+other frames, the default parameters for tooltip frames are stored in a
+special variable.
@defvar tooltip-frame-parameters
-This customizable option holds the frame parameters used for
-displaying tooltips. Any font and color parameters are ignored, and
-the corresponding attributes of the @code{tooltip} face are used
-instead. If @code{left} or @code{top} parameters are included, they
-are used as absolute frame-relative coordinates where the tooltip
-should be shown. (Mouse-relative position of the tooltip can be
-customized using the variables described in @ref{Tooltips,,, emacs,
-The GNU Emacs Manual}.) Note that the @code{left} and @code{top}
-parameters, if present, override the values of mouse-relative offsets.
+This customizable option holds the default frame parameters used for
+displaying tooltips. Any font and color parameters are ignored, and the
+corresponding attributes of the @code{tooltip} face are used instead.
+If @code{left} or @code{top} parameters are included, they are used as
+absolute frame-relative coordinates where the tooltip should be shown.
+(Mouse-relative position of the tooltip can be customized using the
+variables described in @ref{Tooltips,,, emacs, The GNU Emacs Manual}.)
+Note that the @code{left} and @code{top} parameters, if present,
+override the values of mouse-relative offsets.
@end defvar
@vindex address@hidden face}
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index bff3112..7cc91a8 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1062,6 +1062,7 @@ Windows
* Vertical Scrolling:: Moving the contents up and down on the window.
* Horizontal Scrolling:: Moving the contents sideways on the window.
* Coordinates and Windows:: Converting coordinates to windows.
+* Mouse Window Auto-selection:: Automatically selecting windows with the mouse.
* Window Configurations:: Saving and restoring the state of the screen.
* Window Parameters:: Associating additional information with windows.
* Window Hooks:: Hooks for scrolling, window size changes,
@@ -1089,16 +1090,16 @@ Frames
* Minibuffers and Frames:: How a frame finds the minibuffer to use.
* Input Focus:: Specifying the selected frame.
* Visibility of Frames:: Frames may be visible or invisible, or icons.
-* Raising and Lowering:: Raising a frame makes it hide other windows;
- lowering it makes the others hide it.
+* Raising and Lowering:: Raising, Lowering and Restacking Frames.
* Frame Configurations:: Saving the state of all frames.
+* Child Frames:: Making a frame the child of another.
* Mouse Tracking:: Getting events that say when the mouse moves.
* Mouse Position:: Asking where the mouse is, or moving it.
* Pop-Up Menus:: Displaying a menu for the user to select from.
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shape:: Specifying the shape of the mouse pointer.
* Window System Selections::Transferring text to and from other X clients.
-* Drag and Drop:: Internals of Drag-and-Drop implementation.
+* Drag and Drop:: Internals of Drag-and-Drop implementation.
* Color Names:: Getting the definitions of color names.
* Text Terminal Colors:: Defining colors for text terminals.
* Resources:: Getting resource values from the server.
@@ -1108,7 +1109,8 @@ Frame Geometry
* Frame Layout:: Basic layout of frames.
* Frame Font:: The default font of a frame and how to set it.
-* Size and Position:: Changing the size and position of a frame.
+* Frame Position:: The position of a frame on its display.
+* Frame Size:: Specifying and retrieving a frame's size.
* Implied Frame Resizing:: Implied resizing of frames and how to prevent it.
Frame Parameters
@@ -1126,6 +1128,8 @@ Window Frame Parameters
* Layout Parameters:: Size of parts of the frame, and
enabling or disabling some parts.
* Buffer Parameters:: Which buffers have been or should be shown.
+* Frame Interaction Parameters:: Parameters for interacting with other
+ frames.
* Management Parameters:: Communicating with the window manager.
* Cursor Parameters:: Controlling the cursor appearance.
* Font and Color Parameters:: Fonts and colors for the frame text.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 68aa40f..2fac802 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -77,6 +77,13 @@ displayed on that terminal; the list of possible values is
the same as
for @code{framep} above.
@end defun
address@hidden top-level frame
+On a graphical terminal we distinguish two types of frames: A normal
address@hidden frame} is a frame whose window-system window is a child
+of the window-system's root window for that terminal. A child frame is
+a frame whose window-system window is the child of the window-system
+window of another Emacs frame. @xref{Child Frames}.
+
@menu
* Creating Frames:: Creating additional frames.
* Multiple Terminals:: Displaying on several different devices.
@@ -89,9 +96,9 @@ for @code{framep} above.
* Minibuffers and Frames:: How a frame finds the minibuffer to use.
* Input Focus:: Specifying the selected frame.
* Visibility of Frames:: Frames may be visible or invisible, or icons.
-* Raising and Lowering:: Raising a frame makes it hide other windows;
- lowering it makes the others hide it.
+* Raising and Lowering:: Raising, Lowering and Restacking Frames.
* Frame Configurations:: Saving the state of all frames.
+* Child Frames:: Making a frame the child of another.
* Mouse Tracking:: Getting events that say when the mouse moves.
* Mouse Position:: Asking where the mouse is, or moving it.
* Pop-Up Menus:: Displaying a menu for the user to select from.
@@ -436,7 +443,8 @@ has to specify a live frame (@pxref{Deleting Frames}). If
omitted or
@menu
* Frame Layout:: Basic layout of frames.
* Frame Font:: The default font of a frame and how to set it.
-* Size and Position:: Changing the size and position of a frame.
+* Frame Position:: The position of a frame on its display.
+* Frame Size:: Specifying and retrieving a frame's size.
* Implied Frame Resizing:: Implied resizing of frames and how to prevent it.
@end menu
@@ -446,14 +454,16 @@ has to specify a live frame (@pxref{Deleting Frames}).
If omitted or
@cindex frame layout
@cindex layout of frame
-The drawing below sketches the layout of a frame on a graphical
-terminal:
+A visible frame occupies a rectangular area on its terminal's display.
+This area may contain a number of nested rectangles, each serving a
+different purpose. The drawing below sketches the layout of a frame on
+a graphical terminal:
@smallexample
@group
<------------ Outer Frame Width ----------->
- ___________________________________________
- ^(0) ___________ External Border __________ |
+ ____________________________________________
+ ^(0) ________ External/Outer Border _______ |
| | |_____________ Title Bar ______________| |
| | (1)_____________ Menu Bar ______________| | ^
| | (2)_____________ Tool Bar ______________| | ^
@@ -468,14 +478,14 @@ Height | | | Height | | |
Height
| | | | | | | | |
| | | |___v______________________________| | | |
| | |___________ Internal Border __________| | v
- v |______________ External Border _____________|
+ v |___________ External/Outer Border __________|
<-------- Native Frame Width -------->
@end group
@end smallexample
In practice not all of the areas shown in the drawing will or may be
-present. The meaning of these areas is:
+present. The meaning of these areas is described below.
@table @samp
@item Outer Frame
@@ -483,50 +493,100 @@ present. The meaning of these areas is:
@cindex outer edges
@cindex outer width
@cindex outer height
address@hidden outer size
The @dfn{outer frame} is a rectangle comprising all areas shown in the
drawing. The edges of that rectangle are called the @dfn{outer edges}
-of the frame. The @dfn{outer width} and @dfn{outer height} of the frame
-specify the size of that rectangle.
+of the frame. Together, the @dfn{outer width} and @dfn{outer height} of
+the frame specify the @dfn{outer size} of that rectangle.
+
+Knowing the outer size of a frame is useful for fitting a frame into the
+working area of its display (@pxref{Multiple Terminals}) or for placing
+two frames adjacent to each other on the screen. Usually, the outer
+size of a frame is available only after the frame has been mapped (made
+visible, @pxref{Visibility of Frames}) at least once. For the initial
+frame or a frame that has not been created yet, the outer size can be
+estimated only or must be calculated from the window-system's or window
+manager defaults. One workaround is to obtain the differences of the
+outer and native (see below) sizes of a mapped frame and use them for
+calculating the outer size of the new frame.
@cindex outer position
The upper left corner of the outer frame (indicated by @samp{(0)} in the
-drawing above) is the @dfn{outer position} or the frame. It is
-specified by and settable via the @code{left} and @code{top} frame
-parameters (@pxref{Position Parameters}) as well as the functions
address@hidden and @code{set-frame-position} (@pxref{Size and
-Position}).
+drawing above) is the @dfn{outer position} of the frame. The outer
+position of a graphical frame is also referred to as ``the position'' of
+the frame because it usually remains unchanged on its display whenever
+the frame is resized or its layout is changed.
+
+The outer position is specified by and can be set via the @code{left}
+and @code{top} frame parameters (@pxref{Position Parameters}). For a
+normal, top-level frame these parameters usually represent its absolute
+position (see below) with respect to its display's origin. For a child
+frame (@pxref{Child Frames}) these parameters represent its position
+relative to the native position (see below) of its parent frame. For
+frames on text terminals the values of these parameters are meaningless
+and always zero.
@item External Border
@cindex external border
The @dfn{external border} is part of the decorations supplied by the
-window manager. It's typically used for resizing the frame with the
-mouse. The external border is normally not shown on ``fullboth'' and
-maximized frames (@pxref{Size Parameters}) and doesn't exist for text
-terminal frames.
-
- The external border should not be confused with the @dfn{outer
-border} specified by the @code{border-width} frame parameter
-(@pxref{Layout Parameters}). Since the outer border is usually ignored
-on most platforms it is not covered here.
+window manager. It is typically used for resizing the frame with the
+mouse and is therefore not shown on ``fullboth'' and maximized frames
+(@pxref{Size Parameters}). Its width is determined by the window
+manager and cannot be changed by Emacs' functions.
+
+External borders don't exist on text terminal frames. For graphical
+frames, their display can be suppressed by setting the
address@hidden or @code{undecorated} frame parameter
+(@pxref{Management Parameters}).
+
address@hidden Outer Border
address@hidden outer border
+The @dfn{outer border} is a separate border whose width can be specified
+with the @code{border-width} frame parameter (@pxref{Layout
+Parameters}). In practice, either the external or the outer border of a
+frame are displayed but never both at the same time. Usually, the outer
+border is shown only for special frames that are not (fully) controlled
+by the window manager like tooltip frames (@pxref{Tooltips}), child
+frames (@pxref{Child Frames}) and @code{undecorated} or
address@hidden frames (@pxref{Management Parameters}).
+
+Outer borders are never shown on text terminal frames and on frames
+generated by GTK+ routines. On Windows, the outer border is emulated
+with the help of a one pixel wide external border. Non-toolkit builds
+allow to change the color of the outer border by setting the
address@hidden frame parameter (@pxref{Layout Parameters}).
@item Title Bar
@cindex title bar
The @dfn{title bar} is also part of the window manager's decorations and
typically displays the title of the frame (@pxref{Frame Titles}) as well
-as buttons for minimizing, maximizing and deleting the frame. The title
-bar is usually not displayed on fullboth (@pxref{Size Parameters})
-or tooltip frames. Title bars don't exist for text terminal frames.
+as buttons for minimizing, maximizing and deleting the frame. It can be
+also used for dragging the frame with the mouse. The title bar is
+usually not displayed for fullboth (@pxref{Size Parameters}), tooltip
+(@pxref{Tooltips}) and child frames (@pxref{Child Frames}) and doesn't
+exist for terminal frames. Display of the title bar can be suppressed
+by setting the @code{override-redirect} or the @code{undecorated} frame
+parameters (@pxref{Management Parameters}).
@item Menu Bar
@cindex internal menu bar
@cindex external menu bar
The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs
-itself) or external (drawn by a toolkit). Most builds (GTK+, Lucid,
+itself) or external (drawn by the toolkit). Most builds (GTK+, Lucid,
Motif and Windows) rely on an external menu bar. NS also uses an
external menu bar which, however, is not part of the outer frame.
Non-toolkit builds can provide an internal menu bar. On text terminal
frames, the menu bar is part of the frame's root window (@pxref{Windows
-and Frames}).
+and Frames}). As a rule, menu bars are never shown on child frames
+(@pxref{Child Frames}). Display of the menu bar can be suppressed by
+setting the @code{menu-bar-lines} parameter (@pxref{Layout Parameters})
+to zero.
+
+It depends on the toolkit whether to wrap or truncate the menu bar
+whenever it becomes too long to fit on its frame. Usually, only Motif
+and Windows builds can wrap the menu bar. When they (un-)wrap the menu
+bar, they try to keep the outer height of the frame unchanged, so the
+native height of the frame (see below) will change instead.
@item Tool Bar
@cindex internal tool bar
@@ -536,21 +596,39 @@ internal (drawn by Emacs itself) or external (drawn by a
toolkit). The
GTK+ and NS builds have the tool bar drawn by the toolkit. The
remaining builds use internal tool bars. With GTK+ the tool bar can be
located on either side of the frame, immediately outside the internal
-border, see below.
+border, see below. Tool bars are usually not shown for child frames
+(@pxref{Child Frames}). Display of the tool bar can be suppressed by
+setting the @code{tool-bar-lines} parameter (@pxref{Layout
+Parameters}) to zero.
+
+If the variable @code{auto-resize-tool-bars} is address@hidden, Emacs
+wraps the internal tool bar when it becomes too long for its frame. If
+and when Emacs (un-)wraps the internal tool bar, it by default keeps the
+outer height of the frame unchanged, so the native height of the frame
+(see below) will change instead. Emacs built with GTK+, on the other
+hand, never wraps the tool bar but may automatically increase the outer
+width of a frame in order to accommodate an overlong tool bar.
@item Native Frame
@cindex native frame
@cindex native edges
@cindex native width
@cindex native height
address@hidden display area
address@hidden native size
The @dfn{native frame} is a rectangle located entirely within the outer
-frame. It excludes the areas occupied by the external border, the title
-bar and any external menu or external tool bar. The area enclosed by
-the native frame is sometimes also referred to as the @dfn{display area}
-of the frame. The edges of the native frame are called the @dfn{native
-edges} of the frame. The @dfn{native width} and @dfn{native height} of
-the frame specify the size of the rectangle.
+frame. It excludes the areas occupied by an external or outer border,
+the title bar and any external menu or tool bar. The edges of the
+native frame are called the @dfn{native edges} of the frame. Together,
+the @dfn{native width} and @dfn{native height} of a frame specify the
address@hidden size} of the frame.
+
+The native size of a frame is the size Emacs passes to the window-system
+or window manager when creating or resizing the frame from within Emacs.
+It is also the size Emacs receives from the window-system or window
+manager whenever these resize the frame's window-system window, for
+example, after maximizing the frame by clicking on the corresponding
+button in the title bar or when dragging its external border with the
+mouse.
@cindex native position
The top left corner of the native frame specifies the @dfn{native
@@ -565,30 +643,42 @@ position for the various builds:
@item (3) GTK+ and NS frames
@end itemize
-Accordingly, the native height of a frame includes the height of the
+Accordingly, the native height of a frame may include the height of the
tool bar but not that of the menu bar (Lucid, Motif, Windows) or those
of the menu bar and the tool bar (non-toolkit and text terminal frames).
-The native position of a frame is the reference position of functions
+The native position of a frame is the reference position for functions
that set or return the current position of the mouse (@pxref{Mouse
Position}) and for functions dealing with the position of windows like
@code{window-edges}, @code{window-at} or @code{coordinates-in-window-p}
-(@pxref{Coordinates and Windows}).
+(@pxref{Coordinates and Windows}). It also specifies the (0, 0) origin
+for locating and positioning child frames within this frame
+(@pxref{Child Frames}).
+
+Note also that the native position of a frame usually remains unaltered
+on its display when removing or adding the window manager decorations by
+changing the frame's @code{override-redirect} or @code{undecorated}
+parameter (@pxref{Management Parameters}).
@item Internal Border
-The internal border (@pxref{Layout Parameters}) is a border drawn by
-Emacs around the inner frame (see below).
+The internal border is a border drawn by Emacs around the inner frame
+(see below). Its width is specified by the @code{internal-border-width}
+frame parameter (@pxref{Layout Parameters}). Its color is specified by
+the background of the @code{internal-border} face.
@item Inner Frame
@cindex inner frame
@cindex inner edges
@cindex inner width
@cindex inner height
address@hidden inner size
address@hidden display area
The @dfn{inner frame} is the rectangle reserved for the frame's windows.
It's enclosed by the internal border which, however, is not part of the
inner frame. Its edges are called the @dfn{inner edges} of the frame.
-The @dfn{inner width} and @dfn{inner height} specify the size of the
-rectangle.
+The @dfn{inner width} and @dfn{inner height} specify the @dfn{inner
+size} of the rectangle. The inner frame is sometimes also referred to
+as the @dfn{display area} of the frame.
@cindex minibuffer-less frame
@cindex minibuffer-only frame
@@ -603,22 +693,39 @@ configurations.
@item Text Area
@cindex text area
-The @dfn{text area} of a frame is a somewhat fictitious area located
-entirely within the native frame. It can be obtained by removing from
-the native frame any internal borders, one vertical and one horizontal
-scroll bar, and one left and one right fringe as specified for this
-frame, see @ref{Layout Parameters}.
+The @dfn{text area} of a frame is a somewhat fictitious area that can be
+embedded in the native frame. Its position is unspecified. Its width
+can be obtained by removing from that of the native width the widths of
+the internal border, one vertical scroll bar, and one left and one right
+fringe as specified for this frame, see @ref{Layout Parameters}. Its
+height can be obtained by removing from that of the native height the
+widths of the internal border and the heights of the frame's internal
+menu and tool bars and one horizontal scroll bar as specified for this
+frame.
@end table
@cindex absolute position
-The @dfn{absolute position} of a frame or its edges is usually given in
-terms of pixels counted from an origin at position (0, 0) of the frame's
-display. Note that with multiple monitors the origin does not
-necessarily coincide with the top left corner of the entire usable
-display area. Hence the absolute outer position of a frame or the
-absolute positions of the edges of the outer, native or inner frame can
-be negative in such an environment even when that frame is completely
-visible.
address@hidden absolute frame position
address@hidden absolute edges
address@hidden absolute frame edges
address@hidden display origin
address@hidden origin of display
+The @dfn{absolute position} of a frame is given as a pair (X, Y) of
+horizontal and vertical pixel offsets relative to an origin (0, 0) of
+the frame's display. Correspondingly, the @dfn{absolute edges} of a
+frame are given as pixel offsets from that origin.
+
+ Note that with multiple monitors the origin of the display does not
+necessarily coincide with the top-left corner of the entire usable
+display area of the terminal. Hence the absolute position of a frame
+can be negative in such an environment even when that frame is
+completely visible.
+
+ By convention, vertical offsets increase ``downwards''. This means
+that the height of a frame is obtained by subtracting the offset of its
+top edge from that of its bottom edge. Horizontal offsets increase
+``leftwards'' as expected so a frame's width is calculated by
+subtracting the offset of its left edge from that of its right edge.
For a frame on a graphical terminal the following function returns the
sizes of the areas described above:
@@ -626,13 +733,15 @@ sizes of the areas described above:
@defun frame-geometry &optional frame
This function returns geometric attributes of @var{frame}. The return
value is an association list of the attributes listed below. All
-coordinate, height and width values are integers counting pixels.
+coordinate, height and width values are integers counting pixels. Note
+that if @var{frame} has not been mapped (@pxref{Visibility of Frames})
+yet, some of the return values may only represent approximations of the
+actual values---those that can be seen after the frame has been mapped.
@table @code
@item outer-position
-A cons of the absolute X- and Y-coordinates of the outer position of
address@hidden, relative to the origin at position (0, 0) of @var{frame}'s
-display.
+A cons representing the absolute position of the outer @var{frame},
+relative to the origin at position (0, 0) of @var{frame}'s display.
@item outer-size
A cons of the outer width and height of @var{frame}.
@@ -643,6 +752,10 @@ borders as supplied by the window manager. If the window
manager
doesn't supply these values, Emacs will try to guess them from the
coordinates of the outer and inner frame.
address@hidden outer-border-width
+The width of the outer border of @var{frame}. The value is meaningful
+for non-GTK+ X builds only.
+
@item title-bar-size
A cons of the width and height of the title bar of @var{frame} as
supplied by the window manager or operating system. If both of them are
@@ -677,24 +790,27 @@ The following function can be used to retrieve the edges
of the outer,
native and inner frame.
@defun frame-edges &optional frame type
-This function returns the edges of the outer, native or inner frame of
address@hidden @var{frame} must be a live frame and defaults to the
-selected one. The list returned has the form (@var{left} @var{top}
+This function returns the absolute edges of the outer, native or inner
+frame of @var{frame}. @var{frame} must be a live frame and defaults to
+the selected one. The list returned has the form (@var{left} @var{top}
@var{right} @var{bottom}) where all values are in pixels relative to the
-position (0, 0) of @var{frame}'s display. For terminal frames
address@hidden and @var{top} are both zero.
+origin of @var{frame}'s display. For terminal frames the values
+returned for @var{left} and @var{top} are always zero.
Optional argument @var{type} specifies the type of the edges to return:
address@hidden @code{outer-edges} means to return the outer edges of
address@hidden, @code{native-edges} (or @code{nil}) means to return its
-native edges and @code{inner-edges} means to return its inner edges.
address@hidden means to return the outer edges of @var{frame},
address@hidden (or @code{nil}) means to return its native edges and
address@hidden means to return its inner edges.
-Notice that the pixels at the positions @var{bottom} and @var{right}
-lie immediately outside the corresponding frame. This means that if you
-have, for example, two side-by-side frames positioned such that the
-right outer edge of the frame on the left equals the left outer edge of
-the frame on the right, the pixels representing that edge are part
-of the frame on the right.
+By convention, the pixels of the display at the values returned for
address@hidden and @var{top} are inside (part of) @var{frame}. Hence, if
address@hidden and @var{top} are both zero, the pixel at the display's
+origin is part of @var{frame}. The pixels at @var{bottom} and
address@hidden, on the other hand, lie immediately outside @var{frame}.
+This means that if you have, for example, two side-by-side frames
+positioned such that the right outer edge of the frame on the left
+equals the left outer edge of the frame on the right, the pixels at that
+edge show a part of the frame on the right.
@end defun
@@ -751,62 +867,112 @@ and all future graphical frames.
@end deffn
address@hidden Size and Position
address@hidden Size and Position
address@hidden frame size
address@hidden Frame Position
address@hidden Frame Position
@cindex frame position
@cindex position of frame
-You can read or change the position of a frame using the frame
-parameters @code{left} and @code{top} (@pxref{Position Parameters}) and
-its size using the @code{height} and @code{width} parameters
-(@pxref{Size Parameters}). Here are some special features for working
-with sizes and positions. For all of these functions the argument
address@hidden must denote a live frame and defaults to the selected frame.
+On graphical systems, the position of a normal top-level frame is
+specified as the absolute position of its outer frame (@pxref{Frame
+Geometry}). The position of a child frame (@pxref{Child Frames}) is
+specified via pixel offsets of its outer edges relative to the native
+position of its parent frame.
+
+ You can read or change the position of a frame using the frame
+parameters @code{left} and @code{top} (@pxref{Position Parameters}).
+Here are two additional functions for working with the positions of an
+existing, visible frame. For both functions, the argument @var{frame}
+must denote a live frame and defaults to the selected frame.
@defun frame-position &optional frame
-This function returns the outer position (@pxref{Frame Layout}) of
address@hidden in pixels. The value is a cons giving the coordinates of
-the top left corner of the outer frame of @var{frame} relative to an
-origin at the position (0, 0) of the frame's display. On a text
-terminal frame both values are zero.
+For a normal, non-child frame this function returns a cons of the (X, Y)
+pixel coordinates of its outer position (@pxref{Frame Layout}) with
+respect to the origin (0, 0) of its display. For a child frame
+(@pxref{Child Frames}) this function returns the pixel coordinates of
+its outer position with respect to an origin (0, 0) at the native
+position of @var{frame}'s parent.
+
+Negative return values never indicate an offset from the right or bottom
+edge of @var{frame}'s display or parent frame. Rather, they mean that
address@hidden's outer position is on the left and/or above the origin of
+its display or the native position of its parent frame. This usually
+means that @var{frame} is only partially visible (or completely
+invisible). However, on systems where the display's origin does not
+coincide with its top-left corner, the frame may be visible on a
+secondary monitor.
+
+On a text terminal frame both values are zero.
@end defun
@defun set-frame-position frame x y
-This function sets the outer frame position of @var{frame} to @var{x}
-and @var{y}. The latter arguments specify pixels and normally count
-from an origin at the position (0, 0) of @var{frame}'s display.
+This function sets the outer frame position of @var{frame} to (@var{x},
address@hidden). The latter arguments specify pixels and normally count from
+an origin at the position (0, 0) of @var{frame}'s display. For child
+frames, they count from the native position of @var{frame}'s parent
+frame.
+
+Negative parameter values position the right edge of the outer frame by
address@hidden pixels left from the right edge of the screen (or the parent
+frame's native rectangle) and the bottom edge by @var{-y} pixels up from
+the bottom edge of the screen (or the parent frame's native rectangle).
-A negative parameter value positions the right edge of the outer frame
-by @var{-x} pixels left from the right edge of the screen or the bottom
-edge by @var{-y} pixels up from the bottom edge of the screen.
+Note that negative values do not permit to align the right or bottom
+edge of @var{frame} exactly at the right or bottom edge of its display
+or parent frame. Neither do they allow to specify a position that does
+not lie within the edges of the display or parent frame. The frame
+parameters @code{left} and @code{top} (@pxref{Position Parameters})
+allow to do that but may still fail to provide good results for the
+initial or a new frame.
This function has no effect on text terminal frames.
@end defun
address@hidden frame-pixel-height &optional frame
address@hidden frame-pixel-width &optional frame
- These functions return the inner height and width (the height and
-width of the display area, see @ref{Frame Layout}) of @var{frame} in
-pixels. For a text terminal, the results are in characters rather than
-pixels.
address@hidden defun
address@hidden move-frame-functions
+This hook specifies the functions run when an Emacs frame is moved
+(assigned a new position) by the window-system or window manager. The
+functions are run with one argument, the frame that moved. For a child
+frame (@pxref{Child Frames}), the functions are run only when the
+position of the frame changes in relation to that of its parent frame.
address@hidden defvar
+
+
address@hidden Frame Size
address@hidden Frame Size
address@hidden frame size
address@hidden text width of a frame
address@hidden text height of a frame
address@hidden text size of a frame
+The canonical way to specify the @dfn{size of a frame} from within Emacs
+is by specifying its @dfn{text size}---a tuple of the width and height
+of the frame's text area (@pxref{Frame Layout}). It can be measured
+either in pixels or in terms of the frame's canonical character size
+(@pxref{Frame Font}).
+
+ For frames with an internal menu or tool bar, the frame's native
+height cannot be told exactly before the frame has been actually drawn.
+This means that in general you cannot use the native size to specify the
+initial size of a frame. As soon as you know the native size of a
+visible frame, you can calculate its outer size (@pxref{Frame Layout})
+by adding in the remaining components from the return value of
address@hidden . For invisible frames or for frames that have
+yet to be created, however, the outer size can be estimated only. This
+also means that calculating an exact initial position of a frame
+specified via offsets from the right or bottom edge of the screen
+(@pxref{Frame Position}) is impossible.
+
+ The text size of any frame can be set and retrieved with the help of
+the @code{height} and @code{width} frame parameters (@pxref{Size
+Parameters}). The text size of the initial frame can be also set with
+the help of an X-style geometry specification. @xref{Emacs Invocation,,
+Command Line Arguments for Emacs Invocation, emacs, The GNU Emacs
+Manual}. Below we list some functions to access and set the size of an
+existing, visible frame.
@defun frame-text-height &optional frame
@defunx frame-text-width &optional frame
These functions return the height and width of the text area of
@var{frame} (@pxref{Frame Layout}), measured in pixels. For a text
terminal, the results are in characters rather than pixels.
-
-The value returned by @code{frame-text-height} differs from that
-returned by @code{frame-pixel-height} by not including the heights of
-any internal tool bar or menu bar, the height of one horizontal scroll
-bar and the widths of the internal border.
-
-The value returned by @code{frame-text-width} differs from that returned
-by @code{frame-pixel-width} by not including the width of one vertical
-scroll bar, the widths of one left and one right fringe and the widths
-of the internal border.
@end defun
@defun frame-height &optional frame
@@ -823,12 +989,28 @@ rounded down to the number of characters of the default
font that fully
fit into the text area.
@end defun
address@hidden frame-pixel-height &optional frame
address@hidden frame-pixel-width &optional frame
+These functions return the native width and height, see @ref{Frame
+Layout}) of @var{frame} in pixels. For a text terminal, the results are
+in characters rather than pixels.
address@hidden defun
+
+On window systems that support it, Emacs tries by default to make the
+text size of a frame measured in pixels a multiple of the frame's
+character size. This, however, usually means that a frame can be
+resized only in character size increments when dragging its external
+borders. It also may break attempts to truly maximize the frame or
+making it ``fullheight'' or ``fullwidth'' (@pxref{Size Parameters})
+leaving some empty space below and/or on the right of the frame. The
+following option may help in that case.
+
@defopt frame-resize-pixelwise
-If this option is @code{nil}, a frame's size is usually rounded to a
-multiple of the current values of that frame's @code{frame-char-height}
-and @code{frame-char-width} whenever the frame is resized. If this is
address@hidden, no rounding occurs, hence frame sizes can
-increase/decrease by one pixel.
+If this option is @code{nil}, a frame's text pixel size is usually
+rounded to a multiple of the current values of that frame's
address@hidden and @code{frame-char-width} whenever the frame
+is resized. If this is address@hidden, no rounding occurs, hence frame
+sizes can increase/decrease by one pixel.
Setting this variable usually causes the next resize operation to pass
the corresponding size hints to the window manager. This means that
@@ -855,7 +1037,7 @@ terms of the canonical height and width of a character on
@var{frame}
The optional argument @var{pixelwise} address@hidden means to measure
the new width and height in units of pixels instead. Note that if
@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
-fully honor the request if it does not increase/decrease the frame size
+truly honor the request if it does not increase/decrease the frame size
to a multiple of its character size.
@end defun
@@ -876,9 +1058,9 @@ text terminals.
The optional fourth argument @var{pixelwise} address@hidden means that
@var{frame} should be @var{height} pixels high. Note that if
address@hidden is @code{nil}, some toolkits may refuse to
-fully honor the request if it does not increase/decrease the frame
-height to a multiple of its character height.
address@hidden is @code{nil}, some window managers may
+refuse to truly honor the request if it does not increase/decrease the
+frame height to a multiple of its character height.
@end defun
@defun set-frame-width frame width &optional pretend pixelwise
@@ -888,9 +1070,9 @@ in characters. The argument @var{pretend} has the same
meaning as in
The optional fourth argument @var{pixelwise} address@hidden means that
@var{frame} should be @var{width} pixels wide. Note that if
address@hidden is @code{nil}, some toolkits may refuse to
-fully honor the request if it does not increase/decrease the frame width
-to a multiple of its character width.
address@hidden is @code{nil}, some window managers may
+refuse to fully honor the request if it does not increase/decrease the
+frame width to a multiple of its character width.
@end defun
None of these three functions will make a frame smaller than needed to
@@ -899,7 +1081,25 @@ margins, dividers, mode and header lines. This contrasts
with requests
by the window manager triggered, for example, by dragging the external
border of a frame with the mouse. Such requests are always honored by
clipping, if necessary, portions that cannot be displayed at the right,
-bottom corner of the frame.
+bottom corner of the frame. The parameters @code{min-width} and
address@hidden (@pxref{Size Parameters}) can be used to obtain a
+similar behavior when changing the frame size from within Emacs.
+
address@hidden tracking frame size changes
+ The abnormal hook @code{window-size-change-functions} (@pxref{Window
+Hooks}) tracks all changes of the inner size of a frame including those
+induced by request of the window-system or window manager. To rule out
+false positives that might occur when changing only the sizes of a
+frame's windows without actually changing the size of the inner frame,
+use the following function.
+
address@hidden frame-size-changed-p &optional frame
+This function returns address@hidden when the inner width or height of
address@hidden has changed since @code{window-size-change-functions} was
+run the last time for @var{frame}. It always returns @code{nil}
+immediately after running @code{window-size-change-functions} for
address@hidden
address@hidden defun
@node Implied Frame Resizing
@@ -916,7 +1116,7 @@ size change. Note that wrapping a menu or tool bar
usually does not
resize the frame's outer size, hence this will alter the number of
displayed lines.
- Occasionally, such @dfn{implied frame resizing} may be unwanted, for
+ Occasionally, such @dfn{implied frame resizing} may be unwanted, for
example, when the frame is maximized or made full-screen (where it's
turned off by default). In other cases you can disable implied resizing
with the following option:
@@ -928,7 +1128,7 @@ implicitly resize the frame's display area in order to
preserve the
number of columns or lines the frame displays. If this option is
address@hidden, no implied resizing is done.
-The value of this option can be also be a list of frame parameters. In
+The value of this option can be also a list of frame parameters. In
that case, implied resizing is inhibited when changing a parameter that
appears in this list. The frame parameters currently handled by this
option are: @code{font}, @code{font-backend},
@@ -1135,6 +1335,8 @@ text terminals.
* Layout Parameters:: Size of parts of the frame, and
enabling or disabling some parts.
* Buffer Parameters:: Which buffers have been or should be shown.
+* Frame Interaction Parameters:: Parameters for interacting with other
+ frames.
* Management Parameters:: Communicating with the window manager.
* Cursor Parameters:: Controlling the cursor appearance.
* Font and Color Parameters:: Fonts and colors for the frame text.
@@ -1180,64 +1382,81 @@ 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.
address@hidden explicit-name, a frame parameter
@item explicit-name
If the frame name was specified explicitly when the frame was created,
this parameter will be that name. If the frame wasn't explicitly
named, this parameter will be @code{nil}.
@end table
+
@node Position Parameters
@subsubsection Position Parameters
@cindex window position on display
@cindex frame position
- Position parameters' values are measured in pixels. (Note that none
-of these parameters exist on TTY frames.)
+Parameters describing the X- and Y-offsets of a frame are always
+measured in pixels. For normal, non-child frames they specify the
+frame's absolute outer position (@pxref{Frame Geometry}) with respect to
+its display's origin. For a child frame (@pxref{Child Frames}) they
+specify the frame's outer position relative to the native position of
+the frame's parent frame. (Note that none of these parameters is
+meaningful on TTY frames.)
@table @code
@vindex left, a frame parameter
@item left
-The position, in pixels, of the left (or right) edge of the frame with
-respect to the left (or right) edge of the screen. The value may be:
+The position, in pixels, of the left outer edge of the frame with
+respect to the left edge of the frame's display or parent frame.
@table @asis
@item an integer
-A positive integer relates the left edge of the frame to the left edge
-of the screen. A negative integer relates the right frame edge to the
-right screen edge.
+A positive integer always relates the left edge of the frame to the left
+edge of its display or parent frame. A negative integer relates the
+right frame edge to the right edge of the display or parent frame.
@item @code{(+ @var{pos})}
This specifies the position of the left frame edge relative to the left
-screen edge. The integer @var{pos} may be positive or negative; a
-negative value specifies a position outside the screen or on a monitor
-other than the primary one (for multi-monitor displays).
+edge of its display or parent frame. The integer @var{pos} may be
+positive or negative; a negative value specifies a position outside the
+screen or parent frame or on a monitor other than the primary one (for
+multi-monitor displays).
@item @code{(- @var{pos})}
-This specifies the position of the right frame edge relative to the right
-screen edge. The integer @var{pos} may be positive or negative; a
-negative value specifies a position outside the screen or on a monitor
-other than the primary one (for multi-monitor displays).
+This specifies the position of the right frame edge relative to the
+right edge of the display or parent frame. The integer @var{pos} may be
+positive or negative; a negative value specifies a position outside the
+screen or parent frame or on a monitor other than the primary one (for
+multi-monitor displays).
@end table
Some window managers ignore program-specified positions. If you want to
be sure the position you specify is not ignored, specify a
address@hidden value for the @code{user-position} parameter as well.
-
-If the window manager refuses to align a frame at the left or top screen
-edge, combining position notation and @code{user-position} as in
address@hidden value for the @code{user-position} parameter as in the
+following example:
@example
(modify-frame-parameters
nil '((user-position . t) (left . (+ -4))))
@end example
-may help to override that.
+In general, it is not a good idea to specify negative offsets to
+position a frame relative to the right or bottom edge of its display.
+Positioning the initial or a new frame is either not accurate (because
+the size of the outer frame is not yet fully known before the frame has
+been made visible) or will cause additional flicker (if the frame is
+repositioned after becoming visible).
+
+ Note also, that negative offsets are not stored internally and are not
+returned by the function @code{frame-parameters}. This means that the
+desktop saving routines will restore the frame from the positive offsets
+obtained by that function.
@vindex top, a frame parameter
@item top
The screen position of the top (or bottom) edge, in pixels, with respect
-to the top (or bottom) edge of the screen. It works just like
address@hidden, except vertically instead of horizontally.
+to the top (or bottom) edge of the display or parent frame. It works
+just like @code{left}, except vertically instead of horizontally.
@vindex icon-left, a frame parameter
@item icon-left
@@ -1273,6 +1492,22 @@ When you call @code{make-frame}, you should specify a
address@hidden
value for this parameter if the values of the @code{left} and @code{top}
parameters represent the user's stated preference; otherwise, use
@code{nil}.
+
address@hidden z-group, a frame parameter
address@hidden z-group
+This parameter specifies a relative position of the frame's
+window-system window in the stacking (Z-) order of the frame's display.
+
+If this is @code{above}, the frame's window-system window is displayed
+above all other window-system windows that do not have the @code{above}
+property set. If this is nil, the frame's window is displayed below all
+windows that have the @code{above} property set and above all windows
+that have the @code{below} property set. If this is @code{below}, the
+frame's window is displayed below all windows that do not have the
address@hidden property set.
+
+To position the frame above or below a specific other frame use the
+function @code{frame-restack} (@pxref{Raising and Lowering}).
@end table
@@ -1285,15 +1520,19 @@ graphical displays, the @code{default} face determines
the actual
pixel sizes of these character units (@pxref{Face Attributes}).
@table @code
address@hidden height, a frame parameter
address@hidden height
-The height of the frame's text area (@pxref{Frame Geometry}), in
-characters.
-
@vindex width, a frame parameter
@item width
The width of the frame's text area (@pxref{Frame Geometry}), in
-characters.
+characters. The value can be also a cons cell of the symbol
address@hidden and an integer denoting the width of the text area in
+pixels.
+
address@hidden height, a frame parameter
address@hidden height
+The height of the frame's text area (@pxref{Frame Geometry}), in
+characters. The value can be also a cons cell of the symbol
address@hidden and an integer denoting the height of the text area
+in pixels.
@vindex user-size, a frame parameter
@item user-size
@@ -1302,6 +1541,28 @@ the @code{user-position} parameter (@pxref{Position
Parameters,
user-position}) does for the position parameters @code{top} and
@code{left}.
address@hidden min-width, a frame parameter
address@hidden min-width
+This parameter specifies the minimum native width of the frame
+(@pxref{Frame Geometry}), in characters. Normally, the functions that
+establish a frame's initial width or resize a frame horizontally make
+sure that all the frame's windows, vertical scroll bars, fringes,
+margins and vertical dividers can be displayed. This parameter, if
address@hidden allows to make a frame narrower than that with the
+consequence that any components that do not fit on the frame will be
+clipped by the window manager.
+
address@hidden min-height, a frame parameter
address@hidden min-height
+This parameter specifies the minimum height of the native (@pxref{Frame
+Geometry}), in characters. Normally, the functions that establish a
+frame's initial size or resize a frame make sure that all the frame's
+windows, horizontal scroll bars and dividers, mode and header lines, the
+echo area and the internal menu and tool bar can be displayed. This
+parameter, if address@hidden allows to make a frame smaller than that
+with the consequence that any components that do not fit on the frame
+will be clipped by the window-system or window manager.
+
@cindex fullboth frames
@cindex fullheight frames
@cindex fullwidth frames
@@ -1327,10 +1588,10 @@ of maximized and full-height frames and the widths of
maximized and
full-width frames often differ by a few pixels.
With some window managers you may have to customize the variable
address@hidden (@pxref{Size and Position}) in order to
-make a frame truly appear maximized or full-screen. Moreover,
-some window managers might not support smooth transition between the
-various full-screen or maximization states. Customizing the variable
address@hidden (@pxref{Frame Size}) in order to make a
+frame truly appear maximized or full-screen. Moreover, some window
+managers might not support smooth transition between the various
+full-screen or maximization states. Customizing the variable
@code{x-frame-normalize-before-maximize} can help to overcome that.
@vindex fullscreen-restore, a frame parameter
@@ -1364,11 +1625,12 @@ frame, or control their sizes.
@table @code
@vindex border-width, a frame parameter
@item border-width
-The width in pixels of the frame's border.
+The width in pixels of the frame's outer border (@pxref{Frame Geometry}).
@vindex internal-border-width, a frame parameter
@item internal-border-width
-The distance in pixels between text (or fringe) and the frame's border.
+The width in pixels of the frame's internal border (@pxref{Frame
+Geometry}).
@vindex vertical-scroll-bars, a frame parameter
@item vertical-scroll-bars
@@ -1418,21 +1680,25 @@ to not draw bottom dividers.
@vindex menu-bar-lines frame parameter
@item menu-bar-lines
-The number of lines to allocate at the top of the frame for a menu
-bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
address@hidden Bars,,,emacs, The GNU Emacs Manual}.
+The number of lines to allocate at the top of the frame for a menu bar.
+The default is one if Menu Bar mode is enabled and zero otherwise.
address@hidden Bars,,,emacs, The GNU Emacs Manual}. For an external menu
+bar, this value remains unchanged even when the menu bar wraps to two or
+more lines. In that case, the @code{menu-bar-size} value returned by
address@hidden (@pxref{Frame Geometry}) allows to derive whether
+the menu bar actually occupies one or more lines.
@vindex tool-bar-lines frame parameter
@item tool-bar-lines
-The number of lines to use for the tool bar. The default is 1 if Tool
-Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The
-GNU Emacs Manual}.
+The number of lines to use for the tool bar. The default is one if Tool
+Bar mode is enabled and zero otherwise. @xref{Tool Bars,,,emacs, The
+GNU Emacs Manual}. This value may change whenever the tool bar wraps.
@vindex tool-bar-position frame parameter
@item tool-bar-position
The position of the tool bar. Currently only for the GTK tool bar.
Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
-The default is @code{top}.
+The default is @code{top}.
@vindex line-spacing, a frame parameter
@item line-spacing
@@ -1440,6 +1706,7 @@ Additional space to leave below each text line, in pixels
(a positive
integer). @xref{Line Height}, for more information.
@end table
+
@node Buffer Parameters
@subsubsection Buffer Parameters
@cindex frame, which buffers to display
@@ -1478,6 +1745,40 @@ most-recently-selected first.
If address@hidden, this frame's window is never split automatically.
@end table
address@hidden Frame Interaction Parameters
address@hidden Frame Interaction Parameters
+
+These parameters supply forms of interactions between different frames.
+
address@hidden @code
address@hidden parent-frame, a frame parameter
address@hidden parent-frame
+If address@hidden, this means that this frame is a child frame
+(@pxref{Child Frames}) and this parameter specifies its parent frame.
+If nil, this means that this frame is a normal, top-level frame.
+
address@hidden delete-before, a frame parameter
address@hidden delete-before
+If address@hidden, this parameter specifies another frame whose deletion
+will automatically trigger the deletion of this frame. @xref{Deleting
+Frames}.
+
address@hidden mouse-wheel-frame, a frame parameter
address@hidden mouse-wheel-frame
+If address@hidden, this parameter specifies the frame whose windows will
+be scrolled whenever the mouse wheel is scrolled with the mouse pointer
+hovering over this frame (@pxref{Mouse Commands,,, emacs, The GNU Emacs
+Manual}).
+
address@hidden no-other-frame, a frame parameter
address@hidden no-other-frame
+If this is address@hidden, then this frame is not eligible as candidate
+for the functions @code{next-frame}, @code{previous-frame}
+(@pxref{Finding All Frames}) and @code{other-frame} (@pxref{Frame
+Commands,,, emacs, The GNU Emacs Manual}).
address@hidden table
+
+
@node Management Parameters
@subsubsection Window Management Parameters
@cindex window manager interaction, and frame parameters
@@ -1541,10 +1842,56 @@ with virtual desktops.
@vindex inhibit-double-buffering, a frame parameter
@item inhibit-double-buffering
-If address@hidden, the frame is drawn to the screen without double buffering.
-Emacs normally attempts to use double buffering, where available, to
-reduce flicker. Set this property if you experience display bugs or
-pine for that retro, flicker-y feeling.
+If address@hidden, the frame is drawn to the screen without double
+buffering. Emacs normally attempts to use double buffering, where
+available, to reduce flicker. Set this property if you experience
+display bugs or pine for that retro, flicker-y feeling.
+
address@hidden skip-taskbar, a frame parameter
address@hidden skip-taskbar
+If address@hidden, this tells the window manager to remove the frame's
+icon from the taskbar associated with the frame's display and inhibit
+switching to the frame's window via the combination @address@hidden
+On Windows, iconifying such a frame will "roll in" its window-system
+window at the bottom of the desktop. Some window managers may not honor
+this parameter.
+
address@hidden no-focus-on-map, a frame parameter
address@hidden no-focus-on-map
+If address@hidden, this means that the frame dos not want to receive
+input focus when it is mapped (@pxref{Visibility of Frames}). Some
+window managers may not honor this parameter.
+
address@hidden no-accept-focus, a frame parameter
address@hidden no-accept-focus
+If address@hidden, this means that the frame does not want to receive
+input focus via explicit mouse clicks or when moving the mouse into it
+either via @code{focus-follows-mouse} (@pxref{Input Focus}) or
address@hidden (@pxref{Mouse Window Auto-selection}).
+This may have the unwanted side-effect that a user cannot scroll a
+non-selected frame with the mouse. Some window managers may not honor
+this parameter.
+
address@hidden undecorated, a frame parameter
address@hidden undecorated
+If address@hidden, this frame's window-system window is drawn without
+decorations like title, minimize/maximize boxes and external borders.
+This usually means that the window cannot be dragged, resized,
+iconified, maximized or deleted with the mouse. If nil, the frame's
+window is usually drawn with all the elements listed above unless their
+display has been suspended via window manager settings.
+
+Under X, Emacs uses the Motif window manager hints to turn off
+decorations. Some window managers may not honor these hints.
+
address@hidden override-redirect, a frame parameter
address@hidden override-redirect
address@hidden override redirect frames
+If address@hidden, this means that this is an @dfn{override redirect}
+frame---a frame not handled by window managers under X. Override
+redirect frames have no window manager decorations, can be positioned
+and resized only via Emacs' positioning and resizing functions and are
+usually drawn on top of all other frames.
@ignore
@vindex parent-id, a frame parameter
@@ -1557,6 +1904,7 @@ it and see if it works.)
@end ignore
@end table
+
@node Cursor Parameters
@subsubsection Cursor Parameters
@cindex cursor, and frame parameters
@@ -1904,21 +2252,28 @@ while processing @code{frame-title-format} or
@section Deleting Frames
@cindex deleting frames
- A @dfn{live frame} is one that has not been deleted. When a frame
-is deleted, it is removed from its terminal display, although it may
-continue to exist as a Lisp object until there are no more references
-to it.
+A @dfn{live frame} is one that has not been deleted. When a frame is
+deleted, it is removed from its terminal display, although it may
+continue to exist as a Lisp object until there are no more references to
+it.
@deffn Command delete-frame &optional frame force
@vindex delete-frame-functions
This function deletes the frame @var{frame}. The argument @var{frame}
must specify a live frame (see below) and defaults to the selected
-frame. Unless @var{frame} specifies a tooltip, this function first runs
-the hook @code{delete-frame-functions} (each function getting one
-argument, @var{frame}).
+frame.
-A frame cannot be deleted as long as its minibuffer serves as surrogate
-minibuffer for another frame (@pxref{Minibuffers and Frames}).
+It first deletes any child frame of @var{frame} (@pxref{Child Frames})
+and any frame whose @code{delete-before} frame parameter (@pxref{Frame
+Interaction Parameters}) specifies @var{frame}. All such deletions are
+performed recursively; so this step makes sure that there will not exist
+any other frames with @var{frame} as their ancestor. Then, unless
address@hidden specifies a tooltip, this function runs the hook
address@hidden (each function getting one argument,
address@hidden) before actually killing the frame.
+
+Note that a frame cannot be deleted as long as its minibuffer serves as
+surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}).
Normally, you cannot delete a frame if all other frames are invisible,
but if @var{force} is address@hidden, then you are allowed to do so.
@end deffn
@@ -1942,8 +2297,13 @@ minibuffer frame is left untouched. The argument
@var{frame} must
specify a live frame and defaults to the selected frame. Internally,
this command works by calling @code{delete-frame} with @var{force}
@code{nil} for all frames that shall be deleted.
+
+This function does not delete any of @var{frame}'s child frames
+(@pxref{Child Frames}). If @var{frame} is a child frame, it deletes
address@hidden's siblings only.
@end deffn
+
@node Finding All Frames
@section Finding All Frames
@cindex frames, scanning all
@@ -1962,12 +2322,29 @@ This function returns a list of just the currently
visible frames.
visible, even though only the selected one is actually displayed.
@end defun
address@hidden frame-list-z-order &optional display
+This function returns a list of Emacs' frames, in Z (stacking) order
+(@pxref{Raising and Lowering}). The optional argument @var{display}
+specifies which display to poll. @var{display} should be either a frame
+or a display name (a string). If omitted or @code{nil}, that stands for
+the selected frame's display. It returns @code{nil} if @var{display}
+contains no Emacs frame.
+
+Frames are listed from topmost (first) to bottommost (last). As a
+special case, if @var{display} is address@hidden and specifies a live
+frame, it returns the child frames of that frame in Z (stacking) order.
+
+This function is not meaningful on text terminals.
address@hidden defun
+
@defun next-frame &optional frame minibuf
This function lets you cycle conveniently through all the frames on a
specific terminal from an arbitrary starting point. It returns the
frame following @var{frame}, in the list of all live frames, on
@var{frame}'s terminal. The argument @var{frame} must specify a live
-frame and defaults to the selected frame.
+frame and defaults to the selected frame. It never returns a frame
+whose @code{no-other-frame} parameter (@pxref{Frame Interaction
+Parameters}) is address@hidden
The second argument, @var{minibuf}, says which frames to consider:
@@ -1998,8 +2375,8 @@ Window Ordering}.
@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 Windows}).
+is used whenever that frame is selected. You can get that window with
+the function @code{minibuffer-window} (@pxref{Minibuffer Windows}).
@cindex frame without a minibuffer
@cindex surrogate minibuffer frame
@@ -2009,9 +2386,10 @@ will serve as @dfn{surrogate minibuffer frame} for this
frame and cannot
be deleted via @code{delete-frame} (@pxref{Deleting Frames}) as long as
this frame is live.
-When you create the frame, you can explicitly specify 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
+When you create the frame, you can explicitly specify its minibuffer
+window (in some other frame) with the @code{minibuffer} frame parameter
+(@pxref{Buffer Parameters}). 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 that does
have a minibuffer.
@@ -2026,13 +2404,14 @@ the current terminal and cannot be buffer-local.
@xref{Multiple
Terminals}.
@end defvar
+
@node Input Focus
@section Input Focus
@cindex input focus
address@hidden @cindex selected frame Duplicates selected-frame, same for
selected-window.
address@hidden selected frame
-At any time, one frame in Emacs is the @dfn{selected frame}. The selected
-window always resides on the selected frame.
+At any time, one frame in Emacs is the @dfn{selected frame}. The
+selected window always resides on the selected frame.
When Emacs displays its frames on several terminals (@pxref{Multiple
Terminals}), each terminal has its own selected frame. But only one
@@ -2077,6 +2456,26 @@ same meaning as for @code{select-frame} (see below).
The return value
of this function is not significant.
@end defun
+Ideally, the function described next should focus a frame without also
+raising it above other frames. Unfortunately, many window-systems or
+window managers may refuse to comply.
+
address@hidden x-focus-frame &optional frame noactivate
+This function gives @var{frame} the focus of the X server without
+necessarily raising it. @var{frame} @code{nil} means use the selected
+frame. Under X, the optional argument @var{noactivate}, if
address@hidden, means to avoid making @var{frame}'s window-system window
+the ``active'' window which should insist a bit more on avoiding to
+raise @var{frame} above other frames.
+
+On Windows the @var{noactivate} argument has no effect. However, if
address@hidden is a child frame (@pxref{Child Frames}), this function
+usualy does focus @var{frame} without raising it above other child
+frames.
+
+If there is no window system support, this function does nothing.
address@hidden defun
+
@deffn Command select-frame frame &optional norecord
This function selects frame @var{frame}, temporarily disregarding the
focus of the X server if any. The selection of @var{frame} lasts until
@@ -2091,7 +2490,7 @@ becomes the selected terminal. This function then calls
@code{select-window} as a subroutine, passing the window selected
within @var{frame} as its first argument and @var{norecord} as its
second argument (hence, if @var{norecord} is address@hidden, this
-avoids changing the order of recently selected windows nor the buffer
+avoids changing the order of recently selected windows and the buffer
list). @xref{Selecting Windows}.
This function returns @var{frame}, or @code{nil} if @var{frame} has
@@ -2147,20 +2546,64 @@ change it.
@end defun
@defvar focus-in-hook
-This is a normal hook run when an Emacs frame gains input focus.
+This is a normal hook run when an Emacs frame gains input focus. The
+frame gaining focus is selected when this hook is run.
@end defvar
@defvar focus-out-hook
-This is a normal hook run when an Emacs frame loses input focus.
+This is a normal hook run when an Emacs frame has lost input focus and
+no other Emacs frame has gained input focus instead.
@end defvar
@defopt focus-follows-mouse
-This option is how you inform Emacs whether the window manager transfers
-focus when the user moves the mouse. address@hidden says that it does.
-When this is so, the command @code{other-frame} moves the mouse to a
-position consistent with the new selected frame.
+This option informs Emacs whether and how the window manager transfers
+focus when you move the mouse pointer into a frame. It can have three
+meaningful values:
+
address@hidden @asis
address@hidden @code{nil}
+The default value @code{nil} should be used when your window manager
+follows a ``click-to-focus'' policy where you have to click the mouse
+inside of a frame in order for that frame to gain focus.
+
address@hidden @code{t}
+The value @code{t} should be used when your window manager has the focus
+automatically follow the position of the mouse pointer but a frame that
+gains focus is not raised automatically and may even remain occluded by
+other window-system windows.
+
address@hidden @code{auto-raise}
+The value @code{auto-raise} should be used when your window manager has
+the focus automatically follow the position of the mouse pointer and a
+frame that gains focus is raised automatically.
address@hidden table
+
+If this option is address@hidden, Emacs moves the mouse pointer to the
+frame selected by @code{select-frame-set-input-focus}. That function is
+used by a number of commands like, for example, @code{other-frame} and
address@hidden
+
+The distinction between the values @code{t} and @code{auto-raise} is not
+needed for ``normal'' frames because the window manager usually takes
+care of raising them. It is useful to automatically raise child frames
+via @code{mouse-autoselect-window} (@pxref{Mouse Window
+Auto-selection}).
+
+Note that this option does not distinguish ``sloppy'' focus (where the
+frame that previously had focus retains focus as long as the mouse
+pointer does not move into another window manager window) from
+``strict'' focus (where a frame immediately loses focus when it's left
+by the mouse pointer). It neither recognizes whether your window
+manager supports delayed focusing or auto-raising where you can
+explicitly specify the time until a new frame gets focus or is
+auto-raised.
+
+You can supply a ``focus follows mouse'' policy for individual Emacs
+windows by customizing the variable @code{mouse-autoselect-window}
+(@pxref{Mouse Window Auto-selection}).
@end defopt
+
@node Visibility of Frames
@section Visibility of Frames
@cindex visible frame
@@ -2169,16 +2612,26 @@ position consistent with the new selected frame.
@cindex minimized frame
@cindex frame visibility
-A frame on a graphical display may be @dfn{visible}, @dfn{invisible},
-or @dfn{iconified}. If it is visible, its contents are displayed in
-the usual manner. If it is iconified, its contents are not displayed,
-but there is a little icon somewhere to bring the frame back into view
-(some window managers refer to this state as @dfn{minimized} rather
-than @dfn{iconified}, but from Emacs' point of view they are the same
-thing). If a frame is invisible, it is not displayed at all.
+A frame on a graphical display may be @dfn{visible}, @dfn{invisible}, or
address@hidden If it is visible, its contents are displayed in the
+usual manner. If it is iconified, its contents are not displayed, but
+there is a little icon somewhere to bring the frame back into view (some
+window managers refer to this state as @dfn{minimized} rather than
address@hidden, but from Emacs' point of view they are the same thing).
+If a frame is invisible, it is not displayed at all.
+
address@hidden mapped frame
address@hidden unmapped frame
+ The concept of visibility is strongly related to that of (un-)mapped
+frames. A frame (or, more precisely, its window-system window) is and
+becomes @dfn{mapped} when it is displayed for the first time and
+whenever it changes its state of visibility from @code{iconified} or
address@hidden to @code{visible}. Conversely, a frame is and becomes
address@hidden whenever it changes its status from @code{visible} to
address@hidden or @code{invisible}.
Visibility is meaningless on text terminals, since only the selected
-one is actually displayed in any case.
+frame is actually displayed in any case.
@defun frame-visible-p frame
This function returns the visibility status of frame @var{frame}. The
@@ -2192,22 +2645,28 @@ purposes of this function, even though only one frame
is displayed.
@deffn Command iconify-frame &optional frame
This function iconifies frame @var{frame}. If you omit @var{frame}, it
-iconifies the selected frame.
+iconifies the selected frame. This usually makes all child frames of
address@hidden (and their descendants) invisible (@pxref{Child Frames}).
@end deffn
@deffn Command make-frame-visible &optional frame
-This function makes frame @var{frame} visible. If you omit
address@hidden, it makes the selected frame visible. This does not raise
-the frame, but you can do that with @code{raise-frame} if you wish
-(@pxref{Raising and Lowering}).
+This function makes frame @var{frame} visible. If you omit @var{frame},
+it makes the selected frame visible. This does not raise the frame, but
+you can do that with @code{raise-frame} if you wish (@pxref{Raising and
+Lowering}).
+
+Making a frame visible usually makes all its child frames (and their
+descendants) visible too (@pxref{Child Frames}).
@end deffn
@deffn Command make-frame-invisible &optional frame force
This function makes frame @var{frame} invisible. If you omit
address@hidden, it makes the selected frame invisible.
address@hidden, it makes the selected frame invisible. Usually, this makes
+all child frames of @var{frame} (and their descendants) invisible too
+(@pxref{Child Frames}).
Unless @var{force} is address@hidden, this function refuses to make
address@hidden invisible if all other frames are invisible..
address@hidden invisible if all other frames are invisible.
@end deffn
The visibility status of a frame is also available as a frame
@@ -2223,27 +2682,79 @@ being rendered with double buffering. @var{frame}
defaults to the
selected frame.
@end defun
+
@node Raising and Lowering
address@hidden Raising and Lowering Frames
address@hidden Raising, Lowering and Restacking Frames
@cindex raising a frame
@cindex lowering a frame
- Most window systems use a desktop metaphor. Part of this metaphor
-is the idea that system-level windows (e.g., Emacs frames) are
-stacked in a notional third dimension perpendicular to the screen
-surface. Where two overlap, the one higher up covers the one
-underneath. You can @dfn{raise} or @dfn{lower} a frame using the
-functions @code{raise-frame} and @code{lower-frame}.
address@hidden restacking a frame
address@hidden frame stacking order
address@hidden frame Z-order
+ Most window systems use a desktop metaphor. Part of this metaphor is
+the idea that system-level windows (representing, e.g., Emacs frames)
+are stacked in a notional third dimension perpendicular to the screen
+surface. The order induced by stacking is total and usually referred to
+as stacking (or Z-) order. Where the areas of two windows overlap, the
+one higher up in that order will (partially) cover the one underneath.
+
+ You can @dfn{raise} a frame to the top of that order or @dfn{lower} a
+frame to its bottom by using the functions @code{raise-frame} and
address@hidden You can @dfn{restack} a frame directly above or
+below another frame using the function @code{frame-restack}.
+
+ Note that all functions described below will respect the adherence of
+frames (and all other window-system windows) to their respective z-group
+(@pxref{Position Parameters}). For example, you usually cannot lower a
+frame below that of the desktop window and you cannot raise a frame
+whose @code{z-group} parameter is @code{nil} above the window-system's
+taskbar or tooltip window.
@deffn Command raise-frame &optional frame
-This function raises frame @var{frame} (default, the selected frame).
-If @var{frame} is invisible or iconified, this makes it visible.
+This function raises frame @var{frame} (default, the selected frame)
+above all other frames belonging to the same or a lower z-group as
address@hidden If @var{frame} is invisible or iconified, this makes it
+visible. If @var{frame} is a child frame (@pxref{Child Frames}), this
+raises @var{frame} above all other child frames of its parent.
@end deffn
@deffn Command lower-frame &optional frame
-This function lowers frame @var{frame} (default, the selected frame).
+This function lowers frame @var{frame} (default, the selected frame)
+below all other frames belonging to the same or a higher z-group as
address@hidden If @var{frame} is a child frame (@pxref{Child Frames}),
+this lowers @var{frame} below all other child frames of its parent.
@end deffn
address@hidden frame-restack frame1 frame2 &optional above
+This function restacks @var{frame1} below @var{frame2}. This implies
+that if both frames are visible and their display areas overlap,
address@hidden will (partially) obscure @var{frame1}. If the optional
+third argument @var{above} is address@hidden, this function restacks
address@hidden above @var{frame2}. This means that if both frames are
+visible and their display areas overlap, @var{frame1} will (partially)
+obscure @var{frame2}.
+
+Technically, this function may be thought of as an atomic action
+performed in two steps: The first step removes @var{frame1}'s
+window-system window from the display. The second step reinserts
address@hidden's window into the display below (above if @var{above} is
+true) that of @var{frame2}. Hence the position of @var{frame2} in its
+display's Z (stacking) order relative to all other frames excluding
address@hidden remains unaltered.
+
+Some window managers may refuse to restack windows.
address@hidden defun
+
+Note that the effect of restacking will only hold as long as neither of
+the involved frames is iconified or made invisible. You can use the
address@hidden (@pxref{Position Parameters}) frame parameter to add a
+frame to a group of frames permanently shown above or below other
+frames. As long as a frame belongs to one of these groups, restacking
+it will only affect its relative stacking position within that group.
+The effect of restacking frames belonging to different z-groups is
+undefined. You can list frames in their current stacking order with the
+function @code{frame-list-z-order} (@pxref{Finding All Frames}).
+
@defopt minibuffer-auto-raise
If this is address@hidden, activation of the minibuffer raises the frame
that the minibuffer window is in.
@@ -2265,6 +2776,7 @@ or @code{nil} (meaning the selected frame's terminal).
If it does not
refer to a text terminal, the return value is @code{nil}.
@end defun
+
@node Frame Configurations
@section Frame Configurations
@cindex frame configuration
@@ -2288,6 +2800,135 @@ Ordinarily, this function deletes all existing frames
not listed in
unwanted frames are iconified instead.
@end defun
+
address@hidden Child Frames
address@hidden Child Frames
address@hidden child frames
address@hidden parent frames
+
+On some window-systems the @code{parent-frame} parameter (@pxref{Frame
+Interaction Parameters}) can be used to make a frame a child of the
+frame specified by that parameter. 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 @code{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 @code{nil} restores the frame's status as a top-level frame---one
+whose window-system window is a child of its display's root window.
+
+ 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 child frames sufficiently smaller than that of their
+parent). An error will be signalled for the attempt to make a frame an
+ancestor of itself.
+
+ A child frame is clipped at the native edges (@pxref{Frame Geometry})
+of its parent frame---everything outside these edges is invisible. Its
address@hidden and @code{top} parameters specify positions relative to the
+top-left corner of its parent's native frame. When either of the frames
+is resized, the relative position of the child frame remains unaltered.
+Hence, resizing either of these frames can hide or reveal parts of the
+child frame.
+
+ Usually, moving a parent frame moves along all its child frames and
+their descendants as well, keeping their relative positions unaltered.
+The hook @code{move-frame-functions} (@pxref{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, the child frame
+retains its position respective to the left and upper native edges of
+its parent. In this case, the position respective to the lower or right
+native edge of the parent frame is usually lost.
+
+ A visible child frame always appears on top of its parent frame thus
+obscuring parts of it. 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 (@pxref{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, (@pxref{Deleting Frames}) its child frames are recursively
+deleted before it.
+
+ Whether a child frame can have a menu or tool bar is window-system or
+window manager dependent. Most window-systems explicitly disallow menus
+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 (@pxref{Frame Geometry}). When the child
+frame does not show a menu or tool bar, any other of the frame's borders
+(@pxref{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 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
address@hidden frame parameter @pxref{Management Parameters}).
+
+ 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:
+
address@hidden @bullet
address@hidden
+The semantics of maximizing and iconifying child frames is highly
+window-system dependent. As a rule, applications should never invoke
+these operations for child frames.
+
address@hidden
+Raising, lowering and restacking child frames (@pxref{Raising and
+Lowering}) or changing the @code{z-group} (@pxref{Position Parameters})
+of a child frame changes only the stacking order of child frames with
+the same parent.
+
address@hidden
+Many window-systems are not able to change the opacity (@pxref{Font and
+Color Parameters}) of child frames.
+
address@hidden
+Transferring focus from a child frame to an ancestor that is not its
+parent by clicking with the mouse in a visible part of that ancestor's
+window may fail with some window-systems. You may have to click into
+the direct parent's window-system window first.
+
address@hidden
+Window managers might not bother to extend their focus follows mouse
+policy to child frames. Customizing @code{mouse-autoselect-window} can
+help in this regard (@pxref{Mouse Window Auto-selection}).
+
address@hidden
+Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed too
+work on all window-systems. Some will drop the object on the parent
+frame or some ancestor instead.
address@hidden itemize
+
+ The following two functions may be useful when working with child and
+parent frames:
+
address@hidden frame-parent &optional frame
+This function returns the parent frame of @var{frame}. The parent frame
+of @var{frame} is the Emacs frame whose window-system window is the
+parent window of @var{frame}'s window-system window. If such a frame
+exists, @var{frame} is considered a child frame of that frame.
+
+This function returns @code{nil} if @var{frame} has no parent frame.
address@hidden defun
+
address@hidden frame-ancestor-p &optional ancestor descendant
+This functions returns address@hidden if @var{ancestor} is an ancestor
+of @var{descendant}. @var{ancestor} is an ancestor of @var{descendant}
+when it is either @var{descendant}'s parent frame or it is an ancestor
+of @var{descendant}'s parent frame. Both, @var{ancestor} and
address@hidden must specify live frames and default to the selected
+frame.
address@hidden defun
+
+
@node Mouse Tracking
@section Mouse Tracking
@cindex mouse tracking
@@ -3203,9 +3844,3 @@ ever be developed and distributed noncommercially.
This variable's value is @code{t} if no X window manager is in use.
@end defvar
@end ignore
-
address@hidden
address@hidden
-The functions @code{x-pixel-width} and @code{x-pixel-height} return the
-width and height of an X Window frame, measured in pixels.
address@hidden ignore
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 6aa9591..931d106 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -42,6 +42,7 @@ is displayed in windows.
* Vertical Scrolling:: Moving the contents up and down on the window.
* Horizontal Scrolling:: Moving the contents sideways on the window.
* Coordinates and Windows:: Converting coordinates to windows.
+* Mouse Window Auto-selection:: Automatically selecting windows with the mouse.
* Window Configurations:: Saving and restoring the state of the screen.
* Window Parameters:: Associating additional information with windows.
* Window Hooks:: Hooks for scrolling, window size changes,
@@ -763,7 +764,7 @@ changing the size of its frame. Because live windows do
not overlap,
these functions are meaningful only on frames that contain two or more
windows: resizing a window also changes the size of a neighboring
window. If there is just one window on a frame, its size cannot be
-changed except by resizing the frame (@pxref{Size and Position}).
+changed except by resizing the frame (@pxref{Frame Size}).
Except where noted, these functions also accept internal windows as
arguments. Resizing an internal window causes its child windows to be
@@ -1016,7 +1017,7 @@ A window can get resized explicitly by using one of the
functions from
the preceding section or implicitly, for example, when resizing an
adjacent window, when splitting or deleting a window (@pxref{Splitting
Windows}, @pxref{Deleting Windows}) or when resizing the window's frame
-(@pxref{Size and Position}).
+(@pxref{Frame Size}).
It is possible to avoid implicit resizing of a specific window when
there are one or more other resizable windows on the same frame. For
@@ -1716,23 +1717,47 @@ value of @code{window-point} (@pxref{Window Point}) in
@var{window}.
@var{window} must be a live window. The return value is @var{window}.
By default, this function also moves @var{window}'s buffer to the front
-of the buffer list (@pxref{Buffer List}), and makes @var{window} the
-most recently selected window. However, if the optional argument
address@hidden is address@hidden, these additional actions are omitted.
-
-This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
-unless @var{norecord} is address@hidden Note that applications and
-internal routines often temporarily select a window in order to simplify
-coding. As a rule, such selections (including those made by the macros
address@hidden and @code{with-selected-window} below) are
-not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
-Selections that really count are those causing a visible change in
-the next redisplay of @var{window}'s frame and should be always
-recorded. This also means that to run a function each time a window
-gets selected, putting it on @code{buffer-list-update-hook} should be
-the right choice.
+of the buffer list (@pxref{Buffer List}) and makes @var{window} the most
+recently selected window. If the optional argument @var{norecord} is
address@hidden, these additional actions are omitted.
+
+In addition, this function by default also tells the display engine to
+update the display of @var{window} when its frame gets redisplayed the
+next time. If @var{norecord} is address@hidden, such updates are
+usually not performed. If, however, @var{norecord} equals the special
+symbol @code{mark-for-redisplay}, the additional actions mentioned above
+are omitted but @var{window} will be nevertheless updated.
@end defun
address@hidden select window hook
address@hidden running a hook when a windows gets selected
+For historical reasons, Emacs does not run a separate hook whenever a
+window gets selected. Applications and internal routines often
+temporarily select a window to perform a few actions on it. They do
+that either to simplify coding---because many functions by default
+operate on the selected window when no @var{window} argument is
+specified---or because some functions did not (and still do not) take a
+window as argument and always operate(d) on the selected window instead.
+Running a hook every time a window gets selected for a short time and
+once more when the previously selected window gets restored is not
+useful.
+
+ However, when its @var{norecord} argument is @code{nil},
address@hidden updates the buffer list and thus indirectly runs
+the normal hook @code{buffer-list-update-hook} (@pxref{Buffer List}).
+Consequently, that hook provides a reasonable way to run a function
+whenever a window gets selected more ``permanently''.
+
+ Since @code{buffer-list-update-hook} is also run by functions that are
+not related to window management, it will usually make sense to save the
+value of the selected window somewhere and compare it with the value of
address@hidden while running that hook. Also, to avoid false
+positives when using @code{buffer-list-update-hook} it is good practice
+that every @code{select-window} call supposed to select a window only
+temporarily, passes a address@hidden @var{norecord} argument. If
+possible, the macro @code{with-selected-window} (see below) should be
+used in such cases.
+
@cindex most recently selected windows
The sequence of calls to @code{select-window} with a address@hidden
@var{norecord} argument determines an ordering of windows by their
@@ -1761,13 +1786,13 @@ the buffer list.
@defmac with-selected-window window address@hidden
This macro selects @var{window}, executes @var{forms} in sequence, then
-restores the previously selected window and current buffer. The ordering
-of recently selected windows and the buffer list remain unchanged unless
-you deliberately change them within @var{forms}; for example, by calling
address@hidden with argument @var{norecord} @code{nil}.
-
-This macro does not change the order of recently selected windows or
-the buffer list.
+restores the previously selected window and current buffer. The
+ordering of recently selected windows and the buffer list remain
+unchanged unless you deliberately change them within @var{forms}; for
+example, by calling @code{select-window} with argument @var{norecord}
address@hidden Hence, this macro is the preferred way to temporarily work
+with @var{window} as the selected window without needlessly running
address@hidden
@end defmac
@defun frame-selected-window &optional frame
@@ -4566,6 +4591,55 @@ point in the selected window, it's sufficient to write:
@end defun
address@hidden Mouse Window Auto-selection
address@hidden Mouse Window Auto-selection
address@hidden window auto-selection
address@hidden auto-selection of window
+The following option allows to automatically select the window under the
+mouse pointer. This accomplishes a policy similar to that of window
+managers that give focus to a frame (and thus trigger its subsequent
+selection) whenever the mouse pointer enters its window-system window
+(@pxref{Input Focus}).
+
address@hidden mouse-autoselect-window
+If this variable is address@hidden, Emacs will try to automatically
+select the window under the mouse pointer. The following values are
+meaningful:
+
address@hidden @asis
address@hidden A positive number
+This specifies a delay in seconds after which auto-selection triggers.
+The window under the mouse pointer is selected after the mouse has
+remained in it for the entire duration of the delay.
+
address@hidden A negative number
+A negative number has a similar effect as a positive number, but selects
+the window under the mouse pointer only after the mouse pointer has
+remained in it for the entire duration of the absolute value of that
+number and in addition has stopped moving.
+
address@hidden Other value
+Any other address@hidden value means to select a window instantaneously
+as soon as the mouse pointer enters it.
address@hidden table
+
+In either case the mouse pointer must enter the text area of a window in
+order to trigger its selection. Dragging the scroll bar slider or the
+mode line of a window conceptually should not cause its auto-selection.
+
+Mouse auto-selection selects the minibuffer window only if it is active,
+and never deselects the active minibuffer window.
address@hidden defvar
+
+Mouse auto-selection can be used to emulate a focus follows mouse policy
+for child frames (@pxref{Child Frames}) which usually are not tracked by
+the window manager. This requires to set the value of
address@hidden (@pxref{Input Focus}) to a address@hidden
+value. If the value of @code{focus-follows-mouse} is @code{auto-raise},
+entering a child frame with the mouse will raise it automatically above
+all other child frames of that frame's parent frame.
+
+
@node Window Configurations
@section Window Configurations
@cindex window configurations
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] master 7cc613d: Describe recent frame and window changes in manuals,
Martin Rudalics <=