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