pango-1.0/pango/pango-engine.h

0001 /* Pango
0002  * pango-engine.h: Engines for script and language specific processing
0003  *
0004  * Copyright (C) 2000,2003 Red Hat Software
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Library General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Library General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Library General Public
0017  * License along with this library; if not, write to the
0018  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
0019  * Boston, MA 02111-1307, USA.
0020  */
0021
0022 #ifndef __PANGO_ENGINE_H__
0023 #define __PANGO_ENGINE_H__
0024
0025 #include <pango/pango-types.h>
0026 #include <pango/pango-item.h>
0027 #include <pango/pango-font.h>
0028 #include <pango/pango-glyph.h>
0029 #include <pango/pango-script.h>
0030
0031 G_BEGIN_DECLS
0032
0033 /* All of this is deprecated and entirely useless for bindings.
0034  * Leave it out of the gir file.
0035  */
0036 #ifndef __GI_SCANNER__
0037
0038 #ifndef PANGO_DISABLE_DEPRECATED
0039
0040 /**
0041  * PANGO_RENDER_TYPE_NONE:
0042  *
0043  * A string constant defining the render type
0044  * for engines that are not rendering-system specific.
0045  *
0046  * Deprecated: 1.38
0047  */
0048 #define PANGO_RENDER_TYPE_NONE "PangoRenderNone"
0049
0050 #define PANGO_TYPE_ENGINE              (pango_engine_get_type ())
0051 #define PANGO_ENGINE(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_ENGINE, PangoEngine))
0052 #define PANGO_IS_ENGINE(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_ENGINE))
0053 #define PANGO_ENGINE_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_ENGINE, PangoEngineClass))
0054 #define PANGO_IS_ENGINE_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_ENGINE))
0055 #define PANGO_ENGINE_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_ENGINE, PangoEngineClass))
0056
0057 typedef struct _PangoEngine PangoEngine;
0058 typedef struct _PangoEngineClass PangoEngineClass;
0059
0060 /**
0061  * PangoEngine:
0062  *
0063  * `PangoEngine` is the base class for all types of language and
0064  * script specific engines. It has no functionality by itself.
0065  *
0066  * Deprecated: 1.38
0067  **/
0068 struct _PangoEngine
0069 {
0070   /*< private >*/
0071   GObject parent_instance;
0072 };
0073
0074 /**
0075  * PangoEngineClass:
0076  *
0077  * Class structure for `PangoEngine`
0078  *
0079  * Deprecated: 1.38
0080  **/
0081 struct _PangoEngineClass
0082 {
0083   /*< private >*/
0084   GObjectClass parent_class;
0085 };
0086
0087 PANGO_DEPRECATED_IN_1_38
0088 GType pango_engine_get_type (void) G_GNUC_CONST;
0089
0090 /**
0091  * PANGO_ENGINE_TYPE_LANG:
0092  *
0093  * A string constant defining the engine type for language engines.
0094  * These engines derive from `PangoEngineLang`.
0095  *
0096  * Deprecated: 1.38
0097  */
0098 #define PANGO_ENGINE_TYPE_LANG "PangoEngineLang"
0099
0100 #define PANGO_TYPE_ENGINE_LANG              (pango_engine_lang_get_type ())
0101 #define PANGO_ENGINE_LANG(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_ENGINE_LANG, PangoEngineLang))
0102 #define PANGO_IS_ENGINE_LANG(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_ENGINE_LANG))
0103 #define PANGO_ENGINE_LANG_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_ENGINE_LANG, PangoEngineLangClass))
0104 #define PANGO_IS_ENGINE_LANG_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_ENGINE_LANG))
0105 #define PANGO_ENGINE_LANG_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_ENGINE_LANG, PangoEngineLangClass))
0106
0107 typedef struct _PangoEngineLangClass PangoEngineLangClass;
0108
0109 /**
0110  * PangoEngineLang:
0111  *
0112  * The `PangoEngineLang` class is implemented by engines that
0113  * customize the rendering-system independent part of the
0114  * Pango pipeline for a particular script or language. For
0115  * instance, a custom `PangoEngineLang` could be provided for
0116  * Thai to implement the dictionary-based word boundary
0117  * lookups needed for that language.
0118  *
0119  * Deprecated: 1.38
0120  **/
0121 struct _PangoEngineLang
0122 {
0123   /*< private >*/
0124   PangoEngine parent_instance;
0125 };
0126
0127 /**
0128  * PangoEngineLangClass:
0129  * @script_break: (nullable): Provides a custom implementation of
0130  * pango_break().  If %NULL, pango_default_break() is used instead. If
0131  * not %NULL, for Pango versions before 1.16 (module interface version
0132  * before 1.6.0), this was called instead of pango_default_break(),
0133  * but in newer versions, pango_default_break() is always called and
0134  * this is called after that to allow tailoring the breaking results.
0135  *
0136  * Class structure for `PangoEngineLang`
0137  *
0138  * Deprecated: 1.38
0139  **/
0140 struct _PangoEngineLangClass
0141 {
0142   /*< private >*/
0143   PangoEngineClass parent_class;
0144
0145   /*< public >*/
0146   void (*script_break) (PangoEngineLang *engine,
0147             const char    *text,
0148             int            len,
0149             PangoAnalysis *analysis,
0150             PangoLogAttr  *attrs,
0151             int            attrs_len);
0152 };
0153
0154 PANGO_DEPRECATED_IN_1_38
0155 GType pango_engine_lang_get_type (void) G_GNUC_CONST;
0156
0157 /**
0158  * PANGO_ENGINE_TYPE_SHAPE:
0159  *
0160  * A string constant defining the engine type for shaping engines.
0161  * These engines derive from `PangoEngineShape`.
0162  *
0163  * Deprecated: 1.38
0164  */
0165 #define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape"
0166
0167 #define PANGO_TYPE_ENGINE_SHAPE              (pango_engine_shape_get_type ())
0168 #define PANGO_ENGINE_SHAPE(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_ENGINE_SHAPE, PangoEngineShape))
0169 #define PANGO_IS_ENGINE_SHAPE(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_ENGINE_SHAPE))
0170 #define PANGO_ENGINE_SHAPE_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_ENGINE_SHAPE, PangoEngineShapeClass))
0171 #define PANGO_IS_ENGINE_SHAPE_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_ENGINE_SHAPE))
0172 #define PANGO_ENGINE_SHAPE_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_ENGINE_SHAPE, PangoEngineShapeClass))
0173
0174 typedef struct _PangoEngineShapeClass PangoEngineShapeClass;
0175
0176 /**
0177  * PangoEngineShape:
0178  *
0179  * The `PangoEngineShape` class is implemented by engines that
0180  * customize the rendering-system dependent part of the
0181  * Pango pipeline for a particular script or language.
0182  * A `PangoEngineShape` implementation is then specific to both
0183  * a particular rendering system or group of rendering systems
0184  * and to a particular script. For instance, there is one
0185  * `PangoEngineShape` implementation to handle shaping Arabic
0186  * for Fontconfig-based backends.
0187  *
0188  * Deprecated: 1.38
0189  **/
0190 struct _PangoEngineShape
0191 {
0192   PangoEngine parent_instance;
0193 };
0194
0195 /**
0196  * PangoEngineShapeClass:
0197  * @script_shape: Given a font, a piece of text, and a `PangoAnalysis`
0198  *   structure, converts characters to glyphs and positions the
0199  *   resulting glyphs. The results are stored in the `PangoGlyphString`
0200  *   that is passed in. (The implementation should resize it
0201  *   appropriately using pango_glyph_string_set_size()). All fields
0202  *   of the @log_clusters and @glyphs array must be filled in, with
0203  *   the exception that Pango will automatically generate
0204  *   `glyphs->glyphs[i].attr.is_cluster_start`
0205  *   using the @log_clusters array. Each input character must occur in one
0206  *   of the output logical clusters;
0207  *   if no rendering is desired for a character, this may involve
0208  *   inserting glyphs with the `PangoGlyph` ID %PANGO_GLYPH_EMPTY, which
0209  *   is guaranteed never to render. If the shaping fails for any reason,
0210  *   the shaper should return with an empty (zero-size) glyph string.
0211  *   If the shaper has not set the size on the glyph string yet, simply
0212  *   returning signals the failure too.
0213  * @covers: Returns the characters that this engine can cover
0214  *   with a given font for a given language. If not overridden, the default
0215  *   implementation simply returns the coverage information for the
0216  *   font itself unmodified.
0217  *
0218  * Class structure for `PangoEngineShape`
0219  *
0220  * Deprecated: 1.38
0221  **/
0222 struct _PangoEngineShapeClass
0223 {
0224   /*< private >*/
0225   PangoEngineClass parent_class;
0226
0227   /*< public >*/
0228   void (*script_shape) (PangoEngineShape    *engine,
0229             PangoFont           *font,
0230             const char          *item_text,
0231             unsigned int         item_length,
0232             const PangoAnalysis *analysis,
0233             PangoGlyphString    *glyphs,
0234             const char          *paragraph_text,
0235             unsigned int         paragraph_length);
0236   PangoCoverageLevel (*covers)   (PangoEngineShape *engine,
0237                   PangoFont        *font,
0238                   PangoLanguage    *language,
0239                   gunichar          wc);
0240 };
0241
0242 PANGO_DEPRECATED_IN_1_38
0243 GType pango_engine_shape_get_type (void) G_GNUC_CONST;
0244
0245 typedef struct _PangoEngineInfo PangoEngineInfo;
0246 typedef struct _PangoEngineScriptInfo PangoEngineScriptInfo;
0247
0248 /**
0249  * PangoEngineScriptInfo:
0250  * @script: a `PangoScript`. The value %PANGO_SCRIPT_COMMON has
0251  * the special meaning here of "all scripts"
0252  * @langs: a semicolon separated list of languages that this
0253  * engine handles for this script. This may be empty,
0254  * in which case the engine is saying that it is a
0255  * fallback choice for all languages for this range,
0256  * but should not be used if another engine
0257  * indicates that it is specific for the language for
0258  * a given code point. An entry in this list of "*"
0259  * indicates that this engine is specific to all
0260  * languages for this range.
0261  *
0262  * The `PangoEngineScriptInfo` structure contains
0263  * information about how the shaper covers a particular script.
0264  *
0265  * Deprecated: 1.38
0266  */
0267 struct _PangoEngineScriptInfo
0268 {
0269   PangoScript script;
0270   const gchar *langs;
0271 };
0272
0273 /**
0274  * PangoEngineInfo:
0275  * @id: a unique string ID for the engine.
0276  * @engine_type: a string identifying the engine type.
0277  * @render_type: a string identifying the render type.
0278  * @scripts: array of scripts this engine supports.
0279  * @n_scripts: number of items in @scripts.
0280  *
0281  * The `PangoEngineInfo` structure contains information about a particular
0282  * engine. It contains the following fields:
0283  *
0284  * Deprecated: 1.38
0285  */
0286 struct _PangoEngineInfo
0287 {
0288   const gchar *id;
0289   const gchar *engine_type;
0290   const gchar *render_type;
0291   PangoEngineScriptInfo *scripts;
0292   gint n_scripts;
0293 };
0294
0295 /**
0296  * script_engine_list: (skip)
0297  * @engines: location to store a pointer to an array of engines.
0298  * @n_engines: location to store the number of elements in @engines.
0299  *
0300  * Do not use.
0301  *
0302  * Deprecated: 1.38
0303  **/
0304 PANGO_DEPRECATED_IN_1_38
0305 void script_engine_list (PangoEngineInfo **engines,
0306              int              *n_engines);
0307
0308 /**
0309  * script_engine_init: (skip)
0310  * @module: a `GTypeModule` structure used to associate any
0311  *  GObject types created in this module with the module.
0312  *
0313  * Do not use.
0314  *
0315  * Deprecated: 1.38
0316  **/
0317 PANGO_DEPRECATED_IN_1_38
0318 void script_engine_init (GTypeModule *module);
0319
0320
0321 /**
0322  * script_engine_exit: (skip)
0323  *
0324  * Do not use.
0325  *
0326  * Deprecated: 1.38
0327  **/
0328 PANGO_DEPRECATED_IN_1_38
0329 void script_engine_exit (void);
0330
0331 /**
0332  * script_engine_create: (skip)
0333  * @id: the ID of an engine as reported by script_engine_list.
0334  *
0335  * Do not use.
0336  *
0337  * Deprecated: 1.38
0338  **/
0339 PANGO_DEPRECATED_IN_1_38
0340 PangoEngine *script_engine_create (const char *id);
0341
0342 /* Utility macro used by PANGO_ENGINE_LANG_DEFINE_TYPE and
0343  * PANGO_ENGINE_LANG_DEFINE_TYPE
0344  */
0345 #define PANGO_ENGINE_DEFINE_TYPE(name, prefix, class_init, instance_init, parent_type) \
0346 static GType prefix ## _type;                         \
0347 static void                               \
0348 prefix ## _register_type (GTypeModule *module)                \
0349 {                                     \
0350   const GTypeInfo object_info =                       \
0351     {                                     \
0352       sizeof (name ## Class),                         \
0353       (GBaseInitFunc) NULL,                       \
0354       (GBaseFinalizeFunc) NULL,                       \
0355       (GClassInitFunc) class_init,                    \
0356       (GClassFinalizeFunc) NULL,                      \
0357       NULL,          /* class_data */                     \
0358       sizeof (name),                              \
0359       0,             /* n_prelocs */                      \
0360       (GInstanceInitFunc) instance_init,                  \
0361       NULL           /* value_table */                    \
0362     };                                    \
0363                                       \
0364   prefix ## _type =  g_type_module_register_type (module, parent_type,    \
0365                           # name,         \
0366                           &object_info, 0);   \
0367 }
0368
0369 /**
0370  * PANGO_ENGINE_LANG_DEFINE_TYPE:
0371  * @name: Name of the the type to register (for example:, ArabicEngineFc)
0372  * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc)
0373  * @class_init: (nullable): Class initialization function for the new type
0374  * @instance_init: (nullable): Instance initialization function for the new type
0375  *
0376  * Outputs the necessary code for GObject type registration for a
0377  * `PangoEngineLang` class defined in a module. Two static symbols
0378  * are defined.
0379  *
0380  * <programlisting>
0381  *  static GType *prefix*_type;
0382  *  static void *prefix*_register_type (GTypeModule module);
0383  *
0384  * The *prefix*_register_type()
0385  * function should be called in your script_engine_init() function for
0386  * each type that your module implements, and then your script_engine_create()
0387  * function can create instances of the object as follows:
0388  *
0389  * ```
0390  * PangoEngine *engine = g_object_new (prefix_type, NULL);
0391  * ```
0392  *
0393  * Deprecated: 1.38
0394  **/
0395 #define PANGO_ENGINE_LANG_DEFINE_TYPE(name, prefix, class_init, instance_init)  \
0396   PANGO_ENGINE_DEFINE_TYPE (name, prefix,               \
0397                 class_init, instance_init,          \
0398                 PANGO_TYPE_ENGINE_LANG)
0399
0400 /**
0401  * PANGO_ENGINE_SHAPE_DEFINE_TYPE:
0402  * @name: Name of the the type to register (for example:, ArabicEngineFc)
0403  * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc)
0404  * @class_init: (nullable): Class initialization function for the new type
0405  * @instance_init: (nullable): Instance initialization function for the new type
0406  *
0407  * Outputs the necessary code for GObject type registration for a
0408  * `PangoEngineShape` class defined in a module. Two static symbols
0409  * are defined.
0410  *
0411  * <programlisting>
0412  *  static GType *prefix*_type;
0413  *  static void *prefix*_register_type (GTypeModule module);
0414  * </programlisting>
0415  *
0416  * The *prefix*_register_type()
0417  * function should be called in your script_engine_init() function for
0418  * each type that your module implements, and then your script_engine_create()
0419  * function can create instances of the object as follows:
0420  *
0421  * ```
0422  * PangoEngine *engine = g_object_new (prefix_type, NULL);
0423  * ```
0424  *
0425  * Deprecated: 1.38
0426  **/
0427 #define PANGO_ENGINE_SHAPE_DEFINE_TYPE(name, prefix, class_init, instance_init) \
0428   PANGO_ENGINE_DEFINE_TYPE (name, prefix,               \
0429                 class_init, instance_init,          \
0430                 PANGO_TYPE_ENGINE_SHAPE)
0431
0432 /* Macro used for possibly builtin Pango modules. Not useful
0433  * for externally build modules. If we are compiling a module standalone,
0434  * then we name the entry points script_engine_list, etc. But if we
0435  * are compiling it for inclusion directly in Pango, then we need them to
0436  * to have distinct names for this module, so we prepend a prefix.
0437  *
0438  * The two intermediate macros are to deal with details of the C
0439  * preprocessor; token pasting tokens must be function arguments,
0440  * and macro substitution isn't used on function arguments that
0441  * are used for token pasting.
0442  */
0443 #ifdef PANGO_MODULE_PREFIX
0444 #define PANGO_MODULE_ENTRY(func) _PANGO_MODULE_ENTRY2(PANGO_MODULE_PREFIX,func)
0445 #define _PANGO_MODULE_ENTRY2(prefix,func) _PANGO_MODULE_ENTRY3(prefix,func)
0446 #define _PANGO_MODULE_ENTRY3(prefix,func) prefix##_script_engine_##func
0447 #else
0448 #define PANGO_MODULE_ENTRY(func) script_engine_##func
0449 #endif
0450
0451 #endif /* PANGO_DISABLE_DEPRECATED */
0452
0453 #endif /* __GI_SCANNER__ */
0454
0455 G_END_DECLS
0456
0457 #endif /* __PANGO_ENGINE_H__ */