DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Xft(3)





NAME

        Xft - X FreeType interface library


DESCRIPTION

       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.


HEADER FILE

       #include <X11/Xft/Xft.h>


CONSTANTS

       XFT_MAJOR
              is the major version number of Xft.

       XFT_MINOR
              is the minor version number of Xft.

       XFT_REVISION
              is the revision number of Xft.

       XFT_VERSION
              is  XFT_MAJOR  times  10000 (ten thousand), plus XFT_MINOR times
              100, plus XFT_REVISION.

       XftVersion
              is an alias for XFT_VERSION.

       The following example illustrates how Xft's version constants might  be
       used:
           #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.\n", XFT_MAJOR,
                         XFT_MINOR,
                         XFT_REVISION);
           #endif


DATA TYPES

       XftFont
              typedef struct _XftFont {
                  int         ascent;
                  int         descent;
                  int         height;
                  int         max_advance_width;
                  FcCharSet   *charset;
                  FcPattern   *pattern;
              } XftFont;
              An XftFont is the primary data structure of interest to program-
              mers using Xft; it contains general font metrics and pointers to
              the  Fontconfig  character  set  and pattern associated with the
              font.  The FcCharSet and FcPattern data types are defined by the
              Fontconfig library.

              XftFonts  are  populated with any of XftFontOpen(), XftFontOpen-
              Name(), XftFontOpenXlfd(), XftFontOpenInfo(), or XftFontOpenPat-
              tern().   XftFontCopy()  is used to duplicate XftFonts, and Xft-
              FontClose() is used to mark an XftFont as unused.  XftFonts  are
              internally  allocated,  reference-counted, and freed by Xft; the
              programmer does not ordinarily need to allocate or free  storage
              for them.

              XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(),
              and XftDrawGlyphSpec() use XftFonts to render text to an XftDraw
              object, which may correspond to either a core X drawable or an X
              Rendering Extension drawable.

              XftGlyphExtents() and the XftTextExtents*() family are  used  to
              determine the extents (maximum dimensions) of an XftFont.

              An  XftFont's glyph or character coverage can be determined with
              XftFontCheckGlyph() or XftCharExists().  XftCharIndex()  returns
              the  XftFont-specific  character  index corresponding to a given
              Unicode codepoint.

              XftGlyphRender(), XftGlyphSpecRender(), XftCharSpecRender(), and
              the  XftTextRender*() family use XftFonts to draw into X Render-
              ing Extension Picture structures.   Note:  XftDrawGlyphs(),  the
              XftDrawString*()  family,  XftDrawCharSpec(),  and XftDrawGlyph-
              Spec() provide a means of rendering fonts that is independent of
              the availability of the X Rendering Extension on the X server.

       XftFontInfo
              is  an opaque object that stores information about a font.  Xft-
              FontInfo structures are created with XftFontInfoCreate(),  freed
              with XftFontInfoDestroy(), and compared with XftFontInfoEqual().
              XftFontInfo objects are internally allocated and freed  by  Xft;
              the  programmer  does  not  ordinarily  need to allocate or free
              storage for them.

              Each XftFontInfo structure in use is associated  with  a  unique
              identifier,  which  can be retrieved with XftFontInfoHash().  An
              XftFont can be  opened  based  on  XftFontInfo  data  with  Xft-
              FontOpenInfo().

       XftColor
              typedef struct _XftColor {
                  unsigned long   pixel;
                  XRenderColor    color;
              } XftColor;
              An  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 XRenderColor data type is defined by
              the X Render Extension library.

              XftColorAllocName() and  XftColorAllocValue()  request  a  color
              allocation  from  the X server (if necessary) and initialize the
              members of XftColor.  XftColorFree() instructs the X  server  to
              free the color currently allocated for an XftColor.

              One  an XftColor has been initialized, XftDrawSrcPicture(), Xft-
              DrawGlyphs(), the  XftDrawString*()  family,  XftDrawCharSpec(),
              XftDrawCharFontSpec(),     XftDrawGlyphSpec(),     XftDrawGlyph-
              FontSpec(), and  XftDrawRect()  may  be  used  to  draw  various
              objects using it.

       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.

              XftDraw  objects  are created with any of XftDrawCreate() (which
              associates an XftDraw with an existing X drawable),  XftDrawCre-
              ateBitmap(),  or  XftDrawCreateAlpha(),  and destroyed with Xft-
              DrawDestroy().  The X drawable associated with an XftDraw can be
              changed with XftDrawChange().  XftDraws are internally allocated
              and freed by Xft; the programmer does  not  ordinarily  need  to
              allocate or free storage for them.

              The  X Display, Drawable, Colormap, and Visual of an XftDraw can
              be queried with XftDrawDisplay(), XftDrawDrawable(), XftDrawCol-
              ormap(),  and  XftDrawVisual(),  respectively.   The X Rendering
              Extension Picture associated with an XftDraw is returned by Xft-
              DrawPicture().

       XftCharSpec
              typedef struct _XftCharSpec {
                  FcChar32    ucs4;
                  short       x;
                  short       y;
              } XftCharSpec;

              The FcChar32 data type is defined by the Fontconfig library.

       XftCharFontSpec
              typedef struct _XftCharFontSpec {
                  XftFont     *font;
                  FcChar32    ucs4;
                  short       x;
                  short       y;
              } XftCharFontSpec;

              The FcChar32 data type is defined by the Fontconfig library.

       XftGlyphSpec
              typedef struct _XftGlyphSpec {
                  FT_UInt     glyph;
                  short       x;
                  short       y;
              } XftGlyphSpec;

              The FT_UInt data type is defined by the FreeType library.

       XftGlyphFontSpec
              typedef struct _XftGlyphFontSpec {
                  XftFont     *font;
                  FT_UInt     glyph;
                  short       x;
                  short       y;
              } XftGlyphFontSpec;

              The FT_UInt data type is defined by the FreeType library.


