diff options
Diffstat (limited to 'pango/pango-engine.h')
| -rw-r--r-- | pango/pango-engine.h | 314 |
1 files changed, 282 insertions, 32 deletions
diff --git a/pango/pango-engine.h b/pango/pango-engine.h index 0a7ada25..1aa429de 100644 --- a/pango/pango-engine.h +++ b/pango/pango-engine.h @@ -1,7 +1,7 @@ /* Pango - * pango-engine.h: Module handling + * pango-engine.h: Engines for script and language specific processing * - * Copyright (C) 2000 Red Hat Software + * Copyright (C) 2000,2003 Red Hat Software * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public @@ -33,66 +33,316 @@ G_BEGIN_DECLS /* Module API */ -#define PANGO_ENGINE_TYPE_LANG "PangoEngineLang" -#define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape" - #define PANGO_RENDER_TYPE_NONE "PangoRenderNone" -typedef struct _PangoEngineInfo PangoEngineInfo; -typedef struct _PangoEngineRange PangoEngineRange; +#define PANGO_TYPE_ENGINE (pango_engine_get_type ()) +#define PANGO_ENGINE(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_ENGINE, PangoEngine)) +#define PANGO_IS_ENGINE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_ENGINE)) +#define PANGO_ENGINE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_ENGINE, PangoEngineClass)) +#define PANGO_IS_ENGINE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_ENGINE)) +#define PANGO_ENGINE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_ENGINE, PangoEngineClass)) + typedef struct _PangoEngine PangoEngine; +typedef struct _PangoEngineClass PangoEngineClass; -struct _PangoEngineRange +/** + * PangoEngine: + * + * #PangoEngine is the base class for all types of language and + * script specific engines. It has no functionality by itself. + **/ +struct _PangoEngine { - guint32 start; - guint32 end; - gchar *langs; + /*< private >*/ + GObject parent_instance; }; -struct _PangoEngineInfo +/** + * PangoEngineClass: + * + * Class structure for #PangoEngine + **/ +struct _PangoEngineClass { - gchar *id; - gchar *engine_type; - gchar *render_type; - PangoEngineRange *ranges; - gint n_ranges; + /*< private >*/ + GObjectClass parent_class; }; -struct _PangoEngine +GType pango_engine_get_type (void) G_GNUC_CONST; + +#define PANGO_ENGINE_TYPE_LANG "PangoEngineLang" + +#define PANGO_TYPE_ENGINE_LANG (pango_engine_lang_get_type ()) +#define PANGO_ENGINE_LANG(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_ENGINE_LANG, PangoEngineLang)) +#define PANGO_IS_ENGINE_LANG(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_ENGINE_LANG)) +#define PANGO_ENGINE_LANG_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_ENGINE_LANG, PangoEngineLangClass)) +#define PANGO_IS_ENGINE_LANG_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_ENGINE_LANG)) +#define PANGO_ENGINE_LANG_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_ENGINE_LANG, PangoEngineLangClass)) + +typedef struct _PangoEngineLangClass PangoEngineLangClass; + +/** + * PangoEngineLang: + * + * The #PangoEngineLang class is implemented by engines that + * customize the rendering-system independent part of the + * Pango pipeline for a particular script or language. For + * instance, a custom #PangoEngineLang could be provided for + * Thai to implement the dictionary-based word boundary + * lookups needed for that language. + **/ +struct _PangoEngineLang { - gchar *id; - gchar *type; - gint length; + /*< private >*/ + PangoEngine parent_instance; }; -struct _PangoEngineLang +/** + * PangoEngineLangClass: + * @script_break: Provides a custom implementation of pango_break(). + * if this is %NULL, pango_default_break() will be used. + * + * Class structure for #PangoEngineLang + **/ +struct _PangoEngineLangClass { - PangoEngine engine; - void (*script_break) (const char *text, + /*< private >*/ + PangoEngineClass parent_class; + + /*< public >*/ + void (*script_break) (PangoEngineLang *engine, + const char *text, int len, PangoAnalysis *analysis, PangoLogAttr *attrs, int attrs_len); }; +GType pango_engine_lang_get_type (void) G_GNUC_CONST; + +#define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape" + +#define PANGO_TYPE_ENGINE_SHAPE (pango_engine_shape_get_type ()) +#define PANGO_ENGINE_SHAPE(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_ENGINE_SHAPE, PangoEngineShape)) +#define PANGO_IS_ENGINE_SHAPE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_ENGINE_SHAPE)) +#define PANGO_ENGINE_SHAPE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_ENGINE_SHAPE, PangoEngine_ShapeClass)) +#define PANGO_IS_ENGINE_SHAPE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_ENGINE_SHAPE)) +#define PANGO_ENGINE_SHAPE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_ENGINE_SHAPE, PangoEngineShapeClass)) + +typedef struct _PangoEngineShapeClass PangoEngineShapeClass; + +/** + * PangoEngineShape + * + * The #PangoEngineShape class is implemented by engines that + * customize the rendering-system dependent part of the + * Pango pipeline for a particular script or language. + * A #PangoEngineShape implementation is then specific to both + * a particular rendering system or group of rendering systems + * and to a particular script. For instance, there is one + * #PangoEngineShape implementation to handling shaping Arabic + * for Fontconfig-based backends. + **/ struct _PangoEngineShape { - PangoEngine engine; - void (*script_shape) (PangoFont *font, + PangoEngine parent_instance; +}; + +/** + * PangoEngineShapeClass: + * @script_shape: Given a font, a piece of text, and a #PangoAnalysis + * structure, converts characters to glyphs and positions the + * resulting glyphs. The results are stored in the #PangoGlyphString + * that is passed in. (The implementation should resize it + * appropriately using pango_glyph_string_set_size()). All fields + * of the @log_clusters and @glyphs array must be filled in, with + * the exception that Pango will automatically generate + * <literal>glyphs->glyphs[i].attr.is_cluster_start</literal> + * using the @log_clusters array. Each input character must occur in one + * of the output logical clusters; + * if no rendering is desired for a character, this may involve + * inserting glyphs with the #PangoGlyph ID 0, which is guaranteed never + * to render. + * @get_coverage: Returns the characters that this engine can cover + * with a given font for a given language. If not overridden, the default + * implementation simply returns the coverage information for the + * font itself unmodified. + * + * Class structure for #PangoEngineShape + **/ +struct _PangoEngineShapeClass +{ + /*< private >*/ + PangoEngineClass parent_class; + + /*< public >*/ + void (*script_shape) (PangoEngineShape *engine, + PangoFont *font, const char *text, int length, PangoAnalysis *analysis, PangoGlyphString *glyphs); - PangoCoverage *(*get_coverage) (PangoFont *font, + PangoCoverage *(*get_coverage) (PangoEngineShape *engine, + PangoFont *font, PangoLanguage *language); }; -/* A module should export the following functions */ +GType pango_engine_shape_get_type (void) G_GNUC_CONST; + +typedef struct _PangoEngineInfo PangoEngineInfo; +typedef struct _PangoEngineRange PangoEngineRange; + +struct _PangoEngineRange +{ + guint32 start; + guint32 end; + gchar *langs; +}; + +struct _PangoEngineInfo +{ + gchar *id; + gchar *engine_type; + gchar *render_type; + PangoEngineRange *ranges; + gint n_ranges; +}; + +/** + * script_engine_list: + * @engines: location to store a pointer to an array of engines. + * @n_engines: location to store the number of elements in @engines. + * + * Function to be provided by a module to list the engines that the + * module supplies. The function stores a pointer to an array + * of #PangoEngineInfo structures and the length of that array in + * the given location. + * + * Note that script_engine_init() will not be called before this + * function. + **/ +void script_engine_list (PangoEngineInfo **engines, + int *n_engines); + +/** + * script_engine_init: + * @module: a #GTypeModule structure used to associate any + * GObject types created in this module with the module. + * + * Function to be provided by a module to register any + * GObject types in the module. + **/ +void script_engine_init (GTypeModule *module); + + +/** + * script_engine_exit: + * + * Function to be provided by the module that is called + * when the module is unloading. Frequently does nothing. + **/ +void script_engine_exit (void); + +/** + * script_engine_create: + * @id: the ID of an engine as reported by script_engine_list. + * + * Function to be provided by the module to create an instance + * of one of the engines implemented by the module. + * + * Return value: a newly created #PangoEngine of the specified + * type, or %NULL if an error occurred. (In normal operation, + * a module should not return %NULL. A %NULL return is only + * acceptable in the case where system misconfiguration or + * bugs in the driver routine are encountered.) + **/ +PangoEngine *script_engine_create (const char *id); + +/* Utility macro used by PANGO_ENGINE_LANG_DEFINE_TYPE and + * PANGO_ENGINE_LANG_DEFINE_TYPE + */ +#define PANGO_ENGINE_DEFINE_TYPE(name, prefix, class_init, instance_init, parent_type) \ +static GType prefix ## _type; \ +static void \ +prefix ## _register_type (GTypeModule *module) \ +{ \ + static const GTypeInfo object_info = \ + { \ + sizeof (name ## Class), \ + (GBaseInitFunc) NULL, \ + (GBaseFinalizeFunc) NULL, \ + (GClassInitFunc) class_init, \ + (GClassFinalizeFunc) NULL, \ + NULL, /* class_data */ \ + sizeof (name), \ + 0, /* n_prelocs */ \ + (GInstanceInitFunc) instance_init, \ + }; \ + \ + prefix ## _type = g_type_module_register_type (module, parent_type, \ + # name, \ + &object_info, 0); \ +} -void script_engine_list (PangoEngineInfo **engines, - int *n_engines); -PangoEngine *script_engine_load (const char *id); -void script_engine_unload (PangoEngine *engine); +/** + * PANGO_ENGINE_LANG_DEFINE_TYPE: + * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal> + * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal> + * @class_init: Class initialization function for the new type, or %NULL + * @instance_init: Instance initialization function for the new type, or %NULL + * + * Outputs the necessary code for GObject type registration for a + * #PangoEngineLang class defined in a module. Two static symbols + * are defined. + * + * <programlisting> + * static GType <replaceable>prefix</replaceable>_type; + * static void <replaceable>prefix</replaceable>_register_type (GTypeModule module); + * </programlisting> + * + * The <function><replaceable>prefix</replaceable>_register_type()</function> + * function should be called in your script_engine_init() function for + * each type that your module implements, and then your script_engine_create() + * function can create instances of the object as follows: + * + * <informalexample><programlisting> + * PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL); + * </programlisting></informalexample> + **/ +#define PANGO_ENGINE_LANG_DEFINE_TYPE(name, prefix, class_init, instance_init) \ + PANGO_ENGINE_DEFINE_TYPE (name, prefix, \ + class_init, instance_init, \ + PANGO_TYPE_ENGINE_LANG) + +/** + * PANGO_ENGINE_SHAPE_DEFINE_TYPE: + * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal> + * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal> + * @class_init: Class initialization function for the new type, or %NULL + * @instance_init: Instance initialization function for the new type, or %NULL + * + * Outputs the necessary code for GObject type registration for a + * #PangoEngineShape class defined in a module. Two static symbols + * are defined. + * + * <programlisting> + * static GType <replaceable>prefix</replaceable>_type; + * static void <replaceable>prefix</replaceable>_register_type (GTypeModule module); + * </programlisting> + * + * The <function><replaceable>prefix</replaceable>_register_type()</function> + * function should be called in your script_engine_init() function for + * each type that your module implements, and then your script_engine_create() + * function can create instances of the object as follows: + * + * <informalexample><programlisting> + * PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL); + * </programlisting></informalexample> + **/ +#define PANGO_ENGINE_SHAPE_DEFINE_TYPE(name, prefix, class_init, instance_init) \ + PANGO_ENGINE_DEFINE_TYPE (name, prefix, \ + class_init, instance_init, \ + PANGO_TYPE_ENGINE_SHAPE) /* Macro used for possibly builtin Pango modules. Not useful * for externally build modules. If we are compiling a module standaline, |