Index of Section 3 Manual Pages
| Interix / SUA | Xft.3 | Interix / SUA |
Xft(3) Xft(3)
NAME
Xft - X FreeType interface library
DESCRIPTION
Xft is a simple library designed to interface the FreeType
rasterizer with the X Rendering Extension. This manual
page barely scratches the surface of this library.
HEADER FILE
#include
CONSTANTS
XFT_MAJOR
is the major version number of Xft.
XFT_MINOR
is the minor version number of Xft.
XFT_REVISION
is the revision number of Xft.
XFT_VERSION
is XFT_MAJOR times 10000 (ten thousand), plus
XFT_MINOR times 100, plus XFT_REVISION.
XftVersion
is an alias for XFT_VERSION.
The following example illustrates how Xft's version con-
stants might be used:
#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
DATA TYPES
XftFont
typedef 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 inter-
est to programmers using Xft; it contains general
font metrics and pointers to the Fontconfig charac-
ter set and pattern associated with the font. The
FcCharSet and FcPattern data types are defined by
the Fontconfig library.
XftFonts are populated with any of XftFontOpen(),
XftFontOpenName(), XftFontOpenXlfd(), XftFontOpen-
Info(), 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, Xft-
DrawCharSpec(), and XftDrawGlyphSpec() use XftFonts
to render text to an XftDraw object, which may cor-
respond to either a core X drawable or an X Render-
ing Extension drawable.
XftGlyphExtents() and the XftTextExtents*() family
are used to determine the extents (maximum dimen-
sions) of an XftFont.
An XftFont's glyph or character coverage can be
determined with XftFontCheckGlyph() or XftCharEx-
ists(). XftCharIndex() returns the XftFont-spe-
cific character index corresponding to a given Uni-
code codepoint.
XftGlyphRender(), XftGlyphSpecRender(), XftChar-
SpecRender(), and the XftTextRender*() family use
XftFonts to draw into X Rendering Extension Picture
structures. Note: XftDrawGlyphs(), the XftDraw-
String*() family, XftDrawCharSpec(), and XftDrawG-
lyphSpec() provide a means of rendering fonts that
is independent of the availability of the X Render-
ing Extension on the X server.
XftFontInfo
is an opaque object that stores information about a
font. XftFontInfo structures are created with Xft-
FontInfoCreate(), freed with XftFontInfoDestroy(),
and compared with XftFontInfoEqual(). XftFontInfo
objects are internally allocated and freed by Xft;
the programmer does not ordinarily need to allocate
or free storage for them.
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().
XftColor
typedef 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). The
XRenderColor data type is defined by the X Render
Extension library.
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.
One an XftColor has been initialized, XftDrawSr-
cPicture(), XftDrawGlyphs(), the XftDrawString*()
family, XftDrawCharSpec(), XftDrawCharFontSpec(),
XftDrawGlyphSpec(), XftDrawGlyphFontSpec(), and
XftDrawRect() may be used to draw various objects
using it.
XftDraw
is an opaque object which holds information used to
render to an X drawable using either the core pro-
tocol or the X Rendering extension.
XftDraw objects are created with any of XftDrawCre-
ate() (which associates an XftDraw with an existing
X drawable), XftDrawCreateBitmap(), or XftDrawCre-
ateAlpha(), and destroyed with XftDrawDestroy().
The X drawable associated with an XftDraw can be
changed with XftDrawChange(). XftDraws are inter-
nally allocated and freed by Xft; the programmer
does not ordinarily need to allocate or free stor-
age for them.
The X Display, Drawable, Colormap, and Visual of an
XftDraw can be queried with XftDrawDisplay(), Xft-
DrawDrawable(), XftDrawColormap(), and XftDrawVi-
sual(), respectively. The X Rendering Extension
Picture associated with an XftDraw is returned by
XftDrawPicture().
XftCharSpec
typedef struct _XftCharSpec {
FcChar32 ucs4;
short x;
short y;
} XftCharSpec;
The FcChar32 data type is defined by the Fontconfig
library.
XftCharFontSpec
typedef struct _XftCharFontSpec {
XftFont *font;
FcChar32 ucs4;
short x;
short y;
} XftCharFontSpec;
The FcChar32 data type is defined by the Fontconfig
library.
XftGlyphSpec
typedef struct _XftGlyphSpec {
FT_UInt glyph;
short x;
short y;
} XftGlyphSpec;
The FT_UInt data type is defined by the FreeType
library.
XftGlyphFontSpec
typedef struct _XftGlyphFontSpec {
XftFont *font;
FT_UInt glyph;
short x;
short y;
} XftGlyphFontSpec;
The FT_UInt data type is defined by the FreeType
library.
FUNCTIONS
Opening and Matching Fonts
XftFont *
XftFontOpen (Display *dpy,
int screen,
...);
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. The Display data type is defined
by the X11 library. Returns NULL if no match is found.
Example:
font = XftFontOpen (dpy, screen,
XFT_FAMILY, XftTypeString, "charter",
XFT_SIZE, XftTypeDouble, 12.0,
NULL);
This opens the "charter" font at 12 points. The point
size is automatically converted to the correct pixel size
based on the resolution of the monitor.
XftFont *
XftFontOpenName (Display *dpy,
int screen,
unsigned char *name);
XftFontOpenName behaves as XftFontOpen does, except that
it takes a Fontconfig pattern string (which is passed to
the Fontconfig library's FcNameParse() function).
XftFont *
XftFontOpenXlfd (Display *dpy,
int screen,
unsigned char *xlfd)
XftFontOpenXlfd behaves as XftFontOpen does, except that
it takes a string containing an X Logical Font Description
(XLFD).
FcPattern *
XftFontMatch (Display *dpy,
int screen,
FcPattern *pattern,
FcResult *result);
Also used internally by the XftFontOpen* functions, Xft-
FontMatch can also be used directly to determine the Font-
config font pattern resulting from an Xft font open
request. The FcPattern and FcResult data types are
defined by the Fontconfig library.
Determining the Pixel Extents of a Text String
void
XftTextExtents8 (Display *dpy,
XftFont *font,
FcChar8 *string,
int len,
XGlyphInfo *extents);
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. The FcChar8 data type is defined by the Fontcon-
fig library, and the XGlyphInfo data type is defined by
the X Rendering Extension library.
void
XftTextExtents16 (Display *dpy,
XftFont *font,
FcChar16 *string,
int len,
XGlyphInfo *extents);
XftTextExtents16 computes the pixel extents on display dpy
of no more than len glyphs of a string consisting of six-
teen-bit characters when drawn with font, storing them in
extents. The FcChar16 data type is defined by the Font-
config library, and the XGlyphInfo data type is defined by
the X Rendering Extension library.
void
XftTextExtents32 (Display *dpy,
XftFont *font,
FcChar32 *string,
int len,
XGlyphInfo *extents);
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. The FcChar32 data type is defined by the
Fontconfig library, and the XGlyphInfo data type is
defined by the X Rendering Extension library.
void
XftTextExtentsUtf8 (Display *dpy,
XftFont *font,
FcChar8 *string,
int len,
XGlyphInfo *extents);
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. The
XGlyphInfo data type is defined by the X Rendering Exten-
sion library.
void
XftTextExtentsUtf16 (Display *dpy,
XftFont *font,
FcChar8 *string,
FcEndian endian,
int len,
XGlyphInfo *extents);
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. The FcEndian data type is defined by the Fontcon-
fig library, and the XGlyphInfo data type is defined by
the X Rendering Extension library.
void
XftGlyphExtents (Display *dpy,
XftFont *font,
FT_UInt *glyphs,
int nglyphs,
XGlyphInfo *extents);
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. The FT_UInt data type is
defined by the FreeType library, and the XGlyphInfo data
type is defined by the X Rendering Extension library.
Drawing Strings (and Other Things)
XftDraw *
XftDrawCreate (Display *dpy,
Drawable drawable,
Visual *visual,
Colormap colormap);
XftDrawCreate creates a structure that can be used to ren-
der text and rectangles using the specified drawable,
visual, and colormap on display. The Drawable, Visual,
and Colormap data types are defined by the X11 library.
XftDraw *
XftDrawCreateBitmap (Display *dpy,
Pixmap bitmap);
XftDrawCreateBitmap behaves as XftDrawCreate, except it
uses an X pixmap of color depth 1 instead of an X draw-
able. The Pixmap data type is defined by the X11 library.
XftDraw *
XftDrawCreateAlpha (Display *dpy,
Pixmap pixmap,
int depth);
XftDrawCreateAlpha behaves as XftDrawCreate, except it
uses an X pixmap of color depth depth instead of an X
drawable. The Pixmap data type is defined by the X11
library.
void
XftDrawChange (XftDraw *draw,
Drawable drawable);
XftDrawChange changes the X drawable association of the
existing Xft draw object draw from its current value to
drawable.
Display *
XftDrawDisplay (XftDraw *draw);
XftDrawDisplay returns a pointer to the display associated
with the Xft draw object draw.
Drawable
XftDrawDrawable (XftDraw *draw);
XftDrawDrawable returns the X drawable associated with the
Xft draw object draw.
Colormap
XftDrawColormap (XftDraw *draw);
XftDrawColormap returns the colormap associatied with the
Xft draw object draw.
Visual *
XftDrawVisual (XftDraw *draw);
XftDrawVisual returns a pointer to the visual associated
with the Xft draw object draw.
Picture
XftDrawPicture (XftDraw *draw);
XftDrawPicture returns the picture associated with the Xft
draw object draw. If the the X server does not support
the X Rendering Extension, 0 is returned.
Picture
XftDrawSrcPicture (XftDraw *draw,
XftColor *color);
This function is never called if the X server doesn't sup-
port the X Rendering Extension; instead, XftGlyphCore is
used.
void
XftDrawDestroy (XftDraw *draw);
XftDrawDestroy destroys draw (created by one of the
XftCreate functions) and frees the memory that was allo-
cated for it.
void
XftDrawString8 (XftDraw *d,
XRenderColor *color,
XftFont *font,
int x,
int y,
unsigned char *string,
int len);
XftDrawString8 draws no more than len glyphs of string to
Xft drawable d using font in color at position x, y. The
XRenderColor data type is defined by the X Rendering
Extension library.
void
XftDrawRect (XftDraw *d,
XRenderColor *color,
int x,
int y,
unsigned int width,
unsigned int height);
XftDrawRect draws a solid rectangle of the specified
color, width, and height at position x, y to Xft drawable
d.
COMPATIBILITY
As of version 2, Xft has become relatively stable and is
expected to retain source and binary compatibility in
future releases.
Xft does provide a compatibility interface to its previous
major version, Xft 1.x, described below.
Xft 1.x Compatibility Header File
#include
Xft 1.x Compatibility Data Types
XftPattern
holds a set of names with associated value lists;
each name refers to a property of a font. XftPat-
terns are used as inputs to the matching code as
well as holding information about specific fonts.
XftFontSet
contains a list of XftPatterns. Internally, Xft
uses this data structure to hold sets of fonts.
Externally, Xft returns the results of listing
fonts in this format.
XftObjectSet
holds a set of names and is used to specify which
fields from fonts are placed in the the list of
returned patterns when listing fonts.
AUTHOR
Keith Packard
SEE ALSO
Fontconfig Developers Reference
FreeType API Reference
Xlib - C Language Interface
Xft Version 2.1.13 Xft(3)