new repository

1 files changed, 56 insertions, 0 deletions

diff --git a/devdocs/elisp/window-sizes.html b/devdocs/elisp/window-sizes.html
new file mode 100644
index 00000000..4493b63e
--- /dev/null
+++ b/devdocs/elisp/window-sizes.html
@@ -0,0 +1,56 @@
+ <h3 class="section">Window Sizes</h3>   <p>Emacs provides miscellaneous functions for finding the height and width of a window. The return value of many of these functions can be specified either in units of pixels or in units of lines and columns. On a graphical display, the latter actually correspond to the height and width of a default character specified by the frame’s default font as returned by <code>frame-char-height</code> and <code>frame-char-width</code> (see <a href="frame-font">Frame Font</a>). Thus, if a window is displaying text with a different font or size, the reported line height and column width for that window may differ from the actual number of text lines or columns displayed within it. </p>    <p>The <em>total height</em> of a window is the number of lines comprising its body and its top and bottom decorations (see <a href="basic-windows">Basic Windows</a>). </p> <dl> <dt id="window-total-height">Function: <strong>window-total-height</strong> <em>&amp;optional window round</em>
+</dt> <dd>
+<p>This function returns the total height, in lines, of the window <var>window</var>. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window. If <var>window</var> is an internal window, the return value is the total height occupied by its descendant windows. </p> <p>If a window’s pixel height is not an integral multiple of its frame’s default character height, the number of lines occupied by the window is 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 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 (see <a href="coordinates-and-windows">Coordinates and Windows</a>) </p> <p>If the optional argument <var>round</var> is <code>ceiling</code>, this function returns the smallest integer larger than <var>window</var>’s pixel height divided by the character height of its frame; if it is <code>floor</code>, it returns the largest integer smaller than said value; with any other <var>round</var> it returns the internal value of <var>windows</var>’s total height. </p>
+</dd>
+</dl>    <p>The <em>total width</em> of a window is the number of columns comprising its body and its left and right decorations (see <a href="basic-windows">Basic Windows</a>). </p> <dl> <dt id="window-total-width">Function: <strong>window-total-width</strong> <em>&amp;optional window round</em>
+</dt> <dd>
+<p>This function returns the total width, in columns, of the window <var>window</var>. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window. If <var>window</var> is internal, the return value is the total width occupied by its descendant windows. </p> <p>If a window’s pixel width is not an integral multiple of its frame’s character width, the number of columns occupied by the window is rounded internally. This is done in a way such that, if the window is a parent window, the sum of the total widths of all its children internally equals the total width of their parent. This means that although two windows have the same pixel width, their internal total widths may differ by one column. This means also, that if this window is horizontally combined and has a next sibling, the leftmost column of that sibling can be calculated as the sum of this window’s leftmost column and total width (see <a href="coordinates-and-windows">Coordinates and Windows</a>). The optional argument <var>round</var> behaves as it does for <code>window-total-height</code>. </p>
+</dd>
+</dl> <dl> <dt id="window-total-size">Function: <strong>window-total-size</strong> <em>&amp;optional window horizontal round</em>
+</dt> <dd><p>This function returns either the total height in lines or the total width in columns of the window <var>window</var>. If <var>horizontal</var> is omitted or <code>nil</code>, this is equivalent to calling <code>window-total-height</code> for <var>window</var>; otherwise it is equivalent to calling <code>window-total-width</code> for <var>window</var>. The optional argument <var>round</var> behaves as it does for <code>window-total-height</code>. </p></dd>
+</dl> <p>The following two functions can be used to return the total size of a window in units of pixels. </p>    <dl> <dt id="window-pixel-height">Function: <strong>window-pixel-height</strong> <em>&amp;optional window</em>
+</dt> <dd>
+<p>This function returns the total height of window <var>window</var> in pixels. <var>window</var> must be a valid window and defaults to the selected one. </p> <p>The return value includes the heights of <var>window</var>’s top and bottom decorations. If <var>window</var> is an internal window, its pixel height is the pixel height of the screen areas spanned by its children. </p>
+</dd>
+</dl>    <dl> <dt id="window-pixel-width">Function: <strong>window-pixel-width</strong> <em>&amp;optional window</em>
+</dt> <dd>
+<p>This function returns the width of window <var>window</var> in pixels. <var>window</var> must be a valid window and defaults to the selected one. </p> <p>The return value includes the widths of <var>window</var>’s left and right decorations. If <var>window</var> is an internal window, its pixel width is the width of the screen areas spanned by its children. </p>
+</dd>
+</dl>   <p>The following functions can be used to determine whether a given window has any adjacent windows. </p> <dl> <dt id="window-full-height-p">Function: <strong>window-full-height-p</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns non-<code>nil</code> if <var>window</var> has no other window above or below it in its frame. More precisely, this means that the total height of <var>window</var> equals the total height of the root window on that frame. The minibuffer window does not count in this regard. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window. </p></dd>
+</dl> <dl> <dt id="window-full-width-p">Function: <strong>window-full-width-p</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns non-<code>nil</code> if <var>window</var> has no other window to the left or right in its frame, i.e., its total width equals that of the root window on that frame. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window. </p></dd>
+</dl>   <p>The <em>body height</em> of a window is the height of its body, which does not include any of its top or bottom decorations (see <a href="basic-windows">Basic Windows</a>). </p> <dl> <dt id="window-body-height">Function: <strong>window-body-height</strong> <em>&amp;optional window pixelwise</em>
+</dt> <dd>
+<p>This function returns the height, in lines, of the body of window <var>window</var>. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window; otherwise it must be a live window. </p> <p>If the optional argument <var>pixelwise</var> is non-<code>nil</code>, this function returns the body height of <var>window</var> counted in pixels. </p> <p>If <var>pixelwise</var> is <code>nil</code>, the return value is rounded down to the nearest integer, if necessary. This means that if a line at the bottom of the text area is only partially visible, that line is not counted. It also means that the height of a window’s body can never exceed its total height as returned by <code>window-total-height</code>. </p>
+</dd>
+</dl>   <p>The <em>body width</em> of a window is the width of its body and of the text area, which does not include any of its left or right decorations (see <a href="basic-windows">Basic Windows</a>). </p> <p>Note that when one or both fringes are removed (by setting their width to zero), the display engine reserves two character cells, one on each side of the window, for displaying the continuation and truncation glyphs, which leaves 2 columns less for text display. (The function <code>window-max-chars-per-line</code>, described below, takes this peculiarity into account.) </p> <dl> <dt id="window-body-width">Function: <strong>window-body-width</strong> <em>&amp;optional window pixelwise</em>
+</dt> <dd>
+<p>This function returns the width, in columns, of the body of window <var>window</var>. If <var>window</var> is omitted or <code>nil</code>, it defaults to the selected window; otherwise it must be a live window. </p> <p>If the optional argument <var>pixelwise</var> is non-<code>nil</code>, this function returns the body width of <var>window</var> in units of pixels. </p> <p>If <var>pixelwise</var> is <code>nil</code>, the return value is rounded down to the nearest integer, if necessary. This means that if a column on the right of the text area is only partially visible, that column is not counted. It also means that the width of a window’s body can never exceed its total width as returned by <code>window-total-width</code>. </p>
+</dd>
+</dl>   <dl> <dt id="window-body-size">Function: <strong>window-body-size</strong> <em>&amp;optional window horizontal pixelwise</em>
+</dt> <dd><p>This function returns the body height or body width of <var>window</var>. If <var>horizontal</var> is omitted or <code>nil</code>, it is equivalent to calling <code>window-body-height</code> for <var>window</var>; otherwise it is equivalent to calling <code>window-body-width</code>. In either case, the optional argument <var>pixelwise</var> is passed to the function called. </p></dd>
+</dl> <p>The pixel heights of a window’s mode, tab and header line can be retrieved with the functions given below. Their return value is usually accurate unless the window has not been displayed before: In that case, the return value is based on an estimate of the font used for the window’s frame. </p> <dl> <dt id="window-mode-line-height">Function: <strong>window-mode-line-height</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns the height in pixels of <var>window</var>’s mode line. <var>window</var> must be a live window and defaults to the selected one. If <var>window</var> has no mode line, the return value is zero. </p></dd>
+</dl> <dl> <dt id="window-tab-line-height">Function: <strong>window-tab-line-height</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns the height in pixels of <var>window</var>’s tab line. <var>window</var> must be a live window and defaults to the selected one. If <var>window</var> has no tab line, the return value is zero. </p></dd>
+</dl> <dl> <dt id="window-header-line-height">Function: <strong>window-header-line-height</strong> <em>&amp;optional window</em>
+</dt> <dd><p>This function returns the height in pixels of <var>window</var>’s header line. <var>window</var> must be a live window and defaults to the selected one. If <var>window</var> has no header line, the return value is zero. </p></dd>
+</dl> <p>Functions for retrieving the height and/or width of window dividers (see <a href="window-dividers">Window Dividers</a>), fringes (see <a href="fringes">Fringes</a>), scroll bars (see <a href="scroll-bars">Scroll Bars</a>), and display margins (see <a href="display-margins">Display Margins</a>) are described in the corresponding sections. </p> <p>If your Lisp program needs to make layout decisions, you will find the following function useful: </p> <dl> <dt id="window-max-chars-per-line">Function: <strong>window-max-chars-per-line</strong> <em>&amp;optional window face</em>
+</dt> <dd>
+<p>This function returns the number of characters displayed in the specified face <var>face</var> in the specified window <var>window</var> (which must be a live window). If <var>face</var> was remapped (see <a href="face-remapping">Face Remapping</a>), the information is returned for the remapped face. If omitted or <code>nil</code>, <var>face</var> defaults to the default face, and <var>window</var> defaults to the selected window. </p> <p>Unlike <code>window-body-width</code>, this function accounts for the actual size of <var>face</var>’s font, instead of working in units of the canonical character width of <var>window</var>’s frame (see <a href="frame-font">Frame Font</a>). It also accounts for space used by the continuation glyph, if <var>window</var> lacks one or both of its fringes. </p>
+</dd>
+</dl>    <p>Commands that change the size of windows (see <a href="resizing-windows">Resizing Windows</a>), or split them (see <a href="splitting-windows">Splitting Windows</a>), obey the variables <code>window-min-height</code> and <code>window-min-width</code>, which specify the smallest allowable window height and width. They also obey the variable <code>window-size-fixed</code>, with which a window can be <em>fixed</em> in size (see <a href="preserving-window-sizes">Preserving Window Sizes</a>). </p> <dl> <dt id="window-min-height">User Option: <strong>window-min-height</strong>
+</dt> <dd><p>This option specifies the minimum total height, in lines, of any window. Its value has to accommodate at least one text line and any top or bottom decorations. </p></dd>
+</dl> <dl> <dt id="window-min-width">User Option: <strong>window-min-width</strong>
+</dt> <dd><p>This option specifies the minimum total width, in columns, of any window. Its value has to accommodate at least two text columns and any left or right decorations. </p></dd>
+</dl> <p>The following function tells how small a specific window can get taking into account the sizes of its areas and the values of <code>window-min-height</code>, <code>window-min-width</code> and <code>window-size-fixed</code> (see <a href="preserving-window-sizes">Preserving Window Sizes</a>). </p> <dl> <dt id="window-min-size">Function: <strong>window-min-size</strong> <em>&amp;optional window horizontal ignore pixelwise</em>
+</dt> <dd>
+<p>This function returns the minimum size of <var>window</var>. <var>window</var> must be a valid window and defaults to the selected one. The optional argument <var>horizontal</var> non-<code>nil</code> means to return the minimum number of columns of <var>window</var>; otherwise return the minimum number of <var>window</var>’s lines. </p> <p>The return value makes sure that all components of <var>window</var> remain fully visible if <var>window</var>’s size were actually set to it. With <var>horizontal</var> <code>nil</code> it includes any top or bottom decorations. With <var>horizontal</var> non-<code>nil</code> it includes any left or right decorations of <var>window</var>. </p> <p>The optional argument <var>ignore</var>, if non-<code>nil</code>, means ignore restrictions imposed by fixed size windows, <code>window-min-height</code> or <code>window-min-width</code> settings. If <var>ignore</var> equals <code>safe</code>, live windows may get as small as <code>window-safe-min-height</code> lines and <code>window-safe-min-width</code> columns. If <var>ignore</var> is a window, ignore restrictions for that window only. Any other non-<code>nil</code> value means ignore all of the above restrictions for all windows. </p> <p>The optional argument <var>pixelwise</var> non-<code>nil</code> means to return the minimum size of <var>window</var> counted in pixels. </p>
+</dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Window-Sizes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Window-Sizes.html</a>
+  </p>
+</div>