add section on manipulating font patterns

Signed-off-by: Thomas E. Dickey <dickey@invisible-island.net>

1 files changed, 58 insertions, 4 deletions

diff --git a/man/Xft.man b/man/Xft.man
index 6a2504a..32aa182 100644
--- a/man/Xft.man
+++ b/man/Xft.man
@@ -228,10 +228,6 @@ 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()
 .SS
 .B XftFontInfo
 is an opaque object that stores information about a font.
@@ -1130,6 +1126,64 @@ to
 .B Xft
 drawable
 .IR d .
+.SS Manipulating patterns
+.PS
+\fBFcFontSet\fP *\fBXftListFonts\fP (
+	\fBDisplay\fP	*\fIdpy\fP,
+	\fBint\fP	 \fIscreen\fP,
+	...);
+.PE
+.B Xft
+uses
+.BR FcPatternVapBuild ()
+and
+.BR FcObjectSetVapBuild ()
+to process the variable-length parameter list,
+and
+.BR FcFontList ()
+to obtain a list of matching Fontconfig patterns,
+which it returns to the caller.
+The caller can dispose of the return value using
+.BR FcPatternDestroy ().
+.PS
+\fBFcPattern\fP *\fBXftNameParse\fP (
+	\fB_Xconst char\fP	*\fIname\fP);
+.PE
+.B Xft
+uses Fontconfig to parse the name,
+passing the
+.I name
+to
+.BR FcNameParse (),
+returning the result.
+.PS
+\fBFcBool\fP \fBXftNameUnparse\fP (
+	\fBFcPattern\fP	*\fIpat\fP,
+	\fBchar\fP	*\fIdest\fP,
+	\fBint\fP	 \fIlen\fP);
+.PE
+Like
+.BR XfgNameParse (),
+.B Xft
+uses Fontconfig.
+In this case, it uses
+.BR FcNameUnparse (),
+which converts the pattern
+.I pat
+back into a string that can be parsed.
+.BR XftNameUnparse ()
+stores the result via the caller's pointer
+.IR dest ,
+but checks first if it will fit,
+using the
+.I len
+parameter.
+If it fits,
+.B Xft
+copies the string and returns
+.BR FcTrue ,
+otherwise it returns
+.BR FcFalse .
 .SH COMPATIBILITY
 As of version 2,
 .B Xft