Make PangoEngine{,Lang,Shape} GObjects, and use a GTypeModule-based

Sat Aug  2 23:19:16 2003  Owen Taylor  <otaylor@redhat.com>

        * pango/pango-engine.[ch] modules/*/*-{fc,win32,x}.c
        pango/modules.c pango/break.c pango/pango-context.c
        pango/pango-layout.c pango/pango-modules.h
        pango/querymodules.c pango/shape.c: Make
        PangoEngine{,Lang,Shape} GObjects, and use a
        GTypeModule-based module-loading system closely based
        on the one used for GtkIMContext and GtkThemeEngine.

        * pango/pango-impl-utils.h: OK, I'm tired of typing
        in get_type() functions.

        * pango/pango-script.[ch] pango/pango-script-table.h
        tests/testscript.c tools/gen-script-table.pl: Add port
        of script-range code from ICU in preparation for future
        use. (#91542)

        * tools/gen-script-for-lang.c: Utility program to determine
        the script for each fontconfig .orth file.

        * docs/tmpl/{scripts.sgml,pango-engine-lang.sgml,
        pango-engine-shape.sgml} docs/pango-sections.txt docs/pango-docs.sgml:
        Redo to go along with the above changes.

        * configure.in: chmod +x tests/runtests.sh

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,