.\" .\" $Id: Xft.3.in,v 1.1.1.1 2006/11/25 17:21:40 matthieu Exp $ .\" .\" Copyright © 2000 Keith Packard .\" .\" Permission to use, copy, modify, distribute, and sell this software and its .\" documentation for any purpose is hereby granted without fee, provided that .\" the above copyright notice appear in all copies and that both that .\" copyright notice and this permission notice appear in supporting .\" documentation, and that the name of Keith Packard not be used in .\" advertising or publicity pertaining to distribution of the software without .\" specific, written prior permission. Keith Packard makes no .\" representations about the suitability of this software for any purpose. It .\" is provided "as is" without express or implied warranty. .\" .\" KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, .\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO .\" EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR .\" CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, .\" DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" .TH Xft 3 "Version @VERSION@" "Xft" .SH NAME Xft \- X FreeType interface library .SH DESCRIPTION .B 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. .SH "HEADER FILE" .B #include .SH CONSTANTS .TP .B XFT_MAJOR is the major version number of .BR Xft . .TP .B XFT_MINOR is the minor version number of .BR Xft . .TP .B XFT_REVISION is the revision number of .BR Xft . .TP .B XFT_VERSION is .B XFT_MAJOR times 10000 (ten thousand), plus .B XFT_MINOR times 100, plus .BR XFT_REVISION . .TP .B XftVersion is an alias for .BR XFT_VERSION . .PP The following example illustrates how .BR Xft 's version constants might be used: .nf #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.\(rsn", XFT_MAJOR, XFT_MINOR, XFT_REVISION); #endif .fi .\" I don't understand what these are for. -- BR, 2005-04-02 .\" XFT_CORE used in xftname.c .\" XFT_RENDER used in xftdpy.c, xftfreetype.c, xftname.c .\" XFT_XLFD used in xftname.c, xftxlfd.c .\" XFT_MAX_GLYPH_MEMORY used in xftdpy.c, xftfreetype.c .\" XFT_MAX_UNREF_FONTS used in xftdpy.c .\" XFT_NMISSING used in xftcore.c, xftextent.c, xftglyphs.c, .\" xftrender.c .SH "DATA TYPES" .TP .B XftFont .nf typedef struct _XftFont { int ascent; int descent; int height; int max_advance_width; FcCharSet *charset; FcPattern *pattern; } XftFont; .fi An .B XftFont is the primary data structure of interest to programmers using .BR Xft ; it contains general font metrics and pointers to the Fontconfig character set and pattern associated with the font. The .B FcCharSet and .B FcPattern data types are defined by the Fontconfig library. .TP .B "" .BR XftFont s are populated with any of .BR XftFontOpen (), .BR XftFontOpenName (), .BR XftFontOpenXlfd (), .BR XftFontOpenInfo (), or .BR XftFontOpenPattern (). .BR XftFontCopy () is used to duplicate .BR XftFont s, and .BR XftFontClose () is used to mark an .B XftFont as unused. .BR XftFont s are internally allocated, reference-counted, and freed by .BR Xft ; the programmer does not ordinarily need to allocate or free storage for them. .TP .B "" .BR XftDrawGlyphs (), the .BR XftDrawString *() family, .BR XftDrawCharSpec (), and .BR XftDrawGlyphSpec () use .BR XftFont s to render text to an .B XftDraw object, which may correspond to either a core X drawable or an X Rendering Extension drawable. .TP .B "" .BR XftGlyphExtents () and the .BR XftTextExtents *() family are used to determine the extents (maximum dimensions) of an .BR XftFont . .TP .B "" An .BR XftFont 's glyph or character coverage can be determined with .BR XftFontCheckGlyph () or .BR XftCharExists (). .BR XftCharIndex () returns the .BR XftFont -specific character index corresponding to a given Unicode codepoint. .TP .B "" .BR XftGlyphRender (), .BR XftGlyphSpecRender (), .BR XftCharSpecRender (), and the .BR XftTextRender *() family use .BR XftFont s to draw into X Rendering Extension .B Picture structures. .B Note: .BR XftDrawGlyphs (), the .BR XftDrawString *() family, .BR XftDrawCharSpec (), and .BR XftDrawGlyphSpec () provide a means of rendering fonts that is independent of the availability of the X Rendering Extension on the X server. .\" I'm not sure what these are for; they're used internally, but why .\" would any external users want them? -- BR, 2005-04-02 .\" .BR XftLockFace() .\" .BR XftUnlockFace() .TP .B XftFontInfo is an opaque object that stores information about a font. .B XftFontInfo structures are created with .BR XftFontInfoCreate (), freed with .BR XftFontInfoDestroy (), and compared with .BR XftFontInfoEqual (). .B XftFontInfo objects are internally allocated and freed by .BR Xft ; the programmer does not ordinarily need to allocate or free storage for them. .TP .B "" Each .B XftFontInfo structure in use is associated with a unique identifier, which can be retrieved with .BR XftFontInfoHash (). An .B XftFont can be opened based on .B XftFontInfo data with .BR XftFontOpenInfo (). .TP .B XftColor .nf typedef struct _XftColor { unsigned long pixel; XRenderColor color; } XftColor; .fi An .B 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 .B XRenderColor data type is defined by the X Render Extension library. .TP .B "" .BR XftColorAllocName () and .BR XftColorAllocValue () request a color allocation from the X server (if necessary) and initialize the members of .BR XftColor . .BR XftColorFree () instructs the X server to free the color currently allocated for an .BR XftColor . .TP .B "" One an .B XftColor has been initialized, .BR XftDrawSrcPicture (), .BR XftDrawGlyphs (), the .BR XftDrawString *() family, .BR XftDrawCharSpec (), .BR XftDrawCharFontSpec (), .BR XftDrawGlyphSpec (), .BR XftDrawGlyphFontSpec (), and .BR XftDrawRect () may be used to draw various objects using it. .TP .B 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. .TP .B "" .B XftDraw objects are created with any of .BR XftDrawCreate () (which associates an .B XftDraw with an existing X drawable), .BR XftDrawCreateBitmap (), or .BR XftDrawCreateAlpha (), and destroyed with .BR XftDrawDestroy (). The X drawable associated with an .B XftDraw can be changed with .BR XftDrawChange (). .BR XftDraw s are internally allocated and freed by .BR Xft ; the programmer does not ordinarily need to allocate or free storage for them. .TP .B "" The X .BR Display , .BR Drawable , .BR Colormap , and .BR Visual of an .B XftDraw can be queried with .BR XftDrawDisplay (), .BR XftDrawDrawable (), .BR XftDrawColormap (), and .BR XftDrawVisual (), respectively. The X Rendering Extension .B Picture associated with an .B XftDraw is returned by .BR XftDrawPicture (). .\" XftDrawSrcPicture .\" XftDrawGlyphs .\" XftDrawString* .\" XftDrawCharSpec .\" XftDrawCharFontSpec .\" XftDrawGlyphSpec .\" XftDrawGlyphFontSpec .\" XftDrawRect .\" XftDrawSetClip .\" XftDrawSetClipRectangles .\" XftDrawSetSubwindowMode .TP .B XftCharSpec .nf typedef struct _XftCharSpec { FcChar32 ucs4; short x; short y; } XftCharSpec; .fi .TP .B "" The .B FcChar32 data type is defined by the Fontconfig library. .\" XftDrawCharSpec .\" XftCharSpecRender .TP .B XftCharFontSpec .nf typedef struct _XftCharFontSpec { XftFont *font; FcChar32 ucs4; short x; short y; } XftCharFontSpec; .fi .TP .B "" The .B FcChar32 data type is defined by the Fontconfig library. .\" XftDrawCharFontSpec .\" XftCharFontSpecRender .TP .B XftGlyphSpec .nf typedef struct _XftGlyphSpec { FT_UInt glyph; short x; short y; } XftGlyphSpec; .fi .TP .B "" The .B FT_UInt data type is defined by the FreeType library. .\" XftDrawGlyphSpec .\" XftGlyphSpecRender .TP .B XftGlyphFontSpec .nf typedef struct _XftGlyphFontSpec { XftFont *font; FT_UInt glyph; short x; short y; } XftGlyphFontSpec; .fi .TP .B "" The .B FT_UInt data type is defined by the FreeType library. .\" XftDrawGlyphFontSpec .\" XftGlyphFontSpecRender .SH FUNCTIONS .SS "Opening and Matching Fonts" .nf \fBXftFont *\fR \fBXftFontOpen (Display *\fIdpy\fB,\fR \fB int \fIscreen\fB,\fR \fB ...);\fR\fR .fi .B XftFontOpen takes a list of pattern element triples of the form .IR 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 .I screen on display .IR dpy . The .B Display data type is defined by the X11 library. Returns NULL if no match is found. .PP Example: .nf font = XftFontOpen (dpy, screen, XFT_FAMILY, XftTypeString, "charter", XFT_SIZE, XftTypeDouble, 12.0, NULL); .fi This opens the \(lqcharter\(rq font at 12 points. The point size is automatically converted to the correct pixel size based on the resolution of the monitor. .PP .nf \fBXftFont *\fR \fBXftFontOpenName (Display *\fIdpy\fB,\fR \fB int \fIscreen\fB,\fR \fB unsigned char *\fIname\fB);\fR .fi .B XftFontOpenName behaves as .B XftFontOpen does, except that it takes a Fontconfig pattern string (which is passed to the Fontconfig library's .BR FcNameParse () function). .PP .nf \fBXftFont *\fR \fBXftFontOpenXlfd (Display *\fIdpy\fB,\fR \fB int \fIscreen\fB,\fR \fB unsigned char *\fIxlfd\fB)\fR .fi .B XftFontOpenXlfd behaves as .B XftFontOpen does, except that it takes a string containing an X Logical Font Description (XLFD). .PP .nf \fBFcPattern *\fR \fBXftFontMatch (Display *\fIdpy\fB,\fR \fB int \fIscreen\fB,\fR \fB FcPattern *\fIpattern\fB,\fR \fB FcResult *\fIresult\fB);\fR .fi Also used internally by the .BR XftFontOpen * functions, .B XftFontMatch can also be used directly to determine the Fontconfig font pattern resulting from an Xft font open request. The .B FcPattern and .B FcResult data types are defined by the Fontconfig library. .SS "Determining the Pixel Extents of a Text String" .nf \fBvoid\fR \fBXftTextExtents8 (Display *\fIdpy\fB,\fR \fB XftFont *\fIfont\fB,\fR \fB FcChar8 *\fIstring\fB,\fR \fB int \fIlen\fB,\fR \fB XGlyphInfo *\fIextents\fB);\fR .fi .B XftTextExtents8 computes the pixel extents on display .I dpy of no more than .I len glyphs of a .I string consisting of eight-bit characters when drawn with .IR font , storing them in .IR extents . The .B FcChar8 data type is defined by the Fontconfig library, and the .B XGlyphInfo data type is defined by the X Rendering Extension library. .PP .nf \fBvoid\fR \fBXftTextExtents16 (Display *\fIdpy\fB,\fR \fB XftFont *\fIfont\fB,\fR \fB FcChar16 *\fIstring\fB,\fR \fB int \fIlen\fB,\fR \fB XGlyphInfo *\fIextents\fB);\fR .fi .B XftTextExtents16 computes the pixel extents on display .I dpy of no more than .I len glyphs of a .I string consisting of sixteen-bit characters when drawn with .IR font , storing them in .IR extents . The .B FcChar16 data type is defined by the Fontconfig library, and the .B XGlyphInfo data type is defined by the X Rendering Extension library. .PP .nf \fBvoid\fR \fBXftTextExtents32 (Display *\fIdpy\fB,\fR \fB XftFont *\fIfont\fB,\fR \fB FcChar32 *\fIstring\fB,\fR \fB int \fIlen\fB,\fR \fB XGlyphInfo *\fIextents\fB);\fR .fi .B XftTextExtents32 computes the pixel extents on display .I dpy of no more than .I len glyphs of a .I string consisting of thirty-two-bit characters when drawn with .IR font , storing them in .IR extents . The .B FcChar32 data type is defined by the Fontconfig library, and the .B XGlyphInfo data type is defined by the X Rendering Extension library. .PP .nf \fBvoid\fR \fBXftTextExtentsUtf8 (Display *\fIdpy\fB,\fR \fB XftFont *\fIfont\fB,\fR \fB FcChar8 *\fIstring\fB,\fR \fB int \fIlen\fB,\fR \fB XGlyphInfo *\fIextents\fB);\fR .fi .B XftTextExtentsUtf8 computes the pixel extents on display .I dpy of no more than .I len bytes of a UTF-8 encoded .I string when drawn with .IR font , storing them in .IR extents . The .B XGlyphInfo data type is defined by the X Rendering Extension library. .PP .nf \fBvoid\fR \fBXftTextExtentsUtf16 (Display *\fIdpy\fB,\fR \fB XftFont *\fIfont\fB,\fR \fB FcChar8 *\fIstring\fB,\fR \fB FcEndian \fIendian\fB,\fR \fB int \fIlen\fB,\fR \fB XGlyphInfo *\fIextents\fB);\fR .fi .B XftTextExtentsUtf16 computes the pixel extents on display .I dpy of no more than .I len bytes of a UTF-16LE- or UTF-16BE-encoded .I string when drawn with .IR font , storing them in .IR extents . The endianness of .I string must be specified in .IR endian . The .B FcEndian data type is defined by the Fontconfig library, and the .B XGlyphInfo data type is defined by the X Rendering Extension library. .PP .nf \fBvoid\fR \fBXftGlyphExtents (Display *\fIdpy\fB,\fR \fB XftFont *\fIfont\fB,\fR \fB FT_UInt *\fIglyphs\fB,\fR \fB int \fInglyphs\fB,\fR \fB XGlyphInfo *\fIextents\fB);\fR .fi Also used internally by the .BR XftTextExtents * functions, .B XftGlyphExtents computes the pixel extents on display .I dpy of no more than .I nglyphs in the array .I glyphs drawn with .IR font , storing them in .IR extents . The .B FT_UInt data type is defined by the FreeType library, and the .B XGlyphInfo data type is defined by the X Rendering Extension library. .SS "Drawing Strings (and Other Things)" .nf \fBXftDraw *\fR \fBXftDrawCreate (Display *\fIdpy\fB,\fR \fB Drawable \fIdrawable\fB,\fR \fB Visual *\fIvisual\fB,\fR \fB Colormap \fIcolormap\fB);\fR .fi .B XftDrawCreate creates a structure that can be used to render text and rectangles using the specified .IR drawable , .IR visual , and .I colormap on .IR display . The .BR Drawable , .BR Visual , and .B Colormap data types are defined by the X11 library. .PP .nf \fBXftDraw *\fR \fBXftDrawCreateBitmap (Display *\fIdpy\fB,\fR \fB Pixmap \fIbitmap\fB);\fR .fi .B XftDrawCreateBitmap behaves as .BR XftDrawCreate , except it uses an X pixmap of color depth 1 instead of an X drawable. The .B Pixmap data type is defined by the X11 library. .PP .nf \fBXftDraw *\fR \fBXftDrawCreateAlpha (Display *\fIdpy\fB,\fR \fB Pixmap \fIpixmap\fB,\fR \fB int \fIdepth\fB);\fR .fi .B XftDrawCreateAlpha behaves as .BR XftDrawCreate , except it uses an X pixmap of color depth .I depth instead of an X drawable. The .B Pixmap data type is defined by the X11 library. .PP .nf \fBvoid\fR \fBXftDrawChange (XftDraw *\fIdraw\fB,\fR \fB Drawable \fIdrawable\fB);\fR .fi .B XftDrawChange changes the X drawable association of the existing Xft draw object .I draw from its current value to .IR drawable . .PP .nf \fBDisplay *\fR \fBXftDrawDisplay (XftDraw *\fIdraw\fB);\fR .fi .B XftDrawDisplay returns a pointer to the display associated with the Xft draw object .IR draw . .PP .nf \fBDrawable\fR \fBXftDrawDrawable (XftDraw *\fIdraw\fB);\fR .fi .B XftDrawDrawable returns the X drawable associated with the Xft draw object .IR draw . .PP .nf \fBColormap\fR \fBXftDrawColormap (XftDraw *\fIdraw\fB);\fR .fi .B XftDrawColormap returns the colormap associatied with the Xft draw object .IR draw . .PP .nf \fBVisual *\fR \fBXftDrawVisual (XftDraw *\fIdraw\fB);\fR .fi .B XftDrawVisual returns a pointer to the visual associated with the Xft draw object .IR draw . .PP .nf \fBPicture\fR \fBXftDrawPicture (XftDraw *\fIdraw\fB);\fR .fi .B XftDrawPicture returns the picture associated with the Xft draw object .IR draw . If the the X server does not support the X Rendering Extension, 0 is returned. .PP .nf \fBPicture\fR \fBXftDrawSrcPicture (XftDraw *\fIdraw\fB,\fR \fB XftColor *\fIcolor\fB);\fR .fi .\" Unfortunately, I'm not quite sure what this does. I think it is the gizmo .\" that is used to create an Xrender Picture object so that glyphs can be .\" drawn in the XftDraw object .\" .I draw .\" using the specified .\" .IR color . .\" -- BR, 2005-04-02 This function is never called if the X server doesn't support the X Rendering Extension; instead, .B XftGlyphCore is used. .PP .nf \fBvoid\fR \fBXftDrawDestroy (XftDraw *\fIdraw\fB);\fR .fi .B XftDrawDestroy destroys .I draw (created by one of the .B XftCreate functions) and frees the memory that was allocated for it. .PP .nf \fBvoid\fR \fBXftDrawString8 (XftDraw *\fId\fB,\fR \fB XRenderColor *\fIcolor\fB,\fR \fB XftFont *\fIfont\fB,\fR \fB int \fIx\fB,\fR \fB int \fIy\fB,\fR \fB unsigned char *\fIstring\fB,\fR \fB int \fIlen\fB);\fR .fi .B XftDrawString8 draws no more than .I len glyphs of .I string to Xft drawable .I d using .I font in .I color at position .IR x , " y" . The .B XRenderColor data type is defined by the X Rendering Extension library. .PP .nf \fBvoid\fR \fBXftDrawRect (XftDraw *\fId\fB,\fR \fB XRenderColor *\fIcolor\fB,\fR \fB int \fIx\fB,\fR \fB int \fIy\fB,\fR \fB unsigned int \fIwidth\fB,\fR \fB unsigned int \fIheight\fB);\fR .fi .B XftDrawRect draws a solid rectangle of the specified .IR color , .IR width , and .I height at position .IR x , " y" to Xft drawable .IR d . .SH COMPATIBILITY As of version 2, .B Xft has become relatively stable and is expected to retain source and binary compatibility in future releases. .PP .B Xft does provide a compatibility interface to its previous major version, Xft .RI 1. x , described below. .SS "Xft 1.x Compatibility Header File" .B #include .\" .SS "Xft 1.x Compatibility Constants" .SS "Xft 1.x Compatibility Data Types" .TP .B XftPattern holds a set of names with associated value lists; each name refers to a property of a font. .BR XftPattern s are used as inputs to the matching code as well as holding information about specific fonts. .TP .B XftFontSet contains a list of .BR XftPattern s. Internally, .B Xft uses this data structure to hold sets of fonts. Externally, .B Xft returns the results of listing fonts in this format. .TP .B 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. .\" .SS "Xft 1.x Compatibility Functions" .SH AUTHOR Keith Packard .SH "SEE ALSO" .I Fontconfig Developers Reference .br .I FreeType API Reference .br .I Xlib \- C Language Interface .\" Set Vim modeline; textwidth is 70 to account for the extra margin .\" padding that man (on Debian GNU/Linux) does for output to .\" terminals (7 spaces on the left, 2 on the right), so that we don't .\" go past 80 columns total, particularly in .nf/.fi regions. .\" vim:set ai et sts=4 sw=4 tw=70: