X Strike Force Xft SVN commit: rev 86 - in trunk: . debian
Author: branden
Date: 2003-11-17 01:43:13 -0500 (Mon, 17 Nov 2003)
New Revision: 86
Modified:
trunk/Xft.3.in
trunk/debian/changelog
Log:
Document more functions in the Xft(3) manual page.
- Xft.3.in
Modified: trunk/Xft.3.in
===================================================================
--- trunk/Xft.3.in 2003-10-13 05:44:24 UTC (rev 85)
+++ trunk/Xft.3.in 2003-11-17 06:43:13 UTC (rev 86)
@@ -21,121 +21,426 @@
.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
-.de TQ
-.br
-.ns
-.TP \\$1
-..
-.TH XFT 3 "Version @VERSION@" "Xft"
-
+.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 DATATYPES
-
+.SH "HEADER FILE"
+.B #include <X11/Xft/Xft.h>
+.SH "DATA TYPES"
.B 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 specific fonts.
-
+.PP
.B XftFont
contains general font metrics and a pointer to either the core XFontStruct
-data or a structure holding FreeType and X Render Extension data.
-
+data or a structure holding FreeType and X Rendering Extension data.
+.PP
.B XftFontStruct
-contains information about FreeType fonts used with the X Render Extension.
-
+contains information about FreeType fonts used with the X Rendering
+Extension.
+.PP
.B 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.
-
+.PP
.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.
-
+.PP
.B XftDraw
is an opaque object which holds information used to render to an X drawable
-using either core protocol or the X Rendering extension.
-
+using either the core protocol or the X Rendering Extension.
.SH FUNCTIONS
+.SS "Opening and Matching Fonts"
.nf
-XftFont *
-XftFontOpen (Display *dpy, int screen, ...);
+\fBXftFont *\fR
+\fBXftFontOpen (Display *\fIdpy\fB,\fR
+\fB int \fIscreen\fB,\fR
+\fB ...);\fR\fR
.fi
.B XftFontOpen
-takes a list of pattern elements of the form (field, type, value) terminated
-with a NULL, matches that pattern against the available fonts and opens the
-matching font.
+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:
-.br
- font = XftFontOpen (dpy, scr,
- XFT_FAMILY, XftTypeString, "charter",
- XFT_SIZE, XftTypeDouble, 12.0,
- NULL);
+.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
-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.
+.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
-void
-XftTextExtents8 (Display *dpy,
- XftFont *font,
- unsigned char *string,
- int len,
- XGlyphInfo *extents);
+\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
+Used internally by the
+.B 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 of "string" when drawn with "font".
+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
-XftDraw *
-XftDrawCreate (Display *dpy,
- Drawable drawable,
- Visual *visual,
- Colormap colormap);
+\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
+behaves as
+.B XftTextExtents8
+does, except that it expects an array of sixteen\-bit characters as the
+.IR string .
+The
+.B FcChar16
+data type is defined by the Fontconfig 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
+.PP
+.B XftTextExtents32
+behaves as
+.B XftTextExtents8
+does, except that it expects an array of thirty\-two\-bit characters as the
+.IR string .
+The
+.B FcChar32
+data type is defined by the Fontconfig 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
+behaves as
+.B XftTextExtents8
+does, except that it expects a
+.I string
+consisting of UTF\-8 encoded text.
+.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
+behaves as
+.B XftTextExtents8
+does, except that it expects a
+.I string
+consisting of UTF\-16LE or UTF\-16BE encoded text. The endianness must be
+specified in
+.IR endian .
+The
+.B FcEndian
+data type is defined by the Fontconfig 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
+Used internally by the
+.B 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
-to the screen.
+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
-void
-XftDrawString8 (XftDraw *d,
- XRenderColor *color,
- XftFont *font,
- int x,
- int y,
- unsigned char *string,
- int len);
+\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 .
+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 "string" using "font" in "color" at "x, y".
+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
-void
-XftDrawRect (XftDraw *d,
- XRenderColor *color,
- int x,
- int y,
- unsigned int width,
- unsigned int height);
+\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
-fills a solid rectangle in the specified color.
-
+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,
+As of version 2,
.B Xft
has become relatively stable and is expected to retain source and binary
compatibility in future releases.
-
.SH AUTHOR
Keith Packard, member of the XFree86 Project, Inc.
+.SH "SEE ALSO"
+.I Fontconfig Developers Reference
+.br
+.I Xlib \- C Language Interface
Modified: trunk/debian/changelog
===================================================================
--- trunk/debian/changelog 2003-10-13 05:44:24 UTC (rev 85)
+++ trunk/debian/changelog 2003-11-17 06:43:13 UTC (rev 86)
@@ -13,8 +13,11 @@
+ Drop libxft-dev's dependency on pkg-config; pkg-config is supported
but not mandated.
- -- Branden Robinson <branden@debian.org> Mon, 13 Oct 2003 00:38:47 -0500
+ * Document more functions in the Xft(3) manual page.
+ - Xft.3.in
+ -- Branden Robinson <branden@debian.org> Mon, 17 Nov 2003 01:42:06 -0500
+
xft (2.1.2-4) unstable; urgency=low
* Set AM_MAINTAINER_MODE because we do not want users of the Debian source
@@ -301,4 +304,5 @@
-- Colin Walters <walters@debian.org> Sun, 13 Oct 2002 14:43:56 -0400
$Id$
+
vim:set ai tw=78 et sw=2 sts=2:
Reply to: