[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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: