Pango Reference Manual: PangoFcFontMap

## PangoFcFontMap PangoFcFontMap — Base fontmap class for Fontconfig-based backends |

## Synopsis

    struct              PangoFcFontMap;
    struct              PangoFcFontMapClass;
    PangoContext *      pango_fc_font_map_create_context    (PangoFcFontMap *fcfontmap);
    PangoFcDecoder *    (*PangoFcDecoderFindFunc)           (FcPattern *pattern,
                                                             gpointer user_data);
    void                pango_fc_font_map_add_decoder_find_func
                                                            (PangoFcFontMap *fcfontmap,
                                                             PangoFcDecoderFindFunc findfunc,
                                                             gpointer user_data,
                                                             GDestroyNotify dnotify);
    PangoFcDecoder *    pango_fc_font_map_find_decoder      (PangoFcFontMap *fcfontmap,
                                                             FcPattern *pattern);
    void                pango_fc_font_map_cache_clear       (PangoFcFontMap *fcfontmap);
    void                pango_fc_font_map_shutdown          (PangoFcFontMap *fcfontmap);
    PangoFontDescription * pango_fc_font_description_from_pattern
                                                            (FcPattern *pattern,
                                                             gboolean include_size);
    #define             PANGO_FC_FONT_FEATURES
    #define             PANGO_FC_GRAVITY
    #define             PANGO_FC_VERSION
    #define             PANGO_FC_PRGNAME

                        PangoFcFontsetKey;
    gpointer            pango_fc_fontset_key_get_context_key
                                                            (const PangoFcFontsetKey *key);
    const PangoFontDescription * pango_fc_fontset_key_get_description
                                                            (const PangoFcFontsetKey *key);
    PangoLanguage *     pango_fc_fontset_key_get_language   (const PangoFcFontsetKey *key);
    const PangoMatrix * pango_fc_fontset_key_get_matrix     (const PangoFcFontsetKey *key);
    double              pango_fc_fontset_key_get_absolute_size
                                                            (const PangoFcFontsetKey *key);
    double              pango_fc_fontset_key_get_resolution (const PangoFcFontsetKey *key);
                        PangoFcFontKey;
    gpointer            pango_fc_font_key_get_context_key   (const PangoFcFontKey *key);
    const PangoMatrix * pango_fc_font_key_get_matrix        (const PangoFcFontKey *key);
    const FcPattern *   pango_fc_font_key_get_pattern       (const PangoFcFontKey *key);

## Object Hierarchy

      GObject
       +----PangoFontMap
             +----PangoFcFontMap
                   +----PangoFT2FontMap
                   +----PangoXftFontMap

## Description

PangoFcFontMap is a base class for font map implementations using the Fontconfig and FreeType libraries. It is used in the Xft and FreeType backends shipped with Pango, but can also be used when creating new backends. Any backend deriving from this base class will take advantage of the wide range of shapers implemented using FreeType that come with Pango.

## Details

### struct PangoFcFontMap

    struct PangoFcFontMap;

PangoFcFontMap is a base class for font map implementations using the Fontconfig and FreeType libraries. To create a new backend using Fontconfig and FreeType, you derive from this class and implement a `new_font()` virtual function that creates an instance deriving from PangoFcFont.

### struct PangoFcFontMapClass

    struct PangoFcFontMapClass {
      /* Deprecated in favor of fontset_key_substitute */
      void         (*default_substitute) (PangoFcFontMap   *fontmap,
    				      FcPattern        *pattern);
      /* Deprecated in favor of create_font */
      PangoFcFont  *(*new_font)          (PangoFcFontMap  *fontmap,
    				      FcPattern       *pattern);

      double       (*get_resolution)     (PangoFcFontMap             *fcfontmap,
    				      PangoContext               *context);

      gconstpointer (*context_key_get)   (PangoFcFontMap             *fcfontmap,
    				      PangoContext               *context);
      gpointer     (*context_key_copy)   (PangoFcFontMap             *fcfontmap,
    				      gconstpointer               key);
      void         (*context_key_free)   (PangoFcFontMap             *fcfontmap,
    				      gpointer                    key);
      guint32      (*context_key_hash)   (PangoFcFontMap             *fcfontmap,
    				      gconstpointer               key);
      gboolean     (*context_key_equal)  (PangoFcFontMap             *fcfontmap,
    				      gconstpointer               key_a,
    				      gconstpointer               key_b);

      void         (*fontset_key_substitute)(PangoFcFontMap             *fontmap,
    				      PangoFcFontsetKey          *fontsetkey,
    				      FcPattern                  *pattern);
      PangoFcFont  *(*create_font)       (PangoFcFontMap             *fontmap,
    				      PangoFcFontKey             *fontkey);
    };

Class structure for PangoFcFontMap.

`default_substitute` () | Substitutes in default values for unspecified fields in a FcPattern. This will be called prior to creating a font for the pattern. May be `NULL`. Deprecated in favor of ``font_key_substitute()``.
`new_font` () | Creates a new PangoFcFont for the specified pattern of the appropriate type for this font map. The `pattern` argument must be passed to the "pattern" property of PangoFcFont when you call `g_object_new()`. Deprecated in favor of ``create_font()``.
`get_resolution` () | Gets the resolution (the scale factor between logical and absolute font sizes) that the backend will use for a particular fontmap and context. `context` may be null.
`context_key_get` () | Gets an opaque key holding backend specific options for the context that will affect fonts created by `create_font()`. The result must point to persistant storage owned by the fontmap. This key is used to index hash tables used to look up fontsets and fonts.
`context_key_copy` () | Copies a context key. Pango uses this to make a persistant copy of the value returned from `context_key_get`.
`context_key_free` () | Frees a context key copied with `context_key_copy`.
`context_key_hash` () | Gets a hash value for a context key
`context_key_equal` () | Compares two context keys for equality.
`fontset_key_substitute` () | Substitutes in default values for unspecified fields in a FcPattern. This will be called prior to creating a font for the pattern. May be `NULL`. (Since: 1.24)
`create_font` () | Creates a new PangoFcFont for the specified pattern of the appropriate type for this font map using information from the font key that is passed in. The `pattern` member of `font_key` can be retrieved using `pango_fc_font_key_get_pattern()` and must be passed to the "pattern" property of PangoFcFont when you call `g_object_new()`. If `NULL`, `new_font()` is used. (Since: 1.24)

### pango_fc_font_map_create_context ()

    PangoContext *      pango_fc_font_map_create_context    (PangoFcFontMap *fcfontmap);

### Warning

`pango_fc_font_map_create_context` has been deprecated since version 1.22 and should not be used in newly-written code. Use `pango_font_map_create_context()` instead.

Creates a new context for this fontmap. This function is intended only for backend implementations deriving from PangoFcFontMap; it is possible that a backend will store additional information needed for correct operation on the PangoContext after calling this function.

`fcfontmap` : | a PangoFcFontMap
Returns : | a new PangoContext

Since 1.4

### PangoFcDecoderFindFunc ()

    PangoFcDecoder *    (*PangoFcDecoderFindFunc)           (FcPattern *pattern,
                                                             gpointer user_data);

Callback function passed to `pango_fc_font_map_add_decoder_find_func()`.

`pattern` : | a fully resolved FcPattern specifying the font on the system
`user_data` : | user data passed to `pango_fc_font_map_add_decoder_find_func()`
Returns : | a new reference to a custom decoder for this pattern, or `NULL` if the default decoder handling should be used.

### pango_fc_font_map_add_decoder_find_func ()

    void                pango_fc_font_map_add_decoder_find_func
                                                            (PangoFcFontMap *fcfontmap,
                                                             PangoFcDecoderFindFunc findfunc,
                                                             gpointer user_data,
                                                             GDestroyNotify dnotify);

This function saves a callback method in the PangoFcFontMap that will be called whenever new fonts are created. If the function returns a PangoFcDecoder, that decoder will be used to determine both coverage via a FcCharSet and a one-to-one mapping of characters to glyphs. This will allow applications to have application-specific encodings for various fonts.

`fcfontmap` : | The PangoFcFontMap to add this method to.
`findfunc` : | The PangoFcDecoderFindFunc callback function
`user_data` : | User data.
`dnotify` : | A GDestroyNotify callback that will be called when the fontmap is finalized and the decoder is released.

Since 1.6

### pango_fc_font_map_find_decoder ()

    PangoFcDecoder *    pango_fc_font_map_find_decoder      (PangoFcFontMap *fcfontmap,
                                                             FcPattern *pattern);

Finds the decoder to use for `pattern`. Decoders can be added to a font map using `pango_fc_font_map_add_decoder_find_func()`.

`fcfontmap` : | The PangoFcFontMap to use.
`pattern` : | The FcPattern to find the decoder for.
Returns : | a newly created PangoFcDecoder object or `NULL` if no decoder is set for `pattern`.

Since 1.26

### pango_fc_font_map_cache_clear ()

    void                pango_fc_font_map_cache_clear       (PangoFcFontMap *fcfontmap);

Clear all cached information and fontsets for this font map; this should be called whenever there is a change in the output of the `default_substitute()` virtual function of the font map, or if fontconfig has been reinitialized to new configuration.

`fcfontmap` : | a PangoFcFontMap

Since 1.4

### pango_fc_font_map_shutdown ()

    void                pango_fc_font_map_shutdown          (PangoFcFontMap *fcfontmap);

Clears all cached information for the fontmap and marks all fonts open for the fontmap as dead. (See the `shutdown()` virtual function of PangoFcFont.) This function might be used by a backend when the underlying windowing system for the font map exits. This function is only intended to be called only for backend implementations deriving from PangoFcFontMap.

`fcfontmap` : | a PangoFcFontMap

Since 1.4

### pango_fc_font_description_from_pattern ()

    PangoFontDescription * pango_fc_font_description_from_pattern
                                                            (FcPattern *pattern,
                                                             gboolean include_size);

Creates a PangoFontDescription that matches the specified Fontconfig pattern as closely as possible. Many possible Fontconfig pattern values, such as `FC_RASTERIZER` or `FC_DPI`, don't make sense in the context of PangoFontDescription, so will be ignored.

`pattern` : | a FcPattern
`include_size` : | if `TRUE`, the pattern will include the size from the `pattern`; otherwise the resulting pattern will be unsized. (only `FC_SIZE` is examined, not `FC_PIXEL_SIZE`)
Returns : | a new PangoFontDescription. Free with `pango_font_description_free()`.

Since 1.4

### PANGO_FC_FONT_FEATURES

    #define PANGO_FC_FONT_FEATURES "fontfeatures"

String representing a fontconfig property name that Pango reads from font patterns to populate list of OpenType features to be enabled for the font by default.

The property will have a number of string elements, each of which is the OpenType feature tag of one feature to enable.

This is equivalent to FC_FONT_FEATURES in versions of fontconfig that have that.

Since 1.34

### PANGO_FC_GRAVITY

    #define PANGO_FC_GRAVITY "pangogravity"

String representing a fontconfig property name that Pango sets on any fontconfig pattern it passes to fontconfig if a PangoGravity other than `PangoGravitySouth` is desired.

The property will have a PangoGravity value as a string, like "east". This can be used to write fontconfig configuration rules to choose different fonts for horizontal and vertical writing directions.

Since 1.20

### PANGO_FC_VERSION

    #define PANGO_FC_VERSION "pangoversion"

