|
|
This manual page is for Mac OS X version 10.6.3If you are running a different version of Mac OS X, view the documentation locally:
Reading manual pagesManual pages are intended as a quick reference for people who already understand a technology.
|
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 <X11/Xft/Xft.h>
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 constants 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 interest to programmers using Xft; it contains
general font metrics and pointers to the Fontconfig character 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(), Xft-FontOpenInfo(), XftFontOpenInfo(),
FontOpenInfo(), or XftFontOpenPattern(). XftFontCopy() is used to duplicate XftFonts, and
XftFontClose() is used to mark an XftFont as unused. XftFonts are internally allocated, ref-erence-counted, reference-counted,
erence-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 ren-dering rendering
dering fonts that is independent of the availability of the X Rendering Extension on the X
server.
XftFontInfo
is an opaque object that stores information about a font. XftFontInfo structures are created
with XftFontInfoCreate(), freed with XftFontInfoDestroy(), and compared with XftFontInfoE-qual(). XftFontInfoEqual().
qual(). 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, XftDrawSrcPicture(), XftDrawGlyphs(), the XftDraw-String*() XftDrawString*()
String*() family, XftDrawCharSpec(), XftDrawCharFontSpec(), XftDrawGlyphSpec(), XftDrawGlyph-FontSpec(), XftDrawGlyphFontSpec(),
FontSpec(), 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 protocol or the X Rendering extension.
XftDraw objects are created with any of XftDrawCreate() (which associates an XftDraw with an
existing X drawable), XftDrawCreateBitmap(), or XftDrawCreateAlpha(), and destroyed with Xft-DrawDestroy(). XftDrawDestroy().
DrawDestroy(). The X drawable associated with an XftDraw can be changed with XftDrawChange().
XftDraws 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 of an XftDraw can be queried with XftDrawDis-play(), XftDrawDisplay(),
play(), XftDrawDrawable(), XftDrawColormap(), and XftDrawVisual(), respectively. The X Ren-dering Rendering
dering 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 cor-rectly correctly
rectly 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, XftFontMatch can also be used directly to deter-mine determine
mine the Fontconfig 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 con-sisting consisting
sisting of eight-bit characters when drawn with font, storing them in extents. The FcChar8 data type
is defined by the Fontconfig 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 sixteen-bit characters when drawn with font, storing them in extents. The FcChar16
data type is defined by the Fontconfig library, and the XGlyphInfo data type is defined by the X Ren-dering Rendering
dering 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 Ren-dering Rendering
dering 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 Extension 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 Fontconfig 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 render 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 drawable. 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 cur-rent current
rent 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 support 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 allocated 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 posi-tion position
tion 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 compat-ibility compatibility
ibility 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 <X11/Xft/XftCompat.h>
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.
XftPatterns are used as inputs to the matching code as well as holding information about spe-cific specific
cific 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)
|
The way to report a problem with this manual page depends on the type of problem: