This manual page barely scratches the surface of this library.
The following example illustrates how Xft's version constants might be used:
.ta 1.0i 3.0i #if (XFT_VERSION >= 20107) (void) puts("Version 2.1.7 or later of the Xft library is in" " use."); #else (void) printf("Insufficient version of Xft (%d.%d.%d) installed; " need at least version 2.1.7.\n", XFT_MAJOR, XFT_MINOR, XFT_REVISION); #endif
Xft uses these names: Bool, Colormap, Display, Drawable, Pixmap, Region, Visual, and XRectangle.
Some datatypes are especially relevant to Xft:
or read the source code (which provides an outline of libXrender).
Xft uses these names: Picture, XGlyphInfo, XRenderColor.
Xft uses these Fontconfig names: FcBool, FcChar8, FcChar16, FcChar32, FcCharSet, FcEndian, FcFontSet, FcPattern, and FcResult.
Xft uses these names: FT_Face, FT_Library, and FT_UInt.
FreeType 2 uses FT_UInt (an unsigned integer) to represent glyphs.
.ta 1.0i 3.0itypedef struct _XftFont { int ascent; int descent; int height; int max_advance_width; FcCharSet *charset; FcPattern *pattern; } XftFont;
An XftFont is the primary data structure of interest to programmers using Xft; it contains general font metrics and pointers to the Fontconfig character set and pattern associated with the font.
XftFonts are populated with any of XftFontOpen(), XftFontOpenName(), XftFontOpenXlfd(), XftFontOpenInfo(), or XftFontOpenPattern(). XftFontCopy() is used to duplicate XftFonts, and XftFontClose() is used to mark an XftFont as unused. XftFonts are internally allocated, reference-counted, and freed by Xft; the programmer does not ordinarily need to allocate or free storage for them.
XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(), and XftDrawGlyphSpec() use XftFonts to render text to an XftDraw object, which may correspond to either a core X drawable or an X Rendering Extension drawable.
XftGlyphExtents() and the XftTextExtents*() family are used to determine the extents (maximum dimensions) of an XftFont.
An XftFont's glyph or character coverage can be determined with XftFontCheckGlyph() or XftCharExists(). XftCharIndex() returns the XftFont-specific character index corresponding to a given Unicode codepoint.
XftGlyphRender(), XftGlyphSpecRender(), XftCharSpecRender(), and the XftTextRender*() family use XftFonts to draw into X Rendering Extension Picture structures.
Note: XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(), and XftDrawGlyphSpec() provide a means of rendering fonts that is independent of the availability of the X Rendering Extension on the X server.
Each XftFontInfo structure in use is associated with a unique identifier, which can be retrieved with XftFontInfoHash(). An XftFont can be opened based on XftFontInfo data with XftFontOpenInfo().
.ta 1.0i 3.0itypedef struct _XftColor { unsigned long pixel; XRenderColor color; } XftColor;
An XftColor object permits text and other items to be rendered in a particular color (or the closest approximation offered by the X visual in use).
XftColorAllocName() and XftColorAllocValue() request a color allocation from the X server (if necessary) and initialize the members of XftColor. XftColorFree() instructs the X server to free the color currently allocated for an XftColor.
Once an XftColor has been initialized, XftDrawSrcPicture(), XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(), XftDrawCharFontSpec(), XftDrawGlyphSpec(), XftDrawGlyphFontSpec(), and XftDrawRect() may be used to draw various objects using it.
XftDraw objects are created with any of XftDrawCreate() (which associates an XftDraw with an existing X drawable), XftDrawCreateBitmap(), or XftDrawCreateAlpha(), and destroyed with XftDrawDestroy(). The X drawable associated with an XftDraw can be changed with XftDrawChange(). XftDraw objects are internally allocated and freed by Xft; the programmer does not ordinarily need to allocate or free storage for them.
The X Display, Drawable, Colormap, and Visual properties of an XftDraw can be queried with XftDrawDisplay(), XftDrawDrawable(), XftDrawColormap(), and XftDrawVisual(), respectively.
Several functions use XftDraw objects: XftDrawCharFontSpec(), XftDrawCharSpec(), XftDrawGlyphFontSpec(), XftDrawGlyphSpec(), XftDrawGlyphs(), XftDrawRect(), XftDrawSetClip(), XftDrawSetClipRectangles(), XftDrawSetSubwindowMode(), and the XftDrawString*() family.
The X Rendering Extension Picture associated with an XftDraw is returned by XftDrawPicture(), and XftDrawSrcPicture(). It is used by XftCharFontSpecRender(), XftCharSpecRender(), XftGlyphFontSpecRender(), XftGlyphRender(), XftGlyphSpecRender(), and the XftTextRender*() family.
.ta 1.0i 3.0itypedef struct _XftCharSpec { FcChar32 ucs4; short x; short y; } XftCharSpec;
XftCharSpec is used by XftDrawCharSpec(), and XftCharSpecRender().
.ta 1.0i 3.0itypedef struct _XftCharFontSpec { XftFont *font; FcChar32 ucs4; short x; short y; } XftCharFontSpec;
XftCharFontSpec is used by XftCharFontSpecRender().
.ta 1.0i 3.0itypedef struct _XftGlyphSpec { FT_UInt glyph; short x; short y; } XftGlyphSpec;
XftGlyphSpec is used by XftDrawGlyphSpec().
.ta 1.0i 3.0itypedef struct _XftGlyphFontSpec { XftFont *font; FT_UInt glyph; short x; short y; } XftGlyphFontSpec;
XftGlyphFontSpec is used by XftDrawGlyphFontSpec(), and XftGlyphFontSpecRender().
When Xft initializes, it collects information about the display, and stores some of that information in a Fontconfig pattern (essentially a collection of properties with typed values). The calling application can modify that pattern to change the library's behavior.
Not all of the collected information is stored in a pattern. The remainder is stored in internal data structures. Xft makes some of that available to the application via functions.
.ta 0.8i 3.0iBool XftDefaultHasRender ( Display *dpy);
.ta 0.8i 1.6i 2.4i 3.2i
Obtain information about the display
dpy
if not done already, and
return true if
Xft
found that the display supports the X Render extension,
and if it is able to find a suitable
XRenderPictFormat
(X Render's datatype which is analogous to Xlib's Visual)
on the display.
.ta 0.8i 3.0iBool XftDefaultSet ( Display *dpy, FcPattern *defaults);
.ta 0.8i 1.6i 2.4i 3.2i
Obtain information about the display
dpy
if not done already, and
set the Fontconfig pattern holding default properties
which
Xft
will use for this display.
.ta 0.8i 3.0ivoid XftDefaultSubstitute ( Display *dpy, int screen, FcPattern *pattern);
.ta 0.8i 1.6i 2.4i 3.2i
Xft
fills in missing properties in the given
pattern
using default properties for the specified display
dpy,
e.g., as set in
XftDefaultSet().
.ta 0.8i 3.0iFcBool XftInit ( _Xconst char *config);
.ta 0.8i 1.6i 2.4i 3.2i
Initializes the Fontconfig library (calling
FcInit()).
.ta 0.8i 3.0iFcBool XftInitFtLibrary (void);
.ta 0.8i 1.6i 2.4i 3.2i
Initializes the FreeType library
(calling
FT_Init_FreeType()
to create a library object)
if it has not already been initialized.
This is needed before using the FreeType library to read font data from a file.
.ta 0.8i 3.0iint XftGetVersion (void);
.ta 0.8i 1.6i 2.4i 3.2i
Return XftVersion, enabling an application to determine the
actual version of
Xft
which is in use.
.ta 0.8i 3.0iXftFont *XftFontOpen ( Display *dpy, int screen, ...);
.ta 0.8i 1.6i 2.4i 3.2i
XftFontOpen
takes a list of pattern element triples of the form
field, type, value
(terminated with a NULL), matches that pattern against the available fonts,
and opens the matching font, sizing it correctly for screen number
screen
on display
dpy.
Return the matched font, or
NULL if no match is found.
Example:
.ta 1.0i 3.0i font = XftFontOpen (dpy, screen, XFT_FAMILY, XftTypeString, "charter", XFT_SIZE, XftTypeDouble, 12.0, NULL);
.ta 0.8i 3.0iXftFont *XftFontOpenName ( Display *dpy, int screen, _Xconst char *name);
.ta 0.8i 1.6i 2.4i 3.2i
XftFontOpenName
behaves as
XftFontOpen
does, except that it takes a Fontconfig pattern string (which is passed to
the Fontconfig library's
FcNameParse()
function).
.ta 0.8i 3.0iXftFont *XftFontOpenXlfd ( Display *dpy, int screen, _Xconst char *xlfd)
.ta 0.8i 1.6i 2.4i 3.2i
XftFontOpenXlfd
behaves as
XftFontOpen
does, except that it takes a string containing an X Logical Font
Description (XLFD),
and uses the
XftXlfdParse()
function.
.ta 0.8i 3.0iFcPattern *XftFontMatch ( Display *dpy, int screen, _Xconst FcPattern *pattern, FcResult *result);
.ta 0.8i 1.6i 2.4i 3.2i
Also used internally by the
XftFontOpen*
functions,
XftFontMatch
can also be used directly to determine the Fontconfig font pattern
resulting from an
Xft
font open request.
.ta 0.8i 3.0iFcPattern *XftXlfdParse ( _Xconst char *xlfd_orig, Bool ignore_scalable, Bool complete);
.ta 0.8i 1.6i 2.4i 3.2i
XftXlfdParse
parses the
xlfd_orig
parameter according to the
X Logical Font Description Conventions
document, but ignores
some of the fields:
setwidth_name,
add_style_name,
spacing,
and
average_width.
Encoding | XftDrawString* | XftTextExtents* | XftTextRender* |
16 | XftDrawString16 | XftTextExtents16 | XftTextRender16 |
16BE | XftDrawString16 | XftTextExtents16 | XftTextRender16BE |
16LE | XftDrawString16 | XftTextExtents16 | XftTextRender16LE |
32 | XftDrawString32 | XftTextExtents32 | XftTextRender32 |
32BE | XftDrawString32 | XftTextExtents32 | XftTextRender32BE |
32LE | XftDrawString32 | XftTextExtents32 | XftTextRender32LE |
UTF-8 | XftDrawStringUtf8 | XftTextExtentsUtf8 | XftTextRenderUtf8 |
UTF-16 | XftDrawStringUtf16 | XftTextExtentsUtf16 | XftTextRenderUtf16 |
.ta 0.8i 3.0ivoid XftTextExtents8 ( Display *dpy, XftFont *font, _Xconst FcChar8 *string, int len, XGlyphInfo *extents);
.ta 0.8i 1.6i 2.4i 3.2i
XftTextExtents8
computes the pixel extents on display
dpy
of no more than
len
glyphs of a
string
consisting of eight-bit characters when drawn with
font,
storing them in
extents.
.ta 0.8i 3.0ivoid XftTextExtents16 ( Display *dpy, XftFont *font, _Xconst FcChar16 *string, int len, XGlyphInfo *extents);
.ta 0.8i 1.6i 2.4i 3.2i
XftTextExtents16
computes the pixel extents on display
dpy
of no more than
len
glyphs of a
string
consisting of sixteen-bit characters when drawn with
font,
storing them in
extents.
.ta 0.8i 3.0ivoid XftTextExtents32 ( Display *dpy, XftFont *font, _Xconst FcChar32 *string, int len, XGlyphInfo *extents);
.ta 0.8i 1.6i 2.4i 3.2i
XftTextExtents32
computes the pixel extents on display
dpy
of no more than
len
glyphs of a
string
consisting of thirty-two-bit characters when drawn with
font,
storing them in
extents.
.ta 0.8i 3.0ivoid XftTextExtentsUtf8 ( Display *dpy, XftFont *font, _Xconst FcChar8 *string, int len, XGlyphInfo *extents);
.ta 0.8i 1.6i 2.4i 3.2i
XftTextExtentsUtf8
computes the pixel extents on display
dpy
of no more than
len
bytes of a UTF-8 encoded
string
when drawn with
font,
storing them in
extents.
.ta 0.8i 3.0ivoid XftTextExtentsUtf16 ( Display *dpy, XftFont *font, _Xconst FcChar8 *string, FcEndian endian, int len, XGlyphInfo *extents);
.ta 0.8i 1.6i 2.4i 3.2i
XftTextExtentsUtf16
computes the pixel extents on display
dpy
of no more than
len
bytes of a UTF-16LE- or UTF-16BE-encoded
string
when drawn with
font,
storing them in
extents.
The endianness of
string
must be specified in
endian.
.ta 0.8i 3.0ivoid XftGlyphExtents ( Display *dpy, XftFont *font, _Xconst FT_UInt *glyphs, int nglyphs, XGlyphInfo *extents);
.ta 0.8i 1.6i 2.4i 3.2i
Also used internally by the
XftTextExtents*()
functions,
XftGlyphExtents
computes the pixel extents on display
dpy
of no more than
nglyphs
in the array
glyphs
drawn with
font,
storing them in
extents.
.ta 0.8i 3.0iBool XftColorAllocName ( Display *dpy, _Xconst Visual *visual, Colormap cmap, _Xconst char *name, XftColor *result);
.ta 0.8i 1.6i 2.4i 3.2i
Use
XAllocNamedColor()
to look up the named color
name
for the screen associated with the colormap
cmap.
.ta 0.8i 3.0iBool XftColorAllocValue ( Display *dpy, Visual *visual, Colormap cmap, _Xconst XRenderColor *color, XftColor *result);
.ta 0.8i 1.6i 2.4i 3.2i
Allocate a color value:
.ta 0.8i 3.0ivoid XftColorFree ( Display *dpy, Visual *visual, Colormap cmap, XftColor *color);
.ta 0.8i 1.6i 2.4i 3.2i
If the
visual
class is not TrueColor,
Xft
calls
XFreeColors()
to free the entry from the colormap
cmap
whose pixel value in the
color
parameter was allocated by
XftColorAllocName().
.ta 0.8i 3.0iXftDraw *XftDrawCreate ( Display *dpy, Drawable drawable, Visual *visual, Colormap colormap);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawCreate
creates a structure that can be used to render text and rectangles using
the specified
drawable,
visual,
and
colormap
on
display.
.ta 0.8i 3.0iXftDraw *XftDrawCreateBitmap ( Display *dpy, Pixmap bitmap);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawCreateBitmap
behaves as
XftDrawCreate(),
except that it uses an X pixmap of color depth 1 instead of an X drawable.
.ta 0.8i 3.0iXftDraw * XftDrawCreateAlpha ( Display *dpy, Pixmap pixmap, int depth);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawCreateAlpha
behaves as
XftDrawCreate(),
except that it uses an X pixmap of color depth
depth
instead of an X drawable.
.ta 0.8i 3.0ivoid XftDrawChange ( XftDraw *draw, Drawable drawable);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawChange
changes the X drawable association of the existing
Xft
draw object
draw
from its current value to
drawable.
.ta 0.8i 3.0iDisplay *XftDrawDisplay ( XftDraw *draw);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawDisplay
returns a pointer to the display associated with the
Xft
draw object
draw.
.ta 0.8i 3.0iDrawable XftDrawDrawable ( XftDraw *draw);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawDrawable
returns the X drawable associated with the
Xft
draw object
draw.
.ta 0.8i 3.0iColormap XftDrawColormap ( XftDraw *draw);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawColormap()
returns the colormap associated with the
Xft
draw object
draw.
.ta 0.8i 3.0iVisual *XftDrawVisual ( XftDraw *draw);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawVisual
returns a pointer to the visual associated with the
Xft
draw object
draw.
.ta 0.8i 3.0iPicture XftDrawPicture ( XftDraw *draw);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawPicture
returns the picture associated with the
Xft
draw object
draw.
.ta 0.8i 3.0iPicture XftDrawSrcPicture ( XftDraw *draw, _Xconst XftColor *color);
.ta 0.8i 1.6i 2.4i 3.2i
Return an X Render Picture object,
which is used for rendering glyphs,
e.g., with
XftGlyphRender(),
XftGlyphSpecRender(),
or
XftGlyphFontSpecRender(),
by
XftDrawGlyphs(),
XftDrawGlyphSpec(),
XftDrawGlyphFontSpec(),
respectively.
.ta 0.8i 3.0ivoid XftDrawDestroy ( XftDraw *draw);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawDestroy
destroys
draw
(created by one of the
XftDrawCreate*()
functions) and frees the memory that was allocated for it.
.ta 0.8i 3.0iBool XftDrawSetClip ( XftDraw *draw, Region r);
.ta 0.8i 1.6i 2.4i 3.2i
Set up clipping for the given
XftDraw
parameter
draw
starting with a
Region:
.ta 0.8i 3.0iBool XftDrawSetClipRectangles ( XftDraw *draw, int xOrigin, int yOrigin, _Xconst XRectangle *rects, int n);
.ta 0.8i 1.6i 2.4i 3.2i
Like
XftDrawSetClip(),
XftDrawSetClipRectangles()
sets up clipping for the given
XftDraw
parameter
draw
but uses a set of
n
rectangles (the
rects
parameter)
which could be used to construct a
Region .
.ta 0.8i 3.0ivoid XftDrawSetSubwindowMode ( XftDraw *draw, int mode);
.ta 0.8i 1.6i 2.4i 3.2i
Sets the subwindow-mode for the given
XftDraw
parameter
draw.
The mode can be either
ClipByChildren
(the default), or
IncludeInferiors:
.ta 0.8i 3.0ivoid XftDrawString8 ( XftDraw *d, _Xconst XftColor *color, XftFont *font, int x, int y, _Xconst FcChar8 *string, int len);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawString8
draws no more than
len
glyphs of
string
to
Xft
drawable
d
using
font
in
color
at position
x, y.
.ta 0.8i 3.0ivoid XftDrawRect ( XftDraw *d, _Xconst XftColor *color, int x, int y, unsigned int width, unsigned int height);
.ta 0.8i 1.6i 2.4i 3.2i
XftDrawRect
draws a solid rectangle of the specified
color,
width,
and
height
at position
x, y
to
Xft
drawable
d.
.ta 0.8i 3.0ivoid XftCharFontSpecRender ( Display *dpy, int op, Picture src, Picture dst, int srcx, int srcy, _Xconst XftCharFontSpec *chars, int len);
.ta 0.8i 1.6i 2.4i 3.2i
XftCharFontSpecRender()
converts the
chars
parameter from
XftCharFontSpec
to
XftGlyphFontSpec,
passing the converted array along with the other parameters unchanged to
XftGlyphFontSpecRender()
to render the data.
.ta 0.8i 3.0ivoid XftDrawGlyphFontSpec ( XftDraw *draw, _Xconst XftColor *color, _Xconst XftGlyphFontSpec *glyphs, int len);
.ta 0.8i 1.6i 2.4i 3.2i
Draw a list of glyphs associated with fonts at specified coordinates,
passed as an array of
len
XftGlyphFontSpec
structures via the parameter
glyphs.
All of the glyphs are drawn using the color specified in the
color
parameter.
.ta 0.8i 3.0ivoid XftGlyphFontSpecRender ( Display *dpy, int op, Picture src, Picture dst, int srcx, int srcy, _Xconst XftGlyphFontSpec *glyphs, int nglyphs);
.ta 0.8i 1.6i 2.4i 3.2i
This involves several steps:
.ta 0.8i 3.0iFcFontSet *XftListFonts ( Display *dpy, int screen, ...);
.ta 0.8i 1.6i 2.4i 3.2i
Xft
uses
FcPatternVapBuild()
and
FcObjectSetVapBuild()
to process the variable-length parameter list,
and
FcFontList()
to obtain a list of matching Fontconfig patterns,
which it returns to the caller.
The caller can dispose of the return value using
FcPatternDestroy().
.ta 0.8i 3.0iFcPattern *XftNameParse ( _Xconst char *name);
.ta 0.8i 1.6i 2.4i 3.2i
Xft
uses Fontconfig to parse the name,
passing the
name
to
FcNameParse(),
returning the result.
.ta 0.8i 3.0iFcBool XftNameUnparse ( FcPattern *pat, char *dest, int len);
.ta 0.8i 1.6i 2.4i 3.2i
Like
XfgNameParse(),
Xft
uses Fontconfig.
In this case, it uses
FcNameUnparse(),
which converts the pattern
pat
back into a string that can be parsed.
XftNameUnparse()
stores the result via the caller's pointer
dest,
but checks first if it will fit,
using the
len
parameter.
If it fits,
Xft
copies the string and returns
FcTrue,
otherwise it returns
FcFalse.
.ta 0.8i 3.0ivoid XftFontLoadGlyphs ( Display *dpy, XftFont *pub, FcBool need_bitmaps, _Xconst FT_UInt *glyphs, int nglyph);
.ta 0.8i 1.6i 2.4i 3.2i
Using
FT_Load_Glyph(),
load
nglyphs
for the glyph indices (Unicode values)
listed in the array
glyphs
from the given font
pub.
.ta 0.8i 3.0ivoid XftFontUnloadGlyphs ( Display *dpy, XftFont *pub, _Xconst FT_UInt *glyphs, int nglyph);
.ta 0.8i 1.6i 2.4i 3.2i
Discards data for up to
nglyph
glyphs whose glyph indices (Unicode values)
are listed in the array
glyphs
for the given font
pub.
If the glyphs were added to the X Render extension,
Xft
removes those using
XRenderFreeGlyphs().
Xft
keeps track of the amount of memory used for glyphs,
and updates the usage associated with the display
dpy.
.ta 0.8i 3.0iFT_Face XftLockFace ( XftFont *pub);
.ta 0.8i 1.6i 2.4i 3.2i
If no FreeType 2 ``face''
(in-memory representation of a given typeface in a given style)
has been created for the
pub
font, create one using
FT_New_Face().
Face-locks are a reference count used by
Xft
to ensure that only one face is created,
and that it is retained until the font is no longer used.
.ta 0.8i 3.0ivoid XftUnlockFace ( XftFont *pub);
.ta 0.8i 1.6i 2.4i 3.2i
Decrements the reference count for the FreeType 2 ``face''
associated with the font.
Xft provides a compatibility interface to its previous major version, Xft 1.x, described below.