path: root/devdocs/elisp/low_002dlevel-font.html

 <h4 class="subsection">Low-Level Font Representation</h4>  <p>Normally, it is not necessary to manipulate fonts directly. In case you need to do so, this section explains how. </p> <p>In Emacs Lisp, fonts are represented using three different Lisp object types: <em>font objects</em>, <em>font specs</em>, and <em>font entities</em>. </p> <dl> <dt id="fontp">Function: <strong>fontp</strong> <em>object &amp;optional type</em>
</dt> <dd>
<p>Return <code>t</code> if <var>object</var> is a font object, font spec, or font entity. Otherwise, return <code>nil</code>. </p> <p>The optional argument <var>type</var>, if non-<code>nil</code>, determines the exact type of Lisp object to check for. In that case, <var>type</var> should be one of <code>font-object</code>, <code>font-spec</code>, or <code>font-entity</code>. </p>
</dd>
</dl>  <p>A font object is a Lisp object that represents a font that Emacs has <em>opened</em>. Font objects cannot be modified in Lisp, but they can be inspected. </p> <dl> <dt id="font-at">Function: <strong>font-at</strong> <em>position &amp;optional window string</em>
</dt> <dd><p>Return the font object that is being used to display the character at position <var>position</var> in the window <var>window</var>. If <var>window</var> is <code>nil</code>, it defaults to the selected window. If <var>string</var> is <code>nil</code>, <var>position</var> specifies a position in the current buffer; otherwise, <var>string</var> should be a string, and <var>position</var> specifies a position in that string. </p></dd>
</dl>  <p>A font spec is a Lisp object that contains a set of specifications that can be used to find a font. More than one font may match the specifications in a font spec. </p> <dl> <dt id="font-spec">Function: <strong>font-spec</strong> <em>&amp;rest arguments</em>
</dt> <dd>
<p>Return a new font spec using the specifications in <var>arguments</var>, which should come in <code>property</code>-<code>value</code> pairs. The possible specifications are as follows: </p> <dl compact> <dt><code>:name</code></dt> <dd>
<p>The font name (a string), in either XLFD, Fontconfig, or GTK+ format. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Fonts.html#Fonts">Fonts</a> in <cite>The GNU Emacs Manual</cite>. </p> </dd> <dt><code>:family</code></dt> <dt><code>:foundry</code></dt> <dt><code>:weight</code></dt> <dt><code>:slant</code></dt> <dt><code>:width</code></dt> <dd>
<p>These have the same meanings as the face attributes of the same name. See <a href="face-attributes">Face Attributes</a>. <code>:family</code> and <code>:foundry</code> are strings, while the other three are symbols. As example values, <code>:slant</code> may be <code>italic</code>, <code>:weight</code> may be <code>bold</code> and <code>:width</code> may be <code>normal</code>. </p> </dd> <dt><code>:size</code></dt> <dd>
<p>The font size—either a non-negative integer that specifies the pixel size, or a floating-point number that specifies the point size. </p> </dd> <dt><code>:adstyle</code></dt> <dd>
<p>Additional typographic style information for the font, such as ‘<samp>sans</samp>’. The value should be a string or a symbol. </p>  </dd> <dt><code>:registry</code></dt> <dd>
<p>The charset registry and encoding of the font, such as ‘<samp>iso8859-1</samp>’. The value should be a string or a symbol. </p> </dd> <dt><code>:dpi</code></dt> <dd>
<p>The resolution in dots per inch for which the font is designed. The value must be a non-negative number. </p> </dd> <dt><code>:spacing</code></dt> <dd>
<p>The spacing of the font: proportional, dual, mono, or charcell. The value should be either an integer (0 for proportional, 90 for dual, 100 for mono, 110 for charcell) or a one-letter symbol (one of <code>P</code>, <code>D</code>, <code>M</code>, or <code>C</code>). </p> </dd> <dt><code>:avgwidth</code></dt> <dd>
<p>The average width of the font in 1/10 pixel units. The value should be a non-negative number. </p> </dd> <dt><code>:script</code></dt> <dd>
<p>The script that the font must support (a symbol). </p> </dd> <dt><code>:lang</code></dt> <dd>
<p>The language that the font should support. The value should be a symbol whose name is a two-letter ISO-639 language name. On X, the value is matched against the “Additional Style” field of the XLFD name of a font, if it is non-empty. On MS-Windows, fonts matching the spec are required to support codepages needed for the language. Currently, only a small set of CJK languages is supported with this property: ‘<samp>ja</samp>’, ‘<samp>ko</samp>’, and ‘<samp>zh</samp>’. </p> </dd> <dt><code>:otf</code></dt> <dd>
 <p>The font must be an OpenType font that supports these OpenType features, provided Emacs is compiled with a library, such as ‘<samp>libotf</samp>’ on GNU/Linux, that supports complex text layout for scripts which need that. The value must be a list of the form </p> <div class="example"> <pre class="example"><code>(<var>script-tag</var> <var>langsys-tag</var> <var>gsub</var> <var>gpos</var>)</code>
