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.
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.
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.
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 in The GNU Emacs Manual.
: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).
:otf
The font must be an OpenType font that supports these OpenType features, provided Emacs is compiled with support for ‘libotf’ (a library for performing complex text layout in certain scripts). 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.
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.
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.
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.
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.
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.
This function returns the XLFD (X Logical Font Descriptor), a string,
matching font. See Fonts in The GNU Emacs Manual, 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.