FUNCTIONS

   Opening and Matching Fonts
       XftFont *
       XftFontOpen (Display *dpy,
                    int     screen,
                    ...);
       XftFontOpen  takes a list of pattern element triples of the form 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 screen on display dpy.  The Display data type is  defined
       by the X11 library.  Returns NULL if no match is found.

       Example:
           font = XftFontOpen (dpy, screen,
                               XFT_FAMILY, XftTypeString, "charter",
                               XFT_SIZE, XftTypeDouble, 12.0,
                               NULL);
       This opens the "charter" font at 12 points.  The point size is automat-
       ically converted to the correct pixel size based on the  resolution  of
       the monitor.

       XftFont *
       XftFontOpenName (Display       *dpy,
                        int           screen,
                        unsigned char *name);
       XftFontOpenName  behaves  as  XftFontOpen  does, except that it takes a
       Fontconfig pattern string (which is passed to the Fontconfig  library's
       FcNameParse() function).

       XftFont *
       XftFontOpenXlfd (Display       *dpy,
                        int           screen,
                        unsigned char *xlfd)
       XftFontOpenXlfd  behaves  as  XftFontOpen  does, except that it takes a
       string containing an X Logical Font Description (XLFD).

       FcPattern *
       XftFontMatch (Display   *dpy,
                     int       screen,
                     FcPattern *pattern,
                     FcResult  *result);
       Also used internally by the XftFontOpen*  functions,  XftFontMatch  can
       also  be used directly to determine the Fontconfig font pattern result-
       ing from an Xft font open request.  The  FcPattern  and  FcResult  data
       types are defined by the Fontconfig library.

   Determining the Pixel Extents of a Text String
       void
       XftTextExtents8 (Display    *dpy,
                        XftFont    *font,
                        FcChar8    *string,
                        int        len,
                        XGlyphInfo *extents);
       XftTextExtents8  computes  the  pixel extents on display dpy of no more
       than len glyphs of a string consisting  of  eight-bit  characters  when
       drawn  with  font,  storing  them in extents.  The FcChar8 data type is
       defined by the Fontconfig library, and  the  XGlyphInfo  data  type  is
       defined by the X Rendering Extension library.

       void
       XftTextExtents16 (Display    *dpy,
                         XftFont    *font,
                         FcChar16   *string,
                         int        len,
                         XGlyphInfo *extents);
       XftTextExtents16  computes  the pixel extents on display dpy of no more
       than len glyphs of a string consisting of sixteen-bit  characters  when
       drawn  with  font,  storing them in extents.  The FcChar16 data type is
       defined by the Fontconfig library, and  the  XGlyphInfo  data  type  is
       defined by the X Rendering Extension library.

       void
       XftTextExtents32 (Display    *dpy,
                         XftFont    *font,
                         FcChar32   *string,
                         int        len,
                         XGlyphInfo *extents);
       XftTextExtents32  computes  the pixel extents on display dpy of no more
       than len glyphs of a string  consisting  of  thirty-two-bit  characters
       when  drawn with font, storing them in extents.  The FcChar32 data type
       is defined by the Fontconfig library, and the XGlyphInfo data  type  is
       defined by the X Rendering Extension library.

       void
       XftTextExtentsUtf8 (Display    *dpy,
                           XftFont    *font,
                           FcChar8    *string,
                           int        len,
                           XGlyphInfo *extents);
       XftTextExtentsUtf8 computes the pixel extents on display dpy of no more
       than len bytes of a UTF-8 encoded string when drawn with font,  storing
       them  in extents.  The XGlyphInfo data type is defined by the X Render-
       ing Extension library.

       void
       XftTextExtentsUtf16 (Display    *dpy,
                            XftFont    *font,
                            FcChar8    *string,
                            FcEndian   endian,
                            int        len,
                            XGlyphInfo *extents);
       XftTextExtentsUtf16 computes the pixel extents on  display  dpy  of  no
       more  than  len  bytes  of  a UTF-16LE- or UTF-16BE-encoded string when
       drawn with font, storing them in extents.   The  endianness  of  string
       must  be specified in endian.  The FcEndian data type is defined by the
       Fontconfig library, and the XGlyphInfo data type is defined  by  the  X
       Rendering Extension library.

       void
       XftGlyphExtents (Display    *dpy,
                        XftFont    *font,
                        FT_UInt    *glyphs,
                        int        nglyphs,
                        XGlyphInfo *extents);
       Also  used internally by the XftTextExtents* functions, XftGlyphExtents
       computes the pixel extents on display dpy of no more  than  nglyphs  in
       the array glyphs drawn with font, storing them in extents.  The FT_UInt
       data type is defined by the FreeType library, and the  XGlyphInfo  data
       type is defined by the X Rendering Extension library.

   Drawing Strings (and Other Things)
       XftDraw *
       XftDrawCreate (Display  *dpy,
                      Drawable drawable,
                      Visual   *visual,
                      Colormap colormap);
       XftDrawCreate  creates  a structure that can be used to render text and
       rectangles using the specified drawable, visual, and colormap  on  dis-
       play.  The Drawable, Visual, and Colormap data types are defined by the
       X11 library.

       XftDraw *
       XftDrawCreateBitmap (Display *dpy,
                            Pixmap  bitmap);
       XftDrawCreateBitmap behaves as  XftDrawCreate,  except  it  uses  an  X
       pixmap of color depth 1 instead of an X drawable.  The Pixmap data type
       is defined by the X11 library.

       XftDraw *
       XftDrawCreateAlpha (Display *dpy,
                           Pixmap  pixmap,
                           int     depth);
       XftDrawCreateAlpha behaves as XftDrawCreate, except it uses an X pixmap
       of color depth depth instead of an X drawable.  The Pixmap data type is
       defined by the X11 library.

       void
       XftDrawChange (XftDraw  *draw,
                      Drawable drawable);
       XftDrawChange changes the X drawable association of  the  existing  Xft
       draw object draw from its current value to drawable.

       Display *
       XftDrawDisplay (XftDraw *draw);
       XftDrawDisplay returns a pointer to the display associated with the Xft
       draw object draw.

       Drawable
       XftDrawDrawable (XftDraw *draw);
       XftDrawDrawable returns the X drawable associated  with  the  Xft  draw
       object draw.

       Colormap
       XftDrawColormap (XftDraw *draw);
       XftDrawColormap  returns  the  colormap  associatied  with the Xft draw
       object draw.

       Visual *
       XftDrawVisual (XftDraw *draw);
       XftDrawVisual returns a pointer to the visual associated with  the  Xft
       draw object draw.

       Picture
       XftDrawPicture (XftDraw *draw);
       XftDrawPicture  returns the picture associated with the Xft draw object
       draw.  If the the X server does not support the X Rendering  Extension,
       0 is returned.

       Picture
       XftDrawSrcPicture (XftDraw *draw,
                          XftColor *color);
       This  function  is  never  called if the X server doesn't support the X
       Rendering Extension; instead, XftGlyphCore is used.

       void
       XftDrawDestroy (XftDraw *draw);
       XftDrawDestroy destroys draw (created by one  of  the  XftCreate  func-
       tions) and frees the memory that was allocated for it.

       void
       XftDrawString8 (XftDraw         *d,
                       XRenderColor    *color,
                       XftFont         *font,
                       int             x,
                       int             y,
                       unsigned char   *string,
                       int             len);
       XftDrawString8  draws no more than len glyphs of string to Xft drawable
       d using font in color at position x, y.  The XRenderColor data type  is
       defined by the X Rendering Extension library.

       void
       XftDrawRect (XftDraw        *d,
                    XRenderColor   *color,
                    int            x,
                    int            y,
                    unsigned int   width,
                    unsigned int   height);
       XftDrawRect  draws a solid rectangle of the specified color, width, and
       height at position x, y to Xft drawable d.


COMPATIBILITY

       As of version 2, Xft has become relatively stable and  is  expected  to
       retain source and binary compatibility in future releases.

       Xft  does  provide a compatibility interface to its previous major ver-
       sion, Xft 1.x, described below.

   Xft 1.x Compatibility Header File
       #include <X11/Xft/XftCompat.h>

   Xft 1.x Compatibility Data Types
       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  spe-
              cific fonts.

       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.

       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 list-
              ing fonts.


AUTHOR

       Keith Packard


SEE ALSO

       Fontconfig Developers Reference
       FreeType API Reference
       Xlib - C Language Interface

Xft                             Version 2.1.12                          Xft(3)

Man(1) output converted with man2html