Man Linux: Main Page and Category List

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
              programmers 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(),
              XftFontOpenName(),  XftFontOpenXlfd(),   XftFontOpenInfo(),   or
              XftFontOpenPattern().    XftFontCopy()   is  used  to  duplicate
              XftFonts, and XftFontClose() 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
              Rendering Extension Picture structures.  Note:  XftDrawGlyphs(),
              the     XftDrawString*()    family,    XftDrawCharSpec(),    and
              XftDrawGlyphSpec() 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.
              XftFontInfo  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
              XftFontOpenInfo().

       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(),
              XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(),
              XftDrawCharFontSpec(),                       XftDrawGlyphSpec(),
              XftDrawGlyphFontSpec(),  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),
              XftDrawCreateBitmap(), or  XftDrawCreateAlpha(),  and  destroyed
              with  XftDrawDestroy().   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(),
              XftDrawColormap(), and  XftDrawVisual(),  respectively.   The  X
              Rendering  Extension  Picture  associated  with  an  XftDraw  is
              returned by XftDrawPicture().

       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
       automatically  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
       resulting  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
       Rendering 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
       display.  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
       functions) 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
       version, 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
              specific 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
              listing fonts.

AUTHOR

       Keith Packard

SEE ALSO

       Fontconfig Developers Reference
       FreeType API Reference
       Xlib - C Language Interface