diff options
Diffstat (limited to 'libXft/man/Xft.man')
| -rw-r--r-- | libXft/man/Xft.man | 845 |
1 files changed, 845 insertions, 0 deletions
diff --git a/libXft/man/Xft.man b/libXft/man/Xft.man new file mode 100644 index 000000000..4ed2742d2 --- /dev/null +++ b/libXft/man/Xft.man @@ -0,0 +1,845 @@ +.\" +.\" 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 __libmansuffix__ __vendorversion__ +.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 <X11/Xft/Xft.h> +.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 <X11/Xft/XftCompat.h> +.\" .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: |