From 1c82607674c514707ab064a9f05f8acc14c4cdce Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Mon, 24 Feb 2025 09:47:30 +0100 Subject: [PATCH] Clarify semantics of 'frame-inhibit-implied-resize' * src/frame.c (frame_inhibit_implied_resize): * doc/lispref/frames.texi (Implied Frame Resizing): Clarify semantics of 'frame-inhibit-implied-resize'. (cherry picked from commit be60601ae884214503c4f958a74cebc27e8381b6) --- doc/lispref/frames.texi | 60 ++++++++++++++++++++++++++++------------- src/frame.c | 26 +++++++++++------- 2 files changed, 59 insertions(+), 27 deletions(-) diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 8afb2c75ff2..32d6ffc48ed 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1234,11 +1234,22 @@ immediately after running @code{window-size-change-functions} for @cindex implied resizing of frame By default, Emacs tries to keep the number of lines and columns of a -frame's text area unaltered when, for example, toggling its menu or -tool bar, changing its default font or setting the width of any of its -scroll bars. This means that in such case Emacs must ask the window -manager to resize the frame's window in order to accommodate the size -change. +frame's text area (@pxref{Frame Layout}) unaltered when, for example, +toggling the menu or tool bar, changing the default font or setting the +default width of scroll bars on that frame. When any of these +decorations is drawn by a toolkit, this usually means that Emacs has to +work against that toolkit because the latter usually tries to keep the +outer frame size unaltered when the size of a decoration changes, thus +implicitly changing the size of the frame's text area. + + In practice this means that whenever Emacs issues a request to add or +remove such a decoration, it will issue a second request with the +intention to restore the original size of the frame's text area. When +any of these decorations is drawn by Emacs itself (like the tool bar +with the Lucid or MS-Windows builds or the tab bar), Emacs may still +have to alter the size of the native frame accordingly and issue a +resize request because these decorations should not be accounted for by +the text area of the frame. Occasionally, such @dfn{implied frame resizing} may be unwanted, for example, when a frame has been maximized or made full-screen (where @@ -1249,16 +1260,29 @@ resizing with the following option: If this option is @code{nil}, changing a frame's font, menu bar, tool bar, internal borders, fringes or scroll bars may resize its outer frame in order to keep the number of columns or lines of its text area -unaltered. If this option is @code{t}, no such resizing happens once a -frame has obtained its initial size. If the value is the symbol -@code{force}, no implicit resizing happens whenever a new frame is made. -The latter can be useful with tiling window managers where the initial -size of a frame is determined by external means. +unaltered. + +If this option is @code{t}, Emacs will not resize a frame in any of +these cases once it has agreed with the window manager on the final +initial size of that frame. More precisely, this means that Emacs may +resize a frame implicitly until all of its decorations have been taken +into account and it has been given the initial size requested by the +user. Any further changes of decorations will not cause an implied +resizing of the frame. + +If this option equals the symbol @code{force}, Emacs will not perform +any implied resizing of a frame even before it has agreed with the +window manager on the final initial size of that frame. As a +consequence, the initial size of a frame's text area may not necessarily +reflect the one specified by the user. This value can be useful with +tiling window managers where the initial size of a frame is determined +by external means. The value of this option can be also a list of frame parameters. In -that case, implied resizing is inhibited for the change of the -parameters that appear in this list. Parameters currently handled by -this option are @code{font}, @code{font-backend}, +that case, implied resizing of a frame is inhibited for the change of +any parameters that appears in this list once Emacs has agreed with the +window manager on the final initial size of that frame. Parameters +currently handled by this option are @code{font}, @code{font-backend}, @code{internal-border-width}, @code{menu-bar-lines} and @code{tool-bar-lines}. @@ -1288,11 +1312,11 @@ even if this option is non-@code{nil}. Note also that window managers usually do not ask for resizing a frame when they change the number of lines occupied by an external menu or tool bar. Typically, such ``wrappings'' occur when a user shrinks a -frame horizontally, making it impossible to display all elements of -its menu or tool bar. They may also result from a change of the major -mode altering the number of items of a menu or tool bar. Any such -wrappings may implicitly alter the number of lines of a frame's text -area and are unaffected by the setting of this option. +frame horizontally, making it impossible to display all elements of its +menu or tool bar. They may also result from a change of the major mode +altering the number of items of a menu or tool bar. Any such wrappings +may implicitly alter the number of lines of a frame's text area and are +unaffected by the setting of this option. @end defopt diff --git a/src/frame.c b/src/frame.c index d2c6f01168e..95bcdb8b37f 100644 --- a/src/frame.c +++ b/src/frame.c @@ -7113,17 +7113,25 @@ a non-nil value in your init file. */); If this option is nil, setting font, menu bar, tool bar, tab bar, internal borders, fringes or scroll bars of a specific frame may resize the frame in order to preserve the number of columns or lines it -displays. If this option is t, no such resizing happens once a frame -has got its initial size. If this is the symbol `force', no implicit -resizing happens whenever a new frame is made. This can be useful with -tiling window managers where the initial size of a frame is determined -by external means. +displays. + +If this option is t, no such resizing happens once Emacs has agreed with +the window manager on the final initial size of a frame. That size will +have taken into account the size of the text area requested by the user +and the size of all decorations initially present on the frame. + +If this is the symbol `force', no implicit resizing happens even before +a frame has obtained its final initial size. As a consequence, the +initial frame size may not necessarily be the one requested by the user. +This value can be useful with tiling window managers where the initial +size of a frame is determined by external means. The value of this option can be also a list of frame parameters. In -this case, resizing is inhibited when changing a parameter that -appears in that list. The parameters currently handled by this option -include `font', `font-backend', `internal-border-width', -`menu-bar-lines', `tool-bar-lines' and `tab-bar-lines'. +this case, resizing is inhibited once a frame has obtained its final +initial size when changing a parameter that appears in that list. The +parameters currently handled by this option include `font', +`font-backend', `internal-border-width', `menu-bar-lines', +`tool-bar-lines' and `tab-bar-lines'. Changing any of the parameters `scroll-bar-width', `scroll-bar-height', `vertical-scroll-bars', `horizontal-scroll-bars', `left-fringe' and -- 2.39.5