</pre>
</div> <p>where <var>script-tag</var> is the OpenType script tag symbol; <var>langsys-tag</var> is the OpenType language system tag symbol, or <code>nil</code> to use the default language system; <code>gsub</code> is a list of OpenType GSUB feature tag symbols, or <code>nil</code> if none is required; and <code>gpos</code> is a list of OpenType GPOS feature tag symbols, or <code>nil</code> if none is required. If <code>gsub</code> or <code>gpos</code> is a list, a <code>nil</code> element in that list means that the font must not match any of the remaining tag symbols. The <code>gpos</code> element may be omitted. For the list of OpenType script, language, and feature tags, see <a href="https://docs.microsoft.com/en-us/typography/opentype/spec/ttoreg">the list of registered OTF tags</a>. </p> </dd> <dt><code>:type</code></dt> <dd>
 <p>The symbol that specifies the <em>font backend</em> used to draw the characters. The possible values depend on the platform and on how Emacs was configured at build time. Typical values include <code>ftcrhb</code> and <code>xfthb</code> on X, <code>harfbuzz</code> on MS-Windows, <code>ns</code> on GNUstep, etc. It can also be <code>nil</code> if left unspecified, typically in a font-spec. </p>
</dd> </dl> </dd>
</dl> <dl> <dt id="font-put">Function: <strong>font-put</strong> <em>font-spec property value</em>
</dt> <dd><p>Set the font property <var>property</var> in the font-spec <var>font-spec</var> to <var>value</var>. The <var>property</var> can any of the ones described above. </p></dd>
</dl>  <p>A font entity is a reference to a font that need not be open. Its properties are intermediate between a font object and a font spec: like a font object, and unlike a font spec, it refers to a single, specific font. Unlike a font object, creating a font entity does not load the contents of that font into computer memory. Emacs may open multiple font objects of different sizes from a single font entity referring to a scalable font. </p> <dl> <dt id="find-font">Function: <strong>find-font</strong> <em>font-spec &amp;optional frame</em>
</dt> <dd><p>This function returns a font entity that best matches the font spec <var>font-spec</var> on frame <var>frame</var>. If <var>frame</var> is <code>nil</code>, it defaults to the selected frame. </p></dd>
</dl> <dl> <dt id="list-fonts">Function: <strong>list-fonts</strong> <em>font-spec &amp;optional frame num prefer</em>
</dt> <dd>
<p>This function returns a list of all font entities that match the font spec <var>font-spec</var>. </p> <p>The optional argument <var>frame</var>, if non-<code>nil</code>, specifies the frame on which the fonts are to be displayed. The optional argument <var>num</var>, if non-<code>nil</code>, should be an integer that specifies the maximum length of the returned list. The optional argument <var>prefer</var>, if non-<code>nil</code>, should be another font spec, which is used to control the order of the returned list; the returned font entities are sorted in order of decreasing closeness to that font spec. </p>
</dd>
</dl> <p>If you call <code>set-face-attribute</code> and pass a font spec, font entity, or font name string as the value of the <code>:font</code> attribute, Emacs opens the best matching font that is available for display. It then stores the corresponding font object as the actual value of the <code>:font</code> attribute for that face. </p> <p>The following functions can be used to obtain information about a font. For these functions, the <var>font</var> argument can be a font object, a font entity, or a font spec. </p> <dl> <dt id="font-get">Function: <strong>font-get</strong> <em>font property</em>
</dt> <dd>
<p>This function returns the value of the font property <var>property</var> for <var>font</var>. The <var>property</var> can any of the ones that <code>font-spec</code> supports. </p> <p>If <var>font</var> is a font spec and the font spec does not specify <var>property</var>, the return value is <code>nil</code>. If <var>font</var> is a font object or font entity, the value for the <var>:script</var> property may be a list of scripts supported by the font, and the value of the <code>:otf</code> property is a cons of the form <code>(<var>gsub</var> . <var>gpos</var>)</code>, where <var>gsub</var> and <var>gpos</var> are lists representing OpenType features supported by the font, of the form </p> <div class="example"> <pre class="example">((<var>script-tag</var> (<var>langsys-tag</var> <var>feature</var>…) …) …)
</pre>
</div> <p>where <var>script-tag</var>, <var>langsys-tag</var>, and <var>feature</var> are symbols representing OpenType layout tags. </p> <p>If <var>font</var> is a font object, the special property <code>:combining-capability</code> is non-<code>nil</code> if the font backend of <var>font</var> supports rendering of combining characters for non-OpenType fonts. </p>
</dd>
</dl> <dl> <dt id="font-face-attributes">Function: <strong>font-face-attributes</strong> <em>font &amp;optional frame</em>
</dt> <dd>
<p>This function returns a list of face attributes corresponding to <var>font</var>. The optional argument <var>frame</var> specifies the frame on which the font is to be displayed. If it is <code>nil</code>, the selected frame is used. The return value has the form </p> <div class="example"> <pre class="example">(:family <var>family</var> :height <var>height</var> :weight <var>weight</var>
   :slant <var>slant</var> :width <var>width</var>)
</pre>
</div> <p>where the values of <var>family</var>, <var>height</var>, <var>weight</var>, <var>slant</var>, and <var>width</var> are face attribute values. Some of these key-attribute pairs may be omitted from the list if they are not specified by <var>font</var>. </p>
</dd>
</dl> <dl> <dt id="font-xlfd-name">Function: <strong>font-xlfd-name</strong> <em>font &amp;optional fold-wildcards</em>
</dt> <dd>
<p>This function returns the XLFD (X Logical Font Descriptor), a string, matching <var>font</var>. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Fonts.html#Fonts">Fonts</a> in <cite>The GNU Emacs Manual</cite>, for information about XLFDs. If the name is too long for an XLFD (which can contain at most 255 characters), the function returns <code>nil</code>. </p> <p>If the optional argument <var>fold-wildcards</var> is non-<code>nil</code>, consecutive wildcards in the XLFD are folded into one. </p>
</dd>
</dl> <p>The following two functions return important information about a font. </p> <dl> <dt id="font-info">Function: <strong>font-info</strong> <em>name &amp;optional frame</em>
</dt> <dd>
<p>This function returns information about a font specified by its <var>name</var>, a string, as it is used on <var>frame</var>. If <var>frame</var> is omitted or <code>nil</code>, it defaults to the selected frame. </p> <p>The value returned by the function is a vector of the form <code>[<var>opened-name</var> <var>full-name</var> <var>size</var> <var>height</var>
<var>baseline-offset</var> <var>relative-compose</var> <var>default-ascent</var>
<var>max-width</var> <var>ascent</var> <var>descent</var> <var>space-width</var>
<var>average-width</var> <var>filename</var> <var>capability</var>]</code>. Here’s the description of each components of this vector: </p> <dl compact> <dt><var>opened-name</var></dt> <dd>
<p>The name used to open the font, a string. </p> </dd> <dt><var>full-name</var></dt> <dd>
<p>The full name of the font, a string. </p> </dd> <dt><var>size</var></dt> <dd>
<p>The pixel size of the font. </p> </dd> <dt><var>height</var></dt> <dd>
<p>The height of the font in pixels. </p> </dd> <dt><var>baseline-offset</var></dt> <dd>
<p>The offset in pixels from the <acronym>ASCII</acronym> baseline, positive upward. </p> </dd> <dt><var>relative-compose</var></dt> <dt><var>default-ascent</var></dt> <dd>
<p>Numbers controlling how to compose characters. </p> </dd> <dt><var>max-width</var></dt> <dd>
<p>The maximum advance width of the font. </p> </dd> <dt><var>ascent</var></dt> <dt><var>descent</var></dt> <dd>
<p>The ascent and descent of this font. The sum of these two numbers should be equal to the value of <var>height</var> above. </p> </dd> <dt><var>space-width</var></dt> <dd>
<p>The width, in pixels, of the font’s space character. </p> </dd> <dt><var>average-width</var></dt> <dd>
<p>The average width of the font characters. If this is zero, Emacs uses the value of <var>space-width</var> instead, when it calculates text layout on display. </p> </dd> <dt><var>filename</var></dt> <dd>
<p>The file name of the font as a string. This can be <code>nil</code> if the font back-end does not provide a way to find out the font’s file name. </p> </dd> <dt><var>capability</var></dt> <dd><p>A list whose first element is a symbol representing the font type, one of <code>x</code>, <code>opentype</code>, <code>truetype</code>, <code>type1</code>, <code>pcf</code>, or <code>bdf</code>. For OpenType fonts, the list includes 2 additional elements describing the <small>GSUB</small> and <small>GPOS</small> features supported by the font. Each of these elements is a list of the form <code>((<var>script</var> (<var>langsys</var> <var>feature</var> …) …)
…)</code>, where <var>script</var> is a symbol representing an OpenType script tag, <var>langsys</var> is a symbol representing an OpenType langsys tag (or <code>nil</code>, which stands for the default langsys), and each <var>feature</var> is a symbol representing an OpenType feature tag. </p></dd> </dl> </dd>
</dl> <dl> <dt id="query-font">Function: <strong>query-font</strong> <em>font-object</em>
</dt> <dd>
<p>This function returns information about a <var>font-object</var>. (This is in contrast to <code>font-info</code>, which takes the font name, a string, as its argument.) </p> <p>The value returned by the function is a vector of the form <code>[<var>name</var> <var>filename</var> <var>pixel-size</var> <var>max-width</var>
<var>ascent</var> <var>descent</var> <var>space-width</var> <var>average-width</var>
<var>capability</var>]</code>. Here’s the description of each components of this vector: </p> <dl compact> <dt><var>name</var></dt> <dd>
<p>The font name, a string. </p> </dd> <dt><var>filename</var></dt> <dd>
<p>The file name of the font as a string. This can be <code>nil</code> if the font back-end does not provide a way to find out the font’s file name. </p> </dd> <dt><var>pixel-size</var></dt> <dd>
<p>The pixel size of the font used to open the font. </p> </dd> <dt><var>max-width</var></dt> <dd>
<p>The maximum advance width of the font. </p> </dd> <dt><var>ascent</var></dt> <dt><var>descent</var></dt> <dd>
<p>The ascent and descent of this font. The sum of these two numbers gives the font height. </p> </dd> <dt><var>space-width</var></dt> <dd>
<p>The width, in pixels, of the font’s space character. </p> </dd> <dt><var>average-width</var></dt> <dd>
<p>The average width of the font characters. If this is zero, Emacs uses the value of <var>space-width</var> instead, when it calculates text layout on display. </p> </dd> <dt><var>capability</var></dt> <dd><p>A list whose first element is a symbol representing the font type, one of <code>x</code>, <code>opentype</code>, <code>truetype</code>, <code>type1</code>, <code>pcf</code>, or <code>bdf</code>. For OpenType fonts, the list includes 2 additional elements describing the <small>GSUB</small> and <small>GPOS</small> features supported by the font. Each of these elements is a list of the form <code>((<var>script</var> (<var>langsys</var> <var>feature</var> …) …)
…)</code>, where <var>script</var> is a symbol representing an OpenType script tag, <var>langsys</var> is a symbol representing an OpenType langsys tag (or <code>nil</code>, which stands for the default langsys), and each <var>feature</var> is a symbol representing an OpenType feature tag. </p></dd> </dl> </dd>
</dl>  <p>The following four functions return size information about fonts used by various faces, allowing various layout considerations in Lisp programs. These functions take face remapping into consideration, returning information about the remapped face, if the face in question was remapped. See <a href="face-remapping">Face Remapping</a>. </p> <dl> <dt id="default-font-width">Function: <strong>default-font-width</strong>
</dt> <dd><p>This function returns the average width in pixels of the font used by the current buffer’s default face, as that face is defined for the selected frame. </p></dd>
</dl> <dl> <dt id="default-font-height">Function: <strong>default-font-height</strong>
</dt> <dd><p>This function returns the height in pixels of the font used by the current buffer’s default face, as that face is defined for the selected frame. </p></dd>
</dl> <dl> <dt id="window-font-width">Function: <strong>window-font-width</strong> <em>&amp;optional window face</em>
</dt> <dd><p>This function returns the average width in pixels for the font used by <var>face</var> in <var>window</var>. The specified <var>window</var> must be a live window. If <code>nil</code> or omitted, <var>window</var> defaults to the selected window, and <var>face</var> defaults to the default face in <var>window</var>. </p></dd>
</dl> <dl> <dt id="window-font-height">Function: <strong>window-font-height</strong> <em>&amp;optional window face</em>
</dt> <dd><p>This function returns the height in pixels for the font used by <var>face</var> in <var>window</var>. The specified <var>window</var> must be a live window. If <code>nil</code> or omitted, <var>window</var> defaults to the selected window, and <var>face</var> defaults to the default face in <var>window</var>. </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/Low_002dLevel-Font.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Low_002dLevel-Font.html</a>
  </p>
</div>