doc/fontconfig-devel.txt

   1 Fontconfig Developers Reference, Version 2.12.1
   2
   3    Copyright © 2002 Keith Packard
   4
   5    Permission to use, copy, modify, distribute, and sell this
   6    software and its documentation for any purpose is hereby
   7    granted without fee, provided that the above copyright notice
   8    appear in all copies and that both that copyright notice and
   9    this permission notice appear in supporting documentation, and
  10    that the name of the author(s) not be used in advertising or
  11    publicity pertaining to distribution of the software without
  12    specific, written prior permission. The authors make no
  13    representations about the suitability of this software for any
  14    purpose. It is provided "as is" without express or implied
  15    warranty.
  16
  17    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
  18    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  19    AND FITNESS, IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY
  20    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  21    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
  22    IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  23    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  24    THIS SOFTWARE.
  25            _______________________________________________
  26
  27    Table of Contents
  28    DESCRIPTION
  29    FUNCTIONAL OVERVIEW
  30    Datatypes
  31    FUNCTIONS
  32
  33 DESCRIPTION
  34
  35    Fontconfig is a library designed to provide system-wide font
  36    configuration, customization and application access.
  37      __________________________________________________________
  38
  39 FUNCTIONAL OVERVIEW
  40
  41    Fontconfig contains two essential modules, the configuration
  42    module which builds an internal configuration from XML files
  43    and the matching module which accepts font patterns and returns
  44    the nearest matching font.
  45      __________________________________________________________
  46
  47 FONT CONFIGURATION
  48
  49    The configuration module consists of the FcConfig datatype,
  50    libexpat and FcConfigParse which walks over an XML tree and
  51    amends a configuration with data found within. From an external
  52    perspective, configuration of the library consists of
  53    generating a valid XML tree and feeding that to FcConfigParse.
  54    The only other mechanism provided to applications for changing
  55    the running configuration is to add fonts and directories to
  56    the list of application-provided font files.
  57
  58    The intent is to make font configurations relatively static,
  59    and shared by as many applications as possible. It is hoped
  60    that this will lead to more stable font selection when passing
  61    names from one application to another. XML was chosen as a
  62    configuration file format because it provides a format which is
  63    easy for external agents to edit while retaining the correct
  64    structure and syntax.
  65
  66    Font configuration is separate from font matching; applications
  67    needing to do their own matching can access the available fonts
  68    from the library and perform private matching. The intent is to
  69    permit applications to pick and choose appropriate
  70    functionality from the library instead of forcing them to
  71    choose between this library and a private configuration
  72    mechanism. The hope is that this will ensure that configuration
  73    of fonts for all applications can be centralized in one place.
  74    Centralizing font configuration will simplify and regularize
  75    font installation and customization.
  76      __________________________________________________________
  77
  78 FONT PROPERTIES
  79
  80    While font patterns may contain essentially any properties,
  81    there are some well known properties with associated types.
  82    Fontconfig uses some of these properties for font matching and
  83    font completion. Others are provided as a convenience for the
  84    application's rendering mechanism.
  85                  Property Definitions
  86
  87     Property       C Preprocessor Symbol  Type    Description
  88     ----------------------------------------------------
  89     family         FC_FAMILY              String  Font family names
  90     familylang     FC_FAMILYLANG          String  Language corresponding
  91  to
  92                                                   each family name
  93     style          FC_STYLE               String  Font style. Overrides
  94 weight
  95                                                   and slant
  96     stylelang      FC_STYLELANG           String  Language corresponding
  97  to
  98                                                   each style name
  99     fullname       FC_FULLNAME            String  Font face full name wh
 100 ere
 101                                                   different from family
 102 and
 103                                                   family + style
 104     fullnamelang   FC_FULLNAMELANG        String  Language corresponding
 105  to
 106                                                   each fullname
 107     slant          FC_SLANT               Int     Italic, oblique or rom
 108 an
 109     weight         FC_WEIGHT              Int     Light, medium, demibol
 110 d,
 111                                                   bold or black
 112     size           FC_SIZE                Double  Point size
 113     width          FC_WIDTH               Int     Condensed, normal or e
 114 xpanded
 115     aspect         FC_ASPECT              Double  Stretches glyphs horiz
 116 ontally
 117                                                   before hinting
 118     pixelsize      FC_PIXEL_SIZE          Double  Pixel size
 119     spacing        FC_SPACING             Int     Proportional, dual-wid
 120 th,
 121                                                   monospace or charcell
 122     foundry        FC_FOUNDRY             String  Font foundry name
 123     antialias      FC_ANTIALIAS           Bool    Whether glyphs can be
 124                                                   antialiased
 125     hinting        FC_HINTING             Bool    Whether the rasterizer
 126  should
 127                                                   use hinting
 128     hintstyle      FC_HINT_STYLE          Int     Automatic hinting styl
 129 e
 130     verticallayout FC_VERTICAL_LAYOUT     Bool    Use vertical layout
 131     autohint       FC_AUTOHINT            Bool    Use autohinter instead
 132  of
 133                                                   normal hinter
 134     globaladvance  FC_GLOBAL_ADVANCE      Bool    Use font global advanc
 135 e data (deprecated)
 136     file           FC_FILE                String  The filename holding t
 137 he font
 138     index          FC_INDEX               Int     The index of the font
 139 within
 140                                                   the file
 141     ftface         FC_FT_FACE             FT_Face Use the specified Free
 142 Type
 143                                                   face object
 144     rasterizer     FC_RASTERIZER          String  Which rasterizer is in
 145  use (deprecated)
 146     outline        FC_OUTLINE             Bool    Whether the glyphs are
 147  outlines
 148     scalable       FC_SCALABLE            Bool    Whether glyphs can be
 149 scaled
 150     scale          FC_SCALE               Double  Scale factor for point
 151 ->pixel
 152                                                   conversions (deprecate
 153 d)
 154     symbol         FC_SYMBOL              Bool    Whether font uses MS s
 155 ymbol-font encoding
 156     color          FC_COLOR               Bool    Whether any glyphs hav
 157 e color
 158     dpi            FC_DPI                 Double  Target dots per inch
 159     rgba           FC_RGBA                Int     unknown, rgb, bgr, vrg
 160 b,
 161                                                   vbgr, none - subpixel
 162 geometry
 163     lcdfilter      FC_LCD_FILTER          Int     Type of LCD filter
 164     minspace       FC_MINSPACE            Bool    Eliminate leading from
 165  line
 166                                                   spacing
 167     charset        FC_CHARSET             CharSet Unicode chars encoded
 168 by
 169                                                   the font
 170     lang           FC_LANG                LangSet Set of RFC-3066-style
 171                                                   languages this font su
 172 pports
 173     fontversion    FC_FONTVERSION         Int     Version number of the
 174 font
 175     capability     FC_CAPABILITY          String  List of layout capabil
 176 ities in
 177                                                   the font
 178     fontformat     FC_FONTFORMAT          String  String name of the fon
 179 t format
 180     embolden       FC_EMBOLDEN            Bool    Rasterizer should
 181                                                   synthetically embolden
 182  the font
 183     embeddedbitmap FC_EMBEDDED_BITMAP     Bool    Use the embedded bitma
 184 p instead
 185                                                   of the outline
 186     decorative     FC_DECORATIVE          Bool    Whether the style is a
 187  decorative
 188                                                   variant
 189     fontfeatures   FC_FONT_FEATURES       String  List of extra feature
 190 tags in
 191                                                   OpenType to be enabled
 192     namelang       FC_NAMELANG            String  Language name to be us
 193 ed for the
 194                                                   default value of famil
 195 ylang,
 196                                                   stylelang and fullname
 197 lang
 198     prgname        FC_PRGNAME             String  Name of the running pr
 199 ogram
 200     hash           FC_HASH                String  SHA256 hash value of t
 201 he font data
 202                                                   with "sha256:" prefix
 203 (deprecated)
 204     postscriptname FC_POSTSCRIPT_NAME     String  Font name in PostScrip
 205 t
 206      __________________________________________________________
 207
 208 Datatypes
 209
 210    Fontconfig uses abstract data types to hide internal
 211    implementation details for most data structures. A few
 212    structures are exposed where appropriate.
 213      __________________________________________________________
 214
 215 FcChar8, FcChar16, FcChar32, FcBool
 216
 217    These are primitive data types; the FcChar* types hold
 218    precisely the number of bits stated (if supported by the C
 219    implementation). FcBool holds one of two C preprocessor
 220    symbols: FcFalse or FcTrue.
 221      __________________________________________________________
 222
 223 FcMatrix
 224
 225    An FcMatrix holds an affine transformation, usually used to
 226    reshape glyphs. A small set of matrix operations are provided
 227    to manipulate these.
 228         typedef struct _FcMatrix {
 229                 double xx, xy, yx, yy;
 230         } FcMatrix;
 231      __________________________________________________________
 232
 233 FcCharSet
 234
 235    An FcCharSet is an abstract type that holds the set of encoded
 236    Unicode chars in a font. Operations to build and compare these
 237    sets are provided.
 238      __________________________________________________________
 239
 240 FcLangSet
 241
 242    An FcLangSet is an abstract type that holds the set of
 243    languages supported by a font. Operations to build and compare
 244    these sets are provided. These are computed for a font based on
 245    orthographic information built into the fontconfig library.
 246    Fontconfig has orthographies for all of the ISO 639-1 languages
 247    except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA.
 248    If you have orthographic information for any of these
 249    languages, please submit them.
 250      __________________________________________________________
 251
 252 FcLangResult
 253
 254    An FcLangResult is an enumeration used to return the results of
 255    comparing two language strings or FcLangSet objects.
 256    FcLangEqual means the objects match language and territory.
 257    FcLangDifferentTerritory means the objects match in language
 258    but differ in territory. FcLangDifferentLang means the objects
 259    differ in language.
 260      __________________________________________________________
 261
 262 FcType
 263
 264    Tags the kind of data stored in an FcValue.
 265      __________________________________________________________
 266
 267 FcValue
 268
 269    An FcValue object holds a single value with one of a number of
 270    different types. The 'type' tag indicates which member is
 271    valid.
 272         typedef struct _FcValue {
 273                 FcType type;
 274                 union {
 275                         const FcChar8 *s;
 276                         int i;
 277                         FcBool b;
 278                         double d;
 279                         const FcMatrix *m;
 280                         const FcCharSet *c;
 281                         void *f;
 282                         const FcLangSet *l;
 283                 } u;
 284         } FcValue;
 285
 286                   FcValue Members
 287
 288         Type            Union member    Datatype
 289         --------------------------------
 290         FcTypeVoid      (none)          (none)
 291         FcTypeInteger   i               int
 292         FcTypeDouble    d               double
 293         FcTypeString    s               FcChar8 *
 294         FcTypeBool      b               b
 295         FcTypeMatrix    m               FcMatrix *
 296         FcTypeCharSet   c               FcCharSet *
 297         FcTypeFTFace    f               void * (FT_Face)
 298         FcTypeLangSet   l               FcLangSet *
 299      __________________________________________________________
 300
 301 FcPattern
 302
 303    holds a set of names with associated value lists; each name
 304    refers to a property of a font. FcPatterns are used as inputs
 305    to the matching code as well as holding information about
 306    specific fonts. Each property can hold one or more values;
 307    conventionally all of the same type, although the interface
 308    doesn't demand that.
 309      __________________________________________________________
 310
 311 FcFontSet
 312
 313         typedef struct _FcFontSet {
 314                 int nfont;
 315                 int sfont;
 316                 FcPattern **fonts;
 317         } FcFontSet;
 318
 319    An FcFontSet contains a list of FcPatterns. Internally
 320    fontconfig uses this data structure to hold sets of fonts.
 321    Externally, fontconfig returns the results of listing fonts in
 322    this format. 'nfont' holds the number of patterns in the
 323    'fonts' array; 'sfont' is used to indicate the size of that
 324    array.
 325      __________________________________________________________
 326
 327 FcStrSet, FcStrList
 328
 329    FcStrSet holds a list of strings that can be appended to and
 330    enumerated. Its unique characteristic is that the enumeration
 331    works even while strings are appended during enumeration.
 332    FcStrList is used during enumeration to safely and correctly
 333    walk the list of strings even while that list is edited in the
 334    middle of enumeration.
 335      __________________________________________________________
 336
 337 FcObjectSet
 338
 339         typedef struct _FcObjectSet {
 340                 int nobject;
 341                 int sobject;
 342                 const char **objects;
 343         } FcObjectSet;
 344
 345    holds a set of names and is used to specify which fields from
 346    fonts are placed in the the list of returned patterns when
 347    listing fonts.
 348      __________________________________________________________
 349
 350 FcObjectType
 351
 352         typedef struct _FcObjectType {
 353                 const char *object;
 354                 FcType type;
 355         } FcObjectType;
 356
 357    marks the type of a pattern element generated when parsing font
 358    names. Applications can add new object types so that font names
 359    may contain the new elements.
 360      __________________________________________________________
 361
 362 FcConstant
 363
 364         typedef struct _FcConstant {
 365             const FcChar8 *name;
 366             const char *object;
 367             int value;
 368         } FcConstant;
 369
 370    Provides for symbolic constants for new pattern elements. When
 371    'name' is seen in a font name, an 'object' element is created
 372    with value 'value'.
 373      __________________________________________________________
 374
 375 FcBlanks
 376
 377    holds a list of Unicode chars which are expected to be blank;
 378    unexpectedly blank chars are assumed to be invalid and are
 379    elided from the charset associated with the font.
 380      __________________________________________________________
 381
 382 FcFileCache
 383
 384    holds the per-user cache information for use while loading the
 385    font database. This is built automatically for the current
 386    configuration when that is loaded. Applications must always
 387    pass '0' when one is requested.
 388      __________________________________________________________
 389
 390 FcConfig
 391
 392    holds a complete configuration of the library; there is one
 393    default configuration, other can be constructed from XML data
 394    structures. All public entry points that need global data can
 395    take an optional FcConfig* argument; passing 0 uses the default
 396    configuration. FcConfig objects hold two sets of fonts, the
 397    first contains those specified by the configuration, the second
 398    set holds those added by the application at run-time.
 399    Interfaces that need to reference a particular set use one of
 400    the FcSetName enumerated values.
 401      __________________________________________________________
 402
 403 FcSetName
 404
 405    Specifies one of the two sets of fonts available in a
 406    configuration; FcSetSystem for those fonts specified in the
 407    configuration and FcSetApplication which holds fonts provided
 408    by the application.
 409      __________________________________________________________
 410
 411 FcResult
 412
 413    Used as a return type for functions manipulating FcPattern
 414    objects.
 415       FcResult Values
 416         Result Code             Meaning
 417         -----------------------------------------------------------
 418         FcResultMatch           Object exists with the specified ID
 419         FcResultNoMatch         Object doesn't exist at all
 420         FcResultTypeMismatch    Object exists, but the type doesn't matc
 421 h
 422         FcResultNoId            Object exists, but has fewer values
 423                                 than specified
 424         FcResultOutOfMemory     malloc failed
 425      __________________________________________________________
 426
 427 FcAtomic
 428
 429    Used for locking access to configuration files. Provides a safe
 430    way to update configuration files.
 431      __________________________________________________________
 432
 433 FcCache
 434
 435    Holds information about the fonts contained in a single
 436    directory. Normal applications need not worry about this as
 437    caches for font access are automatically managed by the
 438    library. Applications dealing with cache management may want to
 439    use some of these objects in their work, however the included
 440    'fc-cache' program generally suffices for all of that.
 441      __________________________________________________________
 442
 443 FUNCTIONS
 444
 445    These are grouped by functionality, often using the main data
 446    type being manipulated.
 447      __________________________________________________________
 448
 449 Initialization
 450
 451    Table of Contents
 452    FcInitLoadConfig -- load configuration
 453    FcInitLoadConfigAndFonts -- load configuration and font data
 454    FcInit -- initialize fontconfig library
 455    FcFini -- finalize fontconfig library
 456    FcGetVersion -- library version number
 457    FcInitReinitialize -- re-initialize library
 458    FcInitBringUptoDate -- reload configuration files if needed
 459
 460    These functions provide some control over how the library is
 461    initialized.
 462
 463 FcInitLoadConfig
 464
 465 Name
 466
 467    FcInitLoadConfig -- load configuration
 468
 469 Synopsis
 470
 471 #include <fontconfig/fontconfig.h>
 472
 473    FcConfig * FcInitLoadConfig(void);
 474
 475 Description
 476
 477    Loads the default configuration file and returns the resulting
 478    configuration. Does not load any font information.
 479
 480 FcInitLoadConfigAndFonts
 481
 482 Name
 483
 484    FcInitLoadConfigAndFonts -- load configuration and font data
 485
 486 Synopsis
 487
 488 #include <fontconfig/fontconfig.h>
 489
 490    FcConfig * FcInitLoadConfigAndFonts(void);
 491
 492 Description
 493
 494    Loads the default configuration file and builds information
 495    about the available fonts. Returns the resulting configuration.
 496
 497 FcInit
 498
 499 Name
 500
 501    FcInit -- initialize fontconfig library
 502
 503 Synopsis
 504
 505 #include <fontconfig/fontconfig.h>
 506
 507    FcBool FcInit(void);
 508
 509 Description
 510
 511    Loads the default configuration file and the fonts referenced
 512    therein and sets the default configuration to that result.
 513    Returns whether this process succeeded or not. If the default
 514    configuration has already been loaded, this routine does
 515    nothing and returns FcTrue.
 516
 517 FcFini
 518
 519 Name
 520
 521    FcFini -- finalize fontconfig library
 522
 523 Synopsis
 524
 525 #include <fontconfig/fontconfig.h>
 526
 527    void FcFini(void);
 528
 529 Description
 530
 531    Frees all data structures allocated by previous calls to
 532    fontconfig functions. Fontconfig returns to an uninitialized
 533    state, requiring a new call to one of the FcInit functions
 534    before any other fontconfig function may be called.
 535
 536 FcGetVersion
 537
 538 Name
 539
 540    FcGetVersion -- library version number
 541
 542 Synopsis
 543
 544 #include <fontconfig/fontconfig.h>
 545
 546    int FcGetVersion(void);
 547
 548 Description
 549
 550    Returns the version number of the library.
 551
 552 FcInitReinitialize
 553
 554 Name
 555
 556    FcInitReinitialize -- re-initialize library
 557
 558 Synopsis
 559
 560 #include <fontconfig/fontconfig.h>
 561
 562    FcBool FcInitReinitialize(void);
 563
 564 Description
 565
 566    Forces the default configuration file to be reloaded and resets
 567    the default configuration. Returns FcFalse if the configuration
 568    cannot be reloaded (due to configuration file errors,
 569    allocation failures or other issues) and leaves the existing
 570    configuration unchanged. Otherwise returns FcTrue.
 571
 572 FcInitBringUptoDate
 573
 574 Name
 575
 576    FcInitBringUptoDate -- reload configuration files if needed
 577
 578 Synopsis
 579
 580 #include <fontconfig/fontconfig.h>
 581
 582    FcBool FcInitBringUptoDate(void);
 583
 584 Description
 585
 586    Checks the rescan interval in the default configuration,
 587    checking the configuration if the interval has passed and
 588    reloading the configuration if when any changes are detected.
 589    Returns FcFalse if the configuration cannot be reloaded (see
 590    FcInitReinitialize). Otherwise returns FcTrue.
 591      __________________________________________________________
 592
 593 FcPattern
 594
 595    Table of Contents
 596    FcPatternCreate -- Create a pattern
 597    FcPatternDuplicate -- Copy a pattern
 598    FcPatternReference -- Increment pattern reference count
 599    FcPatternDestroy -- Destroy a pattern
 600    FcPatternEqual -- Compare patterns
 601    FcPatternEqualSubset -- Compare portions of patterns
 602    FcPatternFilter -- Filter the objects of pattern
 603    FcPatternHash -- Compute a pattern hash value
 604    FcPatternAdd -- Add a value to a pattern
 605    FcPatternAddWeak -- Add a value to a pattern with weak binding
 606    FcPatternAdd-Type -- Add a typed value to a pattern
 607    FcPatternGet -- Return a value from a pattern
 608    FcPatternGet-Type -- Return a typed value from a pattern
 609    FcPatternBuild -- Create patterns from arguments
 610    FcPatternDel -- Delete a property from a pattern
 611    FcPatternRemove -- Remove one object of the specified type from
 612           the pattern
 613
 614    FcPatternPrint -- Print a pattern for debugging
 615    FcDefaultSubstitute -- Perform default substitutions in a
 616           pattern
 617
 618    FcNameParse -- Parse a pattern string
 619    FcNameUnparse -- Convert a pattern back into a string that can
 620           be parsed
 621
 622    FcPatternFormat -- Format a pattern into a string according to
 623           a format specifier
 624
 625    An FcPattern is an opaque type that holds both patterns to
 626    match against the available fonts, as well as the information
 627    about each font.
 628
 629 FcPatternCreate
 630
 631 Name
 632
 633    FcPatternCreate -- Create a pattern
 634
 635 Synopsis
 636
 637 #include <fontconfig/fontconfig.h>
 638
 639    FcPattern * FcPatternCreate(void);
 640
 641 Description
 642
 643    Creates a pattern with no properties; used to build patterns
 644    from scratch.
 645
 646 FcPatternDuplicate
 647
 648 Name
 649
 650    FcPatternDuplicate -- Copy a pattern
 651
 652 Synopsis
 653
 654 #include <fontconfig/fontconfig.h>
 655
 656    FcPattern * FcPatternDuplicate(const FcPattern *p);
 657
 658 Description
 659
 660    Copy a pattern, returning a new pattern that matches p. Each
 661    pattern may be modified without affecting the other.
 662
 663 FcPatternReference
 664
 665 Name
 666
 667    FcPatternReference -- Increment pattern reference count
 668
 669 Synopsis
 670
 671 #include <fontconfig/fontconfig.h>
 672
 673    void FcPatternReference(FcPattern *p);
 674
 675 Description
 676
 677    Add another reference to p. Patterns are freed only when the
 678    reference count reaches zero.
 679
 680 FcPatternDestroy
 681
 682 Name
 683
 684    FcPatternDestroy -- Destroy a pattern
 685
 686 Synopsis
 687
 688 #include <fontconfig/fontconfig.h>
 689
 690    void FcPatternDestroy(FcPattern *p);
 691
 692 Description
 693
 694    Decrement the pattern reference count. If all references are
 695    gone, destroys the pattern, in the process destroying all
 696    related values.
 697
 698 FcPatternEqual
 699
 700 Name
 701
 702    FcPatternEqual -- Compare patterns
 703
 704 Synopsis
 705
 706 #include <fontconfig/fontconfig.h>
 707
 708    FcBool FcPatternEqual(const FcPattern *pa, const FcPattern
 709    *pb);
 710
 711 Description
 712
 713    Returns whether pa and pb are exactly alike.
 714
 715 FcPatternEqualSubset
 716
 717 Name
 718
 719    FcPatternEqualSubset -- Compare portions of patterns
 720
 721 Synopsis
 722
 723 #include <fontconfig/fontconfig.h>
 724
 725    FcBool FcPatternEqualSubset(const FcPattern *pa, const
 726    FcPattern *pb, const FcObjectSet *os);
 727
 728 Description
 729
 730    Returns whether pa and pb have exactly the same values for all
 731    of the objects in os.
 732
 733 FcPatternFilter
 734
 735 Name
 736
 737    FcPatternFilter -- Filter the objects of pattern
 738
 739 Synopsis
 740
 741 #include <fontconfig/fontconfig.h>
 742
 743    FcPattern * FcPatternFilter(FcPattern *p, const FcObjectSet *);
 744
 745 Description
 746
 747    Returns a new pattern that only has those objects from p that
 748    are in os. If os is NULL, a duplicate of p is returned.
 749
 750 FcPatternHash
 751
 752 Name
 753
 754    FcPatternHash -- Compute a pattern hash value
 755
 756 Synopsis
 757
 758 #include <fontconfig/fontconfig.h>
 759
 760    FcChar32 FcPatternHash(const FcPattern *p);
 761
 762 Description
 763
 764    Returns a 32-bit number which is the same for any two patterns
 765    which are equal.
 766
 767 FcPatternAdd
 768
 769 Name
 770
 771    FcPatternAdd -- Add a value to a pattern
 772
 773 Synopsis
 774
 775 #include <fontconfig/fontconfig.h>
 776
 777    FcBool FcPatternAdd(FcPattern *p, const char *object, FcValue
 778    value, FcBool append);
 779
 780 Description
 781
 782    Adds a single value to the list of values associated with the
 783    property named `object. If `append is FcTrue, the value is
 784    added at the end of any existing list, otherwise it is inserted
 785    at the beginning. `value' is saved (with FcValueSave) when
 786    inserted into the pattern so that the library retains no
 787    reference to any application-supplied data structure.
 788
 789 FcPatternAddWeak
 790
 791 Name
 792
 793    FcPatternAddWeak -- Add a value to a pattern with weak binding
 794
 795 Synopsis
 796
 797 #include <fontconfig/fontconfig.h>
 798
 799    FcBool FcPatternAddWeak(FcPattern *p, const char *object,
 800    FcValue value, FcBool append);
 801
 802 Description
 803
 804    FcPatternAddWeak is essentially the same as FcPatternAdd except
 805    that any values added to the list have binding weak instead of
 806    strong.
 807
 808 FcPatternAdd-Type
 809
 810 Name
 811
 812    FcPatternAddInteger, FcPatternAddDouble, FcPatternAddString,
 813    FcPatternAddMatrix, FcPatternAddCharSet, FcPatternAddBool,
 814    FcPatternAddFTFace, FcPatternAddLangSet,
 815    FcPatternAddRange -- Add a typed value to a pattern
 816
 817 Synopsis
 818
 819 #include <fontconfig/fontconfig.h>
 820
 821    FcBool FcPatternAddInteger(FcPattern *p, const char *object,
 822    int i);
 823
 824    FcBool FcPatternAddDouble(FcPattern *p, const char *object,
 825    double d);
 826
 827    FcBool FcPatternAddString(FcPattern *p, const char *object,
 828    const FcChar8 *s);
 829
 830    FcBool FcPatternAddMatrix(FcPattern *p, const char *object,
 831    const FcMatrix *m);
 832
 833    FcBool FcPatternAddCharSet(FcPattern *p, const char *object,
 834    const FcCharSet *c);
 835
 836    FcBool FcPatternAddBool(FcPattern *p, const char *object,
 837    FcBool b);
 838
 839    FcBool FcPatternAddFTFace(FcPattern *p, const char *object,
 840    const FT_Facef);
 841
 842    FcBool FcPatternAddLangSet(FcPattern *p, const char *object,
 843    const FcLangSet *l);
 844
 845    FcBool FcPatternAddRange(FcPattern *p, const char *object,
 846    const FcRange *r);
 847
 848 Description
 849
 850    These are all convenience functions that insert objects of the
 851    specified type into the pattern. Use these in preference to
 852    FcPatternAdd as they will provide compile-time typechecking.
 853    These all append values to any existing list of values.
 854    FcPatternAddRange are available since 2.11.91.
 855
 856 FcPatternGet
 857
 858 Name
 859
 860    FcPatternGet -- Return a value from a pattern
 861
 862 Synopsis
 863
 864 #include <fontconfig/fontconfig.h>
 865
 866    FcResult FcPatternGet(FcPattern *p, const char *object, int id,
 867    FcValue *v);
 868
 869 Description
 870
 871    Returns in v the id'th value associated with the property
 872    object. The value returned is not a copy, but rather refers to
 873    the data stored within the pattern directly. Applications must
 874    not free this value.
 875
 876 FcPatternGet-Type
 877
 878 Name
 879
 880    FcPatternGetInteger, FcPatternGetDouble, FcPatternGetString,
 881    FcPatternGetMatrix, FcPatternGetCharSet, FcPatternGetBool,
 882    FcPatternGetFTFace, FcPatternGetLangSet,
 883    FcPatternGetRange -- Return a typed value from a pattern
 884
 885 Synopsis
 886
 887 #include <fontconfig/fontconfig.h>
 888
 889    FcResult FcPatternGetInteger(FcPattern *p, const char *object,
 890    int n, int *i);
 891
 892    FcResult FcPatternGetDouble(FcPattern *p, const char *object,
 893    int n, double *d);
 894
 895    FcResult FcPatternGetString(FcPattern *p, const char *object,
 896    int n, FcChar8 **s);
 897
 898    FcResult FcPatternGetMatrix(FcPattern *p, const char *object,
 899    int n, FcMatrix **s);
 900
 901    FcResult FcPatternGetCharSet(FcPattern *p, const char *object,
 902    int n, FcCharSet **c);
 903
 904    FcResult FcPatternGetBool(FcPattern *p, const char *object, int
 905    n, FcBool *b);
 906
 907    FcResult FcPatternGetFTFace(FcPattern *p, const char *object,
 908    int n, FT_Face *f);
 909
 910    FcResult FcPatternGetLangSet(FcPattern *p, const char *object,
 911    int n, FcLangSet **l);
 912
 913    FcResult FcPatternGetRange(FcPattern *p, const char *object,
 914    int n, FcRange **r);
 915
 916 Description
 917
 918    These are convenience functions that call FcPatternGet and
 919    verify that the returned data is of the expected type. They
 920    return FcResultTypeMismatch if this is not the case. Note that
 921    these (like FcPatternGet) do not make a copy of any data
 922    structure referenced by the return value. Use these in
 923    preference to FcPatternGet to provide compile-time
 924    typechecking. FcPatternGetRange are available since 2.11.91.
 925
 926 FcPatternBuild
 927
 928 Name
 929
 930    FcPatternBuild, FcPatternVaBuild, FcPatternVapBuild -- Create
 931    patterns from arguments
 932
 933 Synopsis
 934
 935 #include <fontconfig/fontconfig.h>
 936
 937    FcPattern * FcPatternBuild(FcPattern *pattern, ...);
 938
 939    FcPattern * FcPatternVaBuild(FcPattern *pattern, va_list va);
 940
 941    void FcPatternVapBuild(FcPattern *result, FcPattern *pattern,
 942    va_list va);
 943
 944 Description
 945
 946    Builds a pattern using a list of objects, types and values.
 947    Each value to be entered in the pattern is specified with three
 948    arguments:
 949
 950     1. Object name, a string describing the property to be added.
 951     2. Object type, one of the FcType enumerated values
 952     3. Value, not an FcValue, but the raw type as passed to any of
 953        the FcPatternAdd<type> functions. Must match the type of
 954        the second argument.
 955
 956    The argument list is terminated by a null object name, no
 957    object type nor value need be passed for this. The values are
 958    added to `pattern', if `pattern' is null, a new pattern is
 959    created. In either case, the pattern is returned. Example
 960 pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *)
 961 0);
 962
 963    FcPatternVaBuild is used when the arguments are already in the
 964    form of a varargs value. FcPatternVapBuild is a macro version
 965    of FcPatternVaBuild which returns its result directly in the
 966    result variable.
 967
 968 FcPatternDel
 969
 970 Name
 971
 972    FcPatternDel -- Delete a property from a pattern
 973
 974 Synopsis
 975
 976 #include <fontconfig/fontconfig.h>
 977
 978    FcBool FcPatternDel(FcPattern *p, const char *object);
 979
 980 Description
 981
 982    Deletes all values associated with the property `object',
 983    returning whether the property existed or not.
 984
 985 FcPatternRemove
 986
 987 Name
 988
 989    FcPatternRemove -- Remove one object of the specified type from
 990    the pattern
 991
 992 Synopsis
 993
 994 #include <fontconfig/fontconfig.h>
 995
 996    FcBool FcPatternRemove(FcPattern *p, const char *object, int
 997    id);
 998
 999 Description
1000
1001    Removes the value associated with the property `object' at
1002    position `id', returning whether the property existed and had a
1003    value at that position or not.
1004
1005 FcPatternPrint
1006
1007 Name
1008
1009    FcPatternPrint -- Print a pattern for debugging
1010
1011 Synopsis
1012
1013 #include <fontconfig/fontconfig.h>
1014
1015    void FcPatternPrint(const FcPattern *p);
1016
1017 Description
1018
1019    Prints an easily readable version of the pattern to stdout.
1020    There is no provision for reparsing data in this format, it's
1021    just for diagnostics and debugging.
1022
1023 FcDefaultSubstitute
1024
1025 Name
1026
1027    FcDefaultSubstitute -- Perform default substitutions in a
1028    pattern
1029
1030 Synopsis
1031
1032 #include <fontconfig/fontconfig.h>
1033
1034    void FcDefaultSubstitute(FcPattern *pattern);
1035
1036 Description
1037
1038    Supplies default values for underspecified font patterns:
1039
1040      * Patterns without a specified style or weight are set to
1041        Medium
1042      * Patterns without a specified style or slant are set to
1043        Roman
1044      * Patterns without a specified pixel size are given one
1045        computed from any specified point size (default 12), dpi
1046        (default 75) and scale (default 1).
1047
1048 FcNameParse
1049
1050 Name
1051
1052    FcNameParse -- Parse a pattern string
1053
1054 Synopsis
1055
1056 #include <fontconfig/fontconfig.h>
1057
1058    FcPattern * FcNameParse(const FcChar8 *name);
1059
1060 Description
1061
1062    Converts name from the standard text format described above
1063    into a pattern.
1064
1065 FcNameUnparse
1066
1067 Name
1068
1069    FcNameUnparse -- Convert a pattern back into a string that can
1070    be parsed
1071
1072 Synopsis
1073
1074 #include <fontconfig/fontconfig.h>
1075
1076    FcChar8 * FcNameUnparse(FcPattern *pat);
1077
1078 Description
1079
1080    Converts the given pattern into the standard text format
1081    described above. The return value is not static, but instead
1082    refers to newly allocated memory which should be freed by the
1083    caller using free().
1084
1085 FcPatternFormat
1086
1087 Name
1088
1089    FcPatternFormat -- Format a pattern into a string according to
1090    a format specifier
1091
1092 Synopsis
1093
1094 #include <fontconfig/fontconfig.h>
1095
1096    FcChar8 * FcPatternFormat(FcPattern *pat, const FcChar8
1097    *format);
1098
1099 Description
1100
1101    Converts given pattern pat into text described by the format
1102    specifier format. The return value refers to newly allocated
1103    memory which should be freed by the caller using free(), or
1104    NULL if format is invalid.
1105
1106    The format is loosely modeled after printf-style format string.
1107    The format string is composed of zero or more directives:
1108    ordinary characters (not "%"), which are copied unchanged to
1109    the output stream; and tags which are interpreted to construct
1110    text from the pattern in a variety of ways (explained below).
1111    Special characters can be escaped using backslash. C-string
1112    style special characters like \n and \r are also supported
1113    (this is useful when the format string is not a C string
1114    literal). It is advisable to always escape curly braces that
1115    are meant to be copied to the output as ordinary characters.
1116
1117    Each tag is introduced by the character "%", followed by an
1118    optional minimum field width, followed by tag contents in curly
1119    braces ({}). If the minimum field width value is provided the
1120    tag will be expanded and the result padded to achieve the
1121    minimum width. If the minimum field width is positive, the
1122    padding will right-align the text. Negative field width will
1123    left-align. The rest of this section describes various
1124    supported tag contents and their expansion.
1125
1126    A simple tag is one where the content is an identifier. When
1127    simple tags are expanded, the named identifier will be looked
1128    up in pattern and the resulting list of values returned, joined
1129    together using comma. For example, to print the family name and
1130    style of the pattern, use the format "%{family} %{style}\n". To
1131    extend the family column to forty characters use
1132    "%-40{family}%{style}\n".
1133
1134    Simple tags expand to list of all values for an element. To
1135    only choose one of the values, one can index using the syntax
1136    "%{elt[idx]}". For example, to get the first family name only,
1137    use "%{family[0]}".
1138
1139    If a simple tag ends with "=" and the element is found in the
1140    pattern, the name of the element followed by "=" will be output
1141    before the list of values. For example, "%{weight=}" may expand
1142    to the string "weight=80". Or to the empty string if pattern
1143    does not have weight set.
1144
1145    If a simple tag starts with ":" and the element is found in the
1146    pattern, ":" will be printed first. For example, combining this
1147    with the =, the format "%{:weight=}" may expand to ":weight=80"
1148    or to the empty string if pattern does not have weight set.
1149
1150    If a simple tag contains the string ":-", the rest of the the
1151    tag contents will be used as a default string. The default
1152    string is output if the element is not found in the pattern.
1153    For example, the format "%{:weight=:-123}" may expand to
1154    ":weight=80" or to the string ":weight=123" if pattern does not
1155    have weight set.
1156
1157    A count tag is one that starts with the character "#" followed
1158    by an element name, and expands to the number of values for the
1159    element in the pattern. For example, "%{#family}" expands to
1160    the number of family names pattern has set, which may be zero.
1161
1162    A sub-expression tag is one that expands a sub-expression. The
1163    tag contents are the sub-expression to expand placed inside
1164    another set of curly braces. Sub-expression tags are useful for
1165    aligning an entire sub-expression, or to apply converters
1166    (explained later) to the entire sub-expression output. For
1167    example, the format "%40{{%{family} %{style}}}" expands the
1168    sub-expression to construct the family name followed by the
1169    style, then takes the entire string and pads it on the left to
1170    be at least forty characters.
1171
1172    A filter-out tag is one starting with the character "-"
1173    followed by a comma-separated list of element names, followed
1174    by a sub-expression enclosed in curly braces. The
1175    sub-expression will be expanded but with a pattern that has the
1176    listed elements removed from it. For example, the format
1177    "%{-size,pixelsize{sub-expr}}" will expand "sub-expr" with
1178    pattern sans the size and pixelsize elements.
1179
1180    A filter-in tag is one starting with the character "+" followed
1181    by a comma-separated list of element names, followed by a
1182    sub-expression enclosed in curly braces. The sub-expression
1183    will be expanded but with a pattern that only has the listed
1184    elements from the surrounding pattern. For example, the format
1185    "%{+family,familylang{sub-expr}}" will expand "sub-expr" with a
1186    sub-pattern consisting only the family and family lang elements
1187    of pattern.
1188
1189    A conditional tag is one starting with the character "?"
1190    followed by a comma-separated list of element conditions,
1191    followed by two sub-expression enclosed in curly braces. An
1192    element condition can be an element name, in which case it
1193    tests whether the element is defined in pattern, or the
1194    character "!" followed by an element name, in which case the
1195    test is negated. The conditional passes if all the element
1196    conditions pass. The tag expands the first sub-expression if
1197    the conditional passes, and expands the second sub-expression
1198    otherwise. For example, the format
1199    "%{?size,dpi,!pixelsize{pass}{fail}}" will expand to "pass" if
1200    pattern has size and dpi elements but no pixelsize element, and
1201    to "fail" otherwise.
1202
1203    An enumerate tag is one starting with the string "[]" followed
1204    by a comma-separated list of element names, followed by a
1205    sub-expression enclosed in curly braces. The list of values for
1206    the named elements are walked in parallel and the
1207    sub-expression expanded each time with a pattern just having a
1208    single value for those elements, starting from the first value
1209    and continuing as long as any of those elements has a value.
1210    For example, the format "%{[]family,familylang{%{family}
1211    (%{familylang})\n}}" will expand the pattern "%{family}
1212    (%{familylang})\n" with a pattern having only the first value
1213    of the family and familylang elements, then expands it with the
1214    second values, then the third, etc.
1215
1216    As a special case, if an enumerate tag has only one element,
1217    and that element has only one value in the pattern, and that
1218    value is of type FcLangSet, the individual languages in the
1219    language set are enumerated.
1220
1221    A builtin tag is one starting with the character "=" followed
1222    by a builtin name. The following builtins are defined:
1223
1224    unparse
1225           Expands to the result of calling FcNameUnparse() on the
1226           pattern.
1227
1228    fcmatch
1229           Expands to the output of the default output format of
1230           the fc-match command on the pattern, without the final
1231           newline.
1232
1233    fclist
1234           Expands to the output of the default output format of
1235           the fc-list command on the pattern, without the final
1236           newline.
1237
1238    fccat
1239           Expands to the output of the default output format of
1240           the fc-cat command on the pattern, without the final
1241           newline.
1242
1243    pkgkit
1244           Expands to the list of PackageKit font() tags for the
1245           pattern. Currently this includes tags for each family
1246           name, and each language from the pattern, enumerated and
1247           sanitized into a set of tags terminated by newline.
1248           Package management systems can use these tags to tag
1249           their packages accordingly.
1250
1251    For example, the format "%{+family,style{%{=unparse}}}\n" will
1252    expand to an unparsed name containing only the family and style
1253    element values from pattern.
1254
1255    The contents of any tag can be followed by a set of zero or
1256    more converters. A converter is specified by the character "|"
1257    followed by the converter name and arguments. The following
1258    converters are defined:
1259
1260    basename
1261           Replaces text with the results of calling
1262           FcStrBasename() on it.
1263
1264    dirname
1265           Replaces text with the results of calling FcStrDirname()
1266           on it.
1267
1268    downcase
1269           Replaces text with the results of calling
1270           FcStrDowncase() on it.
1271
1272    shescape
1273           Escapes text for one level of shell expansion. (Escapes
1274           single-quotes, also encloses text in single-quotes.)
1275
1276    cescape
1277           Escapes text such that it can be used as part of a C
1278           string literal. (Escapes backslash and double-quotes.)
1279
1280    xmlescape
1281           Escapes text such that it can be used in XML and HTML.
1282           (Escapes less-than, greater-than, and ampersand.)
1283
1284    delete(chars)
1285           Deletes all occurrences of each of the characters in
1286           chars from the text. FIXME: This converter is not UTF-8
1287           aware yet.
1288
1289    escape(chars)
1290           Escapes all occurrences of each of the characters in
1291           chars by prepending it by the first character in chars.
1292           FIXME: This converter is not UTF-8 aware yet.
1293
1294    translate(from,to)
1295           Translates all occurrences of each of the characters in
1296           from by replacing them with their corresponding
1297           character in to. If to has fewer characters than from,
1298           it will be extended by repeating its last character.
1299           FIXME: This converter is not UTF-8 aware yet.
1300
1301    For example, the format "%{family|downcase|delete( )}\n" will
1302    expand to the values of the family element in pattern,
1303    lower-cased and with spaces removed.
1304
1305 Since
1306
1307    version 2.9.0
1308      __________________________________________________________
1309
1310 FcFontSet
1311
1312    Table of Contents
1313    FcFontSetCreate -- Create a font set
1314    FcFontSetDestroy -- Destroy a font set
1315    FcFontSetAdd -- Add to a font set
1316    FcFontSetList -- List fonts from a set of font sets
1317    FcFontSetMatch -- Return the best font from a set of font sets
1318    FcFontSetPrint -- Print a set of patterns to stdout
1319    FcFontSetSort -- Add to a font set
1320    FcFontSetSortDestroy -- DEPRECATED destroy a font set
1321
1322    An FcFontSet simply holds a list of patterns; these are used to
1323    return the results of listing available fonts.
1324
1325 FcFontSetCreate
1326
1327 Name
1328
1329    FcFontSetCreate -- Create a font set
1330
1331 Synopsis
1332
1333 #include <fontconfig/fontconfig.h>
1334
1335    FcFontSet * FcFontSetCreate(void);
1336
1337 Description
1338
1339    Creates an empty font set.
1340
1341 FcFontSetDestroy
1342
1343 Name
1344
1345    FcFontSetDestroy -- Destroy a font set
1346
1347 Synopsis
1348
1349 #include <fontconfig/fontconfig.h>
1350
1351    void FcFontSetDestroy(FcFontSet *s);
1352
1353 Description
1354
1355    Destroys a font set. Note that this destroys any referenced
1356    patterns as well.
1357
1358 FcFontSetAdd
1359
1360 Name
1361
1362    FcFontSetAdd -- Add to a font set
1363
1364 Synopsis
1365
1366 #include <fontconfig/fontconfig.h>
1367
1368    FcBool FcFontSetAdd(FcFontSet *s, FcPattern *font);
1369
1370 Description
1371
1372    Adds a pattern to a font set. Note that the pattern is not
1373    copied before being inserted into the set. Returns FcFalse if
1374    the pattern cannot be inserted into the set (due to allocation
1375    failure). Otherwise returns FcTrue.
1376
1377 FcFontSetList
1378
1379 Name
1380
1381    FcFontSetList -- List fonts from a set of font sets
1382
1383 Synopsis
1384
1385 #include <fontconfig/fontconfig.h>
1386
1387    FcFontSet * FcFontSetList(FcConfig *config, FcFontSet **sets,
1388    intnsets, FcPattern *pattern, FcObjectSet *object_set);
1389
1390 Description
1391
1392    Selects fonts matching pattern from sets, creates patterns from
1393    those fonts containing only the objects in object_set and
1394    returns the set of unique such patterns. If config is NULL, the
1395    default configuration is checked to be up to date, and used.
1396
1397 FcFontSetMatch
1398
1399 Name
1400
1401    FcFontSetMatch -- Return the best font from a set of font sets
1402
1403 Synopsis
1404
1405 #include <fontconfig/fontconfig.h>
1406
1407    FcPattern * FcFontSetMatch(FcConfig *config, FcFontSet **sets,
1408    intnsets, FcPattern *pattern, FcResult *result);
1409
1410 Description
1411
1412    Finds the font in sets most closely matching pattern and
1413    returns the result of FcFontRenderPrepare for that font and the
1414    provided pattern. This function should be called only after
1415    FcConfigSubstitute and FcDefaultSubstitute have been called for
1416    pattern; otherwise the results will not be correct. If config
1417    is NULL, the current configuration is used. Returns NULL if an
1418    error occurs during this process.
1419
1420 FcFontSetPrint
1421
1422 Name
1423
1424    FcFontSetPrint -- Print a set of patterns to stdout
1425
1426 Synopsis
1427
1428 #include <fontconfig/fontconfig.h>
1429
1430    void FcFontSetPrint(FcFontSet *set);
1431
1432 Description
1433
1434    This function is useful for diagnosing font related issues,
1435    printing the complete contents of every pattern in set. The
1436    format of the output is designed to be of help to users and
1437    developers, and may change at any time.
1438
1439 FcFontSetSort
1440
1441 Name
1442
1443    FcFontSetSort -- Add to a font set
1444
1445 Synopsis
1446
1447 #include <fontconfig/fontconfig.h>
1448
1449    FcFontSetSort(FcConfig *config, FcFontSet **sets, intnsets,
1450    FcPattern *pattern, FcBool trim, FcCharSet **csp, FcResult
1451    *result);
1452
1453 Description
1454
1455    Returns the list of fonts from sets sorted by closeness to
1456    pattern. If trim is FcTrue, elements in the list which don't
1457    include Unicode coverage not provided by earlier elements in
1458    the list are elided. The union of Unicode coverage of all of
1459    the fonts is returned in csp, if csp is not NULL. This function
1460    should be called only after FcConfigSubstitute and
1461    FcDefaultSubstitute have been called for p; otherwise the
1462    results will not be correct.
1463
1464    The returned FcFontSet references FcPattern structures which
1465    may be shared by the return value from multiple FcFontSort
1466    calls, applications cannot modify these patterns. Instead, they
1467    should be passed, along with pattern to FcFontRenderPrepare
1468    which combines them into a complete pattern.
1469
1470    The FcFontSet returned by FcFontSetSort is destroyed by calling
1471    FcFontSetDestroy.
1472
1473 FcFontSetSortDestroy
1474
1475 Name
1476
1477    FcFontSetSortDestroy -- DEPRECATED destroy a font set
1478
1479 Synopsis
1480
1481 #include <fontconfig/fontconfig.h>
1482
1483    FcFontSetSortDestroy(FcFontSet *set);
1484
1485 Description
1486
1487    This function is DEPRECATED. FcFontSetSortDestroy destroys set
1488    by calling FcFontSetDestroy. Applications should use
1489    FcFontSetDestroy directly instead.
1490      __________________________________________________________
1491
1492 FcObjectSet
1493
1494    Table of Contents
1495    FcObjectSetCreate -- Create an object set
1496    FcObjectSetAdd -- Add to an object set
1497    FcObjectSetDestroy -- Destroy an object set
1498    FcObjectSetBuild -- Build object set from args
1499
1500    An FcObjectSet holds a list of pattern property names; it is
1501    used to indicate which properties are to be returned in the
1502    patterns from FcFontList.
1503
1504 FcObjectSetCreate
1505
1506 Name
1507
1508    FcObjectSetCreate -- Create an object set
1509
1510 Synopsis
1511
1512 #include <fontconfig/fontconfig.h>
1513
1514    FcObjectSet * FcObjectSetCreate(void);
1515
1516 Description
1517
1518    Creates an empty set.
1519
1520 FcObjectSetAdd
1521
1522 Name
1523
1524    FcObjectSetAdd -- Add to an object set
1525
1526 Synopsis
1527
1528 #include <fontconfig/fontconfig.h>
1529
1530    FcBool FcObjectSetAdd(FcObjectSet *os, const char *object);
1531
1532 Description
1533
1534    Adds a property name to the set. Returns FcFalse if the
1535    property name cannot be inserted into the set (due to
1536    allocation failure). Otherwise returns FcTrue.
1537
1538 FcObjectSetDestroy
1539
1540 Name
1541
1542    FcObjectSetDestroy -- Destroy an object set
1543
1544 Synopsis
1545
1546 #include <fontconfig/fontconfig.h>
1547
1548    void FcObjectSetDestroy(FcObjectSet *os);
1549
1550 Description
1551
1552    Destroys an object set.
1553
1554 FcObjectSetBuild
1555
1556 Name
1557
1558    FcObjectSetBuild, FcObjectSetVaBuild,
1559    FcObjectSetVapBuild -- Build object set from args
1560
1561 Synopsis
1562
1563 #include <fontconfig/fontconfig.h>
1564
1565    FcObjectSet * FcObjectSetBuild(const char *first, ...);
1566
1567    FcObjectSet * FcObjectSetVaBuild(const char *first, va_list
1568    va);
1569
1570    void FcObjectSetVapBuild(FcObjectSet *result, const char
1571    *first, va_list va);
1572
1573 Description
1574
1575    These build an object set from a null-terminated list of
1576    property names. FcObjectSetVapBuild is a macro version of
1577    FcObjectSetVaBuild which returns the result in the result
1578    variable directly.
1579      __________________________________________________________
1580
1581 FreeType specific functions
1582
1583    Table of Contents
1584    FcFreeTypeCharIndex -- map Unicode to glyph id
1585    FcFreeTypeCharSet -- compute Unicode coverage
1586    FcFreeTypeCharSetAndSpacing -- compute Unicode coverage and
1587           spacing type
1588
1589    FcFreeTypeQuery -- compute pattern from font file (and index)
1590    FcFreeTypeQueryFace -- compute pattern from FT_Face
1591
1592    While the fontconfig library doesn't insist that FreeType be
1593    used as the rasterization mechanism for fonts, it does provide
1594    some convenience functions.
1595
1596 FcFreeTypeCharIndex
1597
1598 Name
1599
1600    FcFreeTypeCharIndex -- map Unicode to glyph id
1601
1602 Synopsis
1603
1604 #include <fontconfig.h>
1605 #include <fcfreetype.h>
1606
1607    FT_UInt FcFreeTypeCharIndex(FT_Face face, FcChar32 ucs4);
1608
1609 Description
1610
1611    Maps a Unicode char to a glyph index. This function uses
1612    information from several possible underlying encoding tables to
1613    work around broken fonts. As a result, this function isn't
1614    designed to be used in performance sensitive areas; results
1615    from this function are intended to be cached by higher level
1616    functions.
1617
1618 FcFreeTypeCharSet
1619
1620 Name
1621
1622    FcFreeTypeCharSet -- compute Unicode coverage
1623
1624 Synopsis
1625
1626 #include <fontconfig.h>
1627 #include <fcfreetype.h>
1628
1629    FcCharSet * FcFreeTypeCharSet(FT_Face face, FcBlanks *blanks);
1630
1631 Description
1632
1633    Scans a FreeType face and returns the set of encoded Unicode
1634    chars. This scans several encoding tables to build as complete
1635    a list as possible. If 'blanks' is not 0, the glyphs in the
1636    font are examined and any blank glyphs not in 'blanks' are not
1637    placed in the returned FcCharSet.
1638
1639 FcFreeTypeCharSetAndSpacing
1640
1641 Name
1642
1643    FcFreeTypeCharSetAndSpacing -- compute Unicode coverage and
1644    spacing type
1645
1646 Synopsis
1647
1648 #include <fontconfig.h>
1649 #include <fcfreetype.h>
1650
1651    FcCharSet * FcFreeTypeCharSetAndSpacing(FT_Face face, FcBlanks
1652    *blanks, int *spacing);
1653
1654 Description
1655
1656    Scans a FreeType face and returns the set of encoded Unicode
1657    chars. This scans several encoding tables to build as complete
1658    a list as possible. If 'blanks' is not 0, the glyphs in the
1659    font are examined and any blank glyphs not in 'blanks' are not
1660    placed in the returned FcCharSet. spacing receives the computed
1661    spacing type of the font, one of FC_MONO for a font where all
1662    glyphs have the same width, FC_DUAL, where the font has glyphs
1663    in precisely two widths, one twice as wide as the other, or
1664    FC_PROPORTIONAL where the font has glyphs of many widths.
1665
1666 FcFreeTypeQuery
1667
1668 Name
1669
1670    FcFreeTypeQuery -- compute pattern from font file (and index)
1671
1672 Synopsis
1673
1674 #include <fontconfig.h>
1675 #include <fcfreetype.h>
1676
1677    FcPattern * FcFreeTypeQuery(const FcChar8 *file, int id,
1678    FcBlanks *blanks, int *count);
1679
1680 Description
1681
1682    Constructs a pattern representing the 'id'th font in 'file'.
1683    The number of fonts in 'file' is returned in 'count'.
1684
1685 FcFreeTypeQueryFace
1686
1687 Name
1688
1689    FcFreeTypeQueryFace -- compute pattern from FT_Face
1690
1691 Synopsis
1692
1693 #include <fontconfig.h>
1694 #include <fcfreetype.h>
1695
1696    FcPattern * FcFreeTypeQueryFace(const FT_Face face, const
1697    FcChar8 *file, int id, FcBlanks *blanks);
1698
1699 Description
1700
1701    Constructs a pattern representing 'face'. 'file' and 'id' are
1702    used solely as data for pattern elements (FC_FILE, FC_INDEX and
1703    sometimes FC_FAMILY).
1704      __________________________________________________________
1705
1706 FcValue
1707
1708    Table of Contents
1709    FcValueDestroy -- Free a value
1710    FcValueSave -- Copy a value
1711    FcValuePrint -- Print a value to stdout
1712    FcValueEqual -- Test two values for equality
1713
1714    FcValue is a structure containing a type tag and a union of all
1715    possible datatypes. The tag is an enum of type FcType and is
1716    intended to provide a measure of run-time typechecking,
1717    although that depends on careful programming.
1718
1719 FcValueDestroy
1720
1721 Name
1722
1723    FcValueDestroy -- Free a value
1724
1725 Synopsis
1726
1727 #include <fontconfig/fontconfig.h>
1728
1729    void FcValueDestroy(FcValue v);
1730
1731 Description
1732
1733    Frees any memory referenced by v. Values of type FcTypeString,
1734    FcTypeMatrix and FcTypeCharSet reference memory, the other
1735    types do not.
1736
1737 FcValueSave
1738
1739 Name
1740
1741    FcValueSave -- Copy a value
1742
1743 Synopsis
1744
1745 #include <fontconfig/fontconfig.h>
1746
1747    FcValue FcValueSave(FcValue v);
1748
1749 Description
1750
1751    Returns a copy of v duplicating any object referenced by it so
1752    that v may be safely destroyed without harming the new value.
1753
1754 FcValuePrint
1755
1756 Name
1757
1758    FcValuePrint -- Print a value to stdout
1759
1760 Synopsis
1761
1762 #include <fontconfig/fontconfig.h>
1763
1764    void FcValuePrint(FcValue v);
1765
1766 Description
1767
1768    Prints a human-readable representation of v to stdout. The
1769    format should not be considered part of the library
1770    specification as it may change in the future.
1771
1772 FcValueEqual
1773
1774 Name
1775
1776    FcValueEqual -- Test two values for equality
1777
1778 Synopsis
1779
1780 #include <fontconfig/fontconfig.h>
1781
1782    FcBool FcValueEqual(FcValue v_a, FcValue v_b);
1783
1784 Description
1785
1786    Compares two values. Integers and Doubles are compared as
1787    numbers; otherwise the two values have to be the same type to
1788    be considered equal. Strings are compared ignoring case.
1789      __________________________________________________________
1790
1791 FcCharSet
1792
1793    Table of Contents
1794    FcCharSetCreate -- Create an empty character set
1795    FcCharSetDestroy -- Destroy a character set
1796    FcCharSetAddChar -- Add a character to a charset
1797    FcCharSetDelChar -- Add a character to a charset
1798    FcCharSetCopy -- Copy a charset
1799    FcCharSetEqual -- Compare two charsets
1800    FcCharSetIntersect -- Intersect charsets
1801    FcCharSetUnion -- Add charsets
1802    FcCharSetSubtract -- Subtract charsets
1803    FcCharSetMerge -- Merge charsets
1804    FcCharSetHasChar -- Check a charset for a char
1805    FcCharSetCount -- Count entries in a charset
1806    FcCharSetIntersectCount -- Intersect and count charsets
1807    FcCharSetSubtractCount -- Subtract and count charsets
1808    FcCharSetIsSubset -- Test for charset inclusion
1809    FcCharSetFirstPage -- Start enumerating charset contents
1810    FcCharSetNextPage -- Continue enumerating charset contents
1811    FcCharSetCoverage -- DEPRECATED return coverage for a Unicode
1812           page
1813
1814    FcCharSetNew -- DEPRECATED alias for FcCharSetCreate
1815
1816    An FcCharSet is a boolean array indicating a set of Unicode
1817    chars. Those associated with a font are marked constant and
1818    cannot be edited. FcCharSets may be reference counted
1819    internally to reduce memory consumption; this may be visible to
1820    applications as the result of FcCharSetCopy may return it's
1821    argument, and that CharSet may remain unmodifiable.
1822
1823 FcCharSetCreate
1824
1825 Name
1826
1827    FcCharSetCreate -- Create an empty character set
1828
1829 Synopsis
1830
1831 #include <fontconfig/fontconfig.h>
1832
1833    FcCharSet * FcCharSetCreate(void);
1834
1835 Description
1836
1837    FcCharSetCreate allocates and initializes a new empty character
1838    set object.
1839
1840 FcCharSetDestroy
1841
1842 Name
1843
1844    FcCharSetDestroy -- Destroy a character set
1845
1846 Synopsis
1847
1848 #include <fontconfig/fontconfig.h>
1849
1850    void FcCharSetDestroy(FcCharSet *fcs);
1851
1852 Description
1853
1854    FcCharSetDestroy decrements the reference count fcs. If the
1855    reference count becomes zero, all memory referenced is freed.
1856
1857 FcCharSetAddChar
1858
1859 Name
1860
1861    FcCharSetAddChar -- Add a character to a charset
1862
1863 Synopsis
1864
1865 #include <fontconfig/fontconfig.h>
1866
1867    FcBool FcCharSetAddChar(FcCharSet *fcs, FcChar32 ucs4);
1868
1869 Description
1870
1871    FcCharSetAddChar adds a single Unicode char to the set,
1872    returning FcFalse on failure, either as a result of a constant
1873    set or from running out of memory.
1874
1875 FcCharSetDelChar
1876
1877 Name
1878
1879    FcCharSetDelChar -- Add a character to a charset
1880
1881 Synopsis
1882
1883 #include <fontconfig/fontconfig.h>
1884
1885    FcBool FcCharSetDelChar(FcCharSet *fcs, FcChar32 ucs4);
1886
1887 Description
1888
1889    FcCharSetDelChar deletes a single Unicode char from the set,
1890    returning FcFalse on failure, either as a result of a constant
1891    set or from running out of memory.
1892
1893 Since
1894
1895    version 2.9.0
1896
1897 FcCharSetCopy
1898
1899 Name
1900
1901    FcCharSetCopy -- Copy a charset
1902
1903 Synopsis
1904
1905 #include <fontconfig/fontconfig.h>
1906
1907    FcCharSet * FcCharSetCopy(FcCharSet *src);
1908
1909 Description
1910
1911    Makes a copy of src; note that this may not actually do
1912    anything more than increment the reference count on src.
1913
1914 FcCharSetEqual
1915
1916 Name
1917
1918    FcCharSetEqual -- Compare two charsets
1919
1920 Synopsis
1921
1922 #include <fontconfig/fontconfig.h>
1923
1924    FcBool FcCharSetEqual(const FcCharSet *a, const FcCharSet *b);
1925
1926 Description
1927
1928    Returns whether a and b contain the same set of Unicode chars.
1929
1930 FcCharSetIntersect
1931
1932 Name
1933
1934    FcCharSetIntersect -- Intersect charsets
1935
1936 Synopsis
1937
1938 #include <fontconfig/fontconfig.h>
1939
1940    FcCharSet * FcCharSetIntersect(const FcCharSet *a, const
1941    FcCharSet *b);
1942
1943 Description
1944
1945    Returns a set including only those chars found in both a and b.
1946
1947 FcCharSetUnion
1948
1949 Name
1950
1951    FcCharSetUnion -- Add charsets
1952
1953 Synopsis
1954
1955 #include <fontconfig/fontconfig.h>
1956
1957    FcCharSet * FcCharSetUnion(const FcCharSet *a, const FcCharSet
1958    *b);
1959
1960 Description
1961
1962    Returns a set including only those chars found in either a or
1963    b.
1964
1965 FcCharSetSubtract
1966
1967 Name
1968
1969    FcCharSetSubtract -- Subtract charsets
1970
1971 Synopsis
1972
1973 #include <fontconfig/fontconfig.h>
1974
1975    FcCharSet * FcCharSetSubtract(const FcCharSet *a, const
1976    FcCharSet *b);
1977
1978 Description
1979
1980    Returns a set including only those chars found in a but not b.
1981
1982 FcCharSetMerge
1983
1984 Name
1985
1986    FcCharSetMerge -- Merge charsets
1987
1988 Synopsis
1989
1990 #include <fontconfig/fontconfig.h>
1991
1992    FcBool FcCharSetMerge(FcCharSet *a, const FcCharSet *b, FcBool
1993    *changed);
1994
1995 Description
1996
1997    Adds all chars in b to a. In other words, this is an in-place
1998    version of FcCharSetUnion. If changed is not NULL, then it
1999    returns whether any new chars from b were added to a. Returns
2000    FcFalse on failure, either when a is a constant set or from
2001    running out of memory.
2002
2003 FcCharSetHasChar
2004
2005 Name
2006
2007    FcCharSetHasChar -- Check a charset for a char
2008
2009 Synopsis
2010
2011 #include <fontconfig/fontconfig.h>
2012
2013    FcBool FcCharSetHasChar(const FcCharSet *fcs, FcChar32 ucs4);
2014
2015 Description
2016
2017    Returns whether fcs contains the char ucs4.
2018
2019 FcCharSetCount
2020
2021 Name
2022
2023    FcCharSetCount -- Count entries in a charset
2024
2025 Synopsis
2026
2027 #include <fontconfig/fontconfig.h>
2028
2029    FcChar32 FcCharSetCount(const FcCharSet *a);
2030
2031 Description
2032
2033    Returns the total number of Unicode chars in a.
2034
2035 FcCharSetIntersectCount
2036
2037 Name
2038
2039    FcCharSetIntersectCount -- Intersect and count charsets
2040
2041 Synopsis
2042
2043 #include <fontconfig/fontconfig.h>
2044
2045    FcChar32 FcCharSetIntersectCount(const FcCharSet *a, const
2046    FcCharSet *b);
2047
2048 Description
2049
2050    Returns the number of chars that are in both a and b.
2051
2052 FcCharSetSubtractCount
2053
2054 Name
2055
2056    FcCharSetSubtractCount -- Subtract and count charsets
2057
2058 Synopsis
2059
2060 #include <fontconfig/fontconfig.h>
2061
2062    FcChar32 FcCharSetSubtractCount(const FcCharSet *a, const
2063    FcCharSet *b);
2064
2065 Description
2066
2067    Returns the number of chars that are in a but not in b.
2068
2069 FcCharSetIsSubset
2070
2071 Name
2072
2073    FcCharSetIsSubset -- Test for charset inclusion
2074
2075 Synopsis
2076
2077 #include <fontconfig/fontconfig.h>
2078
2079    FcBool FcCharSetIsSubset(const FcCharSet *a, const FcCharSet
2080    *b);
2081
2082 Description
2083
2084    Returns whether a is a subset of b.
2085
2086 FcCharSetFirstPage
2087
2088 Name
2089
2090    FcCharSetFirstPage -- Start enumerating charset contents
2091
2092 Synopsis
2093
2094 #include <fontconfig/fontconfig.h>
2095
2096    FcChar32 FcCharSetFirstPage(const FcCharSet *a,
2097    FcChar32[FC_CHARSET_MAP_SIZE] map, FcChar32 *next);
2098
2099 Description
2100
2101    Builds an array of bits in map marking the first page of
2102    Unicode coverage of a. *next is set to contains the base code
2103    point for the next page in a. Returns the base code point for
2104    the page, or FC_CHARSET_DONE if a contains no pages. As an
2105    example, if FcCharSetFirstPage returns 0x300 and fills map with
2106 0xffffffff 0xffffffff 0x01000008 0x44300002 0xffffd7f0 0xfffffffb 0xffff
2107 7fff 0xffff0003
2108
2109    Then the page contains code points 0x300 through 0x33f (the
2110    first 64 code points on the page) because map[0] and map[1]
2111    both have all their bits set. It also contains code points
2112    0x343 (0x300 + 32*2 + (4-1)) and 0x35e (0x300 + 32*2 + (31-1))
2113    because map[2] has the 4th and 31st bits set. The code points
2114    represented by map[3] and later are left as an excercise for
2115    the reader ;).
2116
2117 FcCharSetNextPage
2118
2119 Name
2120
2121    FcCharSetNextPage -- Continue enumerating charset contents
2122
2123 Synopsis
2124
2125 #include <fontconfig/fontconfig.h>
2126
2127    FcChar32 FcCharSetNextPage(const FcCharSet *a,
2128    FcChar32[FC_CHARSET_MAP_SIZE] map, FcChar32 *next);
2129
2130 Description
2131
2132    Builds an array of bits in map marking the Unicode coverage of
2133    a for page containing *next (see the FcCharSetFirstPage
2134    description for details). *next is set to contains the base
2135    code point for the next page in a. Returns the base of code
2136    point for the page, or FC_CHARSET_DONE if a does not contain
2137    *next.
2138
2139 FcCharSetCoverage
2140
2141 Name
2142
2143    FcCharSetCoverage -- DEPRECATED return coverage for a Unicode
2144    page
2145
2146 Synopsis
2147
2148 #include <fontconfig/fontconfig.h>
2149
2150    FcChar32 FcCharSetCoverage(const FcCharSet *a, FcChar32page,
2151    FcChar32[8]result);
2152
2153 Description
2154
2155    DEPRECATED This function returns a bitmask in result which
2156    indicates which code points in page are included in a.
2157    FcCharSetCoverage returns the next page in the charset which
2158    has any coverage.
2159
2160 FcCharSetNew
2161
2162 Name
2163
2164    FcCharSetNew -- DEPRECATED alias for FcCharSetCreate
2165
2166 Synopsis
2167
2168 #include <fontconfig/fontconfig.h>
2169
2170    FcCharSet * FcCharSetNew(void);
2171
2172 Description
2173
2174    FcCharSetNew is a DEPRECATED alias for FcCharSetCreate.
2175      __________________________________________________________
2176
2177 FcLangSet
2178
2179    Table of Contents
2180    FcLangSetCreate -- create a langset object
2181    FcLangSetDestroy -- destroy a langset object
2182    FcLangSetCopy -- copy a langset object
2183    FcLangSetAdd -- add a language to a langset
2184    FcLangSetDel -- delete a language from a langset
2185    FcLangSetUnion -- Add langsets
2186    FcLangSetSubtract -- Subtract langsets
2187    FcLangSetCompare -- compare language sets
2188    FcLangSetContains -- check langset subset relation
2189    FcLangSetEqual -- test for matching langsets
2190    FcLangSetHash -- return a hash value for a langset
2191    FcLangSetHasLang -- test langset for language support
2192    FcGetDefaultLangs -- Get the default languages list
2193    FcLangSetGetLangs -- get the list of languages in the langset
2194    FcGetLangs -- Get list of languages
2195    FcLangNormalize -- Normalize the language string
2196    FcLangGetCharSet -- Get character map for a language
2197
2198    An FcLangSet is a set of language names (each of which include
2199    language and an optional territory). They are used when
2200    selecting fonts to indicate which languages the fonts need to
2201    support. Each font is marked, using language orthography
2202    information built into fontconfig, with the set of supported
2203    languages.
2204
2205 FcLangSetCreate
2206
2207 Name
2208
2209    FcLangSetCreate -- create a langset object
2210
2211 Synopsis
2212
2213 #include <fontconfig/fontconfig.h>
2214
2215    FcLangSet * FcLangSetCreate(void);
2216
2217 Description
2218
2219    FcLangSetCreate creates a new FcLangSet object.
2220
2221 FcLangSetDestroy
2222
2223 Name
2224
2225    FcLangSetDestroy -- destroy a langset object
2226
2227 Synopsis
2228
2229 #include <fontconfig/fontconfig.h>
2230
2231    void FcLangSetDestroy(FcLangSet *ls);
2232
2233 Description
2234
2235    FcLangSetDestroy destroys a FcLangSet object, freeing all
2236    memory associated with it.
2237
2238 FcLangSetCopy
2239
2240 Name
2241
2242    FcLangSetCopy -- copy a langset object
2243
2244 Synopsis
2245
2246 #include <fontconfig/fontconfig.h>
2247
2248    FcLangSet * FcLangSetCopy(const FcLangSet *ls);
2249
2250 Description
2251
2252    FcLangSetCopy creates a new FcLangSet object and populates it
2253    with the contents of ls.
2254
2255 FcLangSetAdd
2256
2257 Name
2258
2259    FcLangSetAdd -- add a language to a langset
2260
2261 Synopsis
2262
2263 #include <fontconfig/fontconfig.h>
2264
2265    FcBool FcLangSetAdd(FcLangSet *ls, const FcChar8 *lang);
2266
2267 Description
2268
2269    lang is added to ls. lang should be of the form Ll-Tt where Ll
2270    is a two or three letter language from ISO 639 and Tt is a
2271    territory from ISO 3166.
2272
2273 FcLangSetDel
2274
2275 Name
2276
2277    FcLangSetDel -- delete a language from a langset
2278
2279 Synopsis
2280
2281 #include <fontconfig/fontconfig.h>
2282
2283    FcBool FcLangSetDel(FcLangSet *ls, const FcChar8 *lang);
2284
2285 Description
2286
2287    lang is removed from ls. lang should be of the form Ll-Tt where
2288    Ll is a two or three letter language from ISO 639 and Tt is a
2289    territory from ISO 3166.
2290
2291 Since
2292
2293    version 2.9.0
2294
2295 FcLangSetUnion
2296
2297 Name
2298
2299    FcLangSetUnion -- Add langsets
2300
2301 Synopsis
2302
2303 #include <fontconfig/fontconfig.h>
2304
2305    FcLangSet * FcLangSetUnion(const FcLangSet *ls_a, const
2306    FcLangSet *ls_b);
2307
2308 Description
2309
2310    Returns a set including only those languages found in either
2311    ls_a or ls_b.
2312
2313 Since
2314
2315    version 2.9.0
2316
2317 FcLangSetSubtract
2318
2319 Name
2320
2321    FcLangSetSubtract -- Subtract langsets
2322
2323 Synopsis
2324
2325 #include <fontconfig/fontconfig.h>
2326
2327    FcLangSet * FcLangSetSubtract(const FcLangSet *ls_a, const
2328    FcLangSet *ls_b);
2329
2330 Description
2331
2332    Returns a set including only those languages found in ls_a but
2333    not in ls_b.
2334
2335 Since
2336
2337    version 2.9.0
2338
2339 FcLangSetCompare
2340
2341 Name
2342
2343    FcLangSetCompare -- compare language sets
2344
2345 Synopsis
2346
2347 #include <fontconfig/fontconfig.h>
2348
2349    FcLangResult FcLangSetCompare(const FcLangSet *ls_a, const
2350    FcLangSet *ls_b);
2351
2352 Description
2353
2354    FcLangSetCompare compares language coverage for ls_a and ls_b.
2355    If they share any language and territory pair, this function
2356    returns FcLangEqual. If they share a language but differ in
2357    which territory that language is for, this function returns
2358    FcLangDifferentTerritory. If they share no languages in common,
2359    this function returns FcLangDifferentLang.
2360
2361 FcLangSetContains
2362
2363 Name
2364
2365    FcLangSetContains -- check langset subset relation
2366
2367 Synopsis
2368
2369 #include <fontconfig/fontconfig.h>
2370
2371    FcBool FcLangSetContains(const FcLangSet *ls_a, const FcLangSet
2372    *ls_b);
2373
2374 Description
2375
2376    FcLangSetContains returns FcTrue if ls_a contains every
2377    language in ls_b. ls_a will 'contain' a language from ls_b if
2378    ls_a has exactly the language, or either the language or ls_a
2379    has no territory.
2380
2381 FcLangSetEqual
2382
2383 Name
2384
2385    FcLangSetEqual -- test for matching langsets
2386
2387 Synopsis
2388
2389 #include <fontconfig/fontconfig.h>
2390
2391    FcBool FcLangSetEqual(const FcLangSet *ls_a, const FcLangSet
2392    *ls_b);
2393
2394 Description
2395
2396    Returns FcTrue if and only if ls_a supports precisely the same
2397    language and territory combinations as ls_b.
2398
2399 FcLangSetHash
2400
2401 Name
2402
2403    FcLangSetHash -- return a hash value for a langset
2404
2405 Synopsis
2406
2407 #include <fontconfig/fontconfig.h>
2408
2409    FcChar32 FcLangSetHash(const FcLangSet *ls);
2410
2411 Description
2412
2413    This function returns a value which depends solely on the
2414    languages supported by ls. Any language which equals ls will
2415    have the same result from FcLangSetHash. However, two langsets
2416    with the same hash value may not be equal.
2417
2418 FcLangSetHasLang
2419
2420 Name
2421
2422    FcLangSetHasLang -- test langset for language support
2423
2424 Synopsis
2425
2426 #include <fontconfig/fontconfig.h>
2427
2428    FcLangResult FcLangSetHasLang(const FcLangSet *ls, const
2429    FcChar8 *lang);
2430
2431 Description
2432
2433    FcLangSetHasLang checks whether ls supports lang. If ls has a
2434    matching language and territory pair, this function returns
2435    FcLangEqual. If ls has a matching language but differs in which
2436    territory that language is for, this function returns
2437    FcLangDifferentTerritory. If ls has no matching language, this
2438    function returns FcLangDifferentLang.
2439
2440 FcGetDefaultLangs
2441
2442 Name
2443
2444    FcGetDefaultLangs -- Get the default languages list
2445
2446 Synopsis
2447
2448 #include <fontconfig/fontconfig.h>
2449
2450    FcStrSet * FcGetDefaultLangs(void);
2451
2452 Description
2453
2454    Returns a string set of the default languages according to the
2455    environment variables on the system. This function looks for
2456    them in order of FC_LANG, LC_ALL, LC_CTYPE and LANG then. If
2457    there are no valid values in those environment variables, "en"
2458    will be set as fallback.
2459
2460 Since
2461
2462    version 2.9.91
2463
2464 FcLangSetGetLangs
2465
2466 Name
2467
2468    FcLangSetGetLangs -- get the list of languages in the langset
2469
2470 Synopsis
2471
2472 #include <fontconfig/fontconfig.h>
2473
2474    FcStrSet * FcLangSetGetLangs(const FcLangSet *ls);
2475
2476 Description
2477
2478    Returns a string set of all languages in langset.
2479
2480 FcGetLangs
2481
2482 Name
2483
2484    FcGetLangs -- Get list of languages
2485
2486 Synopsis
2487
2488 #include <fontconfig/fontconfig.h>
2489
2490    FcStrSet * FcGetLangs(void);
2491
2492 Description
2493
2494    Returns a string set of all known languages.
2495
2496 FcLangNormalize
2497
2498 Name
2499
2500    FcLangNormalize -- Normalize the language string
2501
2502 Synopsis
2503
2504 #include <fontconfig/fontconfig.h>
2505
2506    FcChar8 * FcLangNormalize(const FcChar8 *lang);
2507
2508 Description
2509
2510    Returns a string to make lang suitable on fontconfig.
2511
2512 Since
2513
2514    version 2.10.91
2515
2516 FcLangGetCharSet
2517
2518 Name
2519
2520    FcLangGetCharSet -- Get character map for a language
2521
2522 Synopsis
2523
2524 #include <fontconfig/fontconfig.h>
2525
2526    const FcCharSet * FcLangGetCharSet(const FcChar8 *lang);
2527
2528 Description
2529
2530    Returns the FcCharMap for a language.
2531      __________________________________________________________
2532
2533 FcMatrix
2534
2535    Table of Contents
2536    FcMatrixInit -- initialize an FcMatrix structure
2537    FcMatrixCopy -- Copy a matrix
2538    FcMatrixEqual -- Compare two matrices
2539    FcMatrixMultiply -- Multiply matrices
2540    FcMatrixRotate -- Rotate a matrix
2541    FcMatrixScale -- Scale a matrix
2542    FcMatrixShear -- Shear a matrix
2543
2544    FcMatrix structures hold an affine transformation in matrix
2545    form.
2546
2547 FcMatrixInit
2548
2549 Name
2550
2551    FcMatrixInit -- initialize an FcMatrix structure
2552
2553 Synopsis
2554
2555 #include <fontconfig/fontconfig.h>
2556
2557    void FcMatrixInit(FcMatrix *matrix);
2558
2559 Description
2560
2561    FcMatrixInit initializes matrix to the identity matrix.
2562
2563 FcMatrixCopy
2564
2565 Name
2566
2567    FcMatrixCopy -- Copy a matrix
2568
2569 Synopsis
2570
2571 #include <fontconfig/fontconfig.h>
2572
2573    void FcMatrixCopy(const FcMatrix *matrix);
2574
2575 Description
2576
2577    FcMatrixCopy allocates a new FcMatrix and copies mat into it.
2578
2579 FcMatrixEqual
2580
2581 Name
2582
2583    FcMatrixEqual -- Compare two matrices
2584
2585 Synopsis
2586
2587 #include <fontconfig/fontconfig.h>
2588
2589    void FcMatrixEqual(const FcMatrix *matrix1, const FcMatrix
2590    *matrix2);
2591
2592 Description
2593
2594    FcMatrixEqual compares matrix1 and matrix2 returning FcTrue
2595    when they are equal and FcFalse when they are not.
2596
2597 FcMatrixMultiply
2598
2599 Name
2600
2601    FcMatrixMultiply -- Multiply matrices
2602
2603 Synopsis
2604
2605 #include <fontconfig/fontconfig.h>
2606
2607    void FcMatrixMultiply(FcMatrix *result, const FcMatrix
2608    *matrix1, const FcMatrix *matrix2);
2609
2610 Description
2611
2612    FcMatrixMultiply multiplies matrix1 and matrix2 storing the
2613    result in result.
2614
2615 FcMatrixRotate
2616
2617 Name
2618
2619    FcMatrixRotate -- Rotate a matrix
2620
2621 Synopsis
2622
2623 #include <fontconfig/fontconfig.h>
2624
2625    void FcMatrixRotate(FcMatrix *matrix, double cos, double sin);
2626
2627 Description
2628
2629    FcMatrixRotate rotates matrix by the angle who's sine is sin
2630    and cosine is cos. This is done by multiplying by the matrix:
2631   cos -sin
2632   sin  cos
2633
2634 FcMatrixScale
2635
2636 Name
2637
2638    FcMatrixScale -- Scale a matrix
2639
2640 Synopsis
2641
2642 #include <fontconfig/fontconfig.h>
2643
2644    void FcMatrixScale(FcMatrix *matrix, double sx, double dy);
2645
2646 Description
2647
2648    FcMatrixScale multiplies matrix x values by sx and y values by
2649    dy. This is done by multiplying by the matrix:
2650    sx  0
2651    0   dy
2652
2653 FcMatrixShear
2654
2655 Name
2656
2657    FcMatrixShear -- Shear a matrix
2658
2659 Synopsis
2660
2661 #include <fontconfig/fontconfig.h>
2662
2663    void FcMatrixShear(FcMatrix *matrix, double sh, double sv);
2664
2665 Description
2666
2667    FcMatrixShare shears matrix horizontally by sh and vertically
2668    by sv. This is done by multiplying by the matrix:
2669   1  sh
2670   sv  1
2671      __________________________________________________________
2672
2673 FcRange
2674
2675    Table of Contents
2676    FcRangeCopy -- Copy a range object
2677    FcRangeCreateDouble -- create a range object for double
2678    FcRangeCreateInteger -- create a range object for integer
2679    FcRangeDestroy -- destroy a range object
2680    FcRangeGetDouble -- Get the range in double
2681
2682    An FcRange holds two variables to indicate a range in between.
2683
2684 FcRangeCopy
2685
2686 Name
2687
2688    FcRangeCopy -- Copy a range object
2689
2690 Synopsis
2691
2692 #include <fontconfig/fontconfig.h>
2693
2694    FcRange * FcRangeCopy(const FcRange *range);
2695
2696 Description
2697
2698    FcRangeCopy creates a new FcRange object and populates it with
2699    the contents of range.
2700
2701 Since
2702
2703    version 2.11.91
2704
2705 FcRangeCreateDouble
2706
2707 Name
2708
2709    FcRangeCreateDouble -- create a range object for double
2710
2711 Synopsis
2712
2713 #include <fontconfig/fontconfig.h>
2714
2715    FcRange * FcRangeCreateDouble(doublebegin, doubleend);
2716
2717 Description
2718
2719    FcRangeCreateDouble creates a new FcRange object with double
2720    sized value.
2721
2722 Since
2723
2724    version 2.11.91
2725
2726 FcRangeCreateInteger
2727
2728 Name
2729
2730    FcRangeCreateInteger -- create a range object for integer
2731
2732 Synopsis
2733
2734 #include <fontconfig/fontconfig.h>
2735
2736    FcRange * FcRangeCreateInteger(intbegin, intend);
2737
2738 Description
2739
2740    FcRangeCreateInteger creates a new FcRange object with integer
2741    sized value.
2742
2743 Since
2744
2745    version 2.11.91
2746
2747 FcRangeDestroy
2748
2749 Name
2750
2751    FcRangeDestroy -- destroy a range object
2752
2753 Synopsis
2754
2755 #include <fontconfig/fontconfig.h>
2756
2757    void FcRangeDestroy(FcRange *range);
2758
2759 Description
2760
2761    FcRangeDestroy destroys a FcRange object, freeing all memory
2762    associated with it.
2763
2764 Since
2765
2766    version 2.11.91
2767
2768 FcRangeGetDouble
2769
2770 Name
2771
2772    FcRangeGetDouble -- Get the range in double
2773
2774 Synopsis
2775
2776 #include <fontconfig/fontconfig.h>
2777
2778    FcBool FcRangeGetDouble(const FcRange *range, double *begin,
2779    double *end);
2780
2781 Description
2782
2783    Returns in begin and end as the range.
2784
2785 Since
2786
2787    version 2.11.91
2788      __________________________________________________________
2789
2790 FcConfig
2791
2792    Table of Contents
2793    FcConfigCreate -- Create a configuration
2794    FcConfigReference -- Increment config reference count
2795    FcConfigDestroy -- Destroy a configuration
2796    FcConfigSetCurrent -- Set configuration as default
2797    FcConfigGetCurrent -- Return current configuration
2798    FcConfigUptoDate -- Check timestamps on config files
2799    FcConfigHome -- return the current home directory.
2800    FcConfigEnableHome -- controls use of the home directory.
2801    FcConfigBuildFonts -- Build font database
2802    FcConfigGetConfigDirs -- Get config directories
2803    FcConfigGetFontDirs -- Get font directories
2804    FcConfigGetConfigFiles -- Get config files
2805    FcConfigGetCache -- DEPRECATED used to return per-user cache
2806           filename
2807
2808    FcConfigGetCacheDirs -- return the list of directories searched
2809           for cache files
2810
2811    FcConfigGetFonts -- Get config font set
2812    FcConfigGetBlanks -- Get config blanks
2813    FcConfigGetRescanInterval -- Get config rescan interval
2814    FcConfigSetRescanInterval -- Set config rescan interval
2815    FcConfigAppFontAddFile -- Add font file to font database
2816    FcConfigAppFontAddDir -- Add fonts from directory to font
2817           database
2818
2819    FcConfigAppFontClear -- Remove all app fonts from font database
2820    FcConfigSubstituteWithPat -- Execute substitutions
2821    FcConfigSubstitute -- Execute substitutions
2822    FcFontMatch -- Return best font
2823    FcFontSort -- Return list of matching fonts
2824    FcFontRenderPrepare -- Prepare pattern for loading font file
2825    FcFontList -- List fonts
2826    FcConfigFilename -- Find a config file
2827    FcConfigParseAndLoad -- load a configuration file
2828    FcConfigGetSysRoot -- Obtain the system root directory
2829    FcConfigSetSysRoot -- Set the system root directory
2830
2831    An FcConfig object holds the internal representation of a
2832    configuration. There is a default configuration which
2833    applications may use by passing 0 to any function using the
2834    data within an FcConfig.
2835
2836 FcConfigCreate
2837
2838 Name
2839
2840    FcConfigCreate -- Create a configuration
2841
2842 Synopsis
2843
2844 #include <fontconfig/fontconfig.h>
2845
2846    FcConfig * FcConfigCreate(void);
2847
2848 Description
2849
2850    Creates an empty configuration.
2851
2852 FcConfigReference
2853
2854 Name
2855
2856    FcConfigReference -- Increment config reference count
2857
2858 Synopsis
2859
2860 #include <fontconfig/fontconfig.h>
2861
2862    FcConfig * FcConfigReference(FcConfig *config);
2863
2864 Description
2865
2866    Add another reference to config. Configs are freed only when
2867    the reference count reaches zero. If config is NULL, the
2868    current configuration is used. In that case this function will
2869    be similar to FcConfigGetCurrent() except that it increments
2870    the reference count before returning and the user is
2871    responsible for destroying the configuration when not needed
2872    anymore.
2873
2874 FcConfigDestroy
2875
2876 Name
2877
2878    FcConfigDestroy -- Destroy a configuration
2879
2880 Synopsis
2881
2882 #include <fontconfig/fontconfig.h>
2883
2884    void FcConfigDestroy(FcConfig *config);
2885
2886 Description
2887
2888    Decrements the config reference count. If all references are
2889    gone, destroys the configuration and any data associated with
2890    it. Note that calling this function with the return from
2891    FcConfigGetCurrent will cause a new configuration to be created
2892    for use as current configuration.
2893
2894 FcConfigSetCurrent
2895
2896 Name
2897
2898    FcConfigSetCurrent -- Set configuration as default
2899
2900 Synopsis
2901
2902 #include <fontconfig/fontconfig.h>
2903
2904    FcBool FcConfigSetCurrent(FcConfig *config);
2905
2906 Description
2907
2908    Sets the current default configuration to config. Implicitly
2909    calls FcConfigBuildFonts if necessary, and FcConfigReference()
2910    to inrease the reference count in config since 2.12.0,
2911    returning FcFalse if that call fails.
2912
2913 FcConfigGetCurrent
2914
2915 Name
2916
2917    FcConfigGetCurrent -- Return current configuration
2918
2919 Synopsis
2920
2921 #include <fontconfig/fontconfig.h>
2922
2923    FcConfig * FcConfigGetCurrent(void);
2924
2925 Description
2926
2927    Returns the current default configuration.
2928
2929 FcConfigUptoDate
2930
2931 Name
2932
2933    FcConfigUptoDate -- Check timestamps on config files
2934
2935 Synopsis
2936
2937 #include <fontconfig/fontconfig.h>
2938
2939    FcBool FcConfigUptoDate(FcConfig *config);
2940
2941 Description
2942
2943    Checks all of the files related to config and returns whether
2944    any of them has been modified since the configuration was
2945    created. If config is NULL, the current configuration is used.
2946
2947 FcConfigHome
2948
2949 Name
2950
2951    FcConfigHome -- return the current home directory.
2952
2953 Synopsis
2954
2955 #include <fontconfig/fontconfig.h>
2956
2957    FcChar8 * FcConfigHome(void);
2958
2959 Description
2960
2961    Return the current user's home directory, if it is available,
2962    and if using it is enabled, and NULL otherwise. See also
2963    FcConfigEnableHome).
2964
2965 FcConfigEnableHome
2966
2967 Name
2968
2969    FcConfigEnableHome -- controls use of the home directory.
2970
2971 Synopsis
2972
2973 #include <fontconfig/fontconfig.h>
2974
2975    FcBool FcConfigEnableHome(FcBool enable);
2976
2977 Description
2978
2979    If enable is FcTrue, then Fontconfig will use various files
2980    which are specified relative to the user's home directory
2981    (using the ~ notation in the configuration). When enable is
2982    FcFalse, then all use of the home directory in these contexts
2983    will be disabled. The previous setting of the value is
2984    returned.
2985
2986 FcConfigBuildFonts
2987
2988 Name
2989
2990    FcConfigBuildFonts -- Build font database
2991
2992 Synopsis
2993
2994 #include <fontconfig/fontconfig.h>
2995
2996    FcBool FcConfigBuildFonts(FcConfig *config);
2997
2998 Description
2999
3000    Builds the set of available fonts for the given configuration.
3001    Note that any changes to the configuration after this call have
3002    indeterminate effects. Returns FcFalse if this operation runs
3003    out of memory. If config is NULL, the current configuration is
3004    used.
3005
3006 FcConfigGetConfigDirs
3007
3008 Name
3009
3010    FcConfigGetConfigDirs -- Get config directories
3011
3012 Synopsis
3013
3014 #include <fontconfig/fontconfig.h>
3015
3016    FcStrList * FcConfigGetConfigDirs(FcConfig *config);
3017
3018 Description
3019
3020    Returns the list of font directories specified in the
3021    configuration files for config. Does not include any
3022    subdirectories. If config is NULL, the current configuration is
3023    used.
3024
3025 FcConfigGetFontDirs
3026
3027 Name
3028
3029    FcConfigGetFontDirs -- Get font directories
3030
3031 Synopsis
3032
3033 #include <fontconfig/fontconfig.h>
3034
3035    FcStrList * FcConfigGetFontDirs(FcConfig *config);
3036
3037 Description
3038
3039    Returns the list of font directories in config. This includes
3040    the configured font directories along with any directories
3041    below those in the filesystem. If config is NULL, the current
3042    configuration is used.
3043
3044 FcConfigGetConfigFiles
3045
3046 Name
3047
3048    FcConfigGetConfigFiles -- Get config files
3049
3050 Synopsis
3051
3052 #include <fontconfig/fontconfig.h>
3053
3054    FcStrList * FcConfigGetConfigFiles(FcConfig *config);
3055
3056 Description
3057
3058    Returns the list of known configuration files used to generate
3059    config. If config is NULL, the current configuration is used.
3060
3061 FcConfigGetCache
3062
3063 Name
3064
3065    FcConfigGetCache -- DEPRECATED used to return per-user cache
3066    filename
3067
3068 Synopsis
3069
3070 #include <fontconfig/fontconfig.h>
3071
3072    FcChar8 * FcConfigGetCache(FcConfig *config);
3073
3074 Description
3075
3076    With fontconfig no longer using per-user cache files, this
3077    function now simply returns NULL to indicate that no per-user
3078    file exists.
3079
3080 FcConfigGetCacheDirs
3081
3082 Name
3083
3084    FcConfigGetCacheDirs -- return the list of directories searched
3085    for cache files
3086
3087 Synopsis
3088
3089 #include <fontconfig/fontconfig.h>
3090
3091    FcStrList * FcConfigGetCacheDirs(const FcConfig *config);
3092
3093 Description
3094
3095    FcConfigGetCacheDirs returns a string list containing all of
3096    the directories that fontconfig will search when attempting to
3097    load a cache file for a font directory. If config is NULL, the
3098    current configuration is used.
3099
3100 FcConfigGetFonts
3101
3102 Name
3103
3104    FcConfigGetFonts -- Get config font set
3105
3106 Synopsis
3107
3108 #include <fontconfig/fontconfig.h>
3109
3110    FcFontSet * FcConfigGetFonts(FcConfig *config, FcSetName set);
3111
3112 Description
3113
3114    Returns one of the two sets of fonts from the configuration as
3115    specified by set. This font set is owned by the library and
3116    must not be modified or freed. If config is NULL, the current
3117    configuration is used.
3118
3119 FcConfigGetBlanks
3120
3121 Name
3122
3123    FcConfigGetBlanks -- Get config blanks
3124
3125 Synopsis
3126
3127 #include <fontconfig/fontconfig.h>
3128
3129    FcBlanks * FcConfigGetBlanks(FcConfig *config);
3130
3131 Description
3132
3133    Returns the FcBlanks object associated with the given
3134    configuration, if no blanks were present in the configuration,
3135    this function will return 0. The returned FcBlanks object if
3136    not NULL, is valid as long as the owning FcConfig is alive. If
3137    config is NULL, the current configuration is used.
3138
3139 FcConfigGetRescanInterval
3140
3141 Name
3142
3143    FcConfigGetRescanInterval -- Get config rescan interval
3144
3145 Synopsis
3146
3147 #include <fontconfig/fontconfig.h>
3148
3149    int FcConfigGetRescanInterval(FcConfig *config);
3150
3151 Description
3152
3153    Returns the interval between automatic checks of the
3154    configuration (in seconds) specified in config. The
3155    configuration is checked during a call to FcFontList when this
3156    interval has passed since the last check. An interval setting
3157    of zero disables automatic checks. If config is NULL, the
3158    current configuration is used.
3159
3160 FcConfigSetRescanInterval
3161
3162 Name
3163
3164    FcConfigSetRescanInterval -- Set config rescan interval
3165
3166 Synopsis
3167
3168 #include <fontconfig/fontconfig.h>
3169
3170    FcBool FcConfigSetRescanInterval(FcConfig *config, int
3171    rescanInterval);
3172
3173 Description
3174
3175    Sets the rescan interval. Returns FcFalse if the interval
3176    cannot be set (due to allocation failure). Otherwise returns
3177    FcTrue. An interval setting of zero disables automatic checks.
3178    If config is NULL, the current configuration is used.
3179
3180 FcConfigAppFontAddFile
3181
3182 Name
3183
3184    FcConfigAppFontAddFile -- Add font file to font database
3185
3186 Synopsis
3187
3188 #include <fontconfig/fontconfig.h>
3189
3190    FcBool FcConfigAppFontAddFile(FcConfig *config, const FcChar8
3191    *file);
3192
3193 Description
3194
3195    Adds an application-specific font to the configuration. Returns
3196    FcFalse if the fonts cannot be added (due to allocation failure
3197    or no fonts found). Otherwise returns FcTrue. If config is
3198    NULL, the current configuration is used.
3199
3200 FcConfigAppFontAddDir
3201
3202 Name
3203
3204    FcConfigAppFontAddDir -- Add fonts from directory to font
3205    database
3206
3207 Synopsis
3208
3209 #include <fontconfig/fontconfig.h>
3210
3211    FcBool FcConfigAppFontAddDir(FcConfig *config, const FcChar8
3212    *dir);
3213
3214 Description
3215
3216    Scans the specified directory for fonts, adding each one found
3217    to the application-specific set of fonts. Returns FcFalse if
3218    the fonts cannot be added (due to allocation failure).
3219    Otherwise returns FcTrue. If config is NULL, the current
3220    configuration is used.
3221
3222 FcConfigAppFontClear
3223
3224 Name
3225
3226    FcConfigAppFontClear -- Remove all app fonts from font database
3227
3228 Synopsis
3229
3230 #include <fontconfig/fontconfig.h>
3231
3232    void FcConfigAppFontClear(FcConfig *config);
3233
3234 Description
3235
3236    Clears the set of application-specific fonts. If config is
3237    NULL, the current configuration is used.
3238
3239 FcConfigSubstituteWithPat
3240
3241 Name
3242
3243    FcConfigSubstituteWithPat -- Execute substitutions
3244
3245 Synopsis
3246
3247 #include <fontconfig/fontconfig.h>
3248
3249    FcBool FcConfigSubstituteWithPat(FcConfig *config, FcPattern
3250    *p, FcPattern *p_pat, FcMatchKind kind);
3251
3252 Description
3253
3254    Performs the sequence of pattern modification operations, if
3255    kind is FcMatchPattern, then those tagged as pattern operations
3256    are applied, else if kind is FcMatchFont, those tagged as font
3257    operations are applied and p_pat is used for <test> elements
3258    with target=pattern. Returns FcFalse if the substitution cannot
3259    be performed (due to allocation failure). Otherwise returns
3260    FcTrue. If config is NULL, the current configuration is used.
3261
3262 FcConfigSubstitute
3263
3264 Name
3265
3266    FcConfigSubstitute -- Execute substitutions
3267
3268 Synopsis
3269
3270 #include <fontconfig/fontconfig.h>
3271
3272    FcBool FcConfigSubstitute(FcConfig *config, FcPattern *p,
3273    FcMatchKind kind);
3274
3275 Description
3276
3277    Calls FcConfigSubstituteWithPat setting p_pat to NULL. Returns
3278    FcFalse if the substitution cannot be performed (due to
3279    allocation failure). Otherwise returns FcTrue. If config is
3280    NULL, the current configuration is used.
3281
3282 FcFontMatch
3283
3284 Name
3285
3286    FcFontMatch -- Return best font
3287
3288 Synopsis
3289
3290 #include <fontconfig/fontconfig.h>
3291
3292    FcPattern * FcFontMatch(FcConfig *config, FcPattern *p,
3293    FcResult *result);
3294
3295 Description
3296
3297    Finds the font in sets most closely matching pattern and
3298    returns the result of FcFontRenderPrepare for that font and the
3299    provided pattern. This function should be called only after
3300    FcConfigSubstitute and FcDefaultSubstitute have been called for
3301    p; otherwise the results will not be correct. If config is
3302    NULL, the current configuration is used.
3303
3304 FcFontSort
3305
3306 Name
3307
3308    FcFontSort -- Return list of matching fonts
3309
3310 Synopsis
3311
3312 #include <fontconfig/fontconfig.h>
3313
3314    FcFontSet * FcFontSort(FcConfig *config, FcPattern *p, FcBool
3315    trim, FcCharSet **csp, FcResult *result);
3316
3317 Description
3318
3319    Returns the list of fonts sorted by closeness to p. If trim is
3320    FcTrue, elements in the list which don't include Unicode
3321    coverage not provided by earlier elements in the list are
3322    elided. The union of Unicode coverage of all of the fonts is
3323    returned in csp, if csp is not NULL. This function should be
3324    called only after FcConfigSubstitute and FcDefaultSubstitute
3325    have been called for p; otherwise the results will not be
3326    correct.
3327
3328    The returned FcFontSet references FcPattern structures which
3329    may be shared by the return value from multiple FcFontSort
3330    calls, applications must not modify these patterns. Instead,
3331    they should be passed, along with p to FcFontRenderPrepare
3332    which combines them into a complete pattern.
3333
3334    The FcFontSet returned by FcFontSort is destroyed by calling
3335    FcFontSetDestroy. If config is NULL, the current configuration
3336    is used.
3337
3338 FcFontRenderPrepare
3339
3340 Name
3341
3342    FcFontRenderPrepare -- Prepare pattern for loading font file
3343
3344 Synopsis
3345
3346 #include <fontconfig/fontconfig.h>
3347
3348    FcPattern * FcFontRenderPrepare(FcConfig *config, FcPattern
3349    *pat, FcPattern *font);
3350
3351 Description
3352
3353    Creates a new pattern consisting of elements of font not
3354    appearing in pat, elements of pat not appearing in font and the
3355    best matching value from pat for elements appearing in both.
3356    The result is passed to FcConfigSubstituteWithPat with kind
3357    FcMatchFont and then returned.
3358
3359 FcFontList
3360
3361 Name
3362
3363    FcFontList -- List fonts
3364
3365 Synopsis
3366
3367 #include <fontconfig/fontconfig.h>
3368
3369    FcFontSet * FcFontList(FcConfig *config, FcPattern *p,
3370    FcObjectSet *os);
3371
3372 Description
3373
3374    Selects fonts matching p, creates patterns from those fonts
3375    containing only the objects in os and returns the set of unique
3376    such patterns. If config is NULL, the default configuration is
3377    checked to be up to date, and used.
3378
3379 FcConfigFilename
3380
3381 Name
3382
3383    FcConfigFilename -- Find a config file
3384
3385 Synopsis
3386
3387 #include <fontconfig/fontconfig.h>
3388
3389    FcChar8 * FcConfigFilename(const FcChar8 *name);
3390
3391 Description
3392
3393    Given the specified external entity name, return the associated
3394    filename. This provides applications a way to convert various
3395    configuration file references into filename form.
3396
3397    A null or empty name indicates that the default configuration
3398    file should be used; which file this references can be
3399    overridden with the FONTCONFIG_FILE environment variable. Next,
3400    if the name starts with ~, it refers to a file in the current
3401    users home directory. Otherwise if the name doesn't start with
3402    '/', it refers to a file in the default configuration
3403    directory; the built-in default directory can be overridden
3404    with the FONTCONFIG_PATH environment variable.
3405
3406 FcConfigParseAndLoad
3407
3408 Name
3409
3410    FcConfigParseAndLoad -- load a configuration file
3411
3412 Synopsis
3413
3414 #include <fontconfig/fontconfig.h>
3415
3416    FcBool FcConfigParseAndLoad(FcConfig *config, const FcChar8
3417    *file, FcBool complain);
3418
3419 Description
3420
3421    Walks the configuration in 'file' and constructs the internal
3422    representation in 'config'. Any include files referenced from
3423    within 'file' will be loaded and parsed. If 'complain' is
3424    FcFalse, no warning will be displayed if 'file' does not exist.
3425    Error and warning messages will be output to stderr. Returns
3426    FcFalse if some error occurred while loading the file, either a
3427    parse error, semantic error or allocation failure. Otherwise
3428    returns FcTrue.
3429
3430 FcConfigGetSysRoot
3431
3432 Name
3433
3434    FcConfigGetSysRoot -- Obtain the system root directory
3435
3436 Synopsis
3437
3438 #include <fontconfig/fontconfig.h>
3439
3440    const FcChar8 * FcConfigGetSysRoot(const FcConfig *config);
3441
3442 Description
3443
3444    Obtrains the system root directory in 'config' if available.
3445
3446 Since
3447
3448    version 2.10.92
3449
3450 FcConfigSetSysRoot
3451
3452 Name
3453
3454    FcConfigSetSysRoot -- Set the system root directory
3455
3456 Synopsis
3457
3458 #include <fontconfig/fontconfig.h>
3459
3460    void FcConfigSetSysRoot(FcConfig *config, const FcChar8
3461    *sysroot);
3462
3463 Description
3464
3465    Set 'sysroot' as the system root directory. fontconfig prepend
3466    'sysroot' to the cache directories in order to allow people to
3467    generate caches at the build time. Note that this causes
3468    changing current config. i.e. this function calls
3469    FcConfigSetCurrent() internally.
3470
3471 Since
3472
3473    version 2.10.92
3474      __________________________________________________________
3475
3476 FcObjectType
3477
3478    Table of Contents
3479    FcNameRegisterObjectTypes -- Register object types
3480    FcNameUnregisterObjectTypes -- Unregister object types
3481    FcNameGetObjectType -- Lookup an object type
3482
3483    Provides for application-specified font name object types so
3484    that new pattern elements can be generated from font names.
3485
3486 FcNameRegisterObjectTypes
3487
3488 Name
3489
3490    FcNameRegisterObjectTypes -- Register object types
3491
3492 Synopsis
3493
3494 #include <fontconfig/fontconfig.h>
3495
3496    FcBool FcNameRegisterObjectTypes(const FcObjectType *types, int
3497    ntype);
3498
3499 Description
3500
3501    Deprecated. Does nothing. Returns FcFalse.
3502
3503 FcNameUnregisterObjectTypes
3504
3505 Name
3506
3507    FcNameUnregisterObjectTypes -- Unregister object types
3508
3509 Synopsis
3510
3511 #include <fontconfig/fontconfig.h>
3512
3513    FcBool FcNameUnregisterObjectTypes(const FcObjectType *types,
3514    int ntype);
3515
3516 Description
3517
3518    Deprecated. Does nothing. Returns FcFalse.
3519
3520 FcNameGetObjectType
3521
3522 Name
3523
3524    FcNameGetObjectType -- Lookup an object type
3525
3526 Synopsis
3527
3528 #include <fontconfig/fontconfig.h>
3529
3530    const FcObjectType * FcNameGetObjectType(const char *object);
3531
3532 Description
3533
3534    Return the object type for the pattern element named object.
3535      __________________________________________________________
3536
3537 FcConstant
3538
3539    Table of Contents
3540    FcNameRegisterConstants -- Register symbolic constants
3541    FcNameUnregisterConstants -- Unregister symbolic constants
3542    FcNameGetConstant -- Lookup symbolic constant
3543    FcNameConstant -- Get the value for a symbolic constant
3544
3545    Provides for application-specified symbolic constants for font
3546    names.
3547
3548 FcNameRegisterConstants
3549
3550 Name
3551
3552    FcNameRegisterConstants -- Register symbolic constants
3553
3554 Synopsis
3555
3556 #include <fontconfig/fontconfig.h>
3557
3558    FcBool FcNameRegisterConstants(const FcConstant *consts, int
3559    nconsts);
3560
3561 Description
3562
3563    Deprecated. Does nothing. Returns FcFalse.
3564
3565 FcNameUnregisterConstants
3566
3567 Name
3568
3569    FcNameUnregisterConstants -- Unregister symbolic constants
3570
3571 Synopsis
3572
3573 #include <fontconfig/fontconfig.h>
3574
3575    FcBool FcNameUnregisterConstants(const FcConstant *consts, int
3576    nconsts);
3577
3578 Description
3579
3580    Deprecated. Does nothing. Returns FcFalse.
3581
3582 FcNameGetConstant
3583
3584 Name
3585
3586    FcNameGetConstant -- Lookup symbolic constant
3587
3588 Synopsis
3589
3590 #include <fontconfig/fontconfig.h>
3591
3592    const FcConstant * FcNameGetConstant(FcChar8 *string);
3593
3594 Description
3595
3596    Return the FcConstant structure related to symbolic constant
3597    string.
3598
3599 FcNameConstant
3600
3601 Name
3602
3603    FcNameConstant -- Get the value for a symbolic constant
3604
3605 Synopsis
3606
3607 #include <fontconfig/fontconfig.h>
3608
3609    FcBool FcNameConstant(FcChar8 *string, int *result);
3610
3611 Description
3612
3613    Returns whether a symbolic constant with name string is
3614    registered, placing the value of the constant in result if
3615    present.
3616      __________________________________________________________
3617
3618 FcWeight
3619
3620    Table of Contents
3621    FcWeightFromOpenType -- Convert from OpenType weight values to
3622           fontconfig ones
3623
3624    FcWeightToOpenType -- Convert from fontconfig weight values to
3625           OpenType ones
3626
3627    Maps weights to and from OpenType weights.
3628
3629 FcWeightFromOpenType
3630
3631 Name
3632
3633    FcWeightFromOpenType -- Convert from OpenType weight values to
3634    fontconfig ones
3635
3636 Synopsis
3637
3638 #include <fontconfig/fontconfig.h>
3639
3640    int FcWeightFromOpenType(intot_weight);
3641
3642 Description
3643
3644    FcWeightFromOpenType returns an integer value to use with
3645    FC_WEIGHT, from an integer in the 1..1000 range, resembling the
3646    numbers from OpenType specification's OS/2 usWeight numbers,
3647    which are also similar to CSS font-weight numbers. If input is
3648    negative, zero, or greater than 1000, returns -1. This function
3649    linearly interpolates between various FC_WEIGHT_* constants. As
3650    such, the returned value does not necessarily match any of the
3651    predefined constants.
3652
3653 Since
3654
3655    version 2.11.91
3656
3657 FcWeightToOpenType
3658
3659 Name
3660
3661    FcWeightToOpenType -- Convert from fontconfig weight values to
3662    OpenType ones
3663
3664 Synopsis
3665
3666 #include <fontconfig/fontconfig.h>
3667
3668    int FcWeightToOpenType(intot_weight);
3669
3670 Description
3671
3672    FcWeightToOpenType is the inverse of FcWeightFromOpenType. If
3673    the input is less than FC_WEIGHT_THIN or greater than
3674    FC_WEIGHT_EXTRABLACK, returns -1. Otherwise returns a number in
3675    the range 1 to 1000.
3676
3677 Since
3678
3679    version 2.11.91
3680      __________________________________________________________
3681
3682 FcBlanks
3683
3684    Table of Contents
3685    FcBlanksCreate -- Create an FcBlanks
3686    FcBlanksDestroy -- Destroy and FcBlanks
3687    FcBlanksAdd -- Add a character to an FcBlanks
3688    FcBlanksIsMember -- Query membership in an FcBlanks
3689
3690    An FcBlanks object holds a list of Unicode chars which are
3691    expected to be blank when drawn. When scanning new fonts, any
3692    glyphs which are empty and not in this list will be assumed to
3693    be broken and not placed in the FcCharSet associated with the
3694    font. This provides a significantly more accurate CharSet for
3695    applications.
3696
3697 FcBlanksCreate
3698
3699 Name
3700
3701    FcBlanksCreate -- Create an FcBlanks
3702
3703 Synopsis
3704
3705 #include <fontconfig/fontconfig.h>
3706
3707    FcBlanks * FcBlanksCreate(void);
3708
3709 Description
3710
3711    Creates an empty FcBlanks object.
3712
3713 FcBlanksDestroy
3714
3715 Name
3716
3717    FcBlanksDestroy -- Destroy and FcBlanks
3718
3719 Synopsis
3720
3721 #include <fontconfig/fontconfig.h>
3722
3723    void FcBlanksDestroy(FcBlanks *b);
3724
3725 Description
3726
3727    Destroys an FcBlanks object, freeing any associated memory.
3728
3729 FcBlanksAdd
3730
3731 Name
3732
3733    FcBlanksAdd -- Add a character to an FcBlanks
3734
3735 Synopsis
3736
3737 #include <fontconfig/fontconfig.h>
3738
3739    FcBool FcBlanksAdd(FcBlanks *b, FcChar32 ucs4);
3740
3741 Description
3742
3743    Adds a single character to an FcBlanks object, returning
3744    FcFalse if this process ran out of memory.
3745
3746 FcBlanksIsMember
3747
3748 Name
3749
3750    FcBlanksIsMember -- Query membership in an FcBlanks
3751
3752 Synopsis
3753
3754 #include <fontconfig/fontconfig.h>
3755
3756    FcBool FcBlanksIsMember(FcBlanks *b, FcChar32 ucs4);
3757
3758 Description
3759
3760    Returns whether the specified FcBlanks object contains the
3761    indicated Unicode value.
3762      __________________________________________________________
3763
3764 FcAtomic
3765
3766    Table of Contents
3767    FcAtomicCreate -- create an FcAtomic object
3768    FcAtomicLock -- lock a file
3769    FcAtomicNewFile -- return new temporary file name
3770    FcAtomicOrigFile -- return original file name
3771    FcAtomicReplaceOrig -- replace original with new
3772    FcAtomicDeleteNew -- delete new file
3773    FcAtomicUnlock -- unlock a file
3774    FcAtomicDestroy -- destroy an FcAtomic object
3775
3776    These functions provide a safe way to update configuration
3777    files, allowing ongoing reading of the old configuration file
3778    while locked for writing and ensuring that a consistent and
3779    complete version of the configuration file is always available.
3780
3781 FcAtomicCreate
3782
3783 Name
3784
3785    FcAtomicCreate -- create an FcAtomic object
3786
3787 Synopsis
3788
3789 #include <fontconfig/fontconfig.h>
3790
3791    FcAtomic * FcAtomicCreate(const FcChar8 *file);
3792
3793 Description
3794
3795    Creates a data structure containing data needed to control
3796    access to file. Writing is done to a separate file. Once that
3797    file is complete, the original configuration file is atomically
3798    replaced so that reading process always see a consistent and
3799    complete file without the need to lock for reading.
3800
3801 FcAtomicLock
3802
3803 Name
3804
3805    FcAtomicLock -- lock a file
3806
3807 Synopsis
3808
3809 #include <fontconfig/fontconfig.h>
3810
3811    FcBool FcAtomicLock(FcAtomic *atomic);
3812
3813 Description
3814
3815    Attempts to lock the file referenced by atomic. Returns FcFalse
3816    if the file is already locked, else returns FcTrue and leaves
3817    the file locked.
3818
3819 FcAtomicNewFile
3820
3821 Name
3822
3823    FcAtomicNewFile -- return new temporary file name
3824
3825 Synopsis
3826
3827 #include <fontconfig/fontconfig.h>
3828
3829    FcChar8 * FcAtomicNewFile(FcAtomic *atomic);
3830
3831 Description
3832
3833    Returns the filename for writing a new version of the file
3834    referenced by atomic.
3835
3836 FcAtomicOrigFile
3837
3838 Name
3839
3840    FcAtomicOrigFile -- return original file name
3841
3842 Synopsis
3843
3844 #include <fontconfig/fontconfig.h>
3845
3846    FcChar8 * FcAtomicOrigFile(FcAtomic *atomic);
3847
3848 Description
3849
3850    Returns the file referenced by atomic.
3851
3852 FcAtomicReplaceOrig
3853
3854 Name
3855
3856    FcAtomicReplaceOrig -- replace original with new
3857
3858 Synopsis
3859
3860 #include <fontconfig/fontconfig.h>
3861
3862    FcBool FcAtomicReplaceOrig(FcAtomic *atomic);
3863
3864 Description
3865
3866    Replaces the original file referenced by atomic with the new
3867    file. Returns FcFalse if the file cannot be replaced due to
3868    permission issues in the filesystem. Otherwise returns FcTrue.
3869
3870 FcAtomicDeleteNew
3871
3872 Name
3873
3874    FcAtomicDeleteNew -- delete new file
3875
3876 Synopsis
3877
3878 #include <fontconfig/fontconfig.h>
3879
3880    void FcAtomicDeleteNew(FcAtomic *atomic);
3881
3882 Description
3883
3884    Deletes the new file. Used in error recovery to back out
3885    changes.
3886
3887 FcAtomicUnlock
3888
3889 Name
3890
3891    FcAtomicUnlock -- unlock a file
3892
3893 Synopsis
3894
3895 #include <fontconfig/fontconfig.h>
3896
3897    void FcAtomicUnlock(FcAtomic *atomic);
3898
3899 Description
3900
3901    Unlocks the file.
3902
3903 FcAtomicDestroy
3904
3905 Name
3906
3907    FcAtomicDestroy -- destroy an FcAtomic object
3908
3909 Synopsis
3910
3911 #include <fontconfig/fontconfig.h>
3912
3913    void FcAtomicDestroy(FcAtomic *atomic);
3914
3915 Description
3916
3917    Destroys atomic.
3918      __________________________________________________________
3919
3920 File and Directory routines
3921
3922    Table of Contents
3923    FcFileScan -- scan a font file
3924    FcFileIsDir -- check whether a file is a directory
3925    FcDirScan -- scan a font directory without caching it
3926    FcDirSave -- DEPRECATED: formerly used to save a directory
3927           cache
3928
3929    FcDirCacheUnlink -- Remove all caches related to dir
3930    FcDirCacheValid -- check directory cache
3931    FcDirCacheLoad -- load a directory cache
3932    FcDirCacheRescan -- Re-scan a directory cache
3933    FcDirCacheRead -- read or construct a directory cache
3934    FcDirCacheLoadFile -- load a cache file
3935    FcDirCacheUnload -- unload a cache file
3936
3937    These routines work with font files and directories, including
3938    font directory cache files.
3939
3940 FcFileScan
3941
3942 Name
3943
3944    FcFileScan -- scan a font file
3945
3946 Synopsis
3947
3948 #include <fontconfig/fontconfig.h>
3949
3950    FcBool FcFileScan(FcFontSet *set, FcStrSet *dirs, FcFileCache
3951    *cache, FcBlanks *blanks, const FcChar8 *file, FcBool force);
3952
3953 Description
3954
3955    Scans a single file and adds all fonts found to set. If force
3956    is FcTrue, then the file is scanned even if associated
3957    information is found in cache. If file is a directory, it is
3958    added to dirs. Whether fonts are found depends on fontconfig
3959    policy as well as the current configuration. Internally,
3960    fontconfig will ignore BDF and PCF fonts which are not in
3961    Unicode (or the effectively equivalent ISO Latin-1) encoding as
3962    those are not usable by Unicode-based applications. The
3963    configuration can ignore fonts based on filename or contents of
3964    the font file itself. Returns FcFalse if any of the fonts
3965    cannot be added (due to allocation failure). Otherwise returns
3966    FcTrue.
3967
3968 FcFileIsDir
3969
3970 Name
3971
3972    FcFileIsDir -- check whether a file is a directory
3973
3974 Synopsis
3975
3976 #include <fontconfig/fontconfig.h>
3977
3978    FcBool FcFileIsDir(const FcChar8 *file);
3979
3980 Description
3981
3982    Returns FcTrue if file is a directory, otherwise returns
3983    FcFalse.
3984
3985 FcDirScan
3986
3987 Name
3988
3989    FcDirScan -- scan a font directory without caching it
3990
3991 Synopsis
3992
3993 #include <fontconfig/fontconfig.h>
3994
3995    FcBool FcDirScan(FcFontSet *set, FcStrSet *dirs, FcFileCache
3996    *cache, FcBlanks *blanks, const FcChar8 *dir, FcBool force);
3997
3998 Description
3999
4000    If cache is not zero or if force is FcFalse, this function
4001    currently returns FcFalse. Otherwise, it scans an entire
4002    directory and adds all fonts found to set. Any subdirectories
4003    found are added to dirs. Calling this function does not create
4004    any cache files. Use FcDirCacheRead() if caching is desired.
4005
4006 FcDirSave
4007
4008 Name
4009
4010    FcDirSave -- DEPRECATED: formerly used to save a directory
4011    cache
4012
4013 Synopsis
4014
4015 #include <fontconfig/fontconfig.h>
4016
4017    FcBool FcDirSave(FcFontSet *set, FcStrSet *dirs, const FcChar8
4018    *dir);
4019
4020 Description
4021
4022    This function now does nothing aside from returning FcFalse. It
4023    used to creates the per-directory cache file for dir and
4024    populates it with the fonts in set and subdirectories in dirs.
4025    All of this functionality is now automatically managed by
4026    FcDirCacheLoad and FcDirCacheRead.
4027
4028 FcDirCacheUnlink
4029
4030 Name
4031
4032    FcDirCacheUnlink -- Remove all caches related to dir
4033
4034 Synopsis
4035
4036 #include <fontconfig/fontconfig.h>
4037
4038    FcBool FcDirCacheUnlink(const FcChar8 *dir, FcConfig *config);
4039
4040 Description
4041
4042    Scans the cache directories in config, removing any instances
4043    of the cache file for dir. Returns FcFalse when some internal
4044    error occurs (out of memory, etc). Errors actually unlinking
4045    any files are ignored.
4046
4047 FcDirCacheValid
4048
4049 Name
4050
4051    FcDirCacheValid -- check directory cache
4052
4053 Synopsis
4054
4055 #include <fontconfig/fontconfig.h>
4056
4057    FcBool FcDirCacheValid(const FcChar8 *dir);
4058
4059 Description
4060
4061    Returns FcTrue if dir has an associated valid cache file, else
4062    returns FcFalse
4063
4064 FcDirCacheLoad
4065
4066 Name
4067
4068    FcDirCacheLoad -- load a directory cache
4069
4070 Synopsis
4071
4072 #include <fontconfig/fontconfig.h>
4073
4074    FcCache * FcDirCacheLoad(const FcChar8 *dir, FcConfig *config,
4075    FcChar8 **cache_file);
4076
4077 Description
4078
4079    Loads the cache related to dir. If no cache file exists,
4080    returns NULL. The name of the cache file is returned in
4081    cache_file, unless that is NULL. See also FcDirCacheRead.
4082
4083 FcDirCacheRescan
4084
4085 Name
4086
4087    FcDirCacheRescan -- Re-scan a directory cache
4088
4089 Synopsis
4090
4091 #include <fontconfig/fontconfig.h>
4092
4093    FcCache * FcDirCacheRescan(const FcChar8 *dir, FcConfig
4094    *config);
4095
4096 Description
4097
4098    Re-scan directories only at dir and update the cache. returns
4099    NULL if failed.
4100
4101 Since
4102
4103    version 2.11.1
4104
4105 FcDirCacheRead
4106
4107 Name
4108
4109    FcDirCacheRead -- read or construct a directory cache
4110
4111 Synopsis
4112
4113 #include <fontconfig/fontconfig.h>
4114
4115    FcCache * FcDirCacheRead(const FcChar8 *dir, FcBool force,
4116    FcConfig *config);
4117
4118 Description
4119
4120    This returns a cache for dir. If force is FcFalse, then an
4121    existing, valid cache file will be used. Otherwise, a new cache
4122    will be created by scanning the directory and that returned.
4123
4124 FcDirCacheLoadFile
4125
4126 Name
4127
4128    FcDirCacheLoadFile -- load a cache file
4129
4130 Synopsis
4131
4132 #include <fontconfig/fontconfig.h>
4133
4134    FcCache * FcDirCacheLoadFile(const FcChar8 *cache_file, struct
4135    stat *file_stat);
4136
4137 Description
4138
4139    This function loads a directory cache from cache_file. If
4140    file_stat is non-NULL, it will be filled with the results of
4141    stat(2) on the cache file.
4142
4143 FcDirCacheUnload
4144
4145 Name
4146
4147    FcDirCacheUnload -- unload a cache file
4148
4149 Synopsis
4150
4151 #include <fontconfig/fontconfig.h>
4152
4153    void FcDirCacheUnload(FcCache *cache);
4154
4155 Description
4156
4157    This function dereferences cache. When no other references to
4158    it remain, all memory associated with the cache will be freed.
4159      __________________________________________________________
4160
4161 FcCache routines
4162
4163    Table of Contents
4164    FcCacheDir -- Return directory of cache
4165    FcCacheCopySet -- Returns a copy of the fontset from cache
4166    FcCacheSubdir -- Return the i'th subdirectory.
4167    FcCacheNumSubdir -- Return the number of subdirectories in
4168           cache.
4169
4170    FcCacheNumFont -- Returns the number of fonts in cache.
4171    FcDirCacheClean -- This tries to clean up the cache directory
4172           of cache_dir. This returns FcTrue if the operation is
4173           successfully complete. otherwise FcFalse.
4174
4175    FcCacheCreateTagFile -- Create CACHEDIR.TAG at cache directory.
4176
4177    These routines work with font directory caches, accessing their
4178    contents in limited ways. It is not expected that normal
4179    applications will need to use these functions.
4180
4181 FcCacheDir
4182
4183 Name
4184
4185    FcCacheDir -- Return directory of cache
4186
4187 Synopsis
4188
4189 #include <fontconfig/fontconfig.h>
4190
4191    const FcChar8 * FcCacheDir(const FcCache *cache);
4192
4193 Description
4194
4195    This function returns the directory from which the cache was
4196    constructed.
4197
4198 FcCacheCopySet
4199
4200 Name
4201
4202    FcCacheCopySet -- Returns a copy of the fontset from cache
4203
4204 Synopsis
4205
4206 #include <fontconfig/fontconfig.h>
4207
4208    FcFontSet * FcCacheCopySet(const FcCache *cache);
4209
4210 Description
4211
4212    The returned fontset contains each of the font patterns from
4213    cache. This fontset may be modified, but the patterns from the
4214    cache are read-only.
4215
4216 FcCacheSubdir
4217
4218 Name
4219
4220    FcCacheSubdir -- Return the i'th subdirectory.
4221
4222 Synopsis
4223
4224 #include <fontconfig/fontconfig.h>
4225
4226    const FcChar8 * FcCacheSubdir(const FcCache *cache, inti);
4227
4228 Description
4229
4230    The set of subdirectories stored in a cache file are indexed by
4231    this function, i should range from 0 to n-1, where n is the
4232    return value from FcCacheNumSubdir.
4233
4234 FcCacheNumSubdir
4235
4236 Name
4237
4238    FcCacheNumSubdir -- Return the number of subdirectories in
4239    cache.
4240
4241 Synopsis
4242
4243 #include <fontconfig/fontconfig.h>
4244
4245    int FcCacheNumSubdir(const FcCache *cache);
4246
4247 Description
4248
4249    This returns the total number of subdirectories in the cache.
4250
4251 FcCacheNumFont
4252
4253 Name
4254
4255    FcCacheNumFont -- Returns the number of fonts in cache.
4256
4257 Synopsis
4258
4259 #include <fontconfig/fontconfig.h>
4260
4261    int FcCacheNumFont(const FcCache *cache);
4262
4263 Description
4264
4265    This returns the number of fonts which would be included in the
4266    return from FcCacheCopySet.
4267
4268 FcDirCacheClean
4269
4270 Name
4271
4272    FcDirCacheClean -- This tries to clean up the cache directory
4273    of cache_dir. This returns FcTrue if the operation is
4274    successfully complete. otherwise FcFalse.
4275
4276 Synopsis
4277
4278 #include <fontconfig/fontconfig.h>
4279
4280    FcBool FcDirCacheClean(const FcChar8 *cache_dir,
4281    FcBoolverbose);
4282
4283 Description
4284
4285 Since
4286
4287    version 2.9.91
4288
4289 FcCacheCreateTagFile
4290
4291 Name
4292
4293    FcCacheCreateTagFile -- Create CACHEDIR.TAG at cache directory.
4294
4295 Synopsis
4296
4297 #include <fontconfig/fontconfig.h>
4298
4299    void FcCacheCreateTagFile(const FcConfig *config);
4300
4301 Description
4302
4303    This tries to create CACHEDIR.TAG file at the cache directory
4304    registered to config.
4305
4306 Since
4307
4308    version 2.9.91
4309      __________________________________________________________
4310
4311 FcStrSet and FcStrList
4312
4313    Table of Contents
4314    FcStrSetCreate -- create a string set
4315    FcStrSetMember -- check set for membership
4316    FcStrSetEqual -- check sets for equality
4317    FcStrSetAdd -- add to a string set
4318    FcStrSetAddFilename -- add a filename to a string set
4319    FcStrSetDel -- delete from a string set
4320    FcStrSetDestroy -- destroy a string set
4321    FcStrListCreate -- create a string iterator
4322    FcStrListFirst -- get first string in iteration
4323    FcStrListNext -- get next string in iteration
4324    FcStrListDone -- destroy a string iterator
4325
4326    A data structure for enumerating strings, used to list
4327    directories while scanning the configuration as directories are
4328    added while scanning.
4329
4330 FcStrSetCreate
4331
4332 Name
4333
4334    FcStrSetCreate -- create a string set
4335
4336 Synopsis
4337
4338 #include <fontconfig/fontconfig.h>
4339
4340    FcStrSet * FcStrSetCreate(void);
4341
4342 Description
4343
4344    Create an empty set.
4345
4346 FcStrSetMember
4347
4348 Name
4349
4350    FcStrSetMember -- check set for membership
4351
4352 Synopsis
4353
4354 #include <fontconfig/fontconfig.h>
4355
4356    FcBool FcStrSetMember(FcStrSet *set, const FcChar8 *s);
4357
4358 Description
4359
4360    Returns whether s is a member of set.
4361
4362 FcStrSetEqual
4363
4364 Name
4365
4366    FcStrSetEqual -- check sets for equality
4367
4368 Synopsis
4369
4370 #include <fontconfig/fontconfig.h>
4371
4372    FcBool FcStrSetEqual(FcStrSet *set_a, FcStrSet *set_b);
4373
4374 Description
4375
4376    Returns whether set_a contains precisely the same strings as
4377    set_b. Ordering of strings within the two sets is not
4378    considered.
4379
4380 FcStrSetAdd
4381
4382 Name
4383
4384    FcStrSetAdd -- add to a string set
4385
4386 Synopsis
4387
4388 #include <fontconfig/fontconfig.h>
4389
4390    FcBool FcStrSetAdd(FcStrSet *set, const FcChar8 *s);
4391
4392 Description
4393
4394    Adds a copy of s to set.
4395
4396 FcStrSetAddFilename
4397
4398 Name
4399
4400    FcStrSetAddFilename -- add a filename to a string set
4401
4402 Synopsis
4403
4404 #include <fontconfig/fontconfig.h>
4405
4406    FcBool FcStrSetAddFilename(FcStrSet *set, const FcChar8 *s);
4407
4408 Description
4409
4410    Adds a copy s to set, The copy is created with
4411    FcStrCopyFilename so that leading '~' values are replaced with
4412    the value of the HOME environment variable.
4413
4414 FcStrSetDel
4415
4416 Name
4417
4418    FcStrSetDel -- delete from a string set
4419
4420 Synopsis
4421
4422 #include <fontconfig/fontconfig.h>
4423
4424    FcBool FcStrSetDel(FcStrSet *set, const FcChar8 *s);
4425
4426 Description
4427
4428    Removes s from set, returning FcTrue if s was a member else
4429    FcFalse.
4430
4431 FcStrSetDestroy
4432
4433 Name
4434
4435    FcStrSetDestroy -- destroy a string set
4436
4437 Synopsis
4438
4439 #include <fontconfig/fontconfig.h>
4440
4441    void FcStrSetDestroy(FcStrSet *set);
4442
4443 Description
4444
4445    Destroys set.
4446
4447 FcStrListCreate
4448
4449 Name
4450
4451    FcStrListCreate -- create a string iterator
4452
4453 Synopsis
4454
4455 #include <fontconfig/fontconfig.h>
4456
4457    FcStrList * FcStrListCreate(FcStrSet *set);
4458
4459 Description
4460
4461    Creates an iterator to list the strings in set.
4462
4463 FcStrListFirst
4464
4465 Name
4466
4467    FcStrListFirst -- get first string in iteration
4468
4469 Synopsis
4470
4471 #include <fontconfig/fontconfig.h>
4472
4473    void FcStrListFirst(FcStrList *list);
4474
4475 Description
4476
4477    Returns the first string in list.
4478
4479 Since
4480
4481    version 2.11.0
4482
4483 FcStrListNext
4484
4485 Name
4486
4487    FcStrListNext -- get next string in iteration
4488
4489 Synopsis
4490
4491 #include <fontconfig/fontconfig.h>
4492
4493    FcChar8 * FcStrListNext(FcStrList *list);
4494
4495 Description
4496
4497    Returns the next string in list.
4498
4499 FcStrListDone
4500
4501 Name
4502
4503    FcStrListDone -- destroy a string iterator
4504
4505 Synopsis
4506
4507 #include <fontconfig/fontconfig.h>
4508
4509    void FcStrListDone(FcStrList *list);
4510
4511 Description
4512
4513    Destroys the enumerator list.
4514      __________________________________________________________
4515
4516 String utilities
4517
4518    Table of Contents
4519    FcUtf8ToUcs4 -- convert UTF-8 to UCS4
4520    FcUcs4ToUtf8 -- convert UCS4 to UTF-8
4521    FcUtf8Len -- count UTF-8 encoded chars
4522    FcUtf16ToUcs4 -- convert UTF-16 to UCS4
4523    FcUtf16Len -- count UTF-16 encoded chars
4524    FcIsLower -- check for lower case ASCII character
4525    FcIsUpper -- check for upper case ASCII character
4526    FcToLower -- convert upper case ASCII to lower case
4527    FcStrCopy -- duplicate a string
4528    FcStrDowncase -- create a lower case translation of a string
4529    FcStrCopyFilename -- create a complete path from a filename
4530    FcStrCmp -- compare UTF-8 strings
4531    FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring case
4532    FcStrStr -- locate UTF-8 substring
4533    FcStrStrIgnoreCase -- locate UTF-8 substring ignoring ASCII
4534           case
4535
4536    FcStrPlus -- concatenate two strings
4537    FcStrFree -- free a string
4538    FcStrDirname -- directory part of filename
4539    FcStrBasename -- last component of filename
4540
4541    Fontconfig manipulates many UTF-8 strings represented with the
4542    FcChar8 type. These functions are exposed to help applications
4543    deal with these UTF-8 strings in a locale-insensitive manner.
4544
4545 FcUtf8ToUcs4
4546
4547 Name
4548
4549    FcUtf8ToUcs4 -- convert UTF-8 to UCS4
4550
4551 Synopsis
4552
4553 #include <fontconfig/fontconfig.h>
4554
4555    int FcUtf8ToUcs4(FcChar8 *src, FcChar32 *dst, int len);
4556
4557 Description
4558
4559    Converts the next Unicode char from src into dst and returns
4560    the number of bytes containing the char. src must be at least
4561    len bytes long.
4562
4563 FcUcs4ToUtf8
4564
4565 Name
4566
4567    FcUcs4ToUtf8 -- convert UCS4 to UTF-8
4568
4569 Synopsis
4570
4571 #include <fontconfig/fontconfig.h>
4572
4573    int FcUcs4ToUtf8(FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN]);
4574
4575 Description
4576
4577    Converts the Unicode char from src into dst and returns the
4578    number of bytes needed to encode the char.
4579
4580 FcUtf8Len
4581
4582 Name
4583
4584    FcUtf8Len -- count UTF-8 encoded chars
4585
4586 Synopsis
4587
4588 #include <fontconfig/fontconfig.h>
4589
4590    FcBool FcUtf8Len(FcChar8 *src, int len, int *nchar, int
4591    *wchar);
4592
4593 Description
4594
4595    Counts the number of Unicode chars in len bytes of src. Places
4596    that count in nchar. wchar contains 1, 2 or 4 depending on the
4597    number of bytes needed to hold the largest Unicode char
4598    counted. The return value indicates whether src is a
4599    well-formed UTF8 string.
4600
4601 FcUtf16ToUcs4
4602
4603 Name
4604
4605    FcUtf16ToUcs4 -- convert UTF-16 to UCS4
4606
4607 Synopsis
4608
4609 #include <fontconfig/fontconfig.h>
4610
4611    int FcUtf16ToUcs4(FcChar8 *src, FcEndian endian, FcChar32 *dst,
4612    int len);
4613
4614 Description
4615
4616    Converts the next Unicode char from src into dst and returns
4617    the number of bytes containing the char. src must be at least
4618    len bytes long. Bytes of src are combined into 16-bit units
4619    according to endian.
4620
4621 FcUtf16Len
4622
4623 Name
4624
4625    FcUtf16Len -- count UTF-16 encoded chars
4626
4627 Synopsis
4628
4629 #include <fontconfig/fontconfig.h>
4630
4631    FcBool FcUtf16Len(FcChar8 *src, FcEndian endian, int len, int
4632    *nchar, int *wchar);
4633
4634 Description
4635
4636    Counts the number of Unicode chars in len bytes of src. Bytes
4637    of src are combined into 16-bit units according to endian.
4638    Places that count in nchar. wchar contains 1, 2 or 4 depending
4639    on the number of bytes needed to hold the largest Unicode char
4640    counted. The return value indicates whether string is a
4641    well-formed UTF16 string.
4642
4643 FcIsLower
4644
4645 Name
4646
4647    FcIsLower -- check for lower case ASCII character
4648
4649 Synopsis
4650
4651 #include <fontconfig/fontconfig.h>
4652
4653    FcBool FcIsLower(FcChar8c);
4654
4655 Description
4656
4657    This macro checks whether c is an lower case ASCII letter.
4658
4659 FcIsUpper
4660
4661 Name
4662
4663    FcIsUpper -- check for upper case ASCII character
4664
4665 Synopsis
4666
4667 #include <fontconfig/fontconfig.h>
4668
4669    FcBool FcIsUpper(FcChar8c);
4670
4671 Description
4672
4673    This macro checks whether c is a upper case ASCII letter.
4674
4675 FcToLower
4676
4677 Name
4678
4679    FcToLower -- convert upper case ASCII to lower case
4680
4681 Synopsis
4682
4683 #include <fontconfig/fontconfig.h>
4684
4685    FcChar8 FcToLower(FcChar8c);
4686
4687 Description
4688
4689    This macro converts upper case ASCII c to the equivalent lower
4690    case letter.
4691
4692 FcStrCopy
4693
4694 Name
4695
4696    FcStrCopy -- duplicate a string
4697
4698 Synopsis
4699
4700 #include <fontconfig/fontconfig.h>
4701
4702    FcChar8 * FcStrCopy(const FcChar8 *s);
4703
4704 Description
4705
4706    Allocates memory, copies s and returns the resulting buffer.
4707    Yes, this is strdup, but that function isn't available on every
4708    platform.
4709
4710 FcStrDowncase
4711
4712 Name
4713
4714    FcStrDowncase -- create a lower case translation of a string
4715
4716 Synopsis
4717
4718 #include <fontconfig/fontconfig.h>
4719
4720    FcChar8 * FcStrDowncase(const FcChar8 *s);
4721
4722 Description
4723
4724    Allocates memory, copies s, converting upper case letters to
4725    lower case and returns the allocated buffer.
4726
4727 FcStrCopyFilename
4728
4729 Name
4730
4731    FcStrCopyFilename -- create a complete path from a filename
4732
4733 Synopsis
4734
4735 #include <fontconfig/fontconfig.h>
4736
4737    FcChar8 * FcStrCopyFilename(const FcChar8 *s);
4738
4739 Description
4740
4741    FcStrCopyFilename constructs an absolute pathname from s. It
4742    converts any leading '~' characters in to the value of the HOME
4743    environment variable, and any relative paths are converted to
4744    absolute paths using the current working directory. Sequences
4745    of '/' characters are converted to a single '/', and names
4746    containing the current directory '.' or parent directory '..'
4747    are correctly reconstructed. Returns NULL if '~' is the leading
4748    character and HOME is unset or disabled (see
4749    FcConfigEnableHome).
4750
4751 FcStrCmp
4752
4753 Name
4754
4755    FcStrCmp -- compare UTF-8 strings
4756
4757 Synopsis
4758
4759 #include <fontconfig/fontconfig.h>
4760
4761    int FcStrCmp(const FcChar8 *s1, const FcChar8 *s2);
4762
4763 Description
4764
4765    Returns the usual <0, 0, >0 result of comparing s1 and s2.
4766
4767 FcStrCmpIgnoreCase
4768
4769 Name
4770
4771    FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring case
4772
4773 Synopsis
4774
4775 #include <fontconfig/fontconfig.h>
4776
4777    int FcStrCmpIgnoreCase(const FcChar8 *s1, const FcChar8 *s2);
4778
4779 Description
4780
4781    Returns the usual <0, 0, >0 result of comparing s1 and s2. This
4782    test is case-insensitive for all proper UTF-8 encoded strings.
4783
4784 FcStrStr
4785
4786 Name
4787
4788    FcStrStr -- locate UTF-8 substring
4789
4790 Synopsis
4791
4792 #include <fontconfig/fontconfig.h>
4793
4794    FcChar8 * FcStrStr(const FcChar8 *s1, const FcChar8 *s2);
4795
4796 Description
4797
4798    Returns the location of s2 in s1. Returns NULL if s2 is not
4799    present in s1. This test will operate properly with UTF8
4800    encoded strings.
4801
4802 FcStrStrIgnoreCase
4803
4804 Name
4805
4806    FcStrStrIgnoreCase -- locate UTF-8 substring ignoring ASCII
4807    case
4808
4809 Synopsis
4810
4811 #include <fontconfig/fontconfig.h>
4812
4813    FcChar8 * FcStrStrIgnoreCase(const FcChar8 *s1, const FcChar8
4814    *s2);
4815
4816 Description
4817
4818    Returns the location of s2 in s1, ignoring case. Returns NULL
4819    if s2 is not present in s1. This test is case-insensitive for
4820    all proper UTF-8 encoded strings.
4821
4822 FcStrPlus
4823
4824 Name
4825
4826    FcStrPlus -- concatenate two strings
4827
4828 Synopsis
4829
4830 #include <fontconfig/fontconfig.h>
4831
4832    FcChar8 * FcStrPlus(const FcChar8 *s1, const FcChar8 *s2);
4833
4834 Description
4835
4836    This function allocates new storage and places the
4837    concatenation of s1 and s2 there, returning the new string.
4838
4839 FcStrFree
4840
4841 Name
4842
4843    FcStrFree -- free a string
4844
4845 Synopsis
4846
4847 #include <fontconfig/fontconfig.h>
4848
4849    void FcStrFree(FcChar8 *s);
4850
4851 Description
4852
4853    This is just a wrapper around free(3) which helps track memory
4854    usage of strings within the fontconfig library.
4855
4856 FcStrDirname
4857
4858 Name
4859
4860    FcStrDirname -- directory part of filename
4861
4862 Synopsis
4863
4864 #include <fontconfig/fontconfig.h>
4865
4866    FcChar8 * FcStrDirname(const FcChar8 *file);
4867
4868 Description
4869
4870    Returns the directory containing file. This is returned in
4871    newly allocated storage which should be freed when no longer
4872    needed.
4873
4874 FcStrBasename
4875
4876 Name
4877
4878    FcStrBasename -- last component of filename
4879
4880 Synopsis
4881
4882 #include <fontconfig/fontconfig.h>
4883
4884    FcChar8 * FcStrBasename(const FcChar8 *file);
4885
4886 Description
4887
4888    Returns the filename of file stripped of any leading directory
4889    names. This is returned in newly allocated storage which should
4890    be freed when no longer needed.