fontconfig-devel.txt revision 953daeba
1Fontconfig Developers Reference, Version 2.12.4 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 33DESCRIPTION 34 35 Fontconfig is a library designed to provide system-wide font 36 configuration, customization and application access. 37 __________________________________________________________ 38 39FUNCTIONAL 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 47FONT 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 78FONT 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 94weight 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 100ere 101 different from family 102and 103 family + style 104 fullnamelang FC_FULLNAMELANG String Language corresponding 105 to 106 each fullname 107 slant FC_SLANT Int Italic, oblique or rom 108an 109 weight FC_WEIGHT Int Light, medium, demibol 110d, 111 bold or black 112 size FC_SIZE Double Point size 113 width FC_WIDTH Int Condensed, normal or e 114xpanded 115 aspect FC_ASPECT Double Stretches glyphs horiz 116ontally 117 before hinting 118 pixelsize FC_PIXEL_SIZE Double Pixel size 119 spacing FC_SPACING Int Proportional, dual-wid 120th, 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 129e 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 135e data (deprecated) 136 file FC_FILE String The filename holding t 137he font 138 index FC_INDEX Int The index of the font 139within 140 the file 141 ftface FC_FT_FACE FT_Face Use the specified Free 142Type 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 149scaled 150 scale FC_SCALE Double Scale factor for point 151->pixel 152 conversions (deprecate 153d) 154 symbol FC_SYMBOL Bool Whether font uses MS s 155ymbol-font encoding 156 color FC_COLOR Bool Whether any glyphs hav 157e color 158 dpi FC_DPI Double Target dots per inch 159 rgba FC_RGBA Int unknown, rgb, bgr, vrg 160b, 161 vbgr, none - subpixel 162geometry 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 168by 169 the font 170 lang FC_LANG LangSet Set of RFC-3066-style 171 languages this font su 172pports 173 fontversion FC_FONTVERSION Int Version number of the 174font 175 capability FC_CAPABILITY String List of layout capabil 176ities in 177 the font 178 fontformat FC_FONTFORMAT String String name of the fon 179t format 180 embolden FC_EMBOLDEN Bool Rasterizer should 181 synthetically embolden 182 the font 183 embeddedbitmap FC_EMBEDDED_BITMAP Bool Use the embedded bitma 184p 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 190tags in 191 OpenType to be enabled 192 namelang FC_NAMELANG String Language name to be us 193ed for the 194 default value of famil 195ylang, 196 stylelang and fullname 197lang 198 prgname FC_PRGNAME String Name of the running pr 199ogram 200 hash FC_HASH String SHA256 hash value of t 201he font data 202 with "sha256:" prefix 203(deprecated) 204 postscriptname FC_POSTSCRIPT_NAME String Font name in PostScrip 205t 206 __________________________________________________________ 207 208Datatypes 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 215FcChar8, 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 223FcMatrix 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 233FcCharSet 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 240FcLangSet 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 252FcLangResult 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 262FcType 263 264 Tags the kind of data stored in an FcValue. 265 __________________________________________________________ 266 267FcValue 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 301FcPattern 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 311FcFontSet 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 327FcStrSet, 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 337FcObjectSet 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 350FcObjectType 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 362FcConstant 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 375FcBlanks 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 382FcFileCache 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 390FcConfig 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 403FcSetName 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 411FcResult 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 421h 422 FcResultNoId Object exists, but has fewer values 423 than specified 424 FcResultOutOfMemory malloc failed 425 __________________________________________________________ 426 427FcAtomic 428 429 Used for locking access to configuration files. Provides a safe 430 way to update configuration files. 431 __________________________________________________________ 432 433FcCache 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 443FUNCTIONS 444 445 These are grouped by functionality, often using the main data 446 type being manipulated. 447 __________________________________________________________ 448 449Initialization 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 463FcInitLoadConfig 464 465Name 466 467 FcInitLoadConfig -- load configuration 468 469Synopsis 470 471#include <fontconfig/fontconfig.h> 472 473 FcConfig * FcInitLoadConfig(void); 474 475Description 476 477 Loads the default configuration file and returns the resulting 478 configuration. Does not load any font information. 479 480FcInitLoadConfigAndFonts 481 482Name 483 484 FcInitLoadConfigAndFonts -- load configuration and font data 485 486Synopsis 487 488#include <fontconfig/fontconfig.h> 489 490 FcConfig * FcInitLoadConfigAndFonts(void); 491 492Description 493 494 Loads the default configuration file and builds information 495 about the available fonts. Returns the resulting configuration. 496 497FcInit 498 499Name 500 501 FcInit -- initialize fontconfig library 502 503Synopsis 504 505#include <fontconfig/fontconfig.h> 506 507 FcBool FcInit(void); 508 509Description 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 517FcFini 518 519Name 520 521 FcFini -- finalize fontconfig library 522 523Synopsis 524 525#include <fontconfig/fontconfig.h> 526 527 void FcFini(void); 528 529Description 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 536FcGetVersion 537 538Name 539 540 FcGetVersion -- library version number 541 542Synopsis 543 544#include <fontconfig/fontconfig.h> 545 546 int FcGetVersion(void); 547 548Description 549 550 Returns the version number of the library. 551 552FcInitReinitialize 553 554Name 555 556 FcInitReinitialize -- re-initialize library 557 558Synopsis 559 560#include <fontconfig/fontconfig.h> 561 562 FcBool FcInitReinitialize(void); 563 564Description 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 572FcInitBringUptoDate 573 574Name 575 576 FcInitBringUptoDate -- reload configuration files if needed 577 578Synopsis 579 580#include <fontconfig/fontconfig.h> 581 582 FcBool FcInitBringUptoDate(void); 583 584Description 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 593FcPattern 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 629FcPatternCreate 630 631Name 632 633 FcPatternCreate -- Create a pattern 634 635Synopsis 636 637#include <fontconfig/fontconfig.h> 638 639 FcPattern * FcPatternCreate(void); 640 641Description 642 643 Creates a pattern with no properties; used to build patterns 644 from scratch. 645 646FcPatternDuplicate 647 648Name 649 650 FcPatternDuplicate -- Copy a pattern 651 652Synopsis 653 654#include <fontconfig/fontconfig.h> 655 656 FcPattern * FcPatternDuplicate(const FcPattern *p); 657 658Description 659 660 Copy a pattern, returning a new pattern that matches p. Each 661 pattern may be modified without affecting the other. 662 663FcPatternReference 664 665Name 666 667 FcPatternReference -- Increment pattern reference count 668 669Synopsis 670 671#include <fontconfig/fontconfig.h> 672 673 void FcPatternReference(FcPattern *p); 674 675Description 676 677 Add another reference to p. Patterns are freed only when the 678 reference count reaches zero. 679 680FcPatternDestroy 681 682Name 683 684 FcPatternDestroy -- Destroy a pattern 685 686Synopsis 687 688#include <fontconfig/fontconfig.h> 689 690 void FcPatternDestroy(FcPattern *p); 691 692Description 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 698FcPatternEqual 699 700Name 701 702 FcPatternEqual -- Compare patterns 703 704Synopsis 705 706#include <fontconfig/fontconfig.h> 707 708 FcBool FcPatternEqual(const FcPattern *pa, const FcPattern 709 *pb); 710 711Description 712 713 Returns whether pa and pb are exactly alike. 714 715FcPatternEqualSubset 716 717Name 718 719 FcPatternEqualSubset -- Compare portions of patterns 720 721Synopsis 722 723#include <fontconfig/fontconfig.h> 724 725 FcBool FcPatternEqualSubset(const FcPattern *pa, const 726 FcPattern *pb, const FcObjectSet *os); 727 728Description 729 730 Returns whether pa and pb have exactly the same values for all 731 of the objects in os. 732 733FcPatternFilter 734 735Name 736 737 FcPatternFilter -- Filter the objects of pattern 738 739Synopsis 740 741#include <fontconfig/fontconfig.h> 742 743 FcPattern * FcPatternFilter(FcPattern *p, const FcObjectSet *); 744 745Description 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 750FcPatternHash 751 752Name 753 754 FcPatternHash -- Compute a pattern hash value 755 756Synopsis 757 758#include <fontconfig/fontconfig.h> 759 760 FcChar32 FcPatternHash(const FcPattern *p); 761 762Description 763 764 Returns a 32-bit number which is the same for any two patterns 765 which are equal. 766 767FcPatternAdd 768 769Name 770 771 FcPatternAdd -- Add a value to a pattern 772 773Synopsis 774 775#include <fontconfig/fontconfig.h> 776 777 FcBool FcPatternAdd(FcPattern *p, const char *object, FcValue 778 value, FcBool append); 779 780Description 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 789FcPatternAddWeak 790 791Name 792 793 FcPatternAddWeak -- Add a value to a pattern with weak binding 794 795Synopsis 796 797#include <fontconfig/fontconfig.h> 798 799 FcBool FcPatternAddWeak(FcPattern *p, const char *object, 800 FcValue value, FcBool append); 801 802Description 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 808FcPatternAdd-Type 809 810Name 811 812 FcPatternAddInteger, FcPatternAddDouble, FcPatternAddString, 813 FcPatternAddMatrix, FcPatternAddCharSet, FcPatternAddBool, 814 FcPatternAddFTFace, FcPatternAddLangSet, 815 FcPatternAddRange -- Add a typed value to a pattern 816 817Synopsis 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 848Description 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 856FcPatternGet 857 858Name 859 860 FcPatternGet -- Return a value from a pattern 861 862Synopsis 863 864#include <fontconfig/fontconfig.h> 865 866 FcResult FcPatternGet(FcPattern *p, const char *object, int id, 867 FcValue *v); 868 869Description 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 876FcPatternGet-Type 877 878Name 879 880 FcPatternGetInteger, FcPatternGetDouble, FcPatternGetString, 881 FcPatternGetMatrix, FcPatternGetCharSet, FcPatternGetBool, 882 FcPatternGetFTFace, FcPatternGetLangSet, 883 FcPatternGetRange -- Return a typed value from a pattern 884 885Synopsis 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 916Description 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 926FcPatternBuild 927 928Name 929 930 FcPatternBuild, FcPatternVaBuild, FcPatternVapBuild -- Create 931 patterns from arguments 932 933Synopsis 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 944Description 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 960pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 9610); 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 968FcPatternDel 969 970Name 971 972 FcPatternDel -- Delete a property from a pattern 973 974Synopsis 975 976#include <fontconfig/fontconfig.h> 977 978 FcBool FcPatternDel(FcPattern *p, const char *object); 979 980Description 981 982 Deletes all values associated with the property `object', 983 returning whether the property existed or not. 984 985FcPatternRemove 986 987Name 988 989 FcPatternRemove -- Remove one object of the specified type from 990 the pattern 991 992Synopsis 993 994#include <fontconfig/fontconfig.h> 995 996 FcBool FcPatternRemove(FcPattern *p, const char *object, int 997 id); 998 999Description 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 1005FcPatternPrint 1006 1007Name 1008 1009 FcPatternPrint -- Print a pattern for debugging 1010 1011Synopsis 1012 1013#include <fontconfig/fontconfig.h> 1014 1015 void FcPatternPrint(const FcPattern *p); 1016 1017Description 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 1023FcDefaultSubstitute 1024 1025Name 1026 1027 FcDefaultSubstitute -- Perform default substitutions in a 1028 pattern 1029 1030Synopsis 1031 1032#include <fontconfig/fontconfig.h> 1033 1034 void FcDefaultSubstitute(FcPattern *pattern); 1035 1036Description 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 1048FcNameParse 1049 1050Name 1051 1052 FcNameParse -- Parse a pattern string 1053 1054Synopsis 1055 1056#include <fontconfig/fontconfig.h> 1057 1058 FcPattern * FcNameParse(const FcChar8 *name); 1059 1060Description 1061 1062 Converts name from the standard text format described above 1063 into a pattern. 1064 1065FcNameUnparse 1066 1067Name 1068 1069 FcNameUnparse -- Convert a pattern back into a string that can 1070 be parsed 1071 1072Synopsis 1073 1074#include <fontconfig/fontconfig.h> 1075 1076 FcChar8 * FcNameUnparse(FcPattern *pat); 1077 1078Description 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 1085FcPatternFormat 1086 1087Name 1088 1089 FcPatternFormat -- Format a pattern into a string according to 1090 a format specifier 1091 1092Synopsis 1093 1094#include <fontconfig/fontconfig.h> 1095 1096 FcChar8 * FcPatternFormat(FcPattern *pat, const FcChar8 1097 *format); 1098 1099Description 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 1305Since 1306 1307 version 2.9.0 1308 __________________________________________________________ 1309 1310FcFontSet 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 1325FcFontSetCreate 1326 1327Name 1328 1329 FcFontSetCreate -- Create a font set 1330 1331Synopsis 1332 1333#include <fontconfig/fontconfig.h> 1334 1335 FcFontSet * FcFontSetCreate(void); 1336 1337Description 1338 1339 Creates an empty font set. 1340 1341FcFontSetDestroy 1342 1343Name 1344 1345 FcFontSetDestroy -- Destroy a font set 1346 1347Synopsis 1348 1349#include <fontconfig/fontconfig.h> 1350 1351 void FcFontSetDestroy(FcFontSet *s); 1352 1353Description 1354 1355 Destroys a font set. Note that this destroys any referenced 1356 patterns as well. 1357 1358FcFontSetAdd 1359 1360Name 1361 1362 FcFontSetAdd -- Add to a font set 1363 1364Synopsis 1365 1366#include <fontconfig/fontconfig.h> 1367 1368 FcBool FcFontSetAdd(FcFontSet *s, FcPattern *font); 1369 1370Description 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 1377FcFontSetList 1378 1379Name 1380 1381 FcFontSetList -- List fonts from a set of font sets 1382 1383Synopsis 1384 1385#include <fontconfig/fontconfig.h> 1386 1387 FcFontSet * FcFontSetList(FcConfig *config, FcFontSet **sets, 1388 intnsets, FcPattern *pattern, FcObjectSet *object_set); 1389 1390Description 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 1397FcFontSetMatch 1398 1399Name 1400 1401 FcFontSetMatch -- Return the best font from a set of font sets 1402 1403Synopsis 1404 1405#include <fontconfig/fontconfig.h> 1406 1407 FcPattern * FcFontSetMatch(FcConfig *config, FcFontSet **sets, 1408 intnsets, FcPattern *pattern, FcResult *result); 1409 1410Description 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 1420FcFontSetPrint 1421 1422Name 1423 1424 FcFontSetPrint -- Print a set of patterns to stdout 1425 1426Synopsis 1427 1428#include <fontconfig/fontconfig.h> 1429 1430 void FcFontSetPrint(FcFontSet *set); 1431 1432Description 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 1439FcFontSetSort 1440 1441Name 1442 1443 FcFontSetSort -- Add to a font set 1444 1445Synopsis 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 1453Description 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 1473FcFontSetSortDestroy 1474 1475Name 1476 1477 FcFontSetSortDestroy -- DEPRECATED destroy a font set 1478 1479Synopsis 1480 1481#include <fontconfig/fontconfig.h> 1482 1483 FcFontSetSortDestroy(FcFontSet *set); 1484 1485Description 1486 1487 This function is DEPRECATED. FcFontSetSortDestroy destroys set 1488 by calling FcFontSetDestroy. Applications should use 1489 FcFontSetDestroy directly instead. 1490 __________________________________________________________ 1491 1492FcObjectSet 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 1504FcObjectSetCreate 1505 1506Name 1507 1508 FcObjectSetCreate -- Create an object set 1509 1510Synopsis 1511 1512#include <fontconfig/fontconfig.h> 1513 1514 FcObjectSet * FcObjectSetCreate(void); 1515 1516Description 1517 1518 Creates an empty set. 1519 1520FcObjectSetAdd 1521 1522Name 1523 1524 FcObjectSetAdd -- Add to an object set 1525 1526Synopsis 1527 1528#include <fontconfig/fontconfig.h> 1529 1530 FcBool FcObjectSetAdd(FcObjectSet *os, const char *object); 1531 1532Description 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 1538FcObjectSetDestroy 1539 1540Name 1541 1542 FcObjectSetDestroy -- Destroy an object set 1543 1544Synopsis 1545 1546#include <fontconfig/fontconfig.h> 1547 1548 void FcObjectSetDestroy(FcObjectSet *os); 1549 1550Description 1551 1552 Destroys an object set. 1553 1554FcObjectSetBuild 1555 1556Name 1557 1558 FcObjectSetBuild, FcObjectSetVaBuild, 1559 FcObjectSetVapBuild -- Build object set from args 1560 1561Synopsis 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 1573Description 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 1581FreeType 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 1596FcFreeTypeCharIndex 1597 1598Name 1599 1600 FcFreeTypeCharIndex -- map Unicode to glyph id 1601 1602Synopsis 1603 1604#include <fontconfig.h> 1605#include <fcfreetype.h> 1606 1607 FT_UInt FcFreeTypeCharIndex(FT_Face face, FcChar32 ucs4); 1608 1609Description 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 1618FcFreeTypeCharSet 1619 1620Name 1621 1622 FcFreeTypeCharSet -- compute Unicode coverage 1623 1624Synopsis 1625 1626#include <fontconfig.h> 1627#include <fcfreetype.h> 1628 1629 FcCharSet * FcFreeTypeCharSet(FT_Face face, FcBlanks *blanks); 1630 1631Description 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 1639FcFreeTypeCharSetAndSpacing 1640 1641Name 1642 1643 FcFreeTypeCharSetAndSpacing -- compute Unicode coverage and 1644 spacing type 1645 1646Synopsis 1647 1648#include <fontconfig.h> 1649#include <fcfreetype.h> 1650 1651 FcCharSet * FcFreeTypeCharSetAndSpacing(FT_Face face, FcBlanks 1652 *blanks, int *spacing); 1653 1654Description 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 1666FcFreeTypeQuery 1667 1668Name 1669 1670 FcFreeTypeQuery -- compute pattern from font file (and index) 1671 1672Synopsis 1673 1674#include <fontconfig.h> 1675#include <fcfreetype.h> 1676 1677 FcPattern * FcFreeTypeQuery(const FcChar8 *file, int id, 1678 FcBlanks *blanks, int *count); 1679 1680Description 1681 1682 Constructs a pattern representing the 'id'th font in 'file'. 1683 The number of fonts in 'file' is returned in 'count'. 1684 1685FcFreeTypeQueryFace 1686 1687Name 1688 1689 FcFreeTypeQueryFace -- compute pattern from FT_Face 1690 1691Synopsis 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 1699Description 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 1706FcValue 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 1719FcValueDestroy 1720 1721Name 1722 1723 FcValueDestroy -- Free a value 1724 1725Synopsis 1726 1727#include <fontconfig/fontconfig.h> 1728 1729 void FcValueDestroy(FcValue v); 1730 1731Description 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 1737FcValueSave 1738 1739Name 1740 1741 FcValueSave -- Copy a value 1742 1743Synopsis 1744 1745#include <fontconfig/fontconfig.h> 1746 1747 FcValue FcValueSave(FcValue v); 1748 1749Description 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 1754FcValuePrint 1755 1756Name 1757 1758 FcValuePrint -- Print a value to stdout 1759 1760Synopsis 1761 1762#include <fontconfig/fontconfig.h> 1763 1764 void FcValuePrint(FcValue v); 1765 1766Description 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 1772FcValueEqual 1773 1774Name 1775 1776 FcValueEqual -- Test two values for equality 1777 1778Synopsis 1779 1780#include <fontconfig/fontconfig.h> 1781 1782 FcBool FcValueEqual(FcValue v_a, FcValue v_b); 1783 1784Description 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 1791FcCharSet 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 1823FcCharSetCreate 1824 1825Name 1826 1827 FcCharSetCreate -- Create an empty character set 1828 1829Synopsis 1830 1831#include <fontconfig/fontconfig.h> 1832 1833 FcCharSet * FcCharSetCreate(void); 1834 1835Description 1836 1837 FcCharSetCreate allocates and initializes a new empty character 1838 set object. 1839 1840FcCharSetDestroy 1841 1842Name 1843 1844 FcCharSetDestroy -- Destroy a character set 1845 1846Synopsis 1847 1848#include <fontconfig/fontconfig.h> 1849 1850 void FcCharSetDestroy(FcCharSet *fcs); 1851 1852Description 1853 1854 FcCharSetDestroy decrements the reference count fcs. If the 1855 reference count becomes zero, all memory referenced is freed. 1856 1857FcCharSetAddChar 1858 1859Name 1860 1861 FcCharSetAddChar -- Add a character to a charset 1862 1863Synopsis 1864 1865#include <fontconfig/fontconfig.h> 1866 1867 FcBool FcCharSetAddChar(FcCharSet *fcs, FcChar32 ucs4); 1868 1869Description 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 1875FcCharSetDelChar 1876 1877Name 1878 1879 FcCharSetDelChar -- Add a character to a charset 1880 1881Synopsis 1882 1883#include <fontconfig/fontconfig.h> 1884 1885 FcBool FcCharSetDelChar(FcCharSet *fcs, FcChar32 ucs4); 1886 1887Description 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 1893Since 1894 1895 version 2.9.0 1896 1897FcCharSetCopy 1898 1899Name 1900 1901 FcCharSetCopy -- Copy a charset 1902 1903Synopsis 1904 1905#include <fontconfig/fontconfig.h> 1906 1907 FcCharSet * FcCharSetCopy(FcCharSet *src); 1908 1909Description 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 1914FcCharSetEqual 1915 1916Name 1917 1918 FcCharSetEqual -- Compare two charsets 1919 1920Synopsis 1921 1922#include <fontconfig/fontconfig.h> 1923 1924 FcBool FcCharSetEqual(const FcCharSet *a, const FcCharSet *b); 1925 1926Description 1927 1928 Returns whether a and b contain the same set of Unicode chars. 1929 1930FcCharSetIntersect 1931 1932Name 1933 1934 FcCharSetIntersect -- Intersect charsets 1935 1936Synopsis 1937 1938#include <fontconfig/fontconfig.h> 1939 1940 FcCharSet * FcCharSetIntersect(const FcCharSet *a, const 1941 FcCharSet *b); 1942 1943Description 1944 1945 Returns a set including only those chars found in both a and b. 1946 1947FcCharSetUnion 1948 1949Name 1950 1951 FcCharSetUnion -- Add charsets 1952 1953Synopsis 1954 1955#include <fontconfig/fontconfig.h> 1956 1957 FcCharSet * FcCharSetUnion(const FcCharSet *a, const FcCharSet 1958 *b); 1959 1960Description 1961 1962 Returns a set including only those chars found in either a or 1963 b. 1964 1965FcCharSetSubtract 1966 1967Name 1968 1969 FcCharSetSubtract -- Subtract charsets 1970 1971Synopsis 1972 1973#include <fontconfig/fontconfig.h> 1974 1975 FcCharSet * FcCharSetSubtract(const FcCharSet *a, const 1976 FcCharSet *b); 1977 1978Description 1979 1980 Returns a set including only those chars found in a but not b. 1981 1982FcCharSetMerge 1983 1984Name 1985 1986 FcCharSetMerge -- Merge charsets 1987 1988Synopsis 1989 1990#include <fontconfig/fontconfig.h> 1991 1992 FcBool FcCharSetMerge(FcCharSet *a, const FcCharSet *b, FcBool 1993 *changed); 1994 1995Description 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 2003FcCharSetHasChar 2004 2005Name 2006 2007 FcCharSetHasChar -- Check a charset for a char 2008 2009Synopsis 2010 2011#include <fontconfig/fontconfig.h> 2012 2013 FcBool FcCharSetHasChar(const FcCharSet *fcs, FcChar32 ucs4); 2014 2015Description 2016 2017 Returns whether fcs contains the char ucs4. 2018 2019FcCharSetCount 2020 2021Name 2022 2023 FcCharSetCount -- Count entries in a charset 2024 2025Synopsis 2026 2027#include <fontconfig/fontconfig.h> 2028 2029 FcChar32 FcCharSetCount(const FcCharSet *a); 2030 2031Description 2032 2033 Returns the total number of Unicode chars in a. 2034 2035FcCharSetIntersectCount 2036 2037Name 2038 2039 FcCharSetIntersectCount -- Intersect and count charsets 2040 2041Synopsis 2042 2043#include <fontconfig/fontconfig.h> 2044 2045 FcChar32 FcCharSetIntersectCount(const FcCharSet *a, const 2046 FcCharSet *b); 2047 2048Description 2049 2050 Returns the number of chars that are in both a and b. 2051 2052FcCharSetSubtractCount 2053 2054Name 2055 2056 FcCharSetSubtractCount -- Subtract and count charsets 2057 2058Synopsis 2059 2060#include <fontconfig/fontconfig.h> 2061 2062 FcChar32 FcCharSetSubtractCount(const FcCharSet *a, const 2063 FcCharSet *b); 2064 2065Description 2066 2067 Returns the number of chars that are in a but not in b. 2068 2069FcCharSetIsSubset 2070 2071Name 2072 2073 FcCharSetIsSubset -- Test for charset inclusion 2074 2075Synopsis 2076 2077#include <fontconfig/fontconfig.h> 2078 2079 FcBool FcCharSetIsSubset(const FcCharSet *a, const FcCharSet 2080 *b); 2081 2082Description 2083 2084 Returns whether a is a subset of b. 2085 2086FcCharSetFirstPage 2087 2088Name 2089 2090 FcCharSetFirstPage -- Start enumerating charset contents 2091 2092Synopsis 2093 2094#include <fontconfig/fontconfig.h> 2095 2096 FcChar32 FcCharSetFirstPage(const FcCharSet *a, 2097 FcChar32[FC_CHARSET_MAP_SIZE] map, FcChar32 *next); 2098 2099Description 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 21060xffffffff 0xffffffff 0x01000008 0x44300002 0xffffd7f0 0xfffffffb 0xffff 21077fff 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 2117FcCharSetNextPage 2118 2119Name 2120 2121 FcCharSetNextPage -- Continue enumerating charset contents 2122 2123Synopsis 2124 2125#include <fontconfig/fontconfig.h> 2126 2127 FcChar32 FcCharSetNextPage(const FcCharSet *a, 2128 FcChar32[FC_CHARSET_MAP_SIZE] map, FcChar32 *next); 2129 2130Description 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 2139FcCharSetCoverage 2140 2141Name 2142 2143 FcCharSetCoverage -- DEPRECATED return coverage for a Unicode 2144 page 2145 2146Synopsis 2147 2148#include <fontconfig/fontconfig.h> 2149 2150 FcChar32 FcCharSetCoverage(const FcCharSet *a, FcChar32page, 2151 FcChar32[8]result); 2152 2153Description 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 2160FcCharSetNew 2161 2162Name 2163 2164 FcCharSetNew -- DEPRECATED alias for FcCharSetCreate 2165 2166Synopsis 2167 2168#include <fontconfig/fontconfig.h> 2169 2170 FcCharSet * FcCharSetNew(void); 2171 2172Description 2173 2174 FcCharSetNew is a DEPRECATED alias for FcCharSetCreate. 2175 __________________________________________________________ 2176 2177FcLangSet 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 2205FcLangSetCreate 2206 2207Name 2208 2209 FcLangSetCreate -- create a langset object 2210 2211Synopsis 2212 2213#include <fontconfig/fontconfig.h> 2214 2215 FcLangSet * FcLangSetCreate(void); 2216 2217Description 2218 2219 FcLangSetCreate creates a new FcLangSet object. 2220 2221FcLangSetDestroy 2222 2223Name 2224 2225 FcLangSetDestroy -- destroy a langset object 2226 2227Synopsis 2228 2229#include <fontconfig/fontconfig.h> 2230 2231 void FcLangSetDestroy(FcLangSet *ls); 2232 2233Description 2234 2235 FcLangSetDestroy destroys a FcLangSet object, freeing all 2236 memory associated with it. 2237 2238FcLangSetCopy 2239 2240Name 2241 2242 FcLangSetCopy -- copy a langset object 2243 2244Synopsis 2245 2246#include <fontconfig/fontconfig.h> 2247 2248 FcLangSet * FcLangSetCopy(const FcLangSet *ls); 2249 2250Description 2251 2252 FcLangSetCopy creates a new FcLangSet object and populates it 2253 with the contents of ls. 2254 2255FcLangSetAdd 2256 2257Name 2258 2259 FcLangSetAdd -- add a language to a langset 2260 2261Synopsis 2262 2263#include <fontconfig/fontconfig.h> 2264 2265 FcBool FcLangSetAdd(FcLangSet *ls, const FcChar8 *lang); 2266 2267Description 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 2273FcLangSetDel 2274 2275Name 2276 2277 FcLangSetDel -- delete a language from a langset 2278 2279Synopsis 2280 2281#include <fontconfig/fontconfig.h> 2282 2283 FcBool FcLangSetDel(FcLangSet *ls, const FcChar8 *lang); 2284 2285Description 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 2291Since 2292 2293 version 2.9.0 2294 2295FcLangSetUnion 2296 2297Name 2298 2299 FcLangSetUnion -- Add langsets 2300 2301Synopsis 2302 2303#include <fontconfig/fontconfig.h> 2304 2305 FcLangSet * FcLangSetUnion(const FcLangSet *ls_a, const 2306 FcLangSet *ls_b); 2307 2308Description 2309 2310 Returns a set including only those languages found in either 2311 ls_a or ls_b. 2312 2313Since 2314 2315 version 2.9.0 2316 2317FcLangSetSubtract 2318 2319Name 2320 2321 FcLangSetSubtract -- Subtract langsets 2322 2323Synopsis 2324 2325#include <fontconfig/fontconfig.h> 2326 2327 FcLangSet * FcLangSetSubtract(const FcLangSet *ls_a, const 2328 FcLangSet *ls_b); 2329 2330Description 2331 2332 Returns a set including only those languages found in ls_a but 2333 not in ls_b. 2334 2335Since 2336 2337 version 2.9.0 2338 2339FcLangSetCompare 2340 2341Name 2342 2343 FcLangSetCompare -- compare language sets 2344 2345Synopsis 2346 2347#include <fontconfig/fontconfig.h> 2348 2349 FcLangResult FcLangSetCompare(const FcLangSet *ls_a, const 2350 FcLangSet *ls_b); 2351 2352Description 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 2361FcLangSetContains 2362 2363Name 2364 2365 FcLangSetContains -- check langset subset relation 2366 2367Synopsis 2368 2369#include <fontconfig/fontconfig.h> 2370 2371 FcBool FcLangSetContains(const FcLangSet *ls_a, const FcLangSet 2372 *ls_b); 2373 2374Description 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 2381FcLangSetEqual 2382 2383Name 2384 2385 FcLangSetEqual -- test for matching langsets 2386 2387Synopsis 2388 2389#include <fontconfig/fontconfig.h> 2390 2391 FcBool FcLangSetEqual(const FcLangSet *ls_a, const FcLangSet 2392 *ls_b); 2393 2394Description 2395 2396 Returns FcTrue if and only if ls_a supports precisely the same 2397 language and territory combinations as ls_b. 2398 2399FcLangSetHash 2400 2401Name 2402 2403 FcLangSetHash -- return a hash value for a langset 2404 2405Synopsis 2406 2407#include <fontconfig/fontconfig.h> 2408 2409 FcChar32 FcLangSetHash(const FcLangSet *ls); 2410 2411Description 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 2418FcLangSetHasLang 2419 2420Name 2421 2422 FcLangSetHasLang -- test langset for language support 2423 2424Synopsis 2425 2426#include <fontconfig/fontconfig.h> 2427 2428 FcLangResult FcLangSetHasLang(const FcLangSet *ls, const 2429 FcChar8 *lang); 2430 2431Description 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 2440FcGetDefaultLangs 2441 2442Name 2443 2444 FcGetDefaultLangs -- Get the default languages list 2445 2446Synopsis 2447 2448#include <fontconfig/fontconfig.h> 2449 2450 FcStrSet * FcGetDefaultLangs(void); 2451 2452Description 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 2460Since 2461 2462 version 2.9.91 2463 2464FcLangSetGetLangs 2465 2466Name 2467 2468 FcLangSetGetLangs -- get the list of languages in the langset 2469 2470Synopsis 2471 2472#include <fontconfig/fontconfig.h> 2473 2474 FcStrSet * FcLangSetGetLangs(const FcLangSet *ls); 2475 2476Description 2477 2478 Returns a string set of all languages in langset. 2479 2480FcGetLangs 2481 2482Name 2483 2484 FcGetLangs -- Get list of languages 2485 2486Synopsis 2487 2488#include <fontconfig/fontconfig.h> 2489 2490 FcStrSet * FcGetLangs(void); 2491 2492Description 2493 2494 Returns a string set of all known languages. 2495 2496FcLangNormalize 2497 2498Name 2499 2500 FcLangNormalize -- Normalize the language string 2501 2502Synopsis 2503 2504#include <fontconfig/fontconfig.h> 2505 2506 FcChar8 * FcLangNormalize(const FcChar8 *lang); 2507 2508Description 2509 2510 Returns a string to make lang suitable on fontconfig. 2511 2512Since 2513 2514 version 2.10.91 2515 2516FcLangGetCharSet 2517 2518Name 2519 2520 FcLangGetCharSet -- Get character map for a language 2521 2522Synopsis 2523 2524#include <fontconfig/fontconfig.h> 2525 2526 const FcCharSet * FcLangGetCharSet(const FcChar8 *lang); 2527 2528Description 2529 2530 Returns the FcCharMap for a language. 2531 __________________________________________________________ 2532 2533FcMatrix 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 2547FcMatrixInit 2548 2549Name 2550 2551 FcMatrixInit -- initialize an FcMatrix structure 2552 2553Synopsis 2554 2555#include <fontconfig/fontconfig.h> 2556 2557 void FcMatrixInit(FcMatrix *matrix); 2558 2559Description 2560 2561 FcMatrixInit initializes matrix to the identity matrix. 2562 2563FcMatrixCopy 2564 2565Name 2566 2567 FcMatrixCopy -- Copy a matrix 2568 2569Synopsis 2570 2571#include <fontconfig/fontconfig.h> 2572 2573 void FcMatrixCopy(const FcMatrix *matrix); 2574 2575Description 2576 2577 FcMatrixCopy allocates a new FcMatrix and copies mat into it. 2578 2579FcMatrixEqual 2580 2581Name 2582 2583 FcMatrixEqual -- Compare two matrices 2584 2585Synopsis 2586 2587#include <fontconfig/fontconfig.h> 2588 2589 void FcMatrixEqual(const FcMatrix *matrix1, const FcMatrix 2590 *matrix2); 2591 2592Description 2593 2594 FcMatrixEqual compares matrix1 and matrix2 returning FcTrue 2595 when they are equal and FcFalse when they are not. 2596 2597FcMatrixMultiply 2598 2599Name 2600 2601 FcMatrixMultiply -- Multiply matrices 2602 2603Synopsis 2604 2605#include <fontconfig/fontconfig.h> 2606 2607 void FcMatrixMultiply(FcMatrix *result, const FcMatrix 2608 *matrix1, const FcMatrix *matrix2); 2609 2610Description 2611 2612 FcMatrixMultiply multiplies matrix1 and matrix2 storing the 2613 result in result. 2614 2615FcMatrixRotate 2616 2617Name 2618 2619 FcMatrixRotate -- Rotate a matrix 2620 2621Synopsis 2622 2623#include <fontconfig/fontconfig.h> 2624 2625 void FcMatrixRotate(FcMatrix *matrix, double cos, double sin); 2626 2627Description 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 2634FcMatrixScale 2635 2636Name 2637 2638 FcMatrixScale -- Scale a matrix 2639 2640Synopsis 2641 2642#include <fontconfig/fontconfig.h> 2643 2644 void FcMatrixScale(FcMatrix *matrix, double sx, double dy); 2645 2646Description 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 2653FcMatrixShear 2654 2655Name 2656 2657 FcMatrixShear -- Shear a matrix 2658 2659Synopsis 2660 2661#include <fontconfig/fontconfig.h> 2662 2663 void FcMatrixShear(FcMatrix *matrix, double sh, double sv); 2664 2665Description 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 2673FcRange 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 2684FcRangeCopy 2685 2686Name 2687 2688 FcRangeCopy -- Copy a range object 2689 2690Synopsis 2691 2692#include <fontconfig/fontconfig.h> 2693 2694 FcRange * FcRangeCopy(const FcRange *range); 2695 2696Description 2697 2698 FcRangeCopy creates a new FcRange object and populates it with 2699 the contents of range. 2700 2701Since 2702 2703 version 2.11.91 2704 2705FcRangeCreateDouble 2706 2707Name 2708 2709 FcRangeCreateDouble -- create a range object for double 2710 2711Synopsis 2712 2713#include <fontconfig/fontconfig.h> 2714 2715 FcRange * FcRangeCreateDouble(doublebegin, doubleend); 2716 2717Description 2718 2719 FcRangeCreateDouble creates a new FcRange object with double 2720 sized value. 2721 2722Since 2723 2724 version 2.11.91 2725 2726FcRangeCreateInteger 2727 2728Name 2729 2730 FcRangeCreateInteger -- create a range object for integer 2731 2732Synopsis 2733 2734#include <fontconfig/fontconfig.h> 2735 2736 FcRange * FcRangeCreateInteger(intbegin, intend); 2737 2738Description 2739 2740 FcRangeCreateInteger creates a new FcRange object with integer 2741 sized value. 2742 2743Since 2744 2745 version 2.11.91 2746 2747FcRangeDestroy 2748 2749Name 2750 2751 FcRangeDestroy -- destroy a range object 2752 2753Synopsis 2754 2755#include <fontconfig/fontconfig.h> 2756 2757 void FcRangeDestroy(FcRange *range); 2758 2759Description 2760 2761 FcRangeDestroy destroys a FcRange object, freeing all memory 2762 associated with it. 2763 2764Since 2765 2766 version 2.11.91 2767 2768FcRangeGetDouble 2769 2770Name 2771 2772 FcRangeGetDouble -- Get the range in double 2773 2774Synopsis 2775 2776#include <fontconfig/fontconfig.h> 2777 2778 FcBool FcRangeGetDouble(const FcRange *range, double *begin, 2779 double *end); 2780 2781Description 2782 2783 Returns in begin and end as the range. 2784 2785Since 2786 2787 version 2.11.91 2788 __________________________________________________________ 2789 2790FcConfig 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 2836FcConfigCreate 2837 2838Name 2839 2840 FcConfigCreate -- Create a configuration 2841 2842Synopsis 2843 2844#include <fontconfig/fontconfig.h> 2845 2846 FcConfig * FcConfigCreate(void); 2847 2848Description 2849 2850 Creates an empty configuration. 2851 2852FcConfigReference 2853 2854Name 2855 2856 FcConfigReference -- Increment config reference count 2857 2858Synopsis 2859 2860#include <fontconfig/fontconfig.h> 2861 2862 FcConfig * FcConfigReference(FcConfig *config); 2863 2864Description 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 2874FcConfigDestroy 2875 2876Name 2877 2878 FcConfigDestroy -- Destroy a configuration 2879 2880Synopsis 2881 2882#include <fontconfig/fontconfig.h> 2883 2884 void FcConfigDestroy(FcConfig *config); 2885 2886Description 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 2894FcConfigSetCurrent 2895 2896Name 2897 2898 FcConfigSetCurrent -- Set configuration as default 2899 2900Synopsis 2901 2902#include <fontconfig/fontconfig.h> 2903 2904 FcBool FcConfigSetCurrent(FcConfig *config); 2905 2906Description 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 2913FcConfigGetCurrent 2914 2915Name 2916 2917 FcConfigGetCurrent -- Return current configuration 2918 2919Synopsis 2920 2921#include <fontconfig/fontconfig.h> 2922 2923 FcConfig * FcConfigGetCurrent(void); 2924 2925Description 2926 2927 Returns the current default configuration. 2928 2929FcConfigUptoDate 2930 2931Name 2932 2933 FcConfigUptoDate -- Check timestamps on config files 2934 2935Synopsis 2936 2937#include <fontconfig/fontconfig.h> 2938 2939 FcBool FcConfigUptoDate(FcConfig *config); 2940 2941Description 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 2947FcConfigHome 2948 2949Name 2950 2951 FcConfigHome -- return the current home directory. 2952 2953Synopsis 2954 2955#include <fontconfig/fontconfig.h> 2956 2957 FcChar8 * FcConfigHome(void); 2958 2959Description 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 2965FcConfigEnableHome 2966 2967Name 2968 2969 FcConfigEnableHome -- controls use of the home directory. 2970 2971Synopsis 2972 2973#include <fontconfig/fontconfig.h> 2974 2975 FcBool FcConfigEnableHome(FcBool enable); 2976 2977Description 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 2986FcConfigBuildFonts 2987 2988Name 2989 2990 FcConfigBuildFonts -- Build font database 2991 2992Synopsis 2993 2994#include <fontconfig/fontconfig.h> 2995 2996 FcBool FcConfigBuildFonts(FcConfig *config); 2997 2998Description 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 3006FcConfigGetConfigDirs 3007 3008Name 3009 3010 FcConfigGetConfigDirs -- Get config directories 3011 3012Synopsis 3013 3014#include <fontconfig/fontconfig.h> 3015 3016 FcStrList * FcConfigGetConfigDirs(FcConfig *config); 3017 3018Description 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 3025FcConfigGetFontDirs 3026 3027Name 3028 3029 FcConfigGetFontDirs -- Get font directories 3030 3031Synopsis 3032 3033#include <fontconfig/fontconfig.h> 3034 3035 FcStrList * FcConfigGetFontDirs(FcConfig *config); 3036 3037Description 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 3044FcConfigGetConfigFiles 3045 3046Name 3047 3048 FcConfigGetConfigFiles -- Get config files 3049 3050Synopsis 3051 3052#include <fontconfig/fontconfig.h> 3053 3054 FcStrList * FcConfigGetConfigFiles(FcConfig *config); 3055 3056Description 3057 3058 Returns the list of known configuration files used to generate 3059 config. If config is NULL, the current configuration is used. 3060 3061FcConfigGetCache 3062 3063Name 3064 3065 FcConfigGetCache -- DEPRECATED used to return per-user cache 3066 filename 3067 3068Synopsis 3069 3070#include <fontconfig/fontconfig.h> 3071 3072 FcChar8 * FcConfigGetCache(FcConfig *config); 3073 3074Description 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 3080FcConfigGetCacheDirs 3081 3082Name 3083 3084 FcConfigGetCacheDirs -- return the list of directories searched 3085 for cache files 3086 3087Synopsis 3088 3089#include <fontconfig/fontconfig.h> 3090 3091 FcStrList * FcConfigGetCacheDirs(const FcConfig *config); 3092 3093Description 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 3100FcConfigGetFonts 3101 3102Name 3103 3104 FcConfigGetFonts -- Get config font set 3105 3106Synopsis 3107 3108#include <fontconfig/fontconfig.h> 3109 3110 FcFontSet * FcConfigGetFonts(FcConfig *config, FcSetName set); 3111 3112Description 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 3119FcConfigGetBlanks 3120 3121Name 3122 3123 FcConfigGetBlanks -- Get config blanks 3124 3125Synopsis 3126 3127#include <fontconfig/fontconfig.h> 3128 3129 FcBlanks * FcConfigGetBlanks(FcConfig *config); 3130 3131Description 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 3139FcConfigGetRescanInterval 3140 3141Name 3142 3143 FcConfigGetRescanInterval -- Get config rescan interval 3144 3145Synopsis 3146 3147#include <fontconfig/fontconfig.h> 3148 3149 int FcConfigGetRescanInterval(FcConfig *config); 3150 3151Description 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 3160FcConfigSetRescanInterval 3161 3162Name 3163 3164 FcConfigSetRescanInterval -- Set config rescan interval 3165 3166Synopsis 3167 3168#include <fontconfig/fontconfig.h> 3169 3170 FcBool FcConfigSetRescanInterval(FcConfig *config, int 3171 rescanInterval); 3172 3173Description 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 3180FcConfigAppFontAddFile 3181 3182Name 3183 3184 FcConfigAppFontAddFile -- Add font file to font database 3185 3186Synopsis 3187 3188#include <fontconfig/fontconfig.h> 3189 3190 FcBool FcConfigAppFontAddFile(FcConfig *config, const FcChar8 3191 *file); 3192 3193Description 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 3200FcConfigAppFontAddDir 3201 3202Name 3203 3204 FcConfigAppFontAddDir -- Add fonts from directory to font 3205 database 3206 3207Synopsis 3208 3209#include <fontconfig/fontconfig.h> 3210 3211 FcBool FcConfigAppFontAddDir(FcConfig *config, const FcChar8 3212 *dir); 3213 3214Description 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 3222FcConfigAppFontClear 3223 3224Name 3225 3226 FcConfigAppFontClear -- Remove all app fonts from font database 3227 3228Synopsis 3229 3230#include <fontconfig/fontconfig.h> 3231 3232 void FcConfigAppFontClear(FcConfig *config); 3233 3234Description 3235 3236 Clears the set of application-specific fonts. If config is 3237 NULL, the current configuration is used. 3238 3239FcConfigSubstituteWithPat 3240 3241Name 3242 3243 FcConfigSubstituteWithPat -- Execute substitutions 3244 3245Synopsis 3246 3247#include <fontconfig/fontconfig.h> 3248 3249 FcBool FcConfigSubstituteWithPat(FcConfig *config, FcPattern 3250 *p, FcPattern *p_pat, FcMatchKind kind); 3251 3252Description 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 3262FcConfigSubstitute 3263 3264Name 3265 3266 FcConfigSubstitute -- Execute substitutions 3267 3268Synopsis 3269 3270#include <fontconfig/fontconfig.h> 3271 3272 FcBool FcConfigSubstitute(FcConfig *config, FcPattern *p, 3273 FcMatchKind kind); 3274 3275Description 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 3282FcFontMatch 3283 3284Name 3285 3286 FcFontMatch -- Return best font 3287 3288Synopsis 3289 3290#include <fontconfig/fontconfig.h> 3291 3292 FcPattern * FcFontMatch(FcConfig *config, FcPattern *p, 3293 FcResult *result); 3294 3295Description 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 3304FcFontSort 3305 3306Name 3307 3308 FcFontSort -- Return list of matching fonts 3309 3310Synopsis 3311 3312#include <fontconfig/fontconfig.h> 3313 3314 FcFontSet * FcFontSort(FcConfig *config, FcPattern *p, FcBool 3315 trim, FcCharSet **csp, FcResult *result); 3316 3317Description 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 3338FcFontRenderPrepare 3339 3340Name 3341 3342 FcFontRenderPrepare -- Prepare pattern for loading font file 3343 3344Synopsis 3345 3346#include <fontconfig/fontconfig.h> 3347 3348 FcPattern * FcFontRenderPrepare(FcConfig *config, FcPattern 3349 *pat, FcPattern *font); 3350 3351Description 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 3359FcFontList 3360 3361Name 3362 3363 FcFontList -- List fonts 3364 3365Synopsis 3366 3367#include <fontconfig/fontconfig.h> 3368 3369 FcFontSet * FcFontList(FcConfig *config, FcPattern *p, 3370 FcObjectSet *os); 3371 3372Description 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 3379FcConfigFilename 3380 3381Name 3382 3383 FcConfigFilename -- Find a config file 3384 3385Synopsis 3386 3387#include <fontconfig/fontconfig.h> 3388 3389 FcChar8 * FcConfigFilename(const FcChar8 *name); 3390 3391Description 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 3406FcConfigParseAndLoad 3407 3408Name 3409 3410 FcConfigParseAndLoad -- load a configuration file 3411 3412Synopsis 3413 3414#include <fontconfig/fontconfig.h> 3415 3416 FcBool FcConfigParseAndLoad(FcConfig *config, const FcChar8 3417 *file, FcBool complain); 3418 3419Description 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 3430FcConfigGetSysRoot 3431 3432Name 3433 3434 FcConfigGetSysRoot -- Obtain the system root directory 3435 3436Synopsis 3437 3438#include <fontconfig/fontconfig.h> 3439 3440 const FcChar8 * FcConfigGetSysRoot(const FcConfig *config); 3441 3442Description 3443 3444 Obtrains the system root directory in 'config' if available. 3445 3446Since 3447 3448 version 2.10.92 3449 3450FcConfigSetSysRoot 3451 3452Name 3453 3454 FcConfigSetSysRoot -- Set the system root directory 3455 3456Synopsis 3457 3458#include <fontconfig/fontconfig.h> 3459 3460 void FcConfigSetSysRoot(FcConfig *config, const FcChar8 3461 *sysroot); 3462 3463Description 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 3471Since 3472 3473 version 2.10.92 3474 __________________________________________________________ 3475 3476FcObjectType 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 3486FcNameRegisterObjectTypes 3487 3488Name 3489 3490 FcNameRegisterObjectTypes -- Register object types 3491 3492Synopsis 3493 3494#include <fontconfig/fontconfig.h> 3495 3496 FcBool FcNameRegisterObjectTypes(const FcObjectType *types, int 3497 ntype); 3498 3499Description 3500 3501 Deprecated. Does nothing. Returns FcFalse. 3502 3503FcNameUnregisterObjectTypes 3504 3505Name 3506 3507 FcNameUnregisterObjectTypes -- Unregister object types 3508 3509Synopsis 3510 3511#include <fontconfig/fontconfig.h> 3512 3513 FcBool FcNameUnregisterObjectTypes(const FcObjectType *types, 3514 int ntype); 3515 3516Description 3517 3518 Deprecated. Does nothing. Returns FcFalse. 3519 3520FcNameGetObjectType 3521 3522Name 3523 3524 FcNameGetObjectType -- Lookup an object type 3525 3526Synopsis 3527 3528#include <fontconfig/fontconfig.h> 3529 3530 const FcObjectType * FcNameGetObjectType(const char *object); 3531 3532Description 3533 3534 Return the object type for the pattern element named object. 3535 __________________________________________________________ 3536 3537FcConstant 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 3548FcNameRegisterConstants 3549 3550Name 3551 3552 FcNameRegisterConstants -- Register symbolic constants 3553 3554Synopsis 3555 3556#include <fontconfig/fontconfig.h> 3557 3558 FcBool FcNameRegisterConstants(const FcConstant *consts, int 3559 nconsts); 3560 3561Description 3562 3563 Deprecated. Does nothing. Returns FcFalse. 3564 3565FcNameUnregisterConstants 3566 3567Name 3568 3569 FcNameUnregisterConstants -- Unregister symbolic constants 3570 3571Synopsis 3572 3573#include <fontconfig/fontconfig.h> 3574 3575 FcBool FcNameUnregisterConstants(const FcConstant *consts, int 3576 nconsts); 3577 3578Description 3579 3580 Deprecated. Does nothing. Returns FcFalse. 3581 3582FcNameGetConstant 3583 3584Name 3585 3586 FcNameGetConstant -- Lookup symbolic constant 3587 3588Synopsis 3589 3590#include <fontconfig/fontconfig.h> 3591 3592 const FcConstant * FcNameGetConstant(FcChar8 *string); 3593 3594Description 3595 3596 Return the FcConstant structure related to symbolic constant 3597 string. 3598 3599FcNameConstant 3600 3601Name 3602 3603 FcNameConstant -- Get the value for a symbolic constant 3604 3605Synopsis 3606 3607#include <fontconfig/fontconfig.h> 3608 3609 FcBool FcNameConstant(FcChar8 *string, int *result); 3610 3611Description 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 3618FcWeight 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 3629FcWeightFromOpenType 3630 3631Name 3632 3633 FcWeightFromOpenType -- Convert from OpenType weight values to 3634 fontconfig ones 3635 3636Synopsis 3637 3638#include <fontconfig/fontconfig.h> 3639 3640 int FcWeightFromOpenType(intot_weight); 3641 3642Description 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 3653Since 3654 3655 version 2.11.91 3656 3657FcWeightToOpenType 3658 3659Name 3660 3661 FcWeightToOpenType -- Convert from fontconfig weight values to 3662 OpenType ones 3663 3664Synopsis 3665 3666#include <fontconfig/fontconfig.h> 3667 3668 int FcWeightToOpenType(intot_weight); 3669 3670Description 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 3677Since 3678 3679 version 2.11.91 3680 __________________________________________________________ 3681 3682FcBlanks 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 3697FcBlanksCreate 3698 3699Name 3700 3701 FcBlanksCreate -- Create an FcBlanks 3702 3703Synopsis 3704 3705#include <fontconfig/fontconfig.h> 3706 3707 FcBlanks * FcBlanksCreate(void); 3708 3709Description 3710 3711 Creates an empty FcBlanks object. 3712 3713FcBlanksDestroy 3714 3715Name 3716 3717 FcBlanksDestroy -- Destroy and FcBlanks 3718 3719Synopsis 3720 3721#include <fontconfig/fontconfig.h> 3722 3723 void FcBlanksDestroy(FcBlanks *b); 3724 3725Description 3726 3727 Destroys an FcBlanks object, freeing any associated memory. 3728 3729FcBlanksAdd 3730 3731Name 3732 3733 FcBlanksAdd -- Add a character to an FcBlanks 3734 3735Synopsis 3736 3737#include <fontconfig/fontconfig.h> 3738 3739 FcBool FcBlanksAdd(FcBlanks *b, FcChar32 ucs4); 3740 3741Description 3742 3743 Adds a single character to an FcBlanks object, returning 3744 FcFalse if this process ran out of memory. 3745 3746FcBlanksIsMember 3747 3748Name 3749 3750 FcBlanksIsMember -- Query membership in an FcBlanks 3751 3752Synopsis 3753 3754#include <fontconfig/fontconfig.h> 3755 3756 FcBool FcBlanksIsMember(FcBlanks *b, FcChar32 ucs4); 3757 3758Description 3759 3760 Returns whether the specified FcBlanks object contains the 3761 indicated Unicode value. 3762 __________________________________________________________ 3763 3764FcAtomic 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 3781FcAtomicCreate 3782 3783Name 3784 3785 FcAtomicCreate -- create an FcAtomic object 3786 3787Synopsis 3788 3789#include <fontconfig/fontconfig.h> 3790 3791 FcAtomic * FcAtomicCreate(const FcChar8 *file); 3792 3793Description 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 3801FcAtomicLock 3802 3803Name 3804 3805 FcAtomicLock -- lock a file 3806 3807Synopsis 3808 3809#include <fontconfig/fontconfig.h> 3810 3811 FcBool FcAtomicLock(FcAtomic *atomic); 3812 3813Description 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 3819FcAtomicNewFile 3820 3821Name 3822 3823 FcAtomicNewFile -- return new temporary file name 3824 3825Synopsis 3826 3827#include <fontconfig/fontconfig.h> 3828 3829 FcChar8 * FcAtomicNewFile(FcAtomic *atomic); 3830 3831Description 3832 3833 Returns the filename for writing a new version of the file 3834 referenced by atomic. 3835 3836FcAtomicOrigFile 3837 3838Name 3839 3840 FcAtomicOrigFile -- return original file name 3841 3842Synopsis 3843 3844#include <fontconfig/fontconfig.h> 3845 3846 FcChar8 * FcAtomicOrigFile(FcAtomic *atomic); 3847 3848Description 3849 3850 Returns the file referenced by atomic. 3851 3852FcAtomicReplaceOrig 3853 3854Name 3855 3856 FcAtomicReplaceOrig -- replace original with new 3857 3858Synopsis 3859 3860#include <fontconfig/fontconfig.h> 3861 3862 FcBool FcAtomicReplaceOrig(FcAtomic *atomic); 3863 3864Description 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 3870FcAtomicDeleteNew 3871 3872Name 3873 3874 FcAtomicDeleteNew -- delete new file 3875 3876Synopsis 3877 3878#include <fontconfig/fontconfig.h> 3879 3880 void FcAtomicDeleteNew(FcAtomic *atomic); 3881 3882Description 3883 3884 Deletes the new file. Used in error recovery to back out 3885 changes. 3886 3887FcAtomicUnlock 3888 3889Name 3890 3891 FcAtomicUnlock -- unlock a file 3892 3893Synopsis 3894 3895#include <fontconfig/fontconfig.h> 3896 3897 void FcAtomicUnlock(FcAtomic *atomic); 3898 3899Description 3900 3901 Unlocks the file. 3902 3903FcAtomicDestroy 3904 3905Name 3906 3907 FcAtomicDestroy -- destroy an FcAtomic object 3908 3909Synopsis 3910 3911#include <fontconfig/fontconfig.h> 3912 3913 void FcAtomicDestroy(FcAtomic *atomic); 3914 3915Description 3916 3917 Destroys atomic. 3918 __________________________________________________________ 3919 3920File 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 3940FcFileScan 3941 3942Name 3943 3944 FcFileScan -- scan a font file 3945 3946Synopsis 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 3953Description 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 3968FcFileIsDir 3969 3970Name 3971 3972 FcFileIsDir -- check whether a file is a directory 3973 3974Synopsis 3975 3976#include <fontconfig/fontconfig.h> 3977 3978 FcBool FcFileIsDir(const FcChar8 *file); 3979 3980Description 3981 3982 Returns FcTrue if file is a directory, otherwise returns 3983 FcFalse. 3984 3985FcDirScan 3986 3987Name 3988 3989 FcDirScan -- scan a font directory without caching it 3990 3991Synopsis 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 3998Description 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 4006FcDirSave 4007 4008Name 4009 4010 FcDirSave -- DEPRECATED: formerly used to save a directory 4011 cache 4012 4013Synopsis 4014 4015#include <fontconfig/fontconfig.h> 4016 4017 FcBool FcDirSave(FcFontSet *set, FcStrSet *dirs, const FcChar8 4018 *dir); 4019 4020Description 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 4028FcDirCacheUnlink 4029 4030Name 4031 4032 FcDirCacheUnlink -- Remove all caches related to dir 4033 4034Synopsis 4035 4036#include <fontconfig/fontconfig.h> 4037 4038 FcBool FcDirCacheUnlink(const FcChar8 *dir, FcConfig *config); 4039 4040Description 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 4047FcDirCacheValid 4048 4049Name 4050 4051 FcDirCacheValid -- check directory cache 4052 4053Synopsis 4054 4055#include <fontconfig/fontconfig.h> 4056 4057 FcBool FcDirCacheValid(const FcChar8 *dir); 4058 4059Description 4060 4061 Returns FcTrue if dir has an associated valid cache file, else 4062 returns FcFalse 4063 4064FcDirCacheLoad 4065 4066Name 4067 4068 FcDirCacheLoad -- load a directory cache 4069 4070Synopsis 4071 4072#include <fontconfig/fontconfig.h> 4073 4074 FcCache * FcDirCacheLoad(const FcChar8 *dir, FcConfig *config, 4075 FcChar8 **cache_file); 4076 4077Description 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 4083FcDirCacheRescan 4084 4085Name 4086 4087 FcDirCacheRescan -- Re-scan a directory cache 4088 4089Synopsis 4090 4091#include <fontconfig/fontconfig.h> 4092 4093 FcCache * FcDirCacheRescan(const FcChar8 *dir, FcConfig 4094 *config); 4095 4096Description 4097 4098 Re-scan directories only at dir and update the cache. returns 4099 NULL if failed. 4100 4101Since 4102 4103 version 2.11.1 4104 4105FcDirCacheRead 4106 4107Name 4108 4109 FcDirCacheRead -- read or construct a directory cache 4110 4111Synopsis 4112 4113#include <fontconfig/fontconfig.h> 4114 4115 FcCache * FcDirCacheRead(const FcChar8 *dir, FcBool force, 4116 FcConfig *config); 4117 4118Description 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 4124FcDirCacheLoadFile 4125 4126Name 4127 4128 FcDirCacheLoadFile -- load a cache file 4129 4130Synopsis 4131 4132#include <fontconfig/fontconfig.h> 4133 4134 FcCache * FcDirCacheLoadFile(const FcChar8 *cache_file, struct 4135 stat *file_stat); 4136 4137Description 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 4143FcDirCacheUnload 4144 4145Name 4146 4147 FcDirCacheUnload -- unload a cache file 4148 4149Synopsis 4150 4151#include <fontconfig/fontconfig.h> 4152 4153 void FcDirCacheUnload(FcCache *cache); 4154 4155Description 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 4161FcCache 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 4181FcCacheDir 4182 4183Name 4184 4185 FcCacheDir -- Return directory of cache 4186 4187Synopsis 4188 4189#include <fontconfig/fontconfig.h> 4190 4191 const FcChar8 * FcCacheDir(const FcCache *cache); 4192 4193Description 4194 4195 This function returns the directory from which the cache was 4196 constructed. 4197 4198FcCacheCopySet 4199 4200Name 4201 4202 FcCacheCopySet -- Returns a copy of the fontset from cache 4203 4204Synopsis 4205 4206#include <fontconfig/fontconfig.h> 4207 4208 FcFontSet * FcCacheCopySet(const FcCache *cache); 4209 4210Description 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 4216FcCacheSubdir 4217 4218Name 4219 4220 FcCacheSubdir -- Return the i'th subdirectory. 4221 4222Synopsis 4223 4224#include <fontconfig/fontconfig.h> 4225 4226 const FcChar8 * FcCacheSubdir(const FcCache *cache, inti); 4227 4228Description 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 4234FcCacheNumSubdir 4235 4236Name 4237 4238 FcCacheNumSubdir -- Return the number of subdirectories in 4239 cache. 4240 4241Synopsis 4242 4243#include <fontconfig/fontconfig.h> 4244 4245 int FcCacheNumSubdir(const FcCache *cache); 4246 4247Description 4248 4249 This returns the total number of subdirectories in the cache. 4250 4251FcCacheNumFont 4252 4253Name 4254 4255 FcCacheNumFont -- Returns the number of fonts in cache. 4256 4257Synopsis 4258 4259#include <fontconfig/fontconfig.h> 4260 4261 int FcCacheNumFont(const FcCache *cache); 4262 4263Description 4264 4265 This returns the number of fonts which would be included in the 4266 return from FcCacheCopySet. 4267 4268FcDirCacheClean 4269 4270Name 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 4276Synopsis 4277 4278#include <fontconfig/fontconfig.h> 4279 4280 FcBool FcDirCacheClean(const FcChar8 *cache_dir, 4281 FcBoolverbose); 4282 4283Description 4284 4285Since 4286 4287 version 2.9.91 4288 4289FcCacheCreateTagFile 4290 4291Name 4292 4293 FcCacheCreateTagFile -- Create CACHEDIR.TAG at cache directory. 4294 4295Synopsis 4296 4297#include <fontconfig/fontconfig.h> 4298 4299 void FcCacheCreateTagFile(const FcConfig *config); 4300 4301Description 4302 4303 This tries to create CACHEDIR.TAG file at the cache directory 4304 registered to config. 4305 4306Since 4307 4308 version 2.9.91 4309 __________________________________________________________ 4310 4311FcStrSet 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 4330FcStrSetCreate 4331 4332Name 4333 4334 FcStrSetCreate -- create a string set 4335 4336Synopsis 4337 4338#include <fontconfig/fontconfig.h> 4339 4340 FcStrSet * FcStrSetCreate(void); 4341 4342Description 4343 4344 Create an empty set. 4345 4346FcStrSetMember 4347 4348Name 4349 4350 FcStrSetMember -- check set for membership 4351 4352Synopsis 4353 4354#include <fontconfig/fontconfig.h> 4355 4356 FcBool FcStrSetMember(FcStrSet *set, const FcChar8 *s); 4357 4358Description 4359 4360 Returns whether s is a member of set. 4361 4362FcStrSetEqual 4363 4364Name 4365 4366 FcStrSetEqual -- check sets for equality 4367 4368Synopsis 4369 4370#include <fontconfig/fontconfig.h> 4371 4372 FcBool FcStrSetEqual(FcStrSet *set_a, FcStrSet *set_b); 4373 4374Description 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 4380FcStrSetAdd 4381 4382Name 4383 4384 FcStrSetAdd -- add to a string set 4385 4386Synopsis 4387 4388#include <fontconfig/fontconfig.h> 4389 4390 FcBool FcStrSetAdd(FcStrSet *set, const FcChar8 *s); 4391 4392Description 4393 4394 Adds a copy of s to set. 4395 4396FcStrSetAddFilename 4397 4398Name 4399 4400 FcStrSetAddFilename -- add a filename to a string set 4401 4402Synopsis 4403 4404#include <fontconfig/fontconfig.h> 4405 4406 FcBool FcStrSetAddFilename(FcStrSet *set, const FcChar8 *s); 4407 4408Description 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 4414FcStrSetDel 4415 4416Name 4417 4418 FcStrSetDel -- delete from a string set 4419 4420Synopsis 4421 4422#include <fontconfig/fontconfig.h> 4423 4424 FcBool FcStrSetDel(FcStrSet *set, const FcChar8 *s); 4425 4426Description 4427 4428 Removes s from set, returning FcTrue if s was a member else 4429 FcFalse. 4430 4431FcStrSetDestroy 4432 4433Name 4434 4435 FcStrSetDestroy -- destroy a string set 4436 4437Synopsis 4438 4439#include <fontconfig/fontconfig.h> 4440 4441 void FcStrSetDestroy(FcStrSet *set); 4442 4443Description 4444 4445 Destroys set. 4446 4447FcStrListCreate 4448 4449Name 4450 4451 FcStrListCreate -- create a string iterator 4452 4453Synopsis 4454 4455#include <fontconfig/fontconfig.h> 4456 4457 FcStrList * FcStrListCreate(FcStrSet *set); 4458 4459Description 4460 4461 Creates an iterator to list the strings in set. 4462 4463FcStrListFirst 4464 4465Name 4466 4467 FcStrListFirst -- get first string in iteration 4468 4469Synopsis 4470 4471#include <fontconfig/fontconfig.h> 4472 4473 void FcStrListFirst(FcStrList *list); 4474 4475Description 4476 4477 Returns the first string in list. 4478 4479Since 4480 4481 version 2.11.0 4482 4483FcStrListNext 4484 4485Name 4486 4487 FcStrListNext -- get next string in iteration 4488 4489Synopsis 4490 4491#include <fontconfig/fontconfig.h> 4492 4493 FcChar8 * FcStrListNext(FcStrList *list); 4494 4495Description 4496 4497 Returns the next string in list. 4498 4499FcStrListDone 4500 4501Name 4502 4503 FcStrListDone -- destroy a string iterator 4504 4505Synopsis 4506 4507#include <fontconfig/fontconfig.h> 4508 4509 void FcStrListDone(FcStrList *list); 4510 4511Description 4512 4513 Destroys the enumerator list. 4514 __________________________________________________________ 4515 4516String 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 4545FcUtf8ToUcs4 4546 4547Name 4548 4549 FcUtf8ToUcs4 -- convert UTF-8 to UCS4 4550 4551Synopsis 4552 4553#include <fontconfig/fontconfig.h> 4554 4555 int FcUtf8ToUcs4(FcChar8 *src, FcChar32 *dst, int len); 4556 4557Description 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 4563FcUcs4ToUtf8 4564 4565Name 4566 4567 FcUcs4ToUtf8 -- convert UCS4 to UTF-8 4568 4569Synopsis 4570 4571#include <fontconfig/fontconfig.h> 4572 4573 int FcUcs4ToUtf8(FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN]); 4574 4575Description 4576 4577 Converts the Unicode char from src into dst and returns the 4578 number of bytes needed to encode the char. 4579 4580FcUtf8Len 4581 4582Name 4583 4584 FcUtf8Len -- count UTF-8 encoded chars 4585 4586Synopsis 4587 4588#include <fontconfig/fontconfig.h> 4589 4590 FcBool FcUtf8Len(FcChar8 *src, int len, int *nchar, int 4591 *wchar); 4592 4593Description 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 4601FcUtf16ToUcs4 4602 4603Name 4604 4605 FcUtf16ToUcs4 -- convert UTF-16 to UCS4 4606 4607Synopsis 4608 4609#include <fontconfig/fontconfig.h> 4610 4611 int FcUtf16ToUcs4(FcChar8 *src, FcEndian endian, FcChar32 *dst, 4612 int len); 4613 4614Description 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 4621FcUtf16Len 4622 4623Name 4624 4625 FcUtf16Len -- count UTF-16 encoded chars 4626 4627Synopsis 4628 4629#include <fontconfig/fontconfig.h> 4630 4631 FcBool FcUtf16Len(FcChar8 *src, FcEndian endian, int len, int 4632 *nchar, int *wchar); 4633 4634Description 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 4643FcIsLower 4644 4645Name 4646 4647 FcIsLower -- check for lower case ASCII character 4648 4649Synopsis 4650 4651#include <fontconfig/fontconfig.h> 4652 4653 FcBool FcIsLower(FcChar8c); 4654 4655Description 4656 4657 This macro checks whether c is an lower case ASCII letter. 4658 4659FcIsUpper 4660 4661Name 4662 4663 FcIsUpper -- check for upper case ASCII character 4664 4665Synopsis 4666 4667#include <fontconfig/fontconfig.h> 4668 4669 FcBool FcIsUpper(FcChar8c); 4670 4671Description 4672 4673 This macro checks whether c is a upper case ASCII letter. 4674 4675FcToLower 4676 4677Name 4678 4679 FcToLower -- convert upper case ASCII to lower case 4680 4681Synopsis 4682 4683#include <fontconfig/fontconfig.h> 4684 4685 FcChar8 FcToLower(FcChar8c); 4686 4687Description 4688 4689 This macro converts upper case ASCII c to the equivalent lower 4690 case letter. 4691 4692FcStrCopy 4693 4694Name 4695 4696 FcStrCopy -- duplicate a string 4697 4698Synopsis 4699 4700#include <fontconfig/fontconfig.h> 4701 4702 FcChar8 * FcStrCopy(const FcChar8 *s); 4703 4704Description 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 4710FcStrDowncase 4711 4712Name 4713 4714 FcStrDowncase -- create a lower case translation of a string 4715 4716Synopsis 4717 4718#include <fontconfig/fontconfig.h> 4719 4720 FcChar8 * FcStrDowncase(const FcChar8 *s); 4721 4722Description 4723 4724 Allocates memory, copies s, converting upper case letters to 4725 lower case and returns the allocated buffer. 4726 4727FcStrCopyFilename 4728 4729Name 4730 4731 FcStrCopyFilename -- create a complete path from a filename 4732 4733Synopsis 4734 4735#include <fontconfig/fontconfig.h> 4736 4737 FcChar8 * FcStrCopyFilename(const FcChar8 *s); 4738 4739Description 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 4751FcStrCmp 4752 4753Name 4754 4755 FcStrCmp -- compare UTF-8 strings 4756 4757Synopsis 4758 4759#include <fontconfig/fontconfig.h> 4760 4761 int FcStrCmp(const FcChar8 *s1, const FcChar8 *s2); 4762 4763Description 4764 4765 Returns the usual <0, 0, >0 result of comparing s1 and s2. 4766 4767FcStrCmpIgnoreCase 4768 4769Name 4770 4771 FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring case 4772 4773Synopsis 4774 4775#include <fontconfig/fontconfig.h> 4776 4777 int FcStrCmpIgnoreCase(const FcChar8 *s1, const FcChar8 *s2); 4778 4779Description 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 4784FcStrStr 4785 4786Name 4787 4788 FcStrStr -- locate UTF-8 substring 4789 4790Synopsis 4791 4792#include <fontconfig/fontconfig.h> 4793 4794 FcChar8 * FcStrStr(const FcChar8 *s1, const FcChar8 *s2); 4795 4796Description 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 4802FcStrStrIgnoreCase 4803 4804Name 4805 4806 FcStrStrIgnoreCase -- locate UTF-8 substring ignoring ASCII 4807 case 4808 4809Synopsis 4810 4811#include <fontconfig/fontconfig.h> 4812 4813 FcChar8 * FcStrStrIgnoreCase(const FcChar8 *s1, const FcChar8 4814 *s2); 4815 4816Description 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 4822FcStrPlus 4823 4824Name 4825 4826 FcStrPlus -- concatenate two strings 4827 4828Synopsis 4829 4830#include <fontconfig/fontconfig.h> 4831 4832 FcChar8 * FcStrPlus(const FcChar8 *s1, const FcChar8 *s2); 4833 4834Description 4835 4836 This function allocates new storage and places the 4837 concatenation of s1 and s2 there, returning the new string. 4838 4839FcStrFree 4840 4841Name 4842 4843 FcStrFree -- free a string 4844 4845Synopsis 4846 4847#include <fontconfig/fontconfig.h> 4848 4849 void FcStrFree(FcChar8 *s); 4850 4851Description 4852 4853 This is just a wrapper around free(3) which helps track memory 4854 usage of strings within the fontconfig library. 4855 4856FcStrDirname 4857 4858Name 4859 4860 FcStrDirname -- directory part of filename 4861 4862Synopsis 4863 4864#include <fontconfig/fontconfig.h> 4865 4866 FcChar8 * FcStrDirname(const FcChar8 *file); 4867 4868Description 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 4874FcStrBasename 4875 4876Name 4877 4878 FcStrBasename -- last component of filename 4879 4880Synopsis 4881 4882#include <fontconfig/fontconfig.h> 4883 4884 FcChar8 * FcStrBasename(const FcChar8 *file); 4885 4886Description 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. 4891