Modules

## Modules Modules — Support for loadable modules |

## Synopsis

                        PangoIncludedModule;
                        PangoMap;
                        PangoMapEntry;
    PangoMap*           pango_find_map                      (PangoLanguage *language,
                                                             guint engine_type_id,
                                                             guint render_type_id);
    PangoEngine*        pango_map_get_engine                (PangoMap *map,
                                                             PangoScript script);
    void                pango_map_get_engines               (PangoMap *map,
                                                             PangoScript script,
                                                             GSList **exact_engines,
                                                             GSList **fallback_engines);
    void                pango_module_register               (PangoIncludedModule *module);

## Description

Functions and macros in this section are used to support loading dynamic modules that add engines to Pango at run time.

## Details

### PangoIncludedModule

    typedef struct {
      void (*list) (PangoEngineInfo **engines,
    		int              *n_engines);
      void (*init) (GTypeModule      *module);
      void (*exit) (void);
      PangoEngine *(*create) (const char       *id);
    } PangoIncludedModule;

The PangoIncludedModule structure for a statically linked module contains the functions that would otherwise be loaded from a dynamically loaded module.

`list` () | a function that lists the engines defined in this module.
`init` () | a function to initialize the module.
`exit` () | a function to finalize the module.
`create` () | a function to create an engine, given the engine name.

### PangoMap

    typedef struct _PangoMap PangoMap;

A PangoMap structure can be used to determine the engine to use for each character.

### PangoMapEntry

    typedef struct _PangoMapEntry PangoMapEntry;

A PangoMapEntry contains information about the engine that should be used for the codepoint to which this entry belongs and also whether the engine matches the language tag for this entry's map exactly or just approximately.

### pango_find_map ()

    PangoMap*           pango_find_map                      (PangoLanguage *language,
                                                             guint engine_type_id,
                                                             guint render_type_id);

Locate a PangoMap for a particular engine type and render type. The resulting map can be used to determine the engine for each character.

`language` : | the language tag for which to find the map
`engine_type_id` : | the engine type for the map to find
`render_type_id` : | the render type for the map to find
Returns : | the suitable PangoMap.

### pango_map_get_engine ()

    PangoEngine*        pango_map_get_engine                (PangoMap *map,
                                                             PangoScript script);

Returns the best engine listed in the map for a given script

`map` : | a PangoMap
`script` : | a PangoScript
Returns : | the best engine, if one is listed for the script, or `NULL`. The lookup may cause the engine to be loaded; once an engine is loaded, it won't be unloaded. If multiple engines are exact for the script, the choice of which is returned is arbitrary.

### pango_map_get_engines ()

    void                pango_map_get_engines               (PangoMap *map,
                                                             PangoScript script,
                                                             GSList **exact_engines,
                                                             GSList **fallback_engines);

Finds engines in the map that handle the given script. The returned lists should be freed with g_slist_free, but the engines in the lists are owned by GLib and will be kept around permanently, so they should not be unref'ed.

`map` : | a PangoMap
`script` : | a PangoScript
`exact_engines` : | location to store list of engines that exactly handle this script.
`fallback_engines` : | location to store list of engines that approximately handle this script.

Since 1.4

### pango_module_register ()

    void                pango_module_register               (PangoIncludedModule *module);

Registers a statically linked module with Pango. The PangoIncludedModule structure that is passed in contains the functions that would otherwise be loaded from a dynamically loaded module.

`module` : | a PangoIncludedModule