comparison doc/lispref/display.texi @ 101033:652cf1b0fd5a

(Font Lookup): Remove obsolete function x-font-family-list. x-list-fonts accepts Fontconfig/GTK syntax. (Low-Level Font): Rename from Fonts, move to end of Faces section. (Font Selection): Reorder order of variable descriptions. Minor clarifications.

101032:097a50a78f81

* Attribute Functions::  Functions to examine and set face attributes.
* Displaying Faces::     How Emacs combines the faces specified for a character.
* Face Remapping::     Remapping faces to alternative definitions.
* Face Functions::      How to define and examine faces.
* Auto Faces::          Hook for automatic face assignment.
* Fonts::               Lisp representation for character display fonts.
* Font Selection::      Finding the best available font for a face.
* Font Lookup::         Looking up the names of available fonts
                          and information about them.
* Fontsets::            A fontset is a collection of fonts
                          that handle a range of character sets.
@end menu

@node Defining Faces
@subsection Defining Faces

For efficiency, we recommend writing these functions so that they
usually assign faces to around 400 to 600 characters at each call.
@end defvar

@node Fonts
@subsection Fonts

  Before Emacs can draw a character on a particular display, it must
select a @dfn{font} for that character@footnote{In this context, the
term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
Mode}).}.  Normally, Emacs automatically chooses a font for displaying
a character based on the faces assigned to that
character---specifically, the face attributes @code{:family},
@code{:weight}, @code{:slant}, and @code{:width}.  The choice of font
also depends on the character to be displayed; some fonts can only
display a limited set of characters.  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: @dfn{font objects}, @dfn{font specs}, and @dfn{font
entities}.

@defun fontp object &optional type
Return @code{t} if @var{object} is a font object, font spec, or font
entity.  Otherwise, return @code{nil}.

@code{font-entity}.
@end defun

  A font object is a Lisp object that represents a font that Emacs has
@dfn{opened}.  Font objects cannot be modified in Lisp, but they can
be inspected.  For instance, if you call @code{set-face-attribute} and
pass a font spec, font entity, or font name string as the value of the
@code{: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 @code{:font} attribute for that face.

@defun font-at position &optional window string

which should come in @code{property}-@code{value} pairs.  The possible
specifications are as follows:

@table @code
@item :name
The font name string, in either XLFD, Fontconfig, or GTK format.
@xref{Font X,, Font Specification Options, emacs, The GNU Emacs
Manual}.

@item :family
@itemx :foundry

@defun font-put font-spec property value
Set the font property @var{property} in the font-spec @var{font-spec}
to @var{value}.
@end defun

  A font entity is a reference to a font that need not have been
opened.  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, it can be modified in
Lisp, and creating a font entity does not load the contents of that
font into computer memory.

@defun find-font font-spec &optional frame
Return a font entity that best matches the font spec @var{font-spec}
on frame @var{frame}.  If @var{frame} is @code{nil}, it defaults to
the selected frame.
@end defun

@defun list-fonts font-spec &optional frame num prefer
This function returns a list of all font entities that match the font
spec @var{font-spec}.

The optional argument @var{frame}, if non-@code{nil}, specifies the
frame on which the fonts are to be displayed.  The optional argument
@var{num}, if non-@code{nil}, should be an integer; in that case, the
function returns a list of at most @var{num} font entities.  The
optional argument @var{prefer}, if non-@code{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.
@end defun

  The following functions can be used to obtain information about font
objects, font entities, and font specs alike:

@defun font-get font property
This function returns the value of the font property @var{property}
for @var{font}, which should be either a font object, font spec, or
font entity.

If @var{font} is a font spec and the font spec does not specify
@var{property}, the return value is @code{nil}.  If @var{font} is a
font object or font entity, the value for the @var{:script} property
may be a list of scripts supported by the font.
@end defun

@defun font-face-attributes font &optional frame
This function returns a list of face attributes corresponding to
@var{font} , which should be either a font name, a font object, a font
spec, or a font entity.  The optional argument @var{frame} specifies
the frame on which the font is to be displayed.  If it is @code{nil},
the selected frame is used.  The return value has the form

@smallexample
(:family @var{family} :height @var{height} :weight @var{weight}
   :slant @var{slant} :width @var{width})
@end smallexample

@end defun

@defun font-xlfd-name font &optional fold-wildcards
This function returns the XLFD (X Logical Font Descriptor), a string,
matching @var{font}.  @xref{Font X,, Font Specification Options,
emacs, The GNU Emacs Manual}, for information about XLFDs.  @var{font}
should be a font spec, font entity, or font object.  If the name is
too long for an XLFD (which can contain at most 255 characters), the
function returns @code{nil}.

If the optional argument @var{fold-wildcards} is non-@code{nil},
consecutive wildcards in the XLFD are folded into one.
@end defun

@node Font Selection
@subsection Font Selection

  Emacs tries to find an available font to display each character
based on the face attributes and the character's registry and
encoding.  If there is a font that matches exactly, it is used, of
course.  The hard case is when no available font exactly fits the
specification.  Then Emacs looks for one that is ``close''---one
attribute at a time.  You can specify the order to consider the
attributes.  In the case where a specified font family is not
available, you can specify a set of mappings for alternatives to try.

@defvar face-font-selection-order
This variable specifies the order of importance of the face attributes
@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}.  The
value should be a list containing those four symbols, in order of
decreasing importance.

Font selection first finds the best available matches for the first
attribute listed; then, among the fonts which are best in that way, it
searches for the best matches in the second attribute, and so on.

The attributes @code{:weight} and @code{:width} have symbolic values in
a range centered around @code{normal}.  Matches that are more extreme
(farther from @code{normal}) are somewhat preferred to matches that are
less extreme (closer to @code{normal}); this is designed to ensure that
non-normal faces contrast with normal ones, whenever possible.

The default is @code{(:width :height :weight :slant)}, which means first
find the fonts closest to the specified @code{:width}, then---among the
fonts with that width---find a best match for the specified font height,
and so on.

One example of a case where this variable makes a difference is when the
default font has no italic equivalent.  With the default ordering, the
@code{italic} face will use a non-italic font that is similar to the
default one.  But if you put @code{:slant} before @code{:height}, the
@code{italic} face will use an italic font, even if its height is not
quite right.
@end defvar

@defvar face-font-family-alternatives
This variable lets you specify alternative font families to try, if a
given family is specified and doesn't exist.  Each element should have
this form:

@example
(@var{family} @var{alternate-families}@dots{})
@end example

If @var{family} is specified but not available, Emacs will try the other
families given in @var{alternate-families}, one by one, until it finds a
family that does exist.
@end defvar

@defvar face-font-registry-alternatives
This variable lets you specify alternative font registries to try, if a
given registry is specified and doesn't exist.  Each element should have
this form:

@example
(@var{registry} @var{alternate-registries}@dots{})
@end example

If @var{registry} is specified but not available, Emacs will try the
other registries given in @var{alternate-registries}, one by one,
until it finds a registry that does exist.
@end defvar

  Emacs can make use of scalable fonts, but by default it does not use
them, since the use of too many or too big scalable fonts can crash
XFree86 servers.

@defvar scalable-fonts-allowed
This variable controls which scalable fonts to use.  A value of
@code{nil}, the default, means do not use scalable fonts.  @code{t}
means to use any scalable font that seems appropriate for the text.

Otherwise, the value must be a list of regular expressions.  Then a
scalable font is enabled for use if its name matches any regular
expression in the list.  For example,

@example
(setq scalable-fonts-allowed '("muleindian-2$"))
@end example

@noindent
allows the use of scalable fonts with registry @code{muleindian-2}.
@end defvar

@defvar face-font-rescale-alist
This variable specifies scaling for certain faces.  Its value should
be a list of elements of the form

@example
(@var{fontname-regexp} . @var{scale-factor})
@end example

If @var{fontname-regexp} matches the font name that is about to be
used, this says to choose a larger similar font according to the
factor @var{scale-factor}.  You would use this feature to normalize
the font size if certain fonts are bigger or smaller than their
nominal heights and widths would suggest.
@end defvar

@node Font Lookup
@subsection Looking Up Fonts

@defun x-list-fonts pattern &optional face frame maximum
This function returns a list of available font names that match
@var{pattern}.  If the optional arguments @var{face} and @var{frame} are
specified, then the list is limited to fonts that are the same size as
@var{face} currently is on @var{frame}.

The argument @var{pattern} should be a string, perhaps with wildcard
characters: the @samp{*} character matches any substring, and the
@samp{?} character matches any single character.  Pattern matching
of font names ignores case.

If you specify @var{face} and @var{frame}, @var{face} should be a face name
(a symbol) and @var{frame} should be a frame.

The optional argument @var{maximum} sets a limit on how many fonts to
return.  If this is non-@code{nil}, then the return value is truncated
after the first @var{maximum} matching fonts.  Specifying a small value
for @var{maximum} can make this function much faster, in cases where
many fonts match the pattern.
@end defun

@defun x-family-fonts &optional family frame
This function returns a list describing the available fonts for family
@var{family} on @var{frame}.  If @var{family} is omitted or @code{nil},
this list applies to all families, and therefore, it contains all
available fonts.  Otherwise, @var{family} must be a string; it may
contain the wildcards @samp{?} and @samp{*}.

The list describes the display that @var{frame} is on; if @var{frame} is
omitted or @code{nil}, it applies to the selected frame's display
(@pxref{Input Focus}).

The list contains a vector of the following form for each font:

@example
[@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
 @var{fixed-p} @var{full} @var{registry-and-encoding}]
@end example

The first five elements correspond to face attributes; if you
specify these attributes for a face, it will use this font.

The last three elements give additional information about the font.
@var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
@var{full} is the full name of the font, and
@var{registry-and-encoding} is a string giving the registry and
encoding of the font.

The result list is sorted according to the current face font sort order.
@end defun

@defun x-font-family-list &optional frame
This function returns a list of the font families available for
@var{frame}'s display.  If @var{frame} is omitted or @code{nil}, it
describes the selected frame's display (@pxref{Input Focus}).

The value is a list of elements of this form:

@example
(@var{family} . @var{fixed-p})
@end example

@noindent
Here @var{family} is a font family, and @var{fixed-p} is
non-@code{nil} if fonts of that family are fixed-pitch.
@end defun

@defvar font-list-limit
This variable specifies maximum number of fonts to consider in font
matching.  The function @code{x-family-fonts} will not return more than
that many fonts, and font selection will consider only that many fonts
when searching a matching font for face attributes.  The default is
currently 100.
@end defvar

@node Fontsets
@subsection Fontsets

  A @dfn{fontset} is a list of fonts, each assigned to a range of
character codes.  An individual font cannot display the whole range of
characters that Emacs supports, but a fontset can.  Fontsets have names,
just as fonts do, and you can use a fontset name in place of a font name
when you specify the ``font'' for a frame or a face.  Here is
information about defining a fontset under Lisp program control.

@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
This function defines a new fontset according to the specification
string @var{fontset-spec}.  The string should have this format:

@smallexample
@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
@end smallexample

@noindent
Whitespace characters before and after the commas are ignored.

The first part of the string, @var{fontpattern}, should have the form of
a standard X font name, except that the last two fields should be
@samp{fontset-@var{alias}}.

The new fontset has two names, one long and one short.  The long name is
@var{fontpattern} in its entirety.  The short name is
@samp{fontset-@var{alias}}.  You can refer to the fontset by either
name.  If a fontset with the same name already exists, an error is
signaled, unless @var{noerror} is non-@code{nil}, in which case this
function does nothing.

If optional argument @var{style-variant-p} is non-@code{nil}, that says
to create bold, italic and bold-italic variants of the fontset as well.
These variant fontsets do not have a short name, only a long one, which
is made by altering @var{fontpattern} to indicate the bold or italic
status.

The specification string also says which fonts to use in the fontset.
See below for the details.
@end defun

  The construct @samp{@var{charset}:@var{font}} specifies which font to
use (in this fontset) for one particular character set.  Here,
@var{charset} is the name of a character set, and @var{font} is the font
to use for that character set.  You can use this construct any number of
times in the specification string.

  For the remaining character sets, those that you don't specify
explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
@samp{fontset-@var{alias}} with a value that names one character set.
For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
with @samp{ISO8859-1}.

  In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard.  This is to prevent use of
auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
for editing, and scaling a smaller font is not useful because it is
better to use the smaller font in its own size, which Emacs does.

  Thus if @var{fontpattern} is this,

@example
-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
@end example

@noindent
the font specification for @acronym{ASCII} characters would be this:

@example
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
@end example

@noindent
and the font specification for Chinese GB2312 characters would be this:

@example
-*-fixed-medium-r-normal-*-24-*-gb2312*-*
@end example

  You may not have any Chinese font matching the above font
specification.  Most X distributions include only Chinese fonts that
have @samp{song ti} or @samp{fangsong ti} in the @var{family} field.  In
such a case, @samp{Fontset-@var{n}} can be specified as below:

@smallexample
Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
@end smallexample

@noindent
Then, the font specifications for all but Chinese GB2312 characters have
@samp{fixed} in the @var{family} field, and the font specification for
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.

@defun set-fontset-font name character fontname &optional frame
This function modifies the existing fontset @var{name} to
use the font name @var{fontname} for the character @var{character}.

If @var{name} is @code{nil}, this function modifies the default
fontset, whose short name is @samp{fontset-default}.

@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
@var{from} and @var{to} are character codepoints.  In that case, use
@var{fontname} for all characters in the range @var{from} and @var{to}
(inclusive).

@var{character} may be a charset.  In that case, use
@var{fontname} for all character in the charsets.

@var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
where @var{family} is a family name of a font (possibly including a
foundry name at the head), @var{registry} is a registry name of a font
(possibly including an encoding name at the tail).

For instance, this changes the default fontset to use a font of which
registry name is @samp{JISX0208.1983} for all characters belonging to
the charset @code{japanese-jisx0208}.

@smallexample
(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
@end smallexample
@end defun

@defun char-displayable-p char
This function returns @code{t} if Emacs ought to be able to display
@var{char}.  More precisely, if the selected frame's fontset has a
font to display the character set that @var{char} belongs to.

Fontsets can specify a font on a per-character basis; when the fontset
does that, this function's value may not be accurate.
@end defun

@node Fringes
@section Fringes
@cindex fringes

101033:652cf1b0fd5a

* Attribute Functions::  Functions to examine and set face attributes.
* Displaying Faces::     How Emacs combines the faces specified for a character.
* Face Remapping::     Remapping faces to alternative definitions.
* Face Functions::      How to define and examine faces.
* Auto Faces::          Hook for automatic face assignment.
* Font Selection::      Finding the best available font for a face.
* Font Lookup::         Looking up the names of available fonts
                          and information about them.
* Fontsets::            A fontset is a collection of fonts
                          that handle a range of character sets.
* Low-Level Font::      Lisp representation for character display fonts.
@end menu

@node Defining Faces
@subsection Defining Faces

For efficiency, we recommend writing these functions so that they
usually assign faces to around 400 to 600 characters at each call.
@end defvar

@node Font Selection
@subsection Font Selection

  Before Emacs can draw a character on a particular display, it must
select a @dfn{font} for that character@footnote{In this context, the
term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
Mode}).}.  Normally, Emacs automatically chooses a font based on the
faces assigned to that character---specifically, the face attributes
@code{:family}, @code{:weight}, @code{:slant}, and @code{:width}
(@pxref{Face Attributes}).  The choice of font also depends on the
character to be displayed; some fonts can only display a limited set
of characters.  If no available font exactly fits the requirements,
Emacs looks for the @dfn{closest matching font}.  The variables in
this section control how Emacs makes this selection.

@defvar face-font-family-alternatives
If a given family is specified but does not exist, this variable
specifies alternative font families to try.  Each element should have
this form:

@example
(@var{family} @var{alternate-families}@dots{})
@end example

If @var{family} is specified but not available, Emacs will try the other
families given in @var{alternate-families}, one by one, until it finds a
family that does exist.
@end defvar

@defvar face-font-selection-order
If there is no font that exactly matches all desired face attributes
(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}),
this variable specifies the order in which these attributes should be
considered when selecting the closest matching font.  The value should
be a list containing those four attribute symbols, in order of
decreasing importance.  The default is @code{(:width :height :weight
:slant)}.

Font selection first finds the best available matches for the first
attribute in the list; then, among the fonts which are best in that
way, it searches for the best matches in the second attribute, and so
on.

The attributes @code{:weight} and @code{:width} have symbolic values in
a range centered around @code{normal}.  Matches that are more extreme
(farther from @code{normal}) are somewhat preferred to matches that are
less extreme (closer to @code{normal}); this is designed to ensure that
non-normal faces contrast with normal ones, whenever possible.

One example of a case where this variable makes a difference is when the
default font has no italic equivalent.  With the default ordering, the
@code{italic} face will use a non-italic font that is similar to the
default one.  But if you put @code{:slant} before @code{:height}, the
@code{italic} face will use an italic font, even if its height is not
quite right.
@end defvar

@defvar face-font-registry-alternatives
This variable lets you specify alternative font registries to try, if a
given registry is specified and doesn't exist.  Each element should have
this form:

@example
(@var{registry} @var{alternate-registries}@dots{})
@end example

If @var{registry} is specified but not available, Emacs will try the
other registries given in @var{alternate-registries}, one by one,
until it finds a registry that does exist.
@end defvar

  Emacs can make use of scalable fonts, but by default it does not use
them.

@defvar scalable-fonts-allowed
This variable controls which scalable fonts to use.  A value of
@code{nil}, the default, means do not use scalable fonts.  @code{t}
means to use any scalable font that seems appropriate for the text.

