emacs/gnu.emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2026-09-10 07:46:51 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

; Clarify issues with frames and windows in Elisp manual

Browse source 
* doc/lispref/frames.texi (Frame Size): Deepen explanation of
"gravity".
(Deleting Frames): Mention terminal when deciding whether a
frame can be safely deleted.
(Child Frame Properties): Cover tab-line dragging.
* doc/lispref/windows.texi (Windows and Frames, Window Sizes)
(Deleting Windows, Changing Window Layouts, Switching Buffers)
(Buffer Display Action Functions, Buffer Display Action Alists)
(Window Parameters): Minor fixes.
This commit is contained in:
Martin Rudalics 2026-08-12 10:29:14 +02:00
parent b9c2b2d0d8
commit 6f71867f27
2 changed files with 64 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
doc/lispref/frames.texi
View file

@ -1318,12 +1318,15 @@ are specified as with the corresponding frame parameters @code{width},
@defun set-frame-size-and-position-pixelwise frame width height x y &optional gravity
This function sets the new size and position of a frame, similarly to
@code{set-frame-size-and-position}, but in pixel units. The optional
argument @var{gravity} specified the new @dfn{gravity} of a frame and
must be a value between 0 and 10; it defaults to 1. The gravity
determines how a window or its contents adjust when resized or
positioned. The interpretation is specific to each window-system; for
example, GTK uses window gravity to define which point of the window
remains fixed during resizing.
argument @var{gravity} specifies the new @dfn{gravity} of @var{frame}
and must be a value between 0 and 10; it defaults to 1. Gravity is
window-system dependent and conceptually determine which corner of a
frame retains its position relative to that of its parent frame when the
size of that frame or its parent changes. (Top-level frames have no
parent frame, the window-system root window will be considered their
parent in this regard.) The value 1 specifies NorthWest gravity and
means that the top-left corner of the frame should keep its relative
position. Many window managers seem to ignore gravity.
@end defun
@cindex tracking frame size changes
@ -2974,16 +2977,16 @@ A frame cannot be safely deleted in the following cases:
@itemize @bullet
@item
It is the only visible or iconified frame (@pxref{Visibility of
Frames}).
Frames}) on its terminal.
@item
It hosts the active minibuffer window and minibuffer windows do not
follow the selected frame (@pxref{Basic Minibuffer,,, emacs}).
@item
All other visible or iconified frames are either child frames
(@pxref{Child Frames}) or have a non-@code{nil} @code{delete-before}
parameter.
All other visible or iconified frames on the same terminal are either
child frames (@pxref{Child Frames}) or have a non-@code{nil}
@code{delete-before} parameter.
@item
The frame or one of its descendants hosts the minibuffer window of a
@ -3970,12 +3973,14 @@ parameter indicates the number of pixels where the frame @dfn{snaps} at
the respective edge or corner of its parent frame. On a text terminal,
the outer border can used for resizing.
There are two ways to drag an entire child frame with the mouse: The
There are three ways to drag an entire child frame with the mouse: The
@code{drag-with-mode-line} parameter, if non-@code{nil}, enables
dragging a frame without minibuffer window (@pxref{Minibuffer
Windows}) via the mode line area of its bottommost window. The
@code{drag-with-header-line} parameter, if non-@code{nil}, enables
dragging the frame via the header line area of its topmost window.
dragging a frame without minibuffer window (@pxref{Minibuffer Windows})
via the mode line area of its bottommost window. The
@code{drag-with-header-line} and the @code{drag-with-tab-line}
parameters, if non-@code{nil}, enable dragging the frame via the header
or tab line area of its topmost window (dragging with the tab line is
possible only when there's no header line above the tab line).
In order to give a child frame a draggable header or mode line, the
window parameters @code{mode-line-format} and @code{header-line-format}
@ -3990,15 +3995,15 @@ prevent such a situation, it is advisable to set the frame's
@code{top-visible} or @code{bottom-visible} parameter (@pxref{Mouse
Dragging Parameters}).
Set the @code{top-visible} parameter of a child frame to a number
when you intend to allow the user dragging that frame by its header
line. Setting @code{top-visible} to a number inhibits dragging the
top edge of the child frame above the top edge of its parent. Set the
@code{bottom-visible} parameter to a number when you intend to drag
that frame via its mode line; this inhibits dragging the bottom edge
of the child frame beneath the bottom edge of its parent. In either
case, that number also specifies width and height (in pixels) of the
area of the child frame that remains visible during dragging.
Set the @code{top-visible} parameter of a child frame to a number when
you intend to allow the user dragging that frame by its header or tab
line. Setting @code{top-visible} to a number inhibits dragging the top
edge of the child frame above the top edge of its parent. Set the
@code{bottom-visible} parameter to a number when you intend to drag that
frame via its mode line; this inhibits dragging the bottom edge of the
child frame beneath the bottom edge of its parent. In either case, that
number also specifies width and height (in pixels) of the area of the
child frame that remains visible during dragging.
When a child frame is used for displaying a buffer via
@code{display-buffer-in-child-frame} (@pxref{Buffer Display Action

63
doc/lispref/windows.texi
View file

@ -428,8 +428,8 @@ appears right below @var{window}.
@cindex window in direction
@defun window-in-direction direction &optional window ignore sign wrap minibuf
This function returns the nearest live window in direction
@var{direction} as seen from the position of @code{window-point} in
window @var{window}. The argument @var{direction} must be one of
@var{direction} as seen from the position of @var{window}'s point
(@pxref{Window Point}). The argument @var{direction} must be one of
@code{above}, @code{below}, @code{left} or @code{right}. The optional
argument @var{window} must denote a live window and defaults to the
selected one.
@ -736,7 +736,7 @@ rounded internally. This is done in a way such that, if the window is a
parent window, the sum of the total heights of all its child windows
internally equals the total height of their parent. This means that
although two windows have the same pixel height, their internal total
heights may differ by one line. This means also, that if window is
heights may differ by one line. This means also, that if a window is
vertically combined and has a next sibling, the topmost row of that
sibling can be calculated as the sum of this window's topmost row and
total height (@pxref{Coordinates and Windows})
@ -745,7 +745,7 @@ total height (@pxref{Coordinates and Windows})
returns the smallest integer larger than @var{window}'s pixel height
divided by the canonical character height of its frame; if it is
@code{floor}, it returns the largest integer smaller than said value;
with any other @var{round} it returns the internal value of
with any other value of @var{round} it returns the internal value of
@var{windows}'s total height.
@end defun
@ -1632,15 +1632,18 @@ selected one. Possible choices are
@itemize
@item @code{mru}
(the default) choose the most recently used window on that frame.
(the default) means to choose the most recently used window
(@pxref{Cyclic Window Ordering}) other than the selected one on that
frame.
@item @code{pos}
choose the window comprising the frame coordinates of point of the
previously selected window on that frame.
means to choose the window comprising the position of
(@code{window-point}, @ref{Window Point}) of the previously selected
window on that frame.
@item @code{nil}
choose the first window (the window returned by
@code{frame-first-window}) on that frame.
means to choose the first window (the window returned by
@code{frame-first-window}, @ref{Windows and Frames}) on that frame.
@end itemize
A window for which @code{window-no-other-p} (@pxref{Cyclic Window
@ -2299,9 +2302,10 @@ windows by deleting them first and resurrecting them
window gets lost and no window is added or duplicated. Where possible,
these commands try to preserve the relative size of windows as well as
all other non-geometric properties including parameters. These commands
will signal an error if windows chosen to transpose or rotate are atomic
or of fixed size. The option @code{transpose-dedicated-windows} below
decides whether dedicated windows may be transposed or rotated.
will signal an error if windows about to change their locations are
atomic or of fixed size. The option @code{transpose-dedicated-windows}
described below decides whether dedicated windows may change their
locations.
The @var{window} argument of all functions described in this section
must specify a valid parent window (@pxref{Windows and Frames}). If it
@ -2313,8 +2317,8 @@ their frame's main window and the @var{window} argument is @code{nil}
unless stated otherwise.
@cindex rotate window layout
The first two commands rotate an entire window layout either
clockwise or counterclockwise.
The first two commands @dfn{rotate a window layout} either clockwise
or counterclockwise.
@deffn Command window-layout-rotate-clockwise &optional window
This command rotates the window layout clockwise by 90 degrees. Imagine
@ -2355,7 +2359,7 @@ layout in the opposite direction as demonstrated in the example below.
@end deffn
@cindex flip window layout
The next two commands @sc{flip} the window layout---rotate it around an
The next two commands @dfn{flip the window layout}---rotate it around an
imaginary horizontal or vertical axis. If the number of windows to be
flipped is odd, the window in the middle remains in its original place.
@ -2395,7 +2399,7 @@ become the windows on the left, and vice-versa.
@end smallexample
@end deffn
The next command can be used for @sc{transposing} windows---changing
The next command can be used to @dfn{transpose windows}---changing
horizontal splits to vertical ones and vice-versa.
@cindex transposing windows
@ -2418,7 +2422,7 @@ becomes a vertical split and vice versa.
@end deffn
@cindex rotating windows
The final two commands can be used to @dfn{rotate} windows within the
The final two commands can be used to @dfn{rotate windows} within the
existing layout. They are like the commands that rotate the layout but
leave the underlying structure of the layout unchanged. What actually
changes are the positions of windows within the existing layout. This
@ -2428,7 +2432,7 @@ non-@code{nil}) it in the cyclic ordering of windows (@pxref{Cyclic
Window Ordering}) on @var{window}'s frame.
@deffn Command rotate-windows &optional window reverse
This command rotates @var{window}'c child windows in cyclic ordering.
This command rotates @var{window}'s child windows in cyclic ordering.
The optional argument @var{reverse} means to rotate windows backwards,
in reverse cyclic order.
@ -2477,9 +2481,10 @@ The last two commands are subject to the following option.
@defopt rotate-windows-change-selected
If this is @code{nil}, the selected window will remain unaffected by
@code{rotate-windows} and @code{rotate-windows-back}. Otherwise, the
selected window will change to the window that appears at the location
of the window selected before any of these commands were invoked.
@code{rotate-windows} and @code{rotate-windows-back}. If this is
@code{t} (the default), the selected window will change to the window
that appears at the location of the window selected before any of these
commands were invoked.
@end defopt
@ -2973,7 +2978,9 @@ buffer.
@defopt switch-to-buffer-obey-display-actions
If this variable is non-@code{nil}, @code{switch-to-buffer} respects
display actions specified by @code{display-buffer-overriding-action},
@code{display-buffer-alist} and other display related variables.
@code{display-buffer-alist} (@pxref{Buffer Display Action Functions})
and other buffer display related variables (@pxref{Buffer Display Action
Alists}).
@end defopt
The next two commands are similar to @code{switch-to-buffer}, except for
@ -3521,9 +3528,9 @@ must also provide an appropriate @code{window-height} entry.
This function tries to display @var{buffer} in a window at the bottom
of the selected frame.
This either tries to split the window at the bottom of the frame or
the frame's root window, or to reuse an existing window at the bottom
of the selected frame.
This either tries to split the window at the bottom of the frame or the
frame's main window, or to reuse an existing window at the bottom of the
selected frame.
@end defun
@defun display-buffer-pop-up-frame buffer alist
@ -3756,8 +3763,8 @@ well. @code{display-buffer-in-previous-window} consults it when
searching for a window that previously displayed the buffer on another
frame.
Action function @code{display-buffer-in-tab} searches the tabs of the
frame(s) identified by this entry, and also interprets the value
The action function @code{display-buffer-in-tab} searches the tabs of
the frame(s) identified by this entry, and also interprets the value
@code{nil} differently.
@vindex inhibit-switch-frame@r{, a buffer display action alist entry}
@ -7591,7 +7598,7 @@ affected.
@vindex min-margins@r{, a window parameter}
The value of this parameter is a cons cell whose @sc{car} and
@sc{cdr}, if non-@code{nil}, specify the minimum values (in columns)
for the left and right margin of this window (@pxref{Display Margins}.
for the left and right margin of this window (@pxref{Display Margins}).
When present, Emacs will use these values instead of the actual margin
widths for determining whether a window can be split or shrunk
horizontally.