summaryrefslogtreecommitdiff
path: root/pango/pango-engine.h
diff options
context:
space:
mode:
Diffstat (limited to 'pango/pango-engine.h')
-rw-r--r--pango/pango-engine.h314
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,