elisp: Low-Level Font
37.12.12 Low-Level Font Representation
--------------------------------------
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. 
(emacs)Fonts.
‘:family’
‘:foundry’
‘:weight’
‘:slant’
‘:width’
These have the same meanings as the face attributes of the
same name. 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. (emacs)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.
The following two functions return important information about a
font.
-- 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. Face Remapping.
-- Function: default-font-width
This function returns the average width in pixels of the font used
by the current buffer’s default face.
-- Function: default-font-height
This function returns the height in pixels of the font used by the
current buffer’s default face.
-- Function: window-font-width &optional window face
This function returns the average width in pixels for the font used
by FACE in WINDOW. The specified WINDOW must be a live window. If
‘nil’ or omitted, WINDOW defaults to the selected window, and FACE
defaults to the default face in WINDOW.
-- Function: window-font-height &optional window face
This function returns the height in pixels for the font used by
FACE in WINDOW. The specified WINDOW must be a live window. If
‘nil’ or omitted, WINDOW defaults to the selected window, and FACE
defaults to the default face in WINDOW.
Info Catalog
elisp: Fontsets
elisp: Faces