Low-Level Font

Normally, it is not necessary to manipulate fonts directly. In case you need to do so, this section explains how.

In Emacs Lisp, fonts are represented using three different Lisp object types: font objects, font specs, and font entities.

— Function: fontp object &optional type

Return t if object is a font object, font spec, or font entity. Otherwise, return nil.
The optional argument type, if non-nil, determines the exact type of Lisp object to check for. In that case, type should be one of font-object, font-spec, or font-entity.

A font object is a Lisp object that represents a font that Emacs has opened. Font objects cannot be modified in Lisp, but they can be inspected.

— Function: font-at position &optional window string

Return the font object that is being used to display the character at position position in the window window. If window is nil, it defaults to the selected window. If string is nil, position specifies a position in the current buffer; otherwise, string should be a string, and position specifies a position in that string.

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.

— Function: font-spec &rest arguments

Return a new font spec using the specifications in arguments, which should come in property-value pairs. The possible specifications are as follows:
:name
The font name (a string), in either XLFD, Fontconfig, or GTK+ format. See Fonts.
:family
:foundry
:weight
:slant
:width
These have the same meanings as the face attributes of the same name. See Face Attributes.
:size
The font size—either a non-negative integer that specifies the pixel size, or a floating-point number that specifies the point size.
:adstyle
Additional typographic style information for the font, such as ‘sans’. The value should be a string or a symbol.

:registry
The charset registry and encoding of the font, such as ‘iso8859-1’. The value should be a string or a symbol.
:script
The script that the font must support (a symbol).
:lang
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: ‘ja’, ‘ko’, and ‘zh’.
:otf
The font must be an OpenType font that supports these OpenType features, provided Emacs is compiled with a library, such as ‘libotf’ on GNU/Linux, that supports complex text layout for scripts which need that. The value must be a list of the form
               (script-tag langsys-tag gsub gpos)
where script-tag is the OpenType script tag symbol; langsys-tag is the OpenType language system tag symbol, or nil to use the default language system; gsub is a list of OpenType GSUB feature tag symbols, or nil if none is required; and gpos is a list of OpenType GPOS feature tag symbols, or nil if none is required. If gsub or gpos is a list, a nil element in that list means that the font must not match any of the remaining tag symbols. The gpos element may be omitted.

— Function: font-put font-spec property value

Set the font property property in the font-spec font-spec to value.

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.

— Function: find-font font-spec &optional frame

This function returns a font entity that best matches the font spec font-spec on frame frame. If frame is nil, it defaults to the selected frame.

— Function: list-fonts font-spec &optional frame num prefer

This function returns a list of all font entities that match the font spec font-spec.
The optional argument frame, if non-nil, specifies the frame on which the fonts are to be displayed. The optional argument num, if non-nil, should be an integer that specifies the maximum length of the returned list. The optional argument prefer, if non-nil, 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.

If you call set-face-attribute and pass a font spec, font entity, or font name string as the value of the :font 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 :font attribute for that face.

The following functions can be used to obtain information about a font. For these functions, the font argument can be a font object, a font entity, or a font spec.

— Function: font-get font property

This function returns the value of the font property property for font.
If font is a font spec and the font spec does not specify property, the return value is nil. If font is a font object or font entity, the value for the :script property may be a list of scripts supported by the font.

— Function: font-face-attributes font &optional frame

This function returns a list of face attributes corresponding to font. The optional argument frame specifies the frame on which the font is to be displayed. If it is nil, the selected frame is used. The return value has the form
          (:family family :height height :weight weight
             :slant slant :width width)
where the values of family, height, weight, slant, and width are face attribute values. Some of these key-attribute pairs may be omitted from the list if they are not specified by font.

— Function: font-xlfd-name font &optional fold-wildcards

This function returns the XLFD (X Logical Font Descriptor), a string, matching font. See Fonts, for information about XLFDs. If the name is too long for an XLFD (which can contain at most 255 characters), the function returns nil.
If the optional argument fold-wildcards is non-nil, consecutive wildcards in the XLFD are folded into one.

— Function: font-info name &optional frame

This function returns information about a font specified by its name, a string, as it is used on frame. If frame is omitted or nil, it defaults to the selected frame.
The value returned by the function is a vector of the form [opened-name full-name size height baseline-offset relative-compose default-ascent max-width ascent descent space-width average-width filename capability]. Here's the description of each components of this vector:

opened-name
The name used to open the font, a string.
full-name
The full name of the font, a string.
size
The pixel size of the font.
height
The height of the font in pixels.
baseline-offset
The offset in pixels from the ASCII baseline, positive upward.
relative-compose
default-ascent
Numbers controlling how to compose characters.
ascent
descent
The ascent and descent of this font. The sum of these two numbers should be equal to the value of height above.
space-width
The width, in pixels, of the font's space character.
average-width
The average width of the font characters. If this is zero, Emacs uses the value of space-width instead, when it calculates text layout on display.
filename
The file name of the font as a string. This can be nil if the font back-end does not provide a way to find out the font's file name.
capability
A list whose first element is a symbol representing the font type, one of x, opentype, truetype, type1, pcf, or bdf. For OpenType fonts, the list includes 2 additional elements describing the gsub and gpos features supported by the font. Each of these elements is a list of the form ((script (langsys feature...) ...) ...), where script is a symbol representing an OpenType script tag, langsys is a symbol representing an OpenType langsys tag (or nil, which stands for the default langsys), and each feature is a symbol representing an OpenType feature tag.

— Function: query-font font-object

This function returns information about a font-object. (This is in contrast to font-info, which takes the font name, a string, as its argument.)
The value returned by the function is a vector of the form [name filename pixel-size max-width ascent descent space-width average-width capability]. Here's the description of each components of this vector:

name
The font name, a string.
filename
The file name of the font as a string. This can be nil if the font back-end does not provide a way to find out the font's file name.
pixel-size
The pixel size of the font used to open the font.
max-width
The maximum advance width of the font.
ascent
descent
The ascent and descent of this font. The sum of these two numbers gives the font height.
space-width
The width, in pixels, of the font's space character.
average-width
The average width of the font characters. If this is zero, Emacs uses the value of space-width instead, when it calculates text layout on display.
capability
A list whose first element is a symbol representing the font type, one of x, opentype, truetype, type1, pcf, or bdf. For OpenType fonts, the list includes 2 additional elements describing the gsub and gpos features supported by the font. Each of these elements is a list of the form ((script (langsys feature...) ...) ...), where script is a symbol representing an OpenType script tag, langsys is a symbol representing an OpenType langsys tag (or nil, which stands for the default langsys), and each feature is a symbol representing an OpenType feature tag.

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 Face Remapping.

39.12.12 Low-Level Font Representation