Otherwise, the value must be a list of regular expressions.  Then a
scalable font is enabled for use if its name matches any regular
expression in the list.  For example,

@example
(setq scalable-fonts-allowed '("muleindian-2$"))
@end example

@noindent
allows the use of scalable fonts with registry @code{muleindian-2}.
@end defvar

@defvar face-font-rescale-alist
This variable specifies scaling for certain faces.  Its value should
be a list of elements of the form

@example
(@var{fontname-regexp} . @var{scale-factor})
@end example

If @var{fontname-regexp} matches the font name that is about to be
used, this says to choose a larger similar font according to the
factor @var{scale-factor}.  You would use this feature to normalize
the font size if certain fonts are bigger or smaller than their
nominal heights and widths would suggest.
@end defvar

@node Font Lookup
@subsection Looking Up Fonts

@defun x-list-fonts name &optional reference-face frame maximum
This function returns a list of available font names that match
@var{name}.  @var{name} should be a string containing a font name in
either the Fontconfig, GTK, or XLFD format (@pxref{Font X,, Font
Specification Options, emacs, The GNU Emacs Manual}).  Within an XLFD
string, wildcard characters may be used: the @samp{*} character
matches any substring, and the @samp{?} character matches any single
character.  Case is ignored when matching font names.

If the optional arguments @var{reference-face} and @var{frame} are
specified, the returned list includes only fonts that are the same
size as @var{reference-face} (a face name) currently is on the frame
@var{frame}.

The optional argument @var{maximum} sets a limit on how many fonts to
return.  If it is non-@code{nil}, then the return value is truncated
after the first @var{maximum} matching fonts.  Specifying a small
value for @var{maximum} can make this function much faster, in cases
where many fonts match the pattern.
@end defun

@defun x-family-fonts &optional family frame
This function returns a list describing the available fonts for family
@var{family} on @var{frame}.  If @var{family} is omitted or @code{nil},
this list applies to all families, and therefore, it contains all
available fonts.  Otherwise, @var{family} must be a string; it may
contain the wildcards @samp{?} and @samp{*}.

The list describes the display that @var{frame} is on; if @var{frame} is
omitted or @code{nil}, it applies to the selected frame's display
(@pxref{Input Focus}).

Each element in the list is a vector of the following form:

@example
[@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
 @var{fixed-p} @var{full} @var{registry-and-encoding}]
@end example

The first five elements correspond to face attributes; if you
specify these attributes for a face, it will use this font.

The last three elements give additional information about the font.
@var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
@var{full} is the full name of the font, and
@var{registry-and-encoding} is a string giving the registry and
encoding of the font.
@end defun

@defvar font-list-limit
This variable specifies maximum number of fonts to consider in font
matching.  The function @code{x-family-fonts} will not return more than
that many fonts, and font selection will consider only that many fonts
when searching a matching font for face attributes.  The default is
currently 100.
@end defvar

@node Fontsets
@subsection Fontsets

  A @dfn{fontset} is a list of fonts, each assigned to a range of
character codes.  An individual font cannot display the whole range of
characters that Emacs supports, but a fontset can.  Fontsets have names,
just as fonts do, and you can use a fontset name in place of a font name
when you specify the ``font'' for a frame or a face.  Here is
information about defining a fontset under Lisp program control.

@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
This function defines a new fontset according to the specification
string @var{fontset-spec}.  The string should have this format:

@smallexample
@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
@end smallexample

@noindent
Whitespace characters before and after the commas are ignored.

The first part of the string, @var{fontpattern}, should have the form of
a standard X font name, except that the last two fields should be
@samp{fontset-@var{alias}}.

The new fontset has two names, one long and one short.  The long name is
@var{fontpattern} in its entirety.  The short name is
@samp{fontset-@var{alias}}.  You can refer to the fontset by either
name.  If a fontset with the same name already exists, an error is
signaled, unless @var{noerror} is non-@code{nil}, in which case this
function does nothing.

If optional argument @var{style-variant-p} is non-@code{nil}, that says
to create bold, italic and bold-italic variants of the fontset as well.
These variant fontsets do not have a short name, only a long one, which
is made by altering @var{fontpattern} to indicate the bold or italic
status.

The specification string also says which fonts to use in the fontset.
See below for the details.
@end defun

  The construct @samp{@var{charset}:@var{font}} specifies which font to
use (in this fontset) for one particular character set.  Here,
@var{charset} is the name of a character set, and @var{font} is the font
to use for that character set.  You can use this construct any number of
times in the specification string.

  For the remaining character sets, those that you don't specify
explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
@samp{fontset-@var{alias}} with a value that names one character set.
For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
with @samp{ISO8859-1}.

  In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard.  This is to prevent use of
auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
for editing, and scaling a smaller font is not useful because it is
better to use the smaller font in its own size, which Emacs does.

  Thus if @var{fontpattern} is this,

@example
-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
@end example

@noindent
the font specification for @acronym{ASCII} characters would be this:

@example
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
@end example

@noindent
and the font specification for Chinese GB2312 characters would be this:

@example
-*-fixed-medium-r-normal-*-24-*-gb2312*-*
@end example

  You may not have any Chinese font matching the above font
specification.  Most X distributions include only Chinese fonts that
have @samp{song ti} or @samp{fangsong ti} in the @var{family} field.  In
such a case, @samp{Fontset-@var{n}} can be specified as below:

@smallexample
Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
@end smallexample

@noindent
Then, the font specifications for all but Chinese GB2312 characters have
@samp{fixed} in the @var{family} field, and the font specification for
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.

@defun set-fontset-font name character fontname &optional frame
This function modifies the existing fontset @var{name} to
use the font name @var{fontname} for the character @var{character}.

If @var{name} is @code{nil}, this function modifies the default
fontset, whose short name is @samp{fontset-default}.

@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
@var{from} and @var{to} are character codepoints.  In that case, use
@var{fontname} for all characters in the range @var{from} and @var{to}
(inclusive).

@var{character} may be a charset.  In that case, use
@var{fontname} for all character in the charsets.

@var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
where @var{family} is a family name of a font (possibly including a
foundry name at the head), @var{registry} is a registry name of a font
(possibly including an encoding name at the tail).

For instance, this changes the default fontset to use a font of which
registry name is @samp{JISX0208.1983} for all characters belonging to
the charset @code{japanese-jisx0208}.

@smallexample
(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
@end smallexample
@end defun

@defun char-displayable-p char
This function returns @code{t} if Emacs ought to be able to display
@var{char}.  More precisely, if the selected frame's fontset has a
font to display the character set that @var{char} belongs to.

Fontsets can specify a font on a per-character basis; when the fontset
does that, this function's value may not be accurate.
@end defun

@node Low-Level Font
@subsection 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
qobject types: @dfn{font objects}, @dfn{font specs}, and @dfn{font
entities}.

@defun fontp object &optional type
Return @code{t} if @var{object} is a font object, font spec, or font
entity.  Otherwise, return @code{nil}.

@code{font-entity}.
@end defun

  A font object is a Lisp object that represents a font that Emacs has
@dfn{opened}.  Font objects cannot be modified in Lisp, but they can
be inspected.  If you call @code{set-face-attribute} and pass a font
spec, font entity, or font name string as the value of the
@code{: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 @code{:font} attribute for that face.

@defun font-at position &optional window string

which should come in @code{property}-@code{value} pairs.  The possible
specifications are as follows:

@table @code
@item :name
The font name (a string), in either XLFD, Fontconfig, or GTK format.
@xref{Font X,, Font Specification Options, emacs, The GNU Emacs
Manual}.

@item :family
@itemx :foundry

@defun font-put font-spec property value
Set the font property @var{property} in the font-spec @var{font-spec}
to @var{value}.
@end defun

  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.

@defun find-font font-spec &optional frame
This function returns a font entity that best matches the font spec
@var{font-spec} on frame @var{frame}.  If @var{frame} is @code{nil},
it defaults to the selected frame.
@end defun

@defun list-fonts font-spec &optional frame num prefer
This function returns a list of all font entities that match the font
spec @var{font-spec}.

The optional argument @var{frame}, if non-@code{nil}, specifies the
frame on which the fonts are to be displayed.  The optional argument
@var{num}, if non-@code{nil}, should be an integer that specifies the
maximum length of the returned list.  The optional argument
@var{prefer}, if non-@code{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.
@end defun

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

@defun font-get font property
This function returns the value of the font property @var{property}
for @var{font}.

If @var{font} is a font spec and the font spec does not specify
@var{property}, the return value is @code{nil}.  If @var{font} is a
font object or font entity, the value for the @var{:script} property
may be a list of scripts supported by the font.
@end defun

@defun font-face-attributes font &optional frame
This function returns a list of face attributes corresponding to
@var{font}.  The optional argument @var{frame} specifies the frame on
which the font is to be displayed.  If it is @code{nil}, the selected
frame is used.  The return value has the form

@smallexample
(:family @var{family} :height @var{height} :weight @var{weight}
   :slant @var{slant} :width @var{width})
@end smallexample

@end defun

@defun font-xlfd-name font &optional fold-wildcards
This function returns the XLFD (X Logical Font Descriptor), a string,
matching @var{font}.  @xref{Font X,, Font Specification Options,
emacs, 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 @code{nil}.

If the optional argument @var{fold-wildcards} is non-@code{nil},
consecutive wildcards in the XLFD are folded into one.
@end defun

@node Fringes
@section Fringes
@cindex fringes