diff options
Diffstat (limited to 'devdocs/elisp/size-of-displayed-text.html')
| -rw-r--r-- | devdocs/elisp/size-of-displayed-text.html | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/devdocs/elisp/size-of-displayed-text.html b/devdocs/elisp/size-of-displayed-text.html new file mode 100644 index 00000000..75af33e2 --- /dev/null +++ b/devdocs/elisp/size-of-displayed-text.html @@ -0,0 +1,35 @@ + <h3 class="section">Size of Displayed Text</h3> <p>Since not all characters have the same width, these functions let you check the width of a character. See <a href="primitive-indent">Primitive Indent</a>, and <a href="screen-lines">Screen Lines</a>, for related functions. </p> <dl> <dt id="char-width">Function: <strong>char-width</strong> <em>char</em> +</dt> <dd><p>This function returns the width in columns of the character <var>char</var>, if it were displayed in the current buffer (i.e., taking into account the buffer’s display table, if any; see <a href="display-tables">Display Tables</a>). The width of a tab character is usually <code>tab-width</code> (see <a href="usual-display">Usual Display</a>). </p></dd> +</dl> <dl> <dt id="string-width">Function: <strong>string-width</strong> <em>string &optional from to</em> +</dt> <dd> +<p>This function returns the width in columns of the string <var>string</var>, if it were displayed in the current buffer and the selected window. Optional arguments <var>from</var> and <var>to</var> specify the substring of <var>string</var> to consider, and are interpreted as in <code>substring</code> (see <a href="creating-strings">Creating Strings</a>). </p> <p>The return value is an approximation: it only considers the values returned by <code>char-width</code> for the constituent characters, always takes a tab character as taking <code>tab-width</code> columns, ignores display properties and fonts, etc. For these reasons, we recommend using <code>window-text-pixel-size</code>, described below, instead. </p> +</dd> +</dl> <dl> <dt id="truncate-string-to-width">Function: <strong>truncate-string-to-width</strong> <em>string width &optional start-column padding ellipsis ellipsis-text-property</em> +</dt> <dd> +<p>This function returns a new string that is a truncation of <var>string</var> which fits within <var>width</var> columns on display. </p> <p>If <var>string</var> is narrower than <var>width</var>, the result is equal to <var>string</var>; otherwise excess characters are omitted from the result. If a multi-column character in <var>string</var> exceeds the goal <var>width</var>, that character is omitted from the result. Thus, the result can sometimes fall short of <var>width</var>, but cannot go beyond it. </p> <p>The optional argument <var>start-column</var> specifies the starting column; it defaults to zero. If this is non-<code>nil</code>, then the first <var>start-column</var> columns of the string are omitted from the result. If one multi-column character in <var>string</var> extends across the column <var>start-column</var>, that character is omitted. </p> <p>The optional argument <var>padding</var>, if non-<code>nil</code>, is a padding character added at the beginning and end of the result string, to extend it to exactly <var>width</var> columns. The padding character is appended at the end of the result if it falls short of <var>width</var>, as many times as needed to reach <var>width</var>. It is also prepended at the beginning of the result if a multi-column character in <var>string</var> extends across the column <var>start-column</var>. </p> <p>If <var>ellipsis</var> is non-<code>nil</code>, it should be a string which will replace the end of <var>string</var> when it is truncated. In this case, more characters will be removed from <var>string</var> to free enough space for <var>ellipsis</var> to fit within <var>width</var> columns. However, if the display width of <var>string</var> is less than the display width of <var>ellipsis</var>, <var>ellipsis</var> will not be appended to the result. If <var>ellipsis</var> is non-<code>nil</code> and not a string, it stands for the value returned by the function <code>truncate-string-ellipsis</code>, described below. </p> <p>The optional argument <var>ellipsis-text-property</var>, if non-<code>nil</code>, means hide the excess parts of <var>string</var> with a <code>display</code> text property (see <a href="display-property">Display Property</a>) showing the ellipsis, instead of actually truncating the string. </p> <div class="example"> <pre class="example">(truncate-string-to-width "\tab\t" 12 4) + ⇒ "ab" +(truncate-string-to-width "\tab\t" 12 4 ?\s) + ⇒ " ab " +</pre> +</div> <p>This function uses <code>string-width</code> and <code>char-width</code> to find the suitable truncation point when <var>string</var> is too wide, so it suffers from the same basic issues as <code>string-width</code> does. In particular, when character composition happens within <var>string</var>, the display width of a string could be smaller than the sum of widths of the constituent characters, and this function might return inaccurate results. </p> +</dd> +</dl> <dl> <dt id="truncate-string-ellipsis">Function: <strong>truncate-string-ellipsis</strong> +</dt> <dd><p>This function returns the string to be used as an ellipses in <code>truncate-string-to-width</code> and other similar contexts. The value is that of the variable <code>truncate-string-ellipsis</code>, if it’s non-<code>nil</code>, the string with the single character <small>U+2026 HORIZONTAL ELLIPSIS</small> if that character can be displayed on the selected frame, and the string ‘<samp>...</samp>’ otherwise. </p></dd> +</dl> <p>The following function returns the size in pixels of text as if it were displayed in a given window. This function is used by <code>fit-window-to-buffer</code> and <code>fit-frame-to-buffer</code> (see <a href="resizing-windows">Resizing Windows</a>) to make a window exactly as large as the text it contains. </p> <dl> <dt id="window-text-pixel-size">Function: <strong>window-text-pixel-size</strong> <em>&optional window from to x-limit y-limit mode-lines</em> +</dt> <dd> +<p>This function returns the size of the text of <var>window</var>’s buffer in pixels. <var>window</var> must be a live window and defaults to the selected one. The return value is a cons of the maximum pixel-width of any text line and the maximum pixel-height of all text lines. This function exists to allow Lisp programs to adjust the dimensions of <var>window</var> to the buffer text it needs to display. </p> <p>The optional argument <var>from</var>, if non-<code>nil</code>, specifies the first text position to consider, and defaults to the minimum accessible position of the buffer. If <var>from</var> is <code>t</code>, it stands for the minimum accessible position that is not a newline character. The optional argument <var>to</var>, if non-<code>nil</code>, specifies the last text position to consider, and defaults to the maximum accessible position of the buffer. If <var>to</var> is <code>t</code>, it stands for the maximum accessible position that is not a newline character. </p> <p>The optional argument <var>x-limit</var>, if non-<code>nil</code>, specifies the maximum X coordinate beyond which text should be ignored; it is therefore also the largest value of pixel-width that the function can return. If <var>x-limit</var> <code>nil</code> or omitted, it means to use the pixel-width of <var>window</var>’s body (see <a href="window-sizes">Window Sizes</a>); this default means that text of truncated lines wider than the window will be ignored. This default is useful when the caller does not intend to change the width of <var>window</var>. Otherwise, the caller should specify here the maximum width <var>window</var>’s body may assume; in particular, if truncated lines are expected and their text needs to be accounted for, <var>x-limit</var> should be set to a large value. Since calculating the width of long lines can take some time, it’s always a good idea to make this argument as small as needed; in particular, if the buffer might contain long lines that will be truncated anyway. </p> <p>The optional argument <var>y-limit</var>, if non-<code>nil</code>, specifies the maximum Y coordinate beyond which text is to be ignored; it is therefore also the maximum pixel-height that the function can return. If <var>y-limit</var> is nil or omitted, it means to considers all the lines of text till the buffer position specified by <var>to</var>. Since calculating the pixel-height of a large buffer can take some time, it makes sense to specify this argument; in particular, if the caller does not know the size of the buffer. </p> <p>The optional argument <var>mode-lines</var> <code>nil</code> or omitted means to not include the height of the mode-, tab- or header-line of <var>window</var> in the return value. If it is either the symbol <code>mode-line</code>, <code>tab-line</code> or <code>header-line</code>, include only the height of that line, if present, in the return value. If it is <code>t</code>, include the height of all of these lines, if present, in the return value. </p> +</dd> +</dl> <p><code>window-text-pixel-size</code> treats the text displayed in a window as a whole and does not care about the size of individual lines. The following function does. </p> <dl> <dt id="window-lines-pixel-dimensions">Function: <strong>window-lines-pixel-dimensions</strong> <em>&optional window first last body inverse left</em> +</dt> <dd> +<p>This function calculates the pixel dimensions of each line displayed in the specified <var>window</var>. It does so by walking <var>window</var>’s current glyph matrix—a matrix storing the glyph (see <a href="glyphs">Glyphs</a>) of each buffer character currently displayed in <var>window</var>. If successful, it returns a list of cons pairs representing the x- and y-coordinates of the lower right corner of the last character of each line. Coordinates are measured in pixels from an origin (0, 0) at the top-left corner of <var>window</var>. <var>window</var> must be a live window and defaults to the selected one. </p> <p>If the optional argument <var>first</var> is an integer, it denotes the index (starting with 0) of the first line of <var>window</var>’s glyph matrix to be returned. Note that if <var>window</var> has a header line, the line with index 0 is that header line. If <var>first</var> is <code>nil</code>, the first line to be considered is determined by the value of the optional argument <var>body</var>: If <var>body</var> is non-<code>nil</code>, this means to start with the first line of <var>window</var>’s body, skipping any header line, if present. Otherwise, this function will start with the first line of <var>window</var>’s glyph matrix, possibly the header line. </p> <p>If the optional argument <var>last</var> is an integer, it denotes the index of the last line of <var>window</var>’s glyph matrix that shall be returned. If <var>last</var> is <code>nil</code>, the last line to be considered is determined by the value of <var>body</var>: If <var>body</var> is non-<code>nil</code>, this means to use the last line of <var>window</var>’s body, omitting <var>window</var>’s mode line, if present. Otherwise, this means to use the last line of <var>window</var> which may be the mode line. </p> <p>The optional argument <var>inverse</var>, if <code>nil</code>, means that the y-pixel value returned for any line specifies the distance in pixels from the left edge (body edge if <var>body</var> is non-<code>nil</code>) of <var>window</var> to the right edge of the last glyph of that line. <var>inverse</var> non-<code>nil</code> means that the y-pixel value returned for any line specifies the distance in pixels from the right edge of the last glyph of that line to the right edge (body edge if <var>body</var> is non-<code>nil</code>) of <var>window</var>. This is useful for determining the amount of slack space at the end of each line. </p> <p>The optional argument <var>left</var>, if non-<code>nil</code> means to return the x- and y-coordinates of the lower left corner of the leftmost character on each line. This is the value that should be used for windows that mostly display text from right to left. </p> <p>If <var>left</var> is non-<code>nil</code> and <var>inverse</var> is <code>nil</code>, this means that the y-pixel value returned for any line specifies the distance in pixels from the left edge of the last (leftmost) glyph of that line to the right edge (body edge if <var>body</var> is non-<code>nil</code>) of <var>window</var>. If <var>left</var> and <var>inverse</var> are both non-<code>nil</code>, the y-pixel value returned for any line specifies the distance in pixels from the left edge (body edge if <var>body</var> is non-<code>nil</code>) of <var>window</var> to the left edge of the last (leftmost) glyph of that line. </p> <p>This function returns <code>nil</code> if the current glyph matrix of <var>window</var> is not up-to-date which usually happens when Emacs is busy, for example, when processing a command. The value should be retrievable though when this function is run from an idle timer with a delay of zero seconds. </p> +</dd> +</dl> <dl> <dt id="line-pixel-height">Function: <strong>line-pixel-height</strong> +</dt> <dd><p>This function returns the height in pixels of the line at point in the selected window. The value includes the line spacing of the line (see <a href="line-height">Line Height</a>). </p></dd> +</dl> <p>When a buffer is displayed with line numbers (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Display-Custom.html#Display-Custom">Display Custom</a> in <cite>The GNU Emacs Manual</cite>), it is sometimes useful to know the width taken for displaying the line numbers. The following function is for Lisp programs which need this information for layout calculations. </p> <dl> <dt id="line-number-display-width">Function: <strong>line-number-display-width</strong> <em>&optional pixelwise</em> +</dt> <dd><p>This function returns the width used for displaying the line numbers in the selected window. If the optional argument <var>pixelwise</var> is the symbol <code>columns</code>, the return value is a float number of the frame’s canonical columns; if <var>pixelwise</var> is <code>t</code> or any other non-<code>nil</code> value, the value is an integer and is measured in pixels. If <var>pixelwise</var> is omitted or <code>nil</code>, the value is the integer number of columns of the font defined for the <code>line-number</code> face, and doesn’t include the 2 columns used to pad the numbers on display. If line numbers are not displayed in the selected window, the value is zero regardless of the value of <var>pixelwise</var>. Use <code>with-selected-window</code> (see <a href="selecting-windows">Selecting Windows</a>) if you need this information about another window. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 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/Size-of-Displayed-Text.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Size-of-Displayed-Text.html</a> + </p> +</div> |