String representing a fontconfig property name that Pango sets on any fontconfig pattern it passes to fontconfig.

The property will have an integer value equal to what `pango_version()` returns. This can be used to write fontconfig configuration rules that only affect certain pango versions (or only pango-using applications, or only non-pango-using applications).

Since 1.20

### PANGO_FC_PRGNAME

    #define PANGO_FC_PRGNAME "prgname"

String representing a fontconfig property name that Pango sets on any fontconfig pattern it passes to fontconfig.

The property will have a string equal to what `g_get_prgname()` returns. This can be used to write fontconfig configuration rules that only affect certain applications.

This is equivalent to FC_PRGNAME in versions of fontconfig that have that.

Since 1.24

### PangoFcFontsetKey

    typedef struct _PangoFcFontsetKey PangoFcFontsetKey;

An opaque structure containing all the information needed for loading a fontset with the PangoFc fontmap.

Since 1.24

### pango_fc_fontset_key_get_context_key ()

    gpointer            pango_fc_fontset_key_get_context_key
                                                            (const PangoFcFontsetKey *key);

Gets the context key member of `key`.

`key` : | the font key
Returns : | the context key, which is owned by `key` and should not be modified.

Since 1.24

### pango_fc_fontset_key_get_description ()

    const PangoFontDescription * pango_fc_fontset_key_get_description
                                                            (const PangoFcFontsetKey *key);

Gets the font description of `key`.

`key` : | the fontset key
Returns : | the font description, which is owned by `key` and should not be modified.

Since 1.24

### pango_fc_fontset_key_get_language ()

    PangoLanguage *     pango_fc_fontset_key_get_language   (const PangoFcFontsetKey *key);

Gets the language member of `key`.

`key` : | the fontset key
Returns : | the language

Since 1.24

### pango_fc_fontset_key_get_matrix ()

    const PangoMatrix * pango_fc_fontset_key_get_matrix     (const PangoFcFontsetKey *key);

Gets the matrix member of `key`.

`key` : | the fontset key
Returns : | the matrix, which is owned by `key` and should not be modified.

Since 1.24

### pango_fc_fontset_key_get_absolute_size ()

    double              pango_fc_fontset_key_get_absolute_size
                                                            (const PangoFcFontsetKey *key);

Gets the absolute font size of `key` in Pango units. This is adjusted for both resolution and transformation matrix.

`key` : | the fontset key
Returns : | the pixel size of `key`.

Since 1.24

### pango_fc_fontset_key_get_resolution ()

    double              pango_fc_fontset_key_get_resolution (const PangoFcFontsetKey *key);

Gets the resolution of `key`

`key` : | the fontset key
Returns : | the resolution of `key`

Since 1.24

### PangoFcFontKey

    typedef struct _PangoFcFontKey PangoFcFontKey;

An opaque structure containing all the information needed for loading a font with the PangoFc fontmap.

Since 1.24

### pango_fc_font_key_get_context_key ()

    gpointer            pango_fc_font_key_get_context_key   (const PangoFcFontKey *key);

Gets the context key member of `key`.

`key` : | the font key
Returns : | the context key, which is owned by `key` and should not be modified.

Since 1.24

### pango_fc_font_key_get_matrix ()

    const PangoMatrix * pango_fc_font_key_get_matrix        (const PangoFcFontKey *key);

Gets the matrix member of `key`.

`key` : | the font key
Returns : | the matrix, which is owned by `key` and should not be modified.

Since 1.24

### pango_fc_font_key_get_pattern ()

    const FcPattern *   pango_fc_font_key_get_pattern       (const PangoFcFontKey *key);

Gets the fontconfig pattern member of `key`.

`key` : | the font key
Returns : | the pattern, which is owned by `key` and should not be modified.

Since 1.24

## See Also

PangoFcFont | The base class for fonts; creating a new Fontconfig-based backend involves deriving from both PangoFcFontMap and PangoFcFont.