doc/fontconfig-devel/x31.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >Datatypes</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
   9 REL="HOME"
  10 HREF="t1.html"><LINK
  11 REL="PREVIOUS"
  12 TITLE="FUNCTIONAL OVERVIEW"
  13 HREF="x19.html"><LINK
  14 REL="NEXT"
  15 TITLE="FUNCTIONS"
  16 HREF="x103.html"></HEAD
  17 ><BODY
  18 CLASS="SECT1"
  19 BGCOLOR="#FFFFFF"
  20 TEXT="#000000"
  21 LINK="#0000FF"
  22 VLINK="#840084"
  23 ALINK="#0000FF"
  24 ><DIV
  25 CLASS="NAVHEADER"
  26 ><TABLE
  27 SUMMARY="Header navigation table"
  28 WIDTH="100%"
  29 BORDER="0"
  30 CELLPADDING="0"
  31 CELLSPACING="0"
  32 ><TR
  33 ><TH
  34 COLSPAN="3"
  35 ALIGN="center"
  36 ></TH
  37 ></TR
  38 ><TR
  39 ><TD
  40 WIDTH="10%"
  41 ALIGN="left"
  42 VALIGN="bottom"
  43 ><A
  44 HREF="x19.html"
  45 ACCESSKEY="P"
  46 >&#60;&#60;&#60; Previous</A
  47 ></TD
  48 ><TD
  49 WIDTH="80%"
  50 ALIGN="center"
  51 VALIGN="bottom"
  52 ></TD
  53 ><TD
  54 WIDTH="10%"
  55 ALIGN="right"
  56 VALIGN="bottom"
  57 ><A
  58 HREF="x103.html"
  59 ACCESSKEY="N"
  60 >Next &#62;&#62;&#62;</A
  61 ></TD
  62 ></TR
  63 ></TABLE
  64 ><HR
  65 ALIGN="LEFT"
  66 WIDTH="100%"></DIV
  67 ><DIV
  68 CLASS="SECT1"
  69 ><H1
  70 CLASS="SECT1"
  71 ><A
  72 NAME="AEN31"
  73 >Datatypes</A
  74 ></H1
  75 ><P
  76 >Fontconfig uses abstract data types to hide internal implementation details
  77 for most data structures.  A few structures are exposed where appropriate.
  78   </P
  79 ><DIV
  80 CLASS="SECT2"
  81 ><H2
  82 CLASS="SECT2"
  83 ><A
  84 NAME="AEN34"
  85 >FcChar8, FcChar16, FcChar32, FcBool</A
  86 ></H2
  87 ><P
  88 >These are primitive data types; the FcChar* types hold precisely the number
  89 of bits stated (if supported by the C implementation).  FcBool holds
  90 one of two C preprocessor symbols: FcFalse or FcTrue.
  91     </P
  92 ></DIV
  93 ><DIV
  94 CLASS="SECT2"
  95 ><H2
  96 CLASS="SECT2"
  97 ><A
  98 NAME="AEN37"
  99 >FcMatrix</A
 100 ></H2
 101 ><P
 102 >An FcMatrix holds an affine transformation, usually used to reshape glyphs.
 103 A small set of matrix operations are provided to manipulate these.
 104     <TABLE
 105 BORDER="0"
 106 BGCOLOR="#E0E0E0"
 107 WIDTH="100%"
 108 ><TR
 109 ><TD
 110 ><PRE
 111 CLASS="PROGRAMLISTING"
 112 >        typedef struct _FcMatrix {
 113                 double xx, xy, yx, yy;
 114         } FcMatrix;
 115     </PRE
 116 ></TD
 117 ></TR
 118 ></TABLE
 119 >
 120     </P
 121 ></DIV
 122 ><DIV
 123 CLASS="SECT2"
 124 ><H2
 125 CLASS="SECT2"
 126 ><A
 127 NAME="AEN41"
 128 >FcCharSet</A
 129 ></H2
 130 ><P
 131 >An FcCharSet is an abstract type that holds the set of encoded Unicode chars
 132 in a font.  Operations to build and compare these sets are provided.
 133     </P
 134 ></DIV
 135 ><DIV
 136 CLASS="SECT2"
 137 ><H2
 138 CLASS="SECT2"
 139 ><A
 140 NAME="AEN44"
 141 >FcLangSet</A
 142 ></H2
 143 ><P
 144 >An FcLangSet is an abstract type that holds the set of languages supported
 145 by a font.  Operations to build and compare these sets are provided. These
 146 are computed for a font based on orthographic information built into the
 147 fontconfig library. Fontconfig has orthographies for all of the ISO 639-1
 148 languages except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA. If
 149 you have orthographic information for any of these languages, please submit
 150 them.
 151     </P
 152 ></DIV
 153 ><DIV
 154 CLASS="SECT2"
 155 ><H2
 156 CLASS="SECT2"
 157 ><A
 158 NAME="AEN47"
 159 >FcLangResult</A
 160 ></H2
 161 ><P
 162 >An FcLangResult is an enumeration used to return the results of comparing
 163 two language strings or FcLangSet objects. FcLangEqual means the
 164 objects match language and territory. FcLangDifferentTerritory means
 165 the objects match in language but differ in territory.
 166 FcLangDifferentLang means the objects differ in language.
 167     </P
 168 ></DIV
 169 ><DIV
 170 CLASS="SECT2"
 171 ><H2
 172 CLASS="SECT2"
 173 ><A
 174 NAME="AEN50"
 175 >FcType</A
 176 ></H2
 177 ><P
 178 >Tags the kind of data stored in an FcValue.
 179     </P
 180 ></DIV
 181 ><DIV
 182 CLASS="SECT2"
 183 ><H2
 184 CLASS="SECT2"
 185 ><A
 186 NAME="AEN53"
 187 >FcValue</A
 188 ></H2
 189 ><P
 190 >An FcValue object holds a single value with one of a number of different
 191 types.  The 'type' tag indicates which member is valid.
 192     <TABLE
 193 BORDER="0"
 194 BGCOLOR="#E0E0E0"
 195 WIDTH="100%"
 196 ><TR
 197 ><TD
 198 ><PRE
 199 CLASS="PROGRAMLISTING"
 200 >        typedef struct _FcValue {
 201                 FcType type;
 202                 union {
 203                         const FcChar8 *s;
 204                         int i;
 205                         FcBool b;
 206                         double d;
 207                         const FcMatrix *m;
 208                         const FcCharSet *c;
 209                         void *f;
 210                         const FcLangSet *l;
 211                 } u;
 212         } FcValue;
 213     </PRE
 214 ></TD
 215 ></TR
 216 ></TABLE
 217 >
 218     <TABLE
 219 BORDER="0"
 220 BGCOLOR="#E0E0E0"
 221 WIDTH="100%"
 222 ><TR
 223 ><TD
 224 ><PRE
 225 CLASS="PROGRAMLISTING"
 226 >                  FcValue Members
 227
 228         Type            Union member    Datatype
 229         --------------------------------
 230         FcTypeVoid      (none)          (none)
 231         FcTypeInteger   i               int
 232         FcTypeDouble    d               double
 233         FcTypeString    s               FcChar8 *
 234         FcTypeBool      b               b
 235         FcTypeMatrix    m               FcMatrix *
 236         FcTypeCharSet   c               FcCharSet *
 237         FcTypeFTFace    f               void * (FT_Face)
 238         FcTypeLangSet   l               FcLangSet *
 239     </PRE
 240 ></TD
 241 ></TR
 242 ></TABLE
 243 >
 244     </P
 245 ></DIV
 246 ><DIV
 247 CLASS="SECT2"
 248 ><H2
 249 CLASS="SECT2"
 250 ><A
 251 NAME="AEN58"
 252 >FcPattern</A
 253 ></H2
 254 ><P
 255 >holds a set of names with associated value lists; each name refers to a
 256 property of a font.  FcPatterns are used as inputs to the matching code as
 257 well as holding information about specific fonts.  Each property can hold
 258 one or more values; conventionally all of the same type, although the
 259 interface doesn't demand that.
 260     </P
 261 ></DIV
 262 ><DIV
 263 CLASS="SECT2"
 264 ><H2
 265 CLASS="SECT2"
 266 ><A
 267 NAME="AEN61"
 268 >FcFontSet</A
 269 ></H2
 270 ><P
 271 >    <TABLE
 272 BORDER="0"
 273 BGCOLOR="#E0E0E0"
 274 WIDTH="100%"
 275 ><TR
 276 ><TD
 277 ><PRE
 278 CLASS="PROGRAMLISTING"
 279 >        typedef struct _FcFontSet {
 280                 int nfont;
 281                 int sfont;
 282                 FcPattern **fonts;
 283         } FcFontSet;
 284     </PRE
 285 ></TD
 286 ></TR
 287 ></TABLE
 288 >
 289 An FcFontSet contains a list of FcPatterns.  Internally fontconfig uses this
 290 data structure to hold sets of fonts.  Externally, fontconfig returns the
 291 results of listing fonts in this format.  'nfont' holds the number of
 292 patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
 293 array.
 294     </P
 295 ></DIV
 296 ><DIV
 297 CLASS="SECT2"
 298 ><H2
 299 CLASS="SECT2"
 300 ><A
 301 NAME="AEN65"
 302 >FcStrSet, FcStrList</A
 303 ></H2
 304 ><P
 305 >FcStrSet holds a list of strings that can be appended to and enumerated.
 306 Its unique characteristic is that the enumeration works even while strings
 307 are appended during enumeration.  FcStrList is used during enumeration to
 308 safely and correctly walk the list of strings even while that list is edited
 309 in the middle of enumeration.
 310     </P
 311 ></DIV
 312 ><DIV
 313 CLASS="SECT2"
 314 ><H2
 315 CLASS="SECT2"
 316 ><A
 317 NAME="AEN68"
 318 >FcObjectSet</A
 319 ></H2
 320 ><P
 321 >      <TABLE
 322 BORDER="0"
 323 BGCOLOR="#E0E0E0"
 324 WIDTH="100%"
 325 ><TR
 326 ><TD
 327 ><PRE
 328 CLASS="PROGRAMLISTING"
 329 >        typedef struct _FcObjectSet {
 330                 int nobject;
 331                 int sobject;
 332                 const char **objects;
 333         } FcObjectSet;
 334       </PRE
 335 ></TD
 336 ></TR
 337 ></TABLE
 338 >
 339 holds a set of names and is used to specify which fields from fonts are
 340 placed in the the list of returned patterns when listing fonts.
 341     </P
 342 ></DIV
 343 ><DIV
 344 CLASS="SECT2"
 345 ><H2
 346 CLASS="SECT2"
 347 ><A
 348 NAME="AEN72"
 349 >FcObjectType</A
 350 ></H2
 351 ><P
 352 >      <TABLE
 353 BORDER="0"
 354 BGCOLOR="#E0E0E0"
 355 WIDTH="100%"
 356 ><TR
 357 ><TD
 358 ><PRE
 359 CLASS="PROGRAMLISTING"
 360 >        typedef struct _FcObjectType {
 361                 const char *object;
 362                 FcType type;
 363         } FcObjectType;
 364       </PRE
 365 ></TD
 366 ></TR
 367 ></TABLE
 368 >
 369 marks the type of a pattern element generated when parsing font names.
 370 Applications can add new object types so that font names may contain the new
 371 elements.
 372     </P
 373 ></DIV
 374 ><DIV
 375 CLASS="SECT2"
 376 ><H2
 377 CLASS="SECT2"
 378 ><A
 379 NAME="AEN76"
 380 >FcConstant</A
 381 ></H2
 382 ><P
 383 >      <TABLE
 384 BORDER="0"
 385 BGCOLOR="#E0E0E0"
 386 WIDTH="100%"
 387 ><TR
 388 ><TD
 389 ><PRE
 390 CLASS="PROGRAMLISTING"
 391 >        typedef struct _FcConstant {
 392             const FcChar8 *name;
 393             const char *object;
 394             int value;
 395         } FcConstant;
 396       </PRE
 397 ></TD
 398 ></TR
 399 ></TABLE
 400 >
 401 Provides for symbolic constants for new pattern elements.  When 'name' is
 402 seen in a font name, an 'object' element is created with value 'value'.
 403     </P
 404 ></DIV
 405 ><DIV
 406 CLASS="SECT2"
 407 ><H2
 408 CLASS="SECT2"
 409 ><A
 410 NAME="AEN80"
 411 >FcBlanks</A
 412 ></H2
 413 ><P
 414 >holds a list of Unicode chars which are expected to be blank; unexpectedly
 415 blank chars are assumed to be invalid and are elided from the charset
 416 associated with the font.
 417     </P
 418 ><P
 419 >        FcBlanks is deprecated and should not be used in newly written code.
 420         It is still accepted by some functions for compatibility with
 421         older code but will be removed in the future.
 422     </P
 423 ></DIV
 424 ><DIV
 425 CLASS="SECT2"
 426 ><H2
 427 CLASS="SECT2"
 428 ><A
 429 NAME="AEN84"
 430 >FcFileCache</A
 431 ></H2
 432 ><P
 433 >holds the per-user cache information for use while loading the font
 434 database. This is built automatically for the current configuration when
 435 that is loaded.  Applications must always pass '0' when one is requested.
 436     </P
 437 ></DIV
 438 ><DIV
 439 CLASS="SECT2"
 440 ><H2
 441 CLASS="SECT2"
 442 ><A
 443 NAME="AEN87"
 444 >FcConfig</A
 445 ></H2
 446 ><P
 447 >holds a complete configuration of the library; there is one default
 448 configuration, other can be constructed from XML data structures.  All
 449 public entry points that need global data can take an optional FcConfig*
 450 argument; passing 0 uses the default configuration.  FcConfig objects hold two
 451 sets of fonts, the first contains those specified by the configuration, the
 452 second set holds those added by the application at run-time.  Interfaces
 453 that need to reference a particular set use one of the FcSetName enumerated
 454 values.
 455     </P
 456 ></DIV
 457 ><DIV
 458 CLASS="SECT2"
 459 ><H2
 460 CLASS="SECT2"
 461 ><A
 462 NAME="AEN90"
 463 >FcSetName</A
 464 ></H2
 465 ><P
 466 >Specifies one of the two sets of fonts available in a configuration;
 467 FcSetSystem for those fonts specified in the configuration and
 468 FcSetApplication which holds fonts provided by the application.
 469     </P
 470 ></DIV
 471 ><DIV
 472 CLASS="SECT2"
 473 ><H2
 474 CLASS="SECT2"
 475 ><A
 476 NAME="AEN93"
 477 >FcResult</A
 478 ></H2
 479 ><P
 480 >Used as a return type for functions manipulating FcPattern objects.
 481     <TABLE
 482 BORDER="0"
 483 BGCOLOR="#E0E0E0"
 484 WIDTH="100%"
 485 ><TR
 486 ><TD
 487 ><PRE
 488 CLASS="PROGRAMLISTING"
 489 >      FcResult Values
 490         Result Code             Meaning
 491         -----------------------------------------------------------
 492         FcResultMatch           Object exists with the specified ID
 493         FcResultNoMatch         Object doesn't exist at all
 494         FcResultTypeMismatch    Object exists, but the type doesn't match
 495         FcResultNoId            Object exists, but has fewer values
 496                                 than specified
 497         FcResultOutOfMemory     malloc failed
 498     </PRE
 499 ></TD
 500 ></TR
 501 ></TABLE
 502 >
 503     </P
 504 ></DIV
 505 ><DIV
 506 CLASS="SECT2"
 507 ><H2
 508 CLASS="SECT2"
 509 ><A
 510 NAME="AEN97"
 511 >FcAtomic</A
 512 ></H2
 513 ><P
 514 >Used for locking access to configuration files.  Provides a safe way to update
 515 configuration files.
 516     </P
 517 ></DIV
 518 ><DIV
 519 CLASS="SECT2"
 520 ><H2
 521 CLASS="SECT2"
 522 ><A
 523 NAME="AEN100"
 524 >FcCache</A
 525 ></H2
 526 ><P
 527 >Holds information about the fonts contained in a single directory. Normal
 528 applications need not worry about this as caches for font access are
 529 automatically managed by the library. Applications dealing with cache
 530 management may want to use some of these objects in their work, however the
 531 included 'fc-cache' program generally suffices for all of that.
 532     </P
 533 ></DIV
 534 ></DIV
 535 ><DIV
 536 CLASS="NAVFOOTER"
 537 ><HR
 538 ALIGN="LEFT"
 539 WIDTH="100%"><TABLE
 540 SUMMARY="Footer navigation table"
 541 WIDTH="100%"
 542 BORDER="0"
 543 CELLPADDING="0"
 544 CELLSPACING="0"
 545 ><TR
 546 ><TD
 547 WIDTH="33%"
 548 ALIGN="left"
 549 VALIGN="top"
 550 ><A
 551 HREF="x19.html"
 552 ACCESSKEY="P"
 553 >&#60;&#60;&#60; Previous</A
 554 ></TD
 555 ><TD
 556 WIDTH="34%"
 557 ALIGN="center"
 558 VALIGN="top"
 559 ><A
 560 HREF="t1.html"
 561 ACCESSKEY="H"
 562 >Home</A
 563 ></TD
 564 ><TD
 565 WIDTH="33%"
 566 ALIGN="right"
 567 VALIGN="top"
 568 ><A
 569 HREF="x103.html"
 570 ACCESSKEY="N"
 571 >Next &#62;&#62;&#62;</A
 572 ></TD
 573 ></TR
 574 ><TR
 575 ><TD
 576 WIDTH="33%"
 577 ALIGN="left"
 578 VALIGN="top"
 579 >FUNCTIONAL OVERVIEW</TD
 580 ><TD
 581 WIDTH="34%"
 582 ALIGN="center"
 583 VALIGN="top"
 584 >&nbsp;</TD
 585 ><TD
 586 WIDTH="33%"
 587 ALIGN="right"
 588 VALIGN="top"
 589 >FUNCTIONS</TD
 590 ></TR
 591 ></TABLE
 592 ></DIV
 593 ></BODY
 594 ></HTML
 595 >