|
|
|
Pango Reference Manual | |
|---|
pango-querymodulespango-querymodules — Module registration utility |
pango-querymodules [module...]
pango-querymodules collects information about loadable
modules for Pango and writes it to stdout.
If called without arguments, it looks for modules in the Pango module path.
If called with arguments, it looks for the specified modules. The arguments may be absolute or relative paths.
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
PangoEngineInfo;
PangoEngineScriptInfo;
PangoEngine;
PangoEngineClass;
#define PANGO_RENDER_TYPE_NONE
void script_engine_list (PangoEngineInfo **engines,
int *n_engines);
void script_engine_init (GTypeModule *module);
void script_engine_exit (void);
PangoEngine * script_engine_create (const char *id);
Pango utilizes a module architecture in which the language-specific and render-system-specific components are provided by loadable modules. Each loadable module supplies one or more engines. Each engine has an associated engine type and render type. These two types are represented by strings.
Each dynamically-loaded module exports several functions which provide
the public API. These functions are script_engine_list(),
script_engine_init() and script_engine_exit, and
script_engine_create(). The latter three functions are used when
creating engines from the module at run time, while the first
function is used when building a catalog of all available modules.
typedef struct {
const gchar *id;
const gchar *engine_type;
const gchar *render_type;
PangoEngineScriptInfo *scripts;
gint n_scripts;
} PangoEngineInfo;
The PangoEngineInfo structure contains information about a particular engine. It contains the following fields:
const gchar * |
a unique string ID for the engine. |
const gchar * |
a string identifying the engine type. |
const gchar * |
a string identifying the render type. |
PangoEngineScriptInfo * |
array of scripts this engine supports. |
gint |
number of items in scripts.
|
typedef struct {
PangoScript script;
const gchar *langs;
} PangoEngineScriptInfo;
The PangoEngineScriptInfo structure contains information about how the shaper covers a particular script.
PangoScript |
a PangoScript. The value PANGO_SCRIPT_COMMON has
the special meaning here of "all scripts"
|
const gchar * |
a semicolon separated list of languages that this engine handles for this script. This may be empty, in which case the engine is saying that it is a fallback choice for all languages for this range, but should not be used if another engine indicates that it is specific for the language for a given code point. An entry in this list of "*" indicates that this engine is specific to all languages for this range. |
typedef struct _PangoEngine PangoEngine;
PangoEngine is the base class for all types of language and script specific engines. It has no functionality by itself.
#define PANGO_RENDER_TYPE_NONE "PangoRenderNone"
A string constant defining the render type for engines that are not rendering-system specific.
void script_engine_list (PangoEngineInfo **engines, int *n_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.
|
location to store a pointer to an array of engines. |
|
location to store the number of elements in engines.
|
void script_engine_init (GTypeModule *module);
Function to be provided by a module to register any GObject types in the module.
|
a GTypeModule structure used to associate any GObject types created in this module with the module. |
void script_engine_exit (void);
Function to be provided by the module that is called when the module is unloading. Frequently does nothing.
PangoEngine * script_engine_create (const char *id);
Function to be provided by the module to create an instance of one of the engines implemented by the module.
|
the ID of an engine as reported by script_engine_list. |
Returns : |
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.)
|
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
typedef PangoOTTag; PangoOTInfo; PangoOTBuffer; PangoOTGlyph; PangoOTRuleset; PangoOTRulesetDescription; enum PangoOTTableType; PangoOTFeatureMap; #define PANGO_OT_TAG_MAKE (c1,c2,c3,c4) #define PANGO_OT_TAG_MAKE_FROM_STRING (s) #define PANGO_OT_ALL_GLYPHS #define PANGO_OT_NO_FEATURE #define PANGO_OT_NO_SCRIPT #define PANGO_OT_DEFAULT_LANGUAGE #define PANGO_OT_TAG_DEFAULT_LANGUAGE #define PANGO_OT_TAG_DEFAULT_SCRIPT PangoOTInfo * pango_ot_info_get (FT_Face face); gboolean pango_ot_info_find_script (PangoOTInfo *info, PangoOTTableType table_type, PangoOTTag script_tag, guint *script_index); gboolean pango_ot_info_find_language (PangoOTInfo *info, PangoOTTableType table_type, guint script_index, PangoOTTag language_tag, guint *language_index, guint *required_feature_index); gboolean pango_ot_info_find_feature (PangoOTInfo *info, PangoOTTableType table_type, PangoOTTag feature_tag, guint script_index, guint language_index, guint *feature_index); PangoOTTag * pango_ot_info_list_scripts (PangoOTInfo *info, PangoOTTableType table_type); PangoOTTag * pango_ot_info_list_languages (PangoOTInfo *info, PangoOTTableType table_type, guint script_index, PangoOTTag language_tag); PangoOTTag * pango_ot_info_list_features (PangoOTInfo *info, PangoOTTableType table_type, PangoOTTag tag, guint script_index, guint language_index); PangoOTBuffer * pango_ot_buffer_new (PangoFcFont *font); void pango_ot_buffer_destroy (PangoOTBuffer *buffer); void pango_ot_buffer_clear (PangoOTBuffer *buffer); void pango_ot_buffer_add_glyph (PangoOTBuffer *buffer, guint glyph, guint properties, guint cluster); void pango_ot_buffer_set_rtl (PangoOTBuffer *buffer, gboolean rtl); void pango_ot_buffer_set_zero_width_marks (PangoOTBuffer *buffer, gboolean zero_width_marks); void pango_ot_buffer_get_glyphs (const PangoOTBuffer *buffer, PangoOTGlyph **glyphs, int *n_glyphs); void pango_ot_buffer_output (const PangoOTBuffer *buffer, PangoGlyphString *glyphs); const PangoOTRuleset * pango_ot_ruleset_get_for_description (PangoOTInfo *info, const PangoOTRulesetDescription *desc); PangoOTRuleset * pango_ot_ruleset_new (PangoOTInfo *info); PangoOTRuleset * pango_ot_ruleset_new_for (PangoOTInfo *info, PangoScript script, PangoLanguage *language); PangoOTRuleset * pango_ot_ruleset_new_from_description (PangoOTInfo *info, const PangoOTRulesetDescription *desc); void pango_ot_ruleset_add_feature (PangoOTRuleset *ruleset, PangoOTTableType table_type, guint feature_index, gulong property_bit); gboolean pango_ot_ruleset_maybe_add_feature (PangoOTRuleset *ruleset, PangoOTTableType table_type, PangoOTTag feature_tag, gulong property_bit); guint pango_ot_ruleset_maybe_add_features (PangoOTRuleset *ruleset, PangoOTTableType table_type, const PangoOTFeatureMap *features, guint n_features); guint pango_ot_ruleset_get_feature_count (const PangoOTRuleset *ruleset, guint *n_gsub_features, guint *n_gpos_features); void pango_ot_ruleset_substitute (const PangoOTRuleset *ruleset, PangoOTBuffer *buffer); void pango_ot_ruleset_position (const PangoOTRuleset *ruleset, PangoOTBuffer *buffer); PangoOTRulesetDescription * pango_ot_ruleset_description_copy (const PangoOTRulesetDescription *desc); gboolean pango_ot_ruleset_description_equal (const PangoOTRulesetDescription *desc1, const PangoOTRulesetDescription *desc2); void pango_ot_ruleset_description_free (PangoOTRulesetDescription *desc); guint pango_ot_ruleset_description_hash (const PangoOTRulesetDescription *desc); PangoOTTag pango_ot_tag_from_language (PangoLanguage *language); PangoOTTag pango_ot_tag_from_script (PangoScript script); PangoLanguage * pango_ot_tag_to_language (PangoOTTag language_tag); PangoScript pango_ot_tag_to_script (PangoOTTag script_tag);
Functions and macros in this section are used to implement the OpenType Layout features and algorithms. These are mostly useful when writing Fontconfig-based shaping engines
typedef guint32 PangoOTTag;
The PangoOTTag typedef is used to represent TrueType and OpenType
four letter tags inside Pango. Use PANGO_OT_TAG_MAKE()
or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create PangoOTTags manually.
typedef struct _PangoOTInfo PangoOTInfo;
The PangoOTInfo struct contains the various
tables associated with an OpenType font. It contains only private fields and
should only be accessed via the pango_ot_info_* functions
which are documented below. To obtain a PangoOTInfo,
use pango_ot_info_new().
typedef struct _PangoOTBuffer PangoOTBuffer;
The PangoOTBuffer structure is used to store strings of glyphs associated
with a PangoFcFont, suitable for OpenType layout processing. It contains
only private fields and should only be accessed via the
pango_ot_buffer_* functions which are documented below.
To obtain a PangoOTBuffer, use pango_ot_buffer_new().
typedef struct {
guint32 glyph;
guint properties;
guint cluster;
gushort component;
gushort ligID;
guint internal;
} PangoOTGlyph;
The PangoOTGlyph structure represents a single glyph together with information used for OpenType layout processing of the glyph. It contains the following fields.
guint32 |
the glyph itself. |
guint |
the properties value, identifying which features should be
applied on this glyph. See pango_ruleset_add_feature().
|
guint |
the cluster that this glyph belongs to. |
gushort |
a component value, set by the OpenType layout engine. |
gushort |
a ligature index value, set by the OpenType layout engine. |
guint |
for Pango internal use |
typedef struct _PangoOTRuleset PangoOTRuleset;
The PangoOTRuleset structure holds a
set of features selected from the tables in an OpenType font.
(A feature is an operation such as adjusting glyph positioning
that should be applied to a text feature such as a certain
type of accent.) A PangoOTRuleset
is created with pango_ot_ruleset_new(), features are added
to it with pango_ot_ruleset_add_feature(), then it is
applied to a PangoGlyphString with pango_ot_ruleset_shape().
typedef struct {
PangoScript script;
PangoLanguage *language;
const PangoOTFeatureMap *static_gsub_features;
guint n_static_gsub_features;
const PangoOTFeatureMap *static_gpos_features;
guint n_static_gpos_features;
const PangoOTFeatureMap *other_features;
guint n_other_features;
} PangoOTRulesetDescription;
The PangoOTRuleset structure holds all the information needed
to build a complete PangoOTRuleset from an OpenType font.
The main use of this struct is to act as the key for a per-font
hash of rulesets. The user populates a ruleset description and
gets the ruleset using pango_ot_ruleset_get_for_description()
or create a new one using pango_ot_ruleset_new_from_description().
PangoScript |
a PangoScript. |
PangoLanguage * |
a PangoLanguage. |
const PangoOTFeatureMap * |
static map of GSUB features, or NULL.
|
guint |
length of static_gsub_features, or 0.
|
const PangoOTFeatureMap * |
static map of GPOS features, or NULL.
|
guint |
length of static_gpos_features, or 0.
|
const PangoOTFeatureMap * |
map of extra features to add to both GSUB and GPOS, or NULL.
Unlike the static maps, this pointer need not live beyond
the life of function calls taking this struct.
|
guint |
length of other_features, or 0.
|
Since 1.18
typedef enum
{
PANGO_OT_TABLE_GSUB,
PANGO_OT_TABLE_GPOS
} PangoOTTableType;
The PangoOTTableType enumeration values are used to
identify the various OpenType tables in the
pango_ot_info_* functions.
typedef struct {
char feature_name[5];
gulong property_bit;
} PangoOTFeatureMap;
The PangoOTFeatureMap typedef is used to represent an OpenType feature with the property bit associated with it. The feature tag is represented as a char array instead of a PangoOTTag for convenience.
char |
feature tag in represented as four-letter ASCII string. |
gulong |
the property bit to use for this feature. See
pango_ot_ruleset_add_feature() for details.
|
Since 1.18
#define PANGO_OT_TAG_MAKE(c1,c2,c3,c4) ((PangoOTTag) FT_MAKE_TAG (c1, c2, c3, c4))
Creates a PangoOTTag from four characters. This is similar and
compatible with the FT_MAKE_TAG()
|
First character. |
|
Second character. |
|
Third character. |
|
Fourth character. |
#define PANGO_OT_TAG_MAKE_FROM_STRING(s)
Creates a PangoOTTag from a string. The string should be at least
four characters long (pad with space characters if needed), and need
not be nul-terminated. This is a convenience wrapper around
PANGO_OT_TAG_MAKE(), but cannot be used in certain situations, for
example, as a switch expression, as it dereferences pointers.
|
The string representation of the tag. |
#define PANGO_OT_ALL_GLYPHS ((guint) 0xFFFF)
This is used as the property bit in pango_ot_ruleset_add_feature() when a
feature should be applied to all glyphs.
Since 1.16
#define PANGO_OT_NO_FEATURE ((guint) 0xFFFF)
This is used as a feature index that represent no feature, that is, should be
skipped. It may be returned as feature index by pango_ot_info_find_feature()
if the feature is not found, and pango_ot_rulset_add_feature() function
automatically skips this value, so no special handling is required by the
user.
Since 1.18
#define PANGO_OT_NO_SCRIPT ((guint) 0xFFFF)
This is used as a script index that represent no script, that is, when the
requested script was not found, and a default ('DFLT') script was not found
either. It may be returned as script index by pango_ot_info_find_script()
if the script or a default script are not found, all other functions
taking a script index essentially return if the input script index is
this value, so no special handling is required by the user.
Since 1.18
#define PANGO_OT_DEFAULT_LANGUAGE ((guint) 0xFFFF)
This is used as the language index in pango_ot_info_find_feature() when
the default language system of the script is desired.
It is also returned by pango_ot_info_find_language() if the requested language
is not found, or the requested language tag was PANGO_OT_TAG_DEFAULT_LANGUAGE.
The end result is that one can always call pango_ot_tag_from_language()
followed by pango_ot_info_find_language() and pass the result to
pango_ot_info_find_feature() without having to worry about falling back to
default language system explicitly.
Since 1.16
#define PANGO_OT_TAG_DEFAULT_LANGUAGE PANGO_OT_TAG_MAKE ('d', 'f', 'l', 't')
This is a PangoOTTag representing a special language tag 'dflt'. It is
returned as language tag by pango_ot_tag_from_language() if the requested
language is not found. It is safe to pass this value to
pango_ot_info_find_language() as that function falls back to returning default
language-system if the requested language tag is not found.
Since 1.18
#define PANGO_OT_TAG_DEFAULT_SCRIPT PANGO_OT_TAG_MAKE ('D', 'F', 'L', 'T')
This is a PangoOTTag representing the special script tag 'DFLT'. It is
returned as script tag by pango_ot_tag_from_script() if the requested script
is not found.
Since 1.18
PangoOTInfo * pango_ot_info_get (FT_Face face);
Returns the PangoOTInfo structure for the given FreeType font face.
|
a FT_Face. |
Returns : |
the PangoOTInfo for face. This object will have
the same lifetime as face.
|
Since 1.2
gboolean pango_ot_info_find_script (PangoOTInfo *info, PangoOTTableType table_type, PangoOTTag script_tag, guint *script_index);
Finds the index of a script. If not found, tries to find the 'DFLT'
and then 'dflt' scripts and return the index of that in script_index.
If none of those is found either, PANGO_OT_NO_SCRIPT is placed in
script_index.
All other functions taking an input script_index parameter know
how to handle PANGO_OT_NO_SCRIPT, so one can ignore the return
value of this function completely and proceed, to enjoy the automatic
fallback to the 'DFLT'/'dflt' script.
|
a PangoOTInfo. |
|
the table type to obtain information about. |
|
the tag of the script to find. |
|
location to store the index of the script, or NULL.
|
Returns : |
TRUE if the script was found.
|
gboolean pango_ot_info_find_language (PangoOTInfo *info, PangoOTTableType table_type, guint script_index, PangoOTTag language_tag, guint *language_index, guint *required_feature_index);
Finds the index of a language and its required feature index.
If the language is not found, sets language_index to
PANGO_OT_DEFAULT_LANGUAGE and the required feature of the default language
system is returned in required_feature_index. For best compatibility with
some fonts, also searches the language system tag 'dflt' before falling
back to the default language system, but that is transparent to the user.
The user can simply ignore the return value of this function to
automatically fall back to the default language system.
|
a PangoOTInfo. |
|
the table type to obtain information about. |
|
the index of the script whose languages are searched. |
|
the tag of the language to find. |
|
location to store the index of the language, or NULL.
|
|
location to store the required feature index of
the language, or NULL.
|
Returns : |
TRUE if the language was found.
|
gboolean pango_ot_info_find_feature (PangoOTInfo *info, PangoOTTableType table_type, PangoOTTag feature_tag, guint script_index, guint language_index, guint *feature_index);
Finds the index of a feature. If the feature is not found, sets
feature_index to PANGO_OT_NO_FEATURE, which is safe to pass to
pango_ot_ruleset_add_feature() and similar functions.
In the future, this may set feature_index to an special value that if used
in pango_ot_ruleset_add_feature() will ask Pango to synthesize the
requested feature based on Unicode properties and data. However, this
function will still return FALSE in those cases. So, users may want to
ignore the return value of this function in certain cases.
|
a PangoOTInfo. |
|
the table type to obtain information about. |
|
the tag of the feature to find. |
|
the index of the script. |
|
the index of the language whose features are searched,
or PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script.
|
|
location to store the index of the feature, or NULL.
|
Returns : |
TRUE if the feature was found.
|
PangoOTTag * pango_ot_info_list_scripts (PangoOTInfo *info, PangoOTTableType table_type);
Obtains the list of available scripts.
|
a PangoOTInfo. |
|
the table type to obtain information about. |
Returns : |
a newly-allocated zero-terminated array containing the tags of the
available scripts. Should be freed using g_free().
|
PangoOTTag * pango_ot_info_list_languages (PangoOTInfo *info, PangoOTTableType table_type, guint script_index, PangoOTTag language_tag);
Obtains the list of available languages for a given script.
|
a PangoOTInfo. |
|
the table type to obtain information about. |
|
the index of the script to list languages for. |
|
unused parameter. |
Returns : |
a newly-allocated zero-terminated array containing the tags of the
available languages. Should be freed using g_free().
|
PangoOTTag * pango_ot_info_list_features (PangoOTInfo *info, PangoOTTableType table_type, PangoOTTag tag, guint script_index, guint language_index);
Obtains the list of features for the given language of the given script.
|
a PangoOTInfo. |
|
the table type to obtain information about. |
|
unused parameter. |
|
the index of the script to obtain information about. |
|
the index of the language to list features for, or
PANGO_OT_DEFAULT_LANGUAGE, to list features for the default
language of the script.
|
Returns : |
a newly-allocated zero-terminated array containing the tags of the
available features. Should be freed using g_free().
|
PangoOTBuffer * pango_ot_buffer_new (PangoFcFont *font);
Creates a new PangoOTBuffer for the given OpenType font.
|
a PangoFcFont |
Returns : |
the newly allocated PangoOTBuffer, which should
be freed with pango_ot_buffer_destroy().
|
Since 1.4
void pango_ot_buffer_destroy (PangoOTBuffer *buffer);
Destroys a PangoOTBuffer and free all associated memory.
|
a PangoOTBuffer |
Since 1.4
void pango_ot_buffer_clear (PangoOTBuffer *buffer);
Empties a PangoOTBuffer, make it ready to add glyphs to.
|
a PangoOTBuffer |
Since 1.4
void pango_ot_buffer_add_glyph (PangoOTBuffer *buffer, guint glyph, guint properties, guint cluster);
Appends a glyph to a PangoOTBuffer, with properties identifying which
features should be applied on this glyph. See pango_ruleset_add_feature().
|
a PangoOTBuffer |
|
the glyph index to add, like a PangoGlyph |
|
the glyph properties |
|
the cluster that this glyph belongs to |
Since 1.4
void pango_ot_buffer_set_rtl (PangoOTBuffer *buffer, gboolean rtl);
Sets whether glyphs will be rendered right-to-left. This setting is needed for proper horizontal positioning of right-to-left scripts.
|
a PangoOTBuffer |
|
TRUE for right-to-left text
|
Since 1.4
void pango_ot_buffer_set_zero_width_marks
(PangoOTBuffer *buffer,
gboolean zero_width_marks);
Sets whether characters with a mark class should be forced to zero width. This setting is needed for proper positioning of Arabic accents, but will produce incorrect results with standard OpenType Indic fonts.
|
a PangoOTBuffer |
|
TRUE if characters with a mark class should
be forced to zero width.
|
Since 1.6
void pango_ot_buffer_get_glyphs (const PangoOTBuffer *buffer, PangoOTGlyph **glyphs, int *n_glyphs);
Gets the glyph array contained in a PangoOTBuffer. The glyphs are owned by the buffer and should not be freed, and are only valid as long as buffer is not modified.
|
a PangoOTBuffer |
|
location to store the array of glyphs, or NULL
|
|
location to store the number of glyphs, or NULL
|
Since 1.4
void pango_ot_buffer_output (const PangoOTBuffer *buffer, PangoGlyphString *glyphs);
Exports the glyphs in a PangoOTBuffer into a PangoGlyphString. This is typically used after the OpenType layout processing is over, to convert the resulting glyphs into a generic Pango glyph string.
|
a PangoOTBuffer |
|
a PangoGlyphString |
Since 1.4
const PangoOTRuleset * pango_ot_ruleset_get_for_description (PangoOTInfo *info, const PangoOTRulesetDescription *desc);
Returns a ruleset for the given OpenType info and ruleset
description. Rulesets are created on demand using
pango_ot_ruleset_new_from_description().
The returned ruleset should not be modified or destroyed.
The static feature map members of desc should be alive as
long as info is.
|
a PangoOTInfo. |
|
a PangoOTRulesetDescription. |
Returns : |
the PangoOTRuleset for desc. This object will have
the same lifetime as info.
|
Since 1.18
PangoOTRuleset * pango_ot_ruleset_new (PangoOTInfo *info);
Creates a new PangoOTRuleset for the given OpenType info.
|
a PangoOTInfo. |
Returns : |
the newly allocated PangoOTRuleset, which
should be freed with g_object_unref().
|
PangoOTRuleset * pango_ot_ruleset_new_for (PangoOTInfo *info, PangoScript script, PangoLanguage *language);
Creates a new PangoOTRuleset for the given OpenType info, script, and language.
This function is part of a convenience scheme that highly simplifies using a PangoOTRuleset to represent features for a specific pair of script and language. So one can use this function passing in the script and language of interest, and later try to add features to the ruleset by just specifying the feature name or tag, without having to deal with finding script, language, or feature indices manually.
In excess to what pango_ot_ruleset_new() does, this function will:
script and language using pango_ot_tag_from_script() and
pango_ot_tag_from_language(),
PANGO_OT_TABLE_GSUB and PANGO_OT_TABLE_GPOS,
find the script index of the script tag found and the language
system index of the language tag found in that script system, using
pango_ot_info_find_script() and pango_ot_info_find_language(),
pango_ot_ruleset_add_feature(),
pango_ot_ruleset_maybe_add_feature() and
pango_ot_ruleset_maybe_add_features().
Because of the way return values of pango_ot_info_find_script() and
pango_ot_info_find_language() are ignored, this function automatically
finds and uses the 'DFLT' script and the default language-system.
|
a PangoOTInfo. |
|
a PangoScript. |
|
a PangoLanguage. |
Returns : |
the newly allocated PangoOTRuleset, which
should be freed with g_object_unref().
|
Since 1.18
PangoOTRuleset * pango_ot_ruleset_new_from_description (PangoOTInfo *info, const PangoOTRulesetDescription *desc);
Creates a new PangoOTRuleset for the given OpenType infor and matching the given ruleset description.
This is a convenience function that calls pango_ot_ruleset_new_for() and
adds the static GSUB/GPOS features to the resulting ruleset, followed by
adding other features to both GSUB and GPOS.
The static feature map members of desc should be alive as
long as info is.
|
a PangoOTInfo. |
|
a PangoOTRulesetDescription. |
Returns : |
the newly allocated PangoOTRuleset, which
should be freed with g_object_unref().
|
Since 1.18
void pango_ot_ruleset_add_feature (PangoOTRuleset *ruleset, PangoOTTableType table_type, guint feature_index, gulong property_bit);
Adds a feature to the ruleset.
|
a PangoOTRuleset. |
|
the table type to add a feature to. |
|
the index of the feature to add. |
|
the property bit to use for this feature. Used to identify
the glyphs that this feature should be applied to, or
PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
|
gboolean pango_ot_ruleset_maybe_add_feature (PangoOTRuleset *ruleset, PangoOTTableType table_type, PangoOTTag feature_tag, gulong property_bit);
This is a convenience function that first tries to find the feature
using pango_ot_info_find_feature() and the ruleset script and language
passed to pango_ot_ruleset_new_for(),
and if the feature is found, adds it to the ruleset.
If ruleset was not created using pango_ot_ruleset_new_for(), this function
does nothing.
|
a PangoOTRuleset. |
|
the table type to add a feature to. |
|
the tag of the feature to add. |
|
the property bit to use for this feature. Used to identify
the glyphs that this feature should be applied to, or
PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
|
Returns : |
TRUE if the feature was found and added to ruleset,
FALSE otherwise.
|
Since 1.18
guint pango_ot_ruleset_maybe_add_features (PangoOTRuleset *ruleset, PangoOTTableType table_type, const PangoOTFeatureMap *features, guint n_features);
This is a convenience function that
for each feature in the feature map array features
converts the feature name to a PangoOTTag feature tag using PANGO_OT_TAG_MAKE()
and calls pango_ot_ruleset_maybe_add_feature() on it.
|
a PangoOTRuleset. |
|
the table type to add features to. |
|
array of feature name and property bits to add. |
|
number of feature records in features array.
|
Returns : |
The number of features in features that were found
and added to ruleset.
|
Since 1.18
guint pango_ot_ruleset_get_feature_count (const PangoOTRuleset *ruleset, guint *n_gsub_features, guint *n_gpos_features);
Gets the number of GSUB and GPOS features in the ruleset.
|
a PangoOTRuleset. |
|
location to store number of GSUB features, or NULL.
|
|
location to store number of GPOS features, or NULL.
|
Returns : |
Total number of features in the ruleset.
|
Since 1.18
void pango_ot_ruleset_substitute (const PangoOTRuleset *ruleset, PangoOTBuffer *buffer);
Performs the OpenType GSUB substitution on buffer using the features
in ruleset
|
a PangoOTRuleset. |
|
a PangoOTBuffer. |
Since 1.4
void pango_ot_ruleset_position (const PangoOTRuleset *ruleset, PangoOTBuffer *buffer);
Performs the OpenType GPOS positioning on buffer using the features
in ruleset
|
a PangoOTRuleset. |
|
a PangoOTBuffer. |
Since 1.4
PangoOTRulesetDescription * pango_ot_ruleset_description_copy (const PangoOTRulesetDescription *desc);
Creates a copy of desc, which should be freed with
pango_ot_ruleset_description_free(). Primarily used internally
by pango_ot_ruleset_get_for_description() to cache rulesets for
ruleset descriptions.
|
ruleset description to copy |
Returns : |
the newly allocated PangoOTRulesetDescription, which
should be freed with pango_ot_ruleset_description_free().
|
Since 1.18
gboolean pango_ot_ruleset_description_equal (const PangoOTRulesetDescription *desc1, const PangoOTRulesetDescription *desc2);
Compares two ruleset descriptions for equality.
Two ruleset descriptions are considered equal if the rulesets
they describe are provably identical. This means that their
script, language, and all feature sets should be equal. For static feature
sets, the array addresses are compared directly, while for other
features, the list of features is compared one by one.
(Two ruleset descriptions may result in identical rulesets
being created, but still compare FALSE.)
|
a ruleset description |
|
a ruleset description |
Returns : |
TRUE if two ruleset descriptions are identical,
FALSE otherwise.
|
Since 1.18
void pango_ot_ruleset_description_free (PangoOTRulesetDescription *desc);
Frees a ruleset description allocated by
pango_ot_ruleset_description_copy().
|
an allocated PangoOTRulesetDescription |
Since 1.18
guint pango_ot_ruleset_description_hash (const PangoOTRulesetDescription *desc);
Computes a hash of a PangoOTRulesetDescription structure suitable
to be used, for example, as an argument to g_hash_table_new().
|
a ruleset description |
Returns : |
the hash value. |
Since 1.18
PangoOTTag pango_ot_tag_from_language (PangoLanguage *language);
Finds the OpenType language-system tag best describing language.
|
A PangoLanguage, or NULL
|
Returns : |
PangoOTTag best matching language or
PANGO_OT_TAG_DEFAULT_LANGUAGE if none found or if language
is NULL.
|
Since 1.18
PangoOTTag pango_ot_tag_from_script (PangoScript script);
Finds the OpenType script tag corresponding to script.
The PANGO_SCRIPT_COMMON, PANGO_SCRIPT_INHERITED, and
PANGO_SCRIPT_UNKNOWN scripts are mapped to the OpenType
'DFLT' script tag that is also defined as
PANGO_OT_TAG_DEFAULT_SCRIPT.
Note that multiple PangoScript values may map to the same
OpenType script tag. In particular, PANGO_SCRIPT_HIRAGANA
and PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'.
|
A PangoScript |
Returns : |
PangoOTTag corresponding to script or
PANGO_OT_TAG_DEFAULT_SCRIPT if none found.
|
Since 1.18
PangoLanguage * pango_ot_tag_to_language (PangoOTTag language_tag);
Finds a PangoLanguage corresponding to language_tag.
|
A PangoOTTag OpenType language-system tag |
Returns : |
PangoLanguage best matching language_tag or
PangoLanguage corresponding to the string "xx" if none found.
|
Since 1.18
PangoScript pango_ot_tag_to_script (PangoOTTag script_tag);
Finds the PangoScript corresponding to script_tag.
The 'DFLT' script tag is mapped to PANGO_SCRIPT_COMMON.
Note that an OpenType script tag may correspond to multiple
PangoScript values. In such cases, the PangoScript value
with the smallest value is returned.
In particular, PANGO_SCRIPT_HIRAGANA
and PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'.
This function will return PANGO_SCRIPT_HIRAGANA for
'kana'.
|
A PangoOTTag OpenType script tag |
Returns : |
PangoScript corresponding to script_tag or
PANGO_SCRIPT_UNKNOWN if none found.
|
Since 1.18
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
#define PANGO_VERSION_ENCODE (major, minor, micro) #define PANGO_VERSION #define PANGO_VERSION_MAJOR #define PANGO_VERSION_MINOR #define PANGO_VERSION_MICRO #define PANGO_VERSION_STRING #define PANGO_VERSION_CHECK (major,minor,micro) int pango_version (void); const char * pango_version_string (void); const char * pango_version_check (int required_major, int required_minor, int required_micro);
The capital-letter macros defined here can be used to check the version of Pango at compile-time, and to encode Pango versions into integers. The functions can be used to check the version of the linked Pango library at run-time.
#define PANGO_VERSION_ENCODE(major, minor, micro)
This macro encodes the given Pango version into an integer. The numbers
returned by PANGO_VERSION and pango_version() are encoded using this macro.
Two encoded version numbers can be compared as integers.
|
the major component of the version number |
|
the minor component of the version number |
|
the micro component of the version number |
#define PANGO_VERSION
The version of Pango available at compile-time, encoded using
PANGO_VERSION_ENCODE().
#define PANGO_VERSION_MAJOR 1
The major component of the version of Pango available at compile-time.
#define PANGO_VERSION_MINOR 26
The minor component of the version of Pango available at compile-time.
#define PANGO_VERSION_MICRO 0
The micro component of the version of Pango available at compile-time.
#define PANGO_VERSION_STRING "1.26.0"
A string literal containing the version of Pango available at compile-time.
#define PANGO_VERSION_CHECK(major,minor,micro)
Checks that the version of Pango available at compile-time is not older than the provided version number.
|
the major component of the version number |
|
the minor component of the version number |
|
the micro component of the version number |
int pango_version (void);
This is similar to the macro PANGO_VERSION except that
it returns the encoded version of Pango available at run-time,
as opposed to the version available at compile-time.
A version number can be encoded into an integer using
PANGO_VERSION_ENCODE().
Returns : |
The encoded version of Pango library available at run time. |
Since 1.16
const char * pango_version_string (void);
This is similar to the macro PANGO_VERSION_STRING except that
it returns the version of Pango available at run-time, as opposed to
the version available at compile-time.
Returns : |
A string containing the version of Pango library available at run time. The returned string is owned by Pango and should not be modified or freed. |
Since 1.16
const char * pango_version_check (int required_major,
int required_minor,
int required_micro);
Checks that the Pango library in use is compatible with the
given version. Generally you would pass in the constants
PANGO_VERSION_MAJOR, PANGO_VERSION_MINOR, PANGO_VERSION_MICRO
as the three arguments to this function; that produces
a check that the library in use at run-time is compatible with
the version of Pango the application or module was compiled against.
Compatibility is defined by two things: first the version
of the running library is newer than the version
required_major.required_minor.required_micro. Second
the running library must be binary compatible with the
version required_major.required_minor.required_micro
(same major version.)
For compile-time version checking use PANGO_VERSION_CHECK().
|
the required major version. |
|
the required minor version. |
|
the required major version. |
Returns : |
NULL if the Pango library is compatible with the
given version, or a string describing the version mismatch.
The returned string is owned by Pango and should not be modified
or freed.
|
Since 1.16
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
FreeType Fonts and RenderingFreeType Fonts and Rendering — Functions for shape engines to manipulate FreeType fonts |
PangoFT2FontMap;
#define PANGO_RENDER_TYPE_FT2
PangoFontMap * pango_ft2_font_map_new (void);
void pango_ft2_font_map_set_resolution (PangoFT2FontMap *fontmap,
double dpi_x,
double dpi_y);
PangoContext * pango_ft2_font_map_create_context (PangoFT2FontMap *fontmap);
void (*PangoFT2SubstituteFunc) (FcPattern *pattern,
gpointer data);
void pango_ft2_font_map_set_default_substitute
(PangoFT2FontMap *fontmap,
PangoFT2SubstituteFunc func,
gpointer data,
GDestroyNotify notify);
void pango_ft2_font_map_substitute_changed
(PangoFT2FontMap *fontmap);
PangoContext * pango_ft2_get_context (double dpi_x,
double dpi_y);
void pango_ft2_render (FT_Bitmap *bitmap,
PangoFont *font,
PangoGlyphString *glyphs,
gint x,
gint y);
void pango_ft2_render_transformed (FT_Bitmap *bitmap,
const PangoMatrix *matrix,
PangoFont *font,
PangoGlyphString *glyphs,
int x,
int y);
void pango_ft2_render_layout_line (FT_Bitmap *bitmap,
PangoLayoutLine *line,
int x,
int y);
void pango_ft2_render_layout_line_subpixel
(FT_Bitmap *bitmap,
PangoLayoutLine *line,
int x,
int y);
void pango_ft2_render_layout (FT_Bitmap *bitmap,
PangoLayout *layout,
int x,
int y);
void pango_ft2_render_layout_subpixel (FT_Bitmap *bitmap,
PangoLayout *layout,
int x,
int y);
PangoGlyph pango_ft2_get_unknown_glyph (PangoFont *font);
int pango_ft2_font_get_kerning (PangoFont *font,
PangoGlyph left,
PangoGlyph right);
FT_Face pango_ft2_font_get_face (PangoFont *font);
PangoCoverage * pango_ft2_font_get_coverage (PangoFont *font,
PangoLanguage *language);
PangoFontMap * pango_ft2_font_map_for_display (void);
void pango_ft2_shutdown_display (void);
The macros and functions in this section are used to access fonts and render text to bitmaps using the FreeType 2 library.
typedef struct _PangoFT2FontMap PangoFT2FontMap;
The PangoFT2FontMap is the PangoFontMap implementation for FreeType fonts.
#define PANGO_RENDER_TYPE_FT2 "PangoRenderFT2"
PANGO_RENDER_TYPE_FT2 is deprecated and should not be used in newly-written code.
A string constant that was used to identify shape engines that work
with the FreeType backend. See PANGO_RENDER_TYPE_FC for the replacement.
PangoFontMap * pango_ft2_font_map_new (void);
Create a new PangoFT2FontMap object; a fontmap is used
to cache information about available fonts, and holds
certain global parameters such as the resolution and
the default substitute function (see
pango_ft2_font_map_set_default_substitute()).
Returns : |
the newly created fontmap object. Unref
with g_object_unref() when you are finished with it.
|
Since 1.2
void pango_ft2_font_map_set_resolution (PangoFT2FontMap *fontmap, double dpi_x, double dpi_y);
Sets the horizontal and vertical resolutions for the fontmap.
|
a PangoFT2Fontmap |
|
dots per inch in the X direction |
|
dots per inch in the Y direction |
Since 1.2
PangoContext * pango_ft2_font_map_create_context (PangoFT2FontMap *fontmap);
pango_ft2_font_map_create_context has been deprecated since version 1.22 and should not be used in newly-written code. Use pango_font_map_create_context() instead.
Create a PangoContext for the given fontmap.
|
a PangoFT2Fontmap |
Returns : |
the newly created context; free with g_object_unref().
|
Since 1.2
void (*PangoFT2SubstituteFunc) (FcPattern *pattern,
gpointer data);
Function type for doing final config tweaking on prepared FcPatterns.
|
the FcPattern to tweak. |
|
user data. |
void pango_ft2_font_map_set_default_substitute
(PangoFT2FontMap *fontmap,
PangoFT2SubstituteFunc func,
gpointer data,
GDestroyNotify notify);
Sets a function that will be called to do final configuration substitution on a FcPattern before it is used to load the font. This function can be used to do things like set hinting and antialiasing options.
|
a PangoFT2FontMap |
|
function to call to to do final config tweaking on FcPattern objects. |
|
data to pass to func
|
|
function to call when data is no longer used.
|
Since 1.2
void pango_ft2_font_map_substitute_changed
(PangoFT2FontMap *fontmap);
Call this function any time the results of the
default substitution function set with
pango_ft2_font_map_set_default_substitute() change.
That is, if your substitution function will return different
results for the same input pattern, you must call this function.
|
a PangoFT2Fontmap |
Since 1.2
PangoContext * pango_ft2_get_context (double dpi_x, double dpi_y);
pango_ft2_get_context has been deprecated since version 1.22 and should not be used in newly-written code. Use pango_font_map_create_context() instead.
Retrieves a PangoContext for the default PangoFT2 fontmap
(see pango_ft2_fontmap_get_for_display()) and sets the resolution
for the default fontmap to dpi_x by dpi_y.
|
the horizontal DPI of the target device |
|
the vertical DPI of the target device |
Returns : |
the new PangoContext |
void pango_ft2_render (FT_Bitmap *bitmap,
PangoFont *font,
PangoGlyphString *glyphs,
gint x,
gint y);
Renders a PangoGlyphString onto a FreeType2 bitmap.
|
the FreeType2 bitmap onto which to draw the string |
|
the font in which to draw the string |
|
the glyph string to draw |
|
the x position of the start of the string (in pixels) |
|
the y position of the baseline (in pixels) |
void pango_ft2_render_transformed (FT_Bitmap *bitmap,
const PangoMatrix *matrix,
PangoFont *font,
PangoGlyphString *glyphs,
int x,
int y);
Renders a PangoGlyphString onto a FreeType2 bitmap, possibly
transforming the layed-out coordinates through a transformation
matrix. Note that the transformation matrix for font is not
changed, so to produce correct rendering results, the font
must have been loaded using a PangoContext with an identical
transformation matrix to that passed in to this function.
|
the FreeType2 bitmap onto which to draw the string |
|
a PangoMatrix, or NULL to use an identity transformation
|
|
the font in which to draw the string |
|
the glyph string to draw |
|
the x position of the start of the string (in Pango units in user space coordinates) |
|
the y position of the baseline (in Pango units in user space coordinates) |
Since 1.6
void pango_ft2_render_layout_line (FT_Bitmap *bitmap,
PangoLayoutLine *line,
int x,
int y);
Render a PangoLayoutLine onto a FreeType2 bitmap
|
a FT_Bitmap to render the line onto |
|
a PangoLayoutLine |
|
the x position of start of string (in pixels) |
|
the y position of baseline (in pixels) |
void pango_ft2_render_layout_line_subpixel
(FT_Bitmap *bitmap,
PangoLayoutLine *line,
int x,
int y);
Render a PangoLayoutLine onto a FreeType2 bitmap, with he location specified in fixed-point Pango units rather than pixels. (Using this will avoid extra inaccuracies from rounding to integer pixels multiple times, even if the final glyph positions are integers.)
|
a FT_Bitmap to render the line onto |
|
a PangoLayoutLine |
|
the x position of start of string (in Pango units) |
|
the y position of baseline (in Pango units) |
Since 1.6
void pango_ft2_render_layout (FT_Bitmap *bitmap,
PangoLayout *layout,
int x,
int y);
Render a PangoLayout onto a FreeType2 bitmap
|
a FT_Bitmap to render the layout onto |
|
a PangoLayout |
|
the X position of the left of the layout (in pixels) |
|
the Y position of the top of the layout (in pixels) |
void pango_ft2_render_layout_subpixel (FT_Bitmap *bitmap,
PangoLayout *layout,
int x,
int y);
Render a PangoLayout onto a FreeType2 bitmap, with he location specified in fixed-point Pango units rather than pixels. (Using this will avoid extra inaccuracies from rounding to integer pixels multiple times, even if the final glyph positions are integers.)
|
a FT_Bitmap to render the layout onto |
|
a PangoLayout |
|
the X position of the left of the layout (in Pango units) |
|
the Y position of the top of the layout (in Pango units) |
Since 1.6
PangoGlyph pango_ft2_get_unknown_glyph (PangoFont *font);
pango_ft2_get_unknown_glyph is deprecated and should not be used in newly-written code.
Return the index of a glyph suitable for drawing unknown characters with
font, or PANGO_GLYPH_EMPTY if no suitable glyph found.
If you want to draw an unknown-box for a character that is not covered
by the font,
use PANGO_GET_UNKNOWN_GLYPH() instead.
|
a PangoFont |
Returns : |
a glyph index into font, or PANGO_GLYPH_EMPTY
|
int pango_ft2_font_get_kerning (PangoFont *font, PangoGlyph left, PangoGlyph right);
pango_ft2_font_get_kerning is deprecated and should not be used in newly-written code.
Retrieves kerning information for a combination of two glyphs.
Use pango_fc_font_kern_glyphs() instead.
|
a PangoFont |
|
the left PangoGlyph |
|
the right PangoGlyph |
Returns : |
The amount of kerning (in Pango units) to apply for the given combination of glyphs. |
FT_Face pango_ft2_font_get_face (PangoFont *font);
pango_ft2_font_get_face is deprecated and should not be used in newly-written code.
Returns the native FreeType2 FT_Face structure used for this PangoFont. This may be useful if you want to use FreeType2 functions directly.
Use pango_fc_font_lock_face() instead; when you are done with a
face from pango_fc_font_lock_face() you must call
pango_fc_font_unlock_face().
PangoCoverage * pango_ft2_font_get_coverage (PangoFont *font, PangoLanguage *language);
pango_ft2_font_get_coverage is deprecated and should not be used in newly-written code.
Gets the PangoCoverage for a PangoFT2Font. Use
pango_font_get_coverage() instead.
|
a PangoFT2Font. |
|
a language tag. |
Returns : |
a PangoCoverage. |
PangoFontMap * pango_ft2_font_map_for_display (void);
pango_ft2_font_map_for_display is deprecated and should not be used in newly-written code.
Returns a PangoFT2FontMap. This font map is cached and should
not be freed. If the font map is no longer needed, it can
be released with pango_ft2_shutdown_display(). Use of the
global PangoFT2 fontmap is deprecated; use pango_ft2_font_map_new()
instead.
Returns : |
a PangoFT2FontMap. |
void pango_ft2_shutdown_display (void);
pango_ft2_shutdown_display is deprecated and should not be used in newly-written code.
Free the global fontmap. (See pango_ft2_font_map_for_display())
Use of the global PangoFT2 fontmap is deprecated.
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | ||||
PangoXftFont;
PangoXftFontMap;
#define PANGO_RENDER_TYPE_XFT
PangoContext * pango_xft_get_context (Display *display,
int screen);
PangoFontMap * pango_xft_get_font_map (Display *display,
int screen);
void pango_xft_set_default_substitute (Display *display,
int screen,
PangoXftSubstituteFunc func,
gpointer data,
GDestroyNotify notify);
void (*PangoXftSubstituteFunc) (FcPattern *pattern,
gpointer data);
void pango_xft_substitute_changed (Display *display,
int screen);
void pango_xft_shutdown_display (Display *display,
int screen);
XftFont * pango_xft_font_get_font (PangoFont *font);
Display * pango_xft_font_get_display (PangoFont *font);
gboolean pango_xft_font_has_char (PangoFont *font,
gunichar wc);
FT_Face pango_xft_font_lock_face (PangoFont *font);
void pango_xft_font_unlock_face (PangoFont *font);
guint pango_xft_font_get_glyph (PangoFont *font,
gunichar wc);
PangoGlyph pango_xft_font_get_unknown_glyph (PangoFont *font,
gunichar wc);
PangoXftRenderer;
PangoXftRendererClass;
PangoRenderer * pango_xft_renderer_new (Display *display,
int screen);
void pango_xft_renderer_set_draw (PangoXftRenderer *xftrenderer,
XftDraw *draw);
void pango_xft_renderer_set_default_color
(PangoXftRenderer *xftrenderer,
PangoColor *default_color);
void pango_xft_render (XftDraw *draw,
XftColor *color,
PangoFont *font,
PangoGlyphString *glyphs,
gint x,
gint y);
void pango_xft_picture_render (Display *display,
Picture src_picture,
Picture dest_picture,
PangoFont *font,
PangoGlyphString *glyphs,
gint x,
gint y);
void pango_xft_render_transformed (XftDraw *draw,
XftColor *color,
PangoMatrix *matrix,
PangoFont *font,
PangoGlyphString *glyphs,
int x,
int y);
void pango_xft_render_layout_line (XftDraw *draw,
XftColor *color,
PangoLayoutLine *line,
int x,
int y);
void pango_xft_render_layout (XftDraw *draw,
XftColor *color,
PangoLayout *layout,
int x,
int y);
GObject +----PangoFont +----PangoFcFont +----PangoXftFont
GObject +----PangoFontMap +----PangoFcFontMap +----PangoXftFontMap
GObject +----PangoRenderer +----PangoXftRenderer
The Xft library is a library for displaying fonts on the X window system; internally it uses the fontconfig library to locate font files, and the FreeType library to load and render fonts. The Xft backend is the recommended Pango font backend for screen display with X. (The Cairo back end is another possibility.)
Using the Xft backend is generally straightforward;
pango_xft_get_context() creates a context for a specified display
and screen. You can then create a PangoLayout with that context
and render it with pango_xft_render_layout(). At a more advanced
level, the low-level fontconfig options used for rendering fonts
can be affected using pango_xft_set_default_substitute(), and
pango_xft_substitute_changed().
A range of functions for drawing pieces of a layout, such as individual layout lines and glyphs strings are provided. You can also directly create a PangoXftRenderer. Finally, in some advanced cases, it is useful to derive from PangoXftRenderer. Deriving from PangoXftRenderer is useful for two reasons. One reason is be to support custom attributes by overriding PangoRendererClass virtual functions like 'prepare_run' or 'draw_shape'. The reason is to customize exactly how the final bits are drawn to the destination by overriding the PangoXftRendererClass virtual functions 'composite_glyphs' and 'composite_trapezoids'.
typedef struct _PangoXftFont PangoXftFont;
PangoXftFont is an implementation of PangoFcFont using the Xft library for rendering. It is used in conjunction with PangoXftFontMap.
typedef struct _PangoXftFontMap PangoXftFontMap;
PangoXftFontMap is an implementation of PangoFcFontMap suitable for the Xft library as the renderer. It is used in to create fonts of type PangoXftFont.
#define PANGO_RENDER_TYPE_XFT "PangoRenderXft"
PANGO_RENDER_TYPE_XFT is deprecated and should not be used in newly-written code.
A string constant that was used to identify shape engines that work
with the Xft backend. See PANGO_RENDER_TYPE_FC for the replacement.
PangoContext * pango_xft_get_context (Display *display, int screen);
pango_xft_get_context has been deprecated since version 1.22 and should not be used in newly-written code. Use pango_xft_get_font_map() followed by
pango_font_map_create_context() instead.
Retrieves a PangoContext appropriate for rendering with Xft fonts on the given screen of the given display.
|
an X display. |
|
an X screen. |
Returns : |
the new PangoContext. |
PangoFontMap * pango_xft_get_font_map (Display *display, int screen);
Returns the PangoXftFontmap for the given display and screen. The fontmap is owned by Pango and will be valid until the display is closed.
|
an X display |
|
the screen number of a screen within display
|
Returns : |
a PangoFontMap object, owned by Pango. |
Since 1.2
void pango_xft_set_default_substitute (Display *display,
int screen,
PangoXftSubstituteFunc func,
gpointer data,
GDestroyNotify notify);
Sets a function that will be called to do final configuration substitution on a FcPattern before it is used to load the font. This function can be used to do things like set hinting and antialiasing options.
|
an X Display |
|
the screen number of a screen within display
|
|
function to call to to do final config tweaking on FcPattern objects. |
|
data to pass to func
|
|
function to call when data is no longer used.
|
Since 1.2
void (*PangoXftSubstituteFunc) (FcPattern *pattern,
gpointer data);
Function type for doing final config tweaking on prepared FcPatterns.
|
the FcPattern to tweak. |
|
user data. |
void pango_xft_substitute_changed (Display *display,
int screen);
Call this function any time the results of the
default substitution function set with
pango_xft_set_default_substitute() change.
That is, if your substitution function will return different
results for the same input pattern, you must call this function.
|
an X Display |
|
the screen number of a screen within display
|
Since 1.2
void pango_xft_shutdown_display (Display *display,
int screen);
Release any resources that have been cached for the
combination of display and screen. Note that when the
X display is closed, resources are released automatically,
without needing to call this function.
|
an X display |
|
the screen number of a screen within display
|
Since 1.2
XftFont * pango_xft_font_get_font (PangoFont *font);
Returns the XftFont of a font.
Display * pango_xft_font_get_display (PangoFont *font);
Returns the X display of the XftFont of a font.
|
a PangoFont. |
Returns : |
the X display of the XftFont associated to font.
|
gboolean pango_xft_font_has_char (PangoFont *font, gunichar wc);
pango_xft_font_has_char is deprecated and should not be used in newly-written code.
Determines whether font has a glyph for the codepoint wc.
Use pango_fc_font_has_char() instead.
|
a PangoFont for the Xft backend |
|
Unicode codepoint to look up |
Returns : |
TRUE if font has the requested codepoint.
|
Since 1.2
FT_Face pango_xft_font_lock_face (PangoFont *font);
pango_xft_font_lock_face is deprecated and should not be used in newly-written code.
Gets the FreeType FT_Face associated with a font,
This face will be kept around until you call
pango_xft_font_unlock_face().
Use pango_fc_font_lock_face() instead.
|
a PangoFont. |
Returns : |
the FreeType FT_Face associated with font.
|
Since 1.2
void pango_xft_font_unlock_face (PangoFont *font);
pango_xft_font_unlock_face is deprecated and should not be used in newly-written code.
Releases a font previously obtained with
pango_xft_font_lock_face().
Use pango_fc_font_unlock_face() instead.
|
a PangoFont. |
Since 1.2
guint pango_xft_font_get_glyph (PangoFont *font, gunichar wc);
pango_xft_font_get_glyph is deprecated and should not be used in newly-written code.
Gets the glyph index for a given Unicode character
for font. If you only want to determine
whether the font has the glyph, use pango_xft_font_has_char().
Use pango_fc_font_get_glyph() instead.
|
a PangoFont for the Xft backend |
|
Unicode codepoint to look up |
Returns : |
the glyph index, or 0, if the Unicode character does not exist in the font. |
Since 1.2
PangoGlyph pango_xft_font_get_unknown_glyph (PangoFont *font, gunichar wc);
pango_xft_font_get_unknown_glyph is deprecated and should not be used in newly-written code.
Returns the index of a glyph suitable for drawing wc as an
unknown character.
Use PANGO_GET_UNKNOWN_GLYPH() instead.
|
a PangoFont. |
|
the Unicode character for which a glyph is needed. |
Returns : |
a glyph index into font.
|
typedef struct _PangoXftRenderer PangoXftRenderer;
PangoXftRenderer is a subclass of PangoRenderer used for rendering with Pango's Xft backend. It can be used directly, or it can be further subclassed to modify exactly how drawing of individual elements occurs.
Since 1.8
typedef struct {
void (*composite_trapezoids) (PangoXftRenderer *xftrenderer,
PangoRenderPart part,
XTrapezoid *trapezoids,
int n_trapezoids);
void (*composite_glyphs) (PangoXftRenderer *xftrenderer,
XftFont *xft_font,
XftGlyphSpec *glyphs,
int n_glyphs);
} PangoXftRendererClass;
The class structure for PangoXftRenderer
|
draw the specified trapezoids using
the current color and other attributes for part
|
|
draw the specified glyphs using the current foreground color and other foreground attributes |
Since 1.8
PangoRenderer * pango_xft_renderer_new (Display *display, int screen);
Create a new PangoXftRenderer to allow rendering Pango objects
with the Xft library. You must call pango_xft_renderer_set_draw() before
using the renderer.
|
an X display |
|
the index of the screen for display to which rendering will be done
|
Returns : |
the newly created PangoXftRenderer, which should
be freed with g_object_unref().
|
Since 1.8
void pango_xft_renderer_set_draw (PangoXftRenderer *xftrenderer, XftDraw *draw);
Sets the XftDraw object that the renderer is drawing to. The renderer must not be currently active.
|
a PangoXftRenderer |
|
a XftDraw |
Since 1.8
void pango_xft_renderer_set_default_color
(PangoXftRenderer *xftrenderer,
PangoColor *default_color);
Sets the default foreground color for a XftRenderer.
|
a XftRenderer |
|
the default foreground color |
Since 1.8
void pango_xft_render (XftDraw *draw,
XftColor *color,
PangoFont *font,
PangoGlyphString *glyphs,
gint x,
gint y);
Renders a PangoGlyphString onto an XftDraw object wrapping an X drawable.
|
the XftDraw object. |
|
the color in which to draw the string |
|
the font in which to draw the string |
|
the glyph string to draw |
|
the x position of start of string (in pixels) |
|
the y position of baseline (in pixels) |
void pango_xft_picture_render (Display *display,
Picture src_picture,
Picture dest_picture,
PangoFont *font,
PangoGlyphString *glyphs,
gint x,
gint y);
Renders a PangoGlyphString onto an Xrender Picture object.
|
an X display |
|
the source picture to draw the string with |
|
the destination picture to draw the string onto |
|
the font in which to draw the string |
|
the glyph string to draw |
|
the x position of start of string (in pixels) |
|
the y position of baseline (in pixels) |
void pango_xft_render_transformed (XftDraw *draw,
XftColor *color,
PangoMatrix *matrix,
PangoFont *font,
PangoGlyphString *glyphs,
int x,
int y);
Renders a PangoGlyphString onto a XftDraw, possibly
transforming the layed-out coordinates through a transformation
matrix. Note that the transformation matrix for font is not
changed, so to produce correct rendering results, the font
must have been loaded using a PangoContext with an identical
transformation matrix to that passed in to this function.
|
an XftDraw |
|
the color in which to draw the glyphs |
|
a PangoMatrix, or NULL to use an identity transformation
|
|
the font in which to draw the string |
|
the glyph string to draw |
|
the x position of the start of the string (in Pango units in user space coordinates) |
|
the y position of the baseline (in Pango units in user space coordinates) |
Since 1.8
void pango_xft_render_layout_line (XftDraw *draw,
XftColor *color,
PangoLayoutLine *line,
int x,
int y);
Render a PangoLayoutLine onto a XftDraw
|
an XftDraw |
|
the foreground color in which to draw the layout line (may be overridden by color attributes) |
|
a PangoLayoutLine |
|
the x position of start of string (in Pango units) |
|
the y position of baseline (in Pango units) |
Since 1.8
void pango_xft_render_layout (XftDraw *draw,
XftColor *color,
PangoLayout *layout,
int x,
int y);
Render a PangoLayout onto a XftDraw
|
an XftDraw |
|
the foreground color in which to draw the layout (may be overridden by color attributes) |
|
a PangoLayout |
|
the X position of the left of the layout (in Pango units) |
|
the Y position of the top of the layout (in Pango units) |
Since 1.8
|
|
Pango Reference Manual | |
|---|
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
enum PangoScript; #define PANGO_TYPE_SCRIPT PangoScriptIter; PangoScript pango_script_for_unichar (gunichar ch); PangoLanguage * pango_script_get_sample_language (PangoScript script); PangoScriptIter * pango_script_iter_new (const char *text, int length); void pango_script_iter_get_range (PangoScriptIter *iter, G_CONST_RETURN char **start, G_CONST_RETURN char **end, PangoScript *script); gboolean pango_script_iter_next (PangoScriptIter *iter); void pango_script_iter_free (PangoScriptIter *iter); PangoLanguage; #define PANGO_TYPE_LANGUAGE PangoLanguage * pango_language_from_string (const char *language); const char * pango_language_to_string (PangoLanguage *language); gboolean pango_language_matches (PangoLanguage *language, const char *range_list); gboolean pango_language_includes_script (PangoLanguage *language, PangoScript script); const PangoScript * pango_language_get_scripts (PangoLanguage *language, int *num_scripts); PangoLanguage * pango_language_get_default (void); const char * pango_language_get_sample_string (PangoLanguage *language);
The functions in this section are used to identify the writing system, or script of individual characters and of ranges within a larger text string.
typedef enum { /* ISO 15924 code */
PANGO_SCRIPT_INVALID_CODE = -1,
PANGO_SCRIPT_COMMON = 0, /* Zyyy */
PANGO_SCRIPT_INHERITED, /* Qaai */
PANGO_SCRIPT_ARABIC, /* Arab */
PANGO_SCRIPT_ARMENIAN, /* Armn */
PANGO_SCRIPT_BENGALI, /* Beng */
PANGO_SCRIPT_BOPOMOFO, /* Bopo */
PANGO_SCRIPT_CHEROKEE, /* Cher */
PANGO_SCRIPT_COPTIC, /* Qaac */
PANGO_SCRIPT_CYRILLIC, /* Cyrl (Cyrs) */
PANGO_SCRIPT_DESERET, /* Dsrt */
PANGO_SCRIPT_DEVANAGARI, /* Deva */
PANGO_SCRIPT_ETHIOPIC, /* Ethi */
PANGO_SCRIPT_GEORGIAN, /* Geor (Geon, Geoa) */
PANGO_SCRIPT_GOTHIC, /* Goth */
PANGO_SCRIPT_GREEK, /* Grek */
PANGO_SCRIPT_GUJARATI, /* Gujr */
PANGO_SCRIPT_GURMUKHI, /* Guru */
PANGO_SCRIPT_HAN, /* Hani */
PANGO_SCRIPT_HANGUL, /* Hang */
PANGO_SCRIPT_HEBREW, /* Hebr */
PANGO_SCRIPT_HIRAGANA, /* Hira */
PANGO_SCRIPT_KANNADA, /* Knda */
PANGO_SCRIPT_KATAKANA, /* Kana */
PANGO_SCRIPT_KHMER, /* Khmr */
PANGO_SCRIPT_LAO, /* Laoo */
PANGO_SCRIPT_LATIN, /* Latn (Latf, Latg) */
PANGO_SCRIPT_MALAYALAM, /* Mlym */
PANGO_SCRIPT_MONGOLIAN, /* Mong */
PANGO_SCRIPT_MYANMAR, /* Mymr */
PANGO_SCRIPT_OGHAM, /* Ogam */
PANGO_SCRIPT_OLD_ITALIC, /* Ital */
PANGO_SCRIPT_ORIYA, /* Orya */
PANGO_SCRIPT_RUNIC, /* Runr */
PANGO_SCRIPT_SINHALA, /* Sinh */
PANGO_SCRIPT_SYRIAC, /* Syrc (Syrj, Syrn, Syre) */
PANGO_SCRIPT_TAMIL, /* Taml */
PANGO_SCRIPT_TELUGU, /* Telu */
PANGO_SCRIPT_THAANA, /* Thaa */
PANGO_SCRIPT_THAI, /* Thai */
PANGO_SCRIPT_TIBETAN, /* Tibt */
PANGO_SCRIPT_CANADIAN_ABORIGINAL, /* Cans */
PANGO_SCRIPT_YI, /* Yiii */
PANGO_SCRIPT_TAGALOG, /* Tglg */
PANGO_SCRIPT_HANUNOO, /* Hano */
PANGO_SCRIPT_BUHID, /* Buhd */
PANGO_SCRIPT_TAGBANWA, /* Tagb */
/* Unicode-4.0 additions */
PANGO_SCRIPT_BRAILLE, /* Brai */
PANGO_SCRIPT_CYPRIOT, /* Cprt */
PANGO_SCRIPT_LIMBU, /* Limb */
PANGO_SCRIPT_OSMANYA, /* Osma */
PANGO_SCRIPT_SHAVIAN, /* Shaw */
PANGO_SCRIPT_LINEAR_B, /* Linb */
PANGO_SCRIPT_TAI_LE, /* Tale */
PANGO_SCRIPT_UGARITIC, /* Ugar */
/* Unicode-4.1 additions */
PANGO_SCRIPT_NEW_TAI_LUE, /* Talu */
PANGO_SCRIPT_BUGINESE, /* Bugi */
PANGO_SCRIPT_GLAGOLITIC, /* Glag */
PANGO_SCRIPT_TIFINAGH, /* Tfng */
PANGO_SCRIPT_SYLOTI_NAGRI, /* Sylo */
PANGO_SCRIPT_OLD_PERSIAN, /* Xpeo */
PANGO_SCRIPT_KHAROSHTHI, /* Khar */
/* Unicode-5.0 additions */
PANGO_SCRIPT_UNKNOWN, /* Zzzz */
PANGO_SCRIPT_BALINESE, /* Bali */
PANGO_SCRIPT_CUNEIFORM, /* Xsux */
PANGO_SCRIPT_PHOENICIAN, /* Phnx */
PANGO_SCRIPT_PHAGS_PA, /* Phag */
PANGO_SCRIPT_NKO, /* Nkoo */
/* Unicode-5.1 additions */
PANGO_SCRIPT_KAYAH_LI, /* Kali */
PANGO_SCRIPT_LEPCHA, /* Lepc */
PANGO_SCRIPT_REJANG, /* Rjng */
PANGO_SCRIPT_SUNDANESE, /* Sund */
PANGO_SCRIPT_SAURASHTRA, /* Saur */
PANGO_SCRIPT_CHAM, /* Cham */
PANGO_SCRIPT_OL_CHIKI, /* Olck */
PANGO_SCRIPT_VAI, /* Vaii */
PANGO_SCRIPT_CARIAN, /* Cari */
PANGO_SCRIPT_LYCIAN, /* Lyci */
PANGO_SCRIPT_LYDIAN /* Lydi */
} PangoScript;
The PangoScript enumeration identifies different writing systems. The values correspond to the names as defined in the Unicode standard. Note that new types may be added in the future. Applications should be ready to handle unknown values. This enumeration is interchangeable with GUnicodeScript. See Unicode Standard Annex #24: Script names.
a value never returned from pango_script_for_unichar()
|
|
| a character used by multiple different scripts | |
| a mark glyph that takes its script from the base glyph to which it is attached | |
| Arabic | |
| Armenian | |
| Bengali | |
| Bopomofo | |
| Cherokee | |
| Coptic | |
| Cyrillic | |
| Deseret | |
| Devanagari | |
| Ethiopic | |
| Georgian | |
| Gothic | |
| Greek | |
| Gujarati | |
| Gurmukhi | |
| Han | |
| Hangul | |
| Hebrew | |
| Hiragana | |
| Kannada | |
| Katakana | |
| Khmer | |
| Lao | |
| Latin | |
| Malayalam | |
| Mongolian | |
| Myanmar | |
| Ogham | |
| Old Italic | |
| Oriya | |
| Runic | |
| Sinhala | |
| Syriac | |
| Tamil | |
| Telugu | |
| Thaana | |
| Thai | |
| Tibetan | |
| Canadian Aboriginal | |
| Yi | |
| Tagalog | |
| Hanunoo | |
| Buhid | |
| Tagbanwa | |
| Braille | |
| Cypriot | |
| Limbu | |
| Osmanya | |
| Shavian | |
| Linear B | |
| Tai Le | |
| Ugaritic | |
| New Tai Lue. Since 1.10 | |
| Buginese. Since 1.10 | |
| Glagolitic. Since 1.10 | |
| Tifinagh. Since 1.10 | |
| Syloti Nagri. Since 1.10 | |
| Old Persian. Since 1.10 | |
| Kharoshthi. Since 1.10 | |
| an unassigned code point. Since 1.14 | |
| Balinese. Since 1.14 | |
| Cuneiform. Since 1.14 | |
| Phoenician. Since 1.14 | |
| Phags-pa. Since 1.14 | |
| N'Ko. Since 1.14 | |
| Kayah Li. Since 1.20.1 | |
| Lepcha. Since 1.20.1 | |
| Rejang. Since 1.20.1 | |
| Sundanese. Since 1.20.1 | |
| Saurashtra. Since 1.20.1 | |
| Cham. Since 1.20.1 | |
| Ol Chiki. Since 1.20.1 | |
| Vai. Since 1.20.1 | |
| Carian. Since 1.20.1 | |
| Lycian. Since 1.20.1 | |
| Lydian. Since 1.20.1 |
#define PANGO_TYPE_SCRIPT (pango_script_get_type())
The GObject type for PangoScript
typedef struct _PangoScriptIter PangoScriptIter;
A PangoScriptIter is used to iterate through a string and identify ranges in different scripts.
PangoScript pango_script_for_unichar (gunichar ch);
Looks up the PangoScript for a particular character (as defined by
Unicode Standard Annex 24). No check is made for ch being a
valid Unicode character; if you pass in invalid character, the
result is undefined.
As of Pango 1.18, this function simply returns the return value of
g_unichar_get_script().
|
a Unicode character |
Returns : |
the PangoScript for the character. |
Since 1.4
PangoLanguage * pango_script_get_sample_language (PangoScript script);
Given a script, finds a language tag that is reasonably
representative of that script. This will usually be the
most widely spoken or used language written in that script:
for instance, the sample language for PANGO_SCRIPT_CYRILLIC
is ru (Russian), the sample language
for PANGO_SCRIPT_ARABIC is ar.
For some
scripts, no sample language will be returned because there
is no language that is sufficiently representative. The best
example of this is PANGO_SCRIPT_HAN, where various different
variants of written Chinese, Japanese, and Korean all use
significantly different sets of Han characters and forms
of shared characters. No sample language can be provided
for many historical scripts as well.
As of 1.18, this function checks the environment variables
PANGO_LANGUAGE and LANGUAGE (checked in that order) first.
If one of them is set, it is parsed as a list of language tags
separated by colons or other separators. This function
will return the first language in the parsed list that Pango
believes may use script for writing. This last predicate
is tested using pango_language_includes_script(). This can
be used to control Pango's font selection for non-primary
languages. For example, a PANGO_LANGUAGE enviroment variable
set to "en:fa" makes Pango choose fonts suitable for Persian (fa)
instead of Arabic (ar) when a segment of Arabic text is found
in an otherwise non-Arabic text. The same trick can be used to
choose a default language for PANGO_SCRIPT_HAN when setting
context language is not feasible.
|
a PangoScript |
Returns : |
a PangoLanguage that is representative
of the script, or NULL if no such language exists.
|
Since 1.4
PangoScriptIter * pango_script_iter_new (const char *text, int length);
Create a new PangoScriptIter, used to break a string of
Unicode into runs by text. No copy is made of text, so
the caller needs to make sure it remains valid until
the iterator is freed with pango_script_iter_free().
|
a UTF-8 string |
|
length of text, or -1 if text is nul-terminated.
|
Returns : |
the new script iterator, initialized
to point at the first range in the text, which should be
freed with pango_script_iter_free(). If the string is
empty, it will point at an empty range.
|
Since 1.4
void pango_script_iter_get_range (PangoScriptIter *iter, G_CONST_RETURN char **start, G_CONST_RETURN char **end, PangoScript *script);
Gets information about the range to which iter currently points.
The range is the set of locations p where *start <= p < *end.
(That is, it doesn't include the character stored at *end)
|
a PangoScriptIter |
|
location to store start position of the range, or NULL
|
|
location to store end position of the range, or NULL
|
|
location to store script for range, or NULL
|
Since 1.4
gboolean pango_script_iter_next (PangoScriptIter *iter);
Advances a PangoScriptIter to the next range. If iter
is already at the end, it is left unchanged and FALSE
is returned.
|
a PangoScriptIter |
Returns : |
TRUE if iter was successfully advanced.
|
Since 1.4
void pango_script_iter_free (PangoScriptIter *iter);
Frees a PangoScriptIter created with pango_script_iter_new().
|
a PangoScriptIter |
Since 1.4
typedef struct _PangoLanguage PangoLanguage;
The PangoLanguage structure is used to represent a language.
PangoLanguage pointers can be efficiently copied and compared with each other.
#define PANGO_TYPE_LANGUAGE (pango_language_get_type ())
The GObject type for PangoLanguage.
PangoLanguage * pango_language_from_string (const char *language);
Take a RFC-3066 format language tag as a string and convert it to a PangoLanguage pointer that can be efficiently copied (copy the pointer) and compared with other language tags (compare the pointer.)
This function first canonicalizes the string by converting it to lowercase, mapping '_' to '-', and stripping all characters other than letters and '-'.
Use pango_language_get_default() if you want to get the PangoLanguage for
the current locale of the process.
|
a string representing a language tag, or NULL
|
Returns : |
an opaque pointer to a PangoLanguage structure, or NULL
if language was NULL. The returned pointer will be valid
forever after, and should not be freed.
|
const char * pango_language_to_string (PangoLanguage *language);
Gets the RFC-3066 format string representing the given language tag.
|
a language tag. |
Returns : |
a string representing the language tag. This is owned by Pango and should not be freed. |
gboolean pango_language_matches (PangoLanguage *language, const char *range_list);
Checks if a language tag matches one of the elements in a list of language ranges. A language tag is considered to match a range in the list if the range is '*', the range is exactly the tag, or the range is a prefix of the tag, and the character after it in the tag is '-'.
|
a language tag (see pango_language_from_string()),
NULL is allowed and matches nothing but '*'
|
|
a list of language ranges, separated by ';', ':',
',', or space characters.
Each element must either be '*', or a RFC 3066 language range
canonicalized as by pango_language_from_string()
|
Returns : |
TRUE if a match was found.
|
gboolean pango_language_includes_script (PangoLanguage *language, PangoScript script);
Determines if script is one of the scripts used to
write language. The returned value is conservative;
if nothing is known about the language tag language,
TRUE will be returned, since, as far as Pango knows,
script might be used to write language.
This routine is used in Pango's itemization process when determining if a supplied language tag is relevant to a particular section of text. It probably is not useful for applications in most circumstances.
This function uses pango_language_get_scripts() internally.
|
a PangoLanguage, or NULL
|
|
a PangoScript |
Returns : |
TRUE if script is one of the scripts used
to write language or if nothing is known about language
(including the case that language is NULL),
FALSE otherwise.
|
Since 1.4
const PangoScript * pango_language_get_scripts (PangoLanguage *language, int *num_scripts);
Determines the scripts used to to write language.
If nothing is known about the language tag language,
or if language is NULL, then NULL is returned.
The list of scripts returned starts with the script that the
language uses most and continues to the one it uses least.
The value num_script points at will be set to the number
of scripts in the returned array (or zero if NULL is returned).
Most languages use only one script for writing, but there are
some that use two (Latin and Cyrillic for example), and a few
use three (Japanese for example). Applications should not make
any assumptions on the maximum number of scripts returned
though, except that it is positive if the return value is not
NULL, and it is a small number.
The pango_language_includes_script() function uses this function
internally.
|
a PangoLanguage, or NULL
|
|
location to return number of scripts, or NULL
|
Returns : |
An array of PangoScript values, with the
number of entries in the array stored in num_scripts, or
NULL if Pango does not have any information about this
particular language tag (also the case if language is NULL).
The returned array is owned by Pango and should not be modified
or freed.
|
Since 1.22
PangoLanguage * pango_language_get_default (void);
Returns the PangoLanguage for the current locale of the process. Note that this can change over the life of an application.
On Unix systems, this is the return value is derived from
setlocale(LC_CTYPE, NULL), and the user can
affect this through the environment variables LC_ALL, LC_CTYPE or
LANG (checked in that order). The locale string typically is in
the form lang_COUNTRY, where lang is an ISO-639 language code, and
COUNTRY is an ISO-3166 country code. For instance, sv_FI for
Swedish as written in Finland or pt_BR for Portuguese as written in
Brazil.
On Windows, the C library does not use any such environment
variables, and setting them won't affect the behavior of functions
like ctime(). The user sets the locale through the Regional Options
in the Control Panel. The C library (in the setlocale() function)
does not use country and language codes, but country and language
names spelled out in English.
However, this function does check the above environment
variables, and does return a Unix-style locale string based on
either said environment variables or the thread's current locale.
Your application should call setlocale(LC_ALL, "");
for the user settings to take effect. Gtk+ does this in its initialization
functions automatically (by calling gtk_set_locale()).
See man setlocale for more details.
Returns : |
the default language as a PangoLanguage, must not be freed. |
Since 1.16
const char * pango_language_get_sample_string (PangoLanguage *language);
Get a string that is representative of the characters needed to render a particular language.
The sample text may be a pangram, but is not necessarily. It is chosen to be demonstrative of normal text in the language, as well as exposing font feature requirements unique to the language. It is suitable for use as sample text in a font selection dialog.
If language is NULL, the default language as found by
pango_language_get_default() is used.
If Pango does not have a sample string for language, the classic
"The quick brown fox..." is returned. This can be detected by
comparing the returned pointer value to that returned for (non-existent)
language code "xx". That is, compare to:
pango_language_get_sample_string (pango_language_from_string ("xx"))
|
a PangoLanguage, or NULL
|
Returns : |
the sample string. This value is owned by Pango and should not be freed. |
|
|
Pango Reference Manual | |
|---|
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
Win32 Fonts and RenderingWin32 Fonts and Rendering — Functions for shape engines to manipulate Win32 fonts |
#define PANGO_RENDER_TYPE_WIN32 PangoContext * pango_win32_get_context (void); void pango_win32_render (HDC hdc, PangoFont *font, PangoGlyphString *glyphs, gint x, gint y); void pango_win32_render_transformed (HDC hdc, const PangoMatrix *matrix, PangoFont *font, PangoGlyphString *glyphs, int x, int y); void pango_win32_render_layout_line (HDC hdc, PangoLayoutLine *line, int x, int y); void pango_win32_render_layout (HDC hdc, PangoLayout *layout, int x, int y); PangoGlyph pango_win32_get_unknown_glyph (PangoFont *font, gunichar wc); gint pango_win32_font_get_glyph_index (PangoFont *font, gunichar wc); gboolean pango_win32_font_select_font (PangoFont *font, HDC hdc); void pango_win32_font_done_font (PangoFont *font); double pango_win32_font_get_metrics_factor (PangoFont *font); gboolean pango_win32_get_debug_flag (void); HDC pango_win32_get_dc (void); PangoWin32FontCache; PangoWin32FontCache * pango_win32_font_cache_new (void); void pango_win32_font_cache_free (PangoWin32FontCache *cache); HFONT pango_win32_font_cache_load (PangoWin32FontCache *cache, const LOGFONTA *logfont); HFONT pango_win32_font_cache_loadw (PangoWin32FontCache *cache, const LOGFONTW *logfont); void pango_win32_font_cache_unload (PangoWin32FontCache *cache, HFONT hfont); PangoFontMap * pango_win32_font_map_for_display (void); void pango_win32_shutdown_display (void); PangoWin32FontCache * pango_win32_font_map_get_font_cache (PangoFontMap *font_map); LOGFONTA * pango_win32_font_logfont (PangoFont *font); LOGFONTW * pango_win32_font_logfontw (PangoFont *font); PangoFontDescription * pango_win32_font_description_from_logfont (const LOGFONTA *lfp); PangoFontDescription * pango_win32_font_description_from_logfontw (const LOGFONTW *lfp);
The macros and functions in this section are used to access fonts natively on Win32 systems and to render text in conjunction with Win32 APIs.
#define PANGO_RENDER_TYPE_WIN32 "PangoRenderWin32"
A string constant identifying the Win32 renderer. The associated quark (see
g_quark_from_string()) is used to identify the renderer in pango_find_map().
PangoContext * pango_win32_get_context (void);
pango_win32_get_context has been deprecated since version 1.22 and should not be used in newly-written code. Use pango_win32_font_map_for_display() followed by
pango_font_map_create_context() instead.
Retrieves a PangoContext appropriate for rendering with Windows fonts.
Returns : |
the new PangoContext |
void pango_win32_render (HDC hdc,
PangoFont *font,
PangoGlyphString *glyphs,
gint x,
gint y);
Render a PangoGlyphString onto a Windows DC
|
the device context |
|
the font in which to draw the string |
|
the glyph string to draw |
|
the x position of start of string (in pixels) |
|
the y position of baseline (in pixels) |
void pango_win32_render_transformed (HDC hdc,
const PangoMatrix *matrix,
PangoFont *font,
PangoGlyphString *glyphs,
int x,
int y);
Renders a PangoGlyphString onto a windows DC, possibly
transforming the layed-out coordinates through a transformation
matrix. Note that the transformation matrix for font is not
changed, so to produce correct rendering results, the font
must have been loaded using a PangoContext with an identical
transformation matrix to that passed in to this function.
|
a windows device context |
|
a PangoMatrix, or NULL to use an identity transformation
|
|
the font in which to draw the string |
|
the glyph string to draw |
|
the x position of the start of the string (in Pango units in user space coordinates) |
|
the y position of the baseline (in Pango units in user space coordinates) |
void pango_win32_render_layout_line (HDC hdc,
PangoLayoutLine *line,
int x,
int y);
Render a PangoLayoutLine onto a device context. For underlining to work property the text alignment of the DC should have TA_BASELINE and TA_LEFT.
|
DC to use for uncolored drawing |
|
a PangoLayoutLine |
|
the x position of start of string (in pixels) |
|
the y position of baseline (in pixels) |
void pango_win32_render_layout (HDC hdc,
PangoLayout *layout,
int x,
int y);
Render a PangoLayoutLine onto an X drawable
|
HDC to use for uncolored drawing |
|
a PangoLayout |
|
the X position of the left of the layout (in pixels) |
|
the Y position of the top of the layout (in pixels) |
PangoGlyph pango_win32_get_unknown_glyph (PangoFont *font, gunichar wc);
pango_win32_get_unknown_glyph is deprecated and should not be used in newly-written code.
Returns the index of a glyph suitable for drawing wc as an
unknown character.
Use PANGO_GET_UNKNOWN_GLYPH() instead.
|
a PangoFont |
|
the Unicode character for which a glyph is needed. |
Returns : |
a glyph index into font
|
gint pango_win32_font_get_glyph_index (PangoFont *font, gunichar wc);
Obtains the index of the glyph for wc in font, or 0, if not
covered.
|
a PangoFont. |
|
a Unicode character. |
Returns : |
the glyph index for wc.
|
gboolean pango_win32_font_select_font (PangoFont *font, HDC hdc);
Selects the font into the specified DC and changes the mapping mode
and world transformation of the DC appropriately for the font.
You may want to surround the use of this function with calls
to SaveDC() and RestoreDC(). Call pango_win32_font_done_font() when
you are done using the DC to release allocated resources.
See pango_win32_font_get_metrics_factor() for information about
converting from the coordinate space used by this function
into Pango units.
void pango_win32_font_done_font (PangoFont *font);
Releases any resources allocated by pango_win32_font_done_font()
|
a PangoFont from the win32 backend |
double pango_win32_font_get_metrics_factor (PangoFont *font);
Returns the scale factor from logical units in the coordinate
space used by pango_win32_font_select_font() to Pango units
in user space.
|
a PangoFont from the win32 backend |
Returns : |
factor to multiply logical units by to get Pango units. |
gboolean pango_win32_get_debug_flag (void);
Returns whether debugging is turned on.
Returns : |
TRUE if debugging is turned on.
|
Since 1.2
HDC pango_win32_get_dc (void);
Obtains a handle to the Windows device context that is used by Pango.
Returns : |
A handle to the Windows device context that is used by Pango. |
typedef struct _PangoWin32FontCache PangoWin32FontCache;
A PangoWin32FontCache caches HFONTs by their LOGFONT descriptions.
PangoWin32FontCache * pango_win32_font_cache_new (void);
Creates a font cache.
Returns : |
The new font cache. This must be freed with
pango_win32_font_cache_free().
|
void pango_win32_font_cache_free (PangoWin32FontCache *cache);
Frees a PangoWin32FontCache and all associated memory. All fonts loaded through this font cache will be freed along with the cache.
|
a PangoWin32FontCache |
HFONT pango_win32_font_cache_load (PangoWin32FontCache *cache, const LOGFONTA *logfont);
Creates a HFONT from a LOGFONTA. The result may be newly loaded, or it may have been previously stored
|
a PangoWin32FontCache |
|
a pointer to a LOGFONTA structure describing the font to load. |
Returns : |
The font structure, or NULL if the font could
not be loaded. In order to free this structure, you must call
pango_win32_font_cache_unload().
|
HFONT pango_win32_font_cache_loadw (PangoWin32FontCache *cache, const LOGFONTW *logfont);
Creates a HFONT from a LOGFONTW. The result may be newly loaded, or it may have been previously stored
|
a PangoWin32FontCache |
|
a pointer to a LOGFONTW structure describing the font to load. |
Returns : |
The font structure, or NULL if the font could
not be loaded. In order to free this structure, you must call
pango_win32_font_cache_unload().
|
Since 1.16
void pango_win32_font_cache_unload (PangoWin32FontCache *cache, HFONT hfont);
Frees a font structure previously loaded with pango_win32_font_cache_load().
|
a PangoWin32FontCache |
|
the HFONT to unload |
PangoFontMap * pango_win32_font_map_for_display (void);
Returns a PangoWin32FontMap. Font maps are cached and should
not be freed. If the font map is no longer needed, it can
be released with pango_win32_shutdown_display().
Returns : |
a PangoFontMap. |
PangoWin32FontCache * pango_win32_font_map_get_font_cache (PangoFontMap *font_map);
Obtains the font cache associated with the given font map.
|
a PangoWin32FontMap. |
Returns : |
the PangoWin32FontCache of font_map.
|
LOGFONTA * pango_win32_font_logfont (PangoFont *font);
Determine the LOGFONTA struct for the specified font. Note that
Pango internally uses LOGFONTW structs, so if converting the UTF-16
face name in the LOGFONTW struct to system codepage fails, the
returned LOGFONTA will have an emppty face name. To get the
LOGFONTW of a PangoFont, use pango_win32_font_logfontw(). It
is recommended to do that always even if you don't expect
to come across fonts with odd names.
LOGFONTW * pango_win32_font_logfontw (PangoFont *font);
Determine the LOGFONTW struct for the specified font.
|
a PangoFont which must be from the Win32 backend |
Returns : |
A newly allocated LOGFONTW struct. It must be
freed with g_free().
|
Since 1.16
PangoFontDescription * pango_win32_font_description_from_logfont (const LOGFONTA *lfp);
Creates a PangoFontDescription that matches the specified LOGFONTA.
The face name, italicness and weight fields in the LOGFONTA are used
to set up the resulting PangoFontDescription. If the face name in
the LOGFONTA contains non-ASCII characters the font is temporarily
loaded (using CreateFontIndirect()) and an ASCII (usually English)
name for it is looked up from the font name tables in the font
data. If that doesn't work, the face name is converted from the
system codepage to UTF-8 and that is used.
|
a LOGFONTA |
Returns : |
the newly allocated PangoFontDescription, which
should be freed using pango_font_description_free()
|
Since 1.12
PangoFontDescription * pango_win32_font_description_from_logfontw (const LOGFONTW *lfp);
Creates a PangoFontDescription that matches the specified LOGFONTW.
The face name, italicness and weight fields in the LOGFONTW are used
to set up the resulting PangoFontDescription. If the face name in
the LOGFONTW contains non-ASCII characters the font is temporarily
loaded (using CreateFontIndirect()) and an ASCII (usually English)
name for it is looked up from the font name tables in the font
data. If that doesn't work, the face name is converted from UTF-16
to UTF-8 and that is used.
|
a LOGFONTW |
Returns : |
the newly allocated PangoFontDescription, which
should be freed using pango_font_description_free()
|
Since 1.16
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
char ** pango_split_file_list (const char *str); char * pango_trim_string (const char *str); gint pango_read_line (FILE *stream, GString *str); gboolean pango_skip_space (const char **pos); gboolean pango_scan_word (const char **pos, GString *out); gboolean pango_scan_string (const char **pos, GString *out); gboolean pango_scan_int (const char **pos, int *out); char * pango_config_key_get (const char *key); void pango_lookup_aliases (const char *fontname, char ***families, int *n_families); gboolean pango_parse_enum (GType type, const char *str, int *value, gboolean warn, char **possible_values); gboolean pango_parse_style (const char *str, PangoStyle *style, gboolean warn); gboolean pango_parse_variant (const char *str, PangoVariant *variant, gboolean warn); gboolean pango_parse_weight (const char *str, PangoWeight *weight, gboolean warn); gboolean pango_parse_stretch (const char *str, PangoStretch *stretch, gboolean warn); const char * pango_get_sysconf_subdirectory (void); const char * pango_get_lib_subdirectory (void); guint8 * pango_log2vis_get_embedding_levels (const gchar *text, int length, PangoDirection *pbase_dir); gboolean pango_is_zero_width (gunichar ch); void pango_quantize_line_geometry (int *thickness, int *position);
The functions and utilities in this section are mostly used from Pango backends and modules, but may be useful for other purposes too.
char ** pango_split_file_list (const char *str);
Splits a G_SEARCHPATH_SEPARATOR-separated list of files, stripping
white space and substituting ~/ with $HOME/.
|
a G_SEARCHPATH_SEPARATOR separated list of filenames
|
Returns : |
a list of strings to be freed with g_strfreev()
|
char * pango_trim_string (const char *str);
Trims leading and trailing whitespace from a string.
|
a string |
Returns : |
A newly-allocated string that must be freed with g_free()
|
gint pango_read_line (FILE *stream, GString *str);
Reads an entire line from a file into a buffer. Lines may be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter is not written into the buffer. Text after a '#' character is treated as a comment and skipped. '\' can be used to escape a # character. '\' proceeding a line delimiter combines adjacent lines. A '\' proceeding any other character is ignored and written into the output buffer unmodified.
|
a stdio stream |
|
GString buffer into which to write the result |
Returns : |
0 if the stream was already at an EOF character, otherwise
the number of lines read (this is useful for maintaining
a line number counter which doesn't combine lines with '\')
|
gboolean pango_skip_space (const char **pos);
Skips 0 or more characters of white space.
|
in/out string position |
Returns : |
FALSE if skipping the white space leaves
the position at a '\0' character.
|
gboolean pango_scan_word (const char **pos, GString *out);
Scans a word into a GString buffer. A word consists of [A-Za-z_] followed by zero or more [A-Za-z_0-9] Leading white space is skipped.
gboolean pango_scan_string (const char **pos, GString *out);
Scans a string into a GString buffer. The string may either be a sequence of non-white-space characters, or a quoted string with '"'. Instead a quoted string, '\"' represents a literal quote. Leading white space outside of quotes is skipped.
gboolean pango_scan_int (const char **pos, int *out);
Scans an integer. Leading white space is skipped.
|
in/out string position |
|
an int into which to write the result |
Returns : |
FALSE if a parse error occurred.
|
char * pango_config_key_get (const char *key);
Looks up a key in the Pango config database (pseudo-win.ini style, read from $sysconfdir/pango/pangorc, ~/.pangorc, and getenv (PANGO_RC_FILE).)
void pango_lookup_aliases (const char *fontname,
char ***families,
int *n_families);
Look up all user defined aliases for the alias fontname.
The resulting font family names will be stored in families,
and the number of families in n_families.
|
an ascii string |
|
will be set to an array of font family names. this array is owned by pango and should not be freed. |
|
will be set to the length of the families array.
|
gboolean pango_parse_enum (GType type, const char *str, int *value, gboolean warn, char **possible_values);
Parses an enum type and stores the result in value.
If str does not match the nick name of any of the possible values for the
enum and is not an integer, FALSE is returned, a warning is issued
if warn is TRUE, and a
string representing the list of possible values is stored in
possible_values. The list is slash-separated, eg.
"none/start/middle/end". If failed and possible_values is not NULL,
returned string should be freed using g_free().
|
enum type to parse, eg. PANGO_TYPE_ELLIPSIZE_MODE.
|
|
string to parse. May be NULL.
|
|
integer to store the result in, or NULL.
|
|
if TRUE, issue a g_warning() on bad input.
|
|
place to store list of possible values on failure, or NULL.
|
Returns : |
TRUE if str was successfully parsed.
|
Since 1.16
gboolean pango_parse_style (const char *str, PangoStyle *style, gboolean warn);
Parses a font style. The allowed values are "normal", "italic" and "oblique", case variations being ignored.
|
a string to parse. |
|
a PangoStyle to store the result in. |
|
if TRUE, issue a g_warning() on bad input.
|
Returns : |
TRUE if str was successfully parsed.
|
gboolean pango_parse_variant (const char *str, PangoVariant *variant, gboolean warn);
Parses a font variant. The allowed values are "normal" and "smallcaps" or "small_caps", case variations being ignored.
|
a string to parse. |
|
a PangoVariant to store the result in. |
|
if TRUE, issue a g_warning() on bad input.
|
Returns : |
TRUE if str was successfully parsed.
|
gboolean pango_parse_weight (const char *str, PangoWeight *weight, gboolean warn);
Parses a font weight. The allowed values are "heavy", "ultrabold", "bold", "normal", "light", "ultraleight" and integers. Case variations are ignored.
|
a string to parse. |
|
a PangoWeight to store the result in. |
|
if TRUE, issue a g_warning() on bad input.
|
Returns : |
TRUE if str was successfully parsed.
|
gboolean pango_parse_stretch (const char *str, PangoStretch *stretch, gboolean warn);
Parses a font stretch. The allowed values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" and "ultra_expanded". Case variations are ignored and the '_' characters may be omitted.
|
a string to parse. |
|
a PangoStretch to store the result in. |
|
if TRUE, issue a g_warning() on bad input.
|
Returns : |
TRUE if str was successfully parsed.
|
const char * pango_get_sysconf_subdirectory (void);
On Unix, returns the name of the "pango" subdirectory of SYSCONFDIR (which is set at compile time). On Windows, returns the etc\pango subdirectory of the Pango installation directory (which is deduced at run time from the DLL's location).
Returns : |
the Pango sysconf directory. The returned string should not be freed. |
const char * pango_get_lib_subdirectory (void);
On Unix, returns the name of the "pango" subdirectory of LIBDIR (which is set at compile time). On Windows, returns the lib\pango subdirectory of the Pango installation directory (which is deduced at run time from the DLL's location).
Returns : |
the Pango lib directory. The returned string should not be freed. |
guint8 * pango_log2vis_get_embedding_levels (const gchar *text, int length, PangoDirection *pbase_dir);
This will return the bidirectional embedding levels of the input paragraph as defined by the Unicode Bidirectional Algorithm available at:
http://www.unicode.org/reports/tr9/
If the input base direction is a weak direction, the direction of the characters in the text will determine the final resolved direction.
|
the text to itemize. |
|
the number of bytes (not characters) to process, or -1
if text is nul-terminated and the length should be calculated.
|
|
input base direction, and output resolved direction. |
Returns : |
a newly allocated array of embedding levels, one item per character (not byte), that should be freed using g_free. |
Since 1.4
gboolean pango_is_zero_width (gunichar ch);
Checks ch to see if it is a character that should not be
normally rendered on the screen. This includes all Unicode characters
with "ZERO WIDTH" in their name, as well as bidi formatting characters, and
a few other ones. This is totally different from g_unichar_iszerowidth()
and is at best misnamed.
Since 1.10
void pango_quantize_line_geometry (int *thickness,
int *position);
Quantizes the thickness and position of a line, typically an
underline or strikethrough, to whole device pixels, that is integer
multiples of PANGO_SCALE. The purpose of this function is to avoid
such lines looking blurry.
Care is taken to make sure thickness is at least one pixel when this
function returns, but returned position may become zero as a result
of rounding.
|
pointer to the thickness of a line, in Pango units |
|
corresponding position |
Since 1.12
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
enum PangoGravity; enum PangoGravityHint; #define PANGO_GRAVITY_IS_VERTICAL (gravity) PangoGravity pango_gravity_get_for_matrix (const PangoMatrix *matrix); PangoGravity pango_gravity_get_for_script (PangoScript script, PangoGravity base_gravity, PangoGravityHint hint); PangoGravity pango_gravity_get_for_script_and_width (PangoScript script, gboolean wide, PangoGravity base_gravity, PangoGravityHint hint); double pango_gravity_to_rotation (PangoGravity gravity);
Since 1.16, Pango is able to correctly lay vertical text out. In fact, it can set layouts of mixed vertical and non-vertical text. This section describes the types used for setting vertical text parameters.
The way this is implemented is through the concept of gravity. Gravity of normal Latin text is south. A gravity value of east means that glyphs will be rotated ninety degrees counterclockwise. So, to render vertical text one needs to set the gravity and rotate the layout using the matrix machinery already in place. This has the huge advantage that most algorithms working on a PangoLayout do not need any change as the assumption that lines run in the X direction and stack in the Y direction holds even for vertical text layouts.
Applications should only need to set base gravity on PangoContext in use, and
let Pango decide the gravity assigned to each run of text. This automatically
handles text with mixed scripts. A very common use is to set the context base
gravity to auto using pango_context_set_base_gravity()
and rotate the layout normally. Pango will make sure that
Asian languages take the right form, while other scripts are rotated normally.
The correct way to set gravity on a layout is to set it on the context
associated with it using pango_context_set_base_gravity(). The context
of a layout can be accessed using pango_layout_get_context(). The currently
set base gravity of the context can be accessed using
pango_context_get_base_gravity() and the resolved
gravity of it using pango_context_get_gravity(). The resolved gravity is
the same as the base gravity for the most part, except that if the base
gravity is set to PANGO_GRAVITY_AUTO, the resolved gravity will depend
on the current matrix set on context, and is derived using
pango_gravity_get_for_matrix().
The next thing an application may want to set on the context is the gravity hint. A PangoGravityHint instructs how different scripts should react to the set base gravity.
Font descriptions have a gravity property too, that can be set using
pango_font_description_set_gravity() and accessed using
pango_font_description_get_gravity(). However, those are rarely useful
from application code and are mainly used by PangoLayout internally.
Last but not least, one can create PangoAttributes for gravity
and gravity hint using pango_attr_gravity_new() and
pango_attr_gravity_hint_new().
typedef enum {
PANGO_GRAVITY_SOUTH,
PANGO_GRAVITY_EAST,
PANGO_GRAVITY_NORTH,
PANGO_GRAVITY_WEST,
PANGO_GRAVITY_AUTO
} PangoGravity;
The PangoGravity type represents the orientation of glyphs in a segment
of text. This is useful when rendering vertical text layouts. In
those situations, the layout is rotated using a non-identity PangoMatrix,
and then glyph orientation is controlled using PangoGravity.
Not every value in this enumeration makes sense for every usage of
PangoGravity; for example, PANGO_GRAVITY_AUTO only can be passed to
pango_context_set_base_gravity() and can only be returned by
pango_context_get_base_gravity().
See also: PangoGravityHint
| Glyphs stand upright (default) | |
| Glyphs are rotated 90 degrees clockwise | |
| Glyphs are upside-down | |
| Glyphs are rotated 90 degrees counter-clockwise | |
| Gravity is resolved from the context matrix |
Since 1.16
typedef enum {
PANGO_GRAVITY_HINT_NATURAL,
PANGO_GRAVITY_HINT_STRONG,
PANGO_GRAVITY_HINT_LINE
} PangoGravityHint;
The PangoGravityHint defines how horizontal scripts should behave in a vertical context. That is, English excerpt in a vertical paragraph for example.
See PangoGravity.
| scripts will take their natural gravity based on the base gravity and the script. This is the default. | |
| always use the base gravity set, regardless of the script. | |
| for scripts not in their natural direction (eg. Latin in East gravity), choose per-script gravity such that every script respects the line progression. This means, Latin and Arabic will take opposite gravities and both flow top-to-bottom for example. |
Since 1.16
#define PANGO_GRAVITY_IS_VERTICAL(gravity)
Whether a PangoGravity represents vertical writing directions.
|
the PangoGravity to check |
Since 1.16
PangoGravity pango_gravity_get_for_matrix (const PangoMatrix *matrix);
Finds the gravity that best matches the rotation component in a PangoMatrix.
|
a PangoMatrix |
Returns : |
the gravity of matrix, which will never be
PANGO_GRAVITY_AUTO, or PANGO_GRAVITY_SOUTH if matrix is NULL
|
Since 1.16
PangoGravity pango_gravity_get_for_script (PangoScript script, PangoGravity base_gravity, PangoGravityHint hint);
Based on the script, base gravity, and hint, returns actual gravity to use in laying out a single PangoItem.
If base_gravity is PANGO_GRAVITY_AUTO, it is first replaced with the
preferred gravity of script. To get the preferred gravity of a script,
pass PANGO_GRAVITY_AUTO and PANGO_GRAVITY_HINT_STRONG in.
|
PangoScript to query |
|
base gravity of the paragraph |
|
orientation hint |
Returns : |
resolved gravity suitable to use for a run of text
with script.
|
Since 1.16
PangoGravity pango_gravity_get_for_script_and_width (PangoScript script, gboolean wide, PangoGravity base_gravity, PangoGravityHint hint);
Based on the script, East Asian width, base gravity, and hint, returns actual gravity to use in laying out a single character or PangoItem.
This function is similar to pango_gravity_get_for_script() except
that this function makes a distinction between narrow/half-width and
wide/full-width characters also. Wide/full-width characters always
stand <emph>upright</emph>, that is, they always take the base gravity,
whereas narrow/full-width characters are always rotated in vertical
context.
If base_gravity is PANGO_GRAVITY_AUTO, it is first replaced with the
preferred gravity of script.
|
PangoScript to query |
|
TRUE for wide characters as returned by g_unichar_iswide()
|
|
base gravity of the paragraph |
|
orientation hint |
Returns : |
resolved gravity suitable to use for a run of text
with script and wide.
|
Since 1.26
double pango_gravity_to_rotation (PangoGravity gravity);
Converts a PangoGravity value to its natural rotation in radians.
gravity should not be PANGO_GRAVITY_AUTO.
Note that pango_matrix_rotate() takes angle in degrees, not radians.
So, to call pango_matrix_rotate() with the output of this function
you should multiply it by (180. / G_PI).
|
gravity to query |
Returns : |
the rotation value corresponding to gravity.
|
Since 1.16
pango_context_get_base_gravity(),
pango_context_set_base_gravity(),
pango_context_get_gravity(),
pango_context_get_gravity_hint(),
pango_context_set_gravity_hint(),
pango_font_description_set_gravity(),
pango_font_description_get_gravity(),
pango_attr_gravity_new(),
pango_attr_gravity_hint_new()
|
|
Pango Reference Manual | |
|---|
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
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);
Functions and macros in this section are used to support loading dynamic modules that add engines to Pango at run time.
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.
|
a function that lists the engines defined in this module. |
|
a function to initialize the module. |
|
a function to finalize the module. |
|
a function to create an engine, given the engine name. |
typedef struct _PangoMap PangoMap;
A PangoMap structure can be used to determine the engine to use for each character.
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.
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.
|
the language tag for which to find the map |
|
the engine type for the map to find |
|
the render type for the map to find |
Returns : |
the suitable PangoMap. |
PangoEngine * pango_map_get_engine (PangoMap *map, PangoScript script);
Returns the best engine listed in the map for a given script
|
a PangoMap |
|
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.
|
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.
|
a PangoMap |
|
a PangoScript |
|
location to store list of engines that exactly handle this script. |
|
location to store list of engines that approximately handle this script. |
Since 1.4
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.
|
a PangoIncludedModule |
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
Bidirectional TextBidirectional Text — Types and functions to help with handling bidirectional text |
enum PangoDirection; PangoDirection pango_unichar_direction (gunichar ch); PangoDirection pango_find_base_dir (const gchar *text, gint length); gboolean pango_get_mirror_char (gunichar ch, gunichar *mirrored_ch); enum PangoBidiType; PangoBidiType pango_bidi_type_for_unichar (gunichar ch);
Pango supports bidirectional text (like Arabic and Hebrew) automatically. Some applications however, need some help to correctly handle bidirectional text.
The PangoDirection type can be used with pango_context_set_base_dir() to
instruct Pango about direction of text, though in most cases Pango detects
that correctly and automatically. The rest of the facilities in this section
are used internally by Pango already, and are provided to help applications
that need more direct control over bidirectional setting of text.
typedef enum {
PANGO_DIRECTION_LTR,
PANGO_DIRECTION_RTL,
PANGO_DIRECTION_TTB_LTR,
PANGO_DIRECTION_TTB_RTL,
PANGO_DIRECTION_WEAK_LTR,
PANGO_DIRECTION_WEAK_RTL,
PANGO_DIRECTION_NEUTRAL
} PangoDirection;
The PangoDirection type represents a direction in the
Unicode bidirectional algorithm; not every value in this
enumeration makes sense for every usage of PangoDirection;
for example, the return value of pango_unichar_direction()
and pango_find_base_dir() cannot be PANGO_DIRECTION_WEAK_LTR
or PANGO_DIRECTION_WEAK_RTL, since every character is either
neutral or has a strong direction; on the other hand
PANGO_DIRECTION_NEUTRAL doesn't make sense to pass
to pango_itemize_with_base_dir().
The PANGO_DIRECTION_TTB_LTR, PANGO_DIRECTION_TTB_RTL
values come from an earlier interpretation of this
enumeration as the writing direction of a block of
text and are no longer used; See PangoGravity for how
vertical text is handled in Pango.
| A strong left-to-right direction | |
| A strong right-to-left direction | |
Deprecated value; treated the
same as PANGO_DIRECTION_RTL.
|
|
Deprecated value; treated the
same as PANGO_DIRECTION_LTR
|
|
| A weak left-to-right direction | |
| A weak right-to-left direction | |
| No direction specified |
PangoDirection pango_unichar_direction (gunichar ch);
Determines the inherent direction of a character; either
PANGO_DIRECTION_LTR, PANGO_DIRECTION_RTL, or
PANGO_DIRECTION_NEUTRAL.
This function is useful to categorize characters into left-to-right
letters, right-to-left letters, and everything else. If full
Unicode bidirectional type of a character is needed,
pango_bidi_type_for_gunichar() can be used instead.
|
a Unicode character |
Returns : |
the direction of the character. |
PangoDirection pango_find_base_dir (const gchar *text, gint length);
Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm.
|
the text to process |
|
length of text in bytes (may be -1 if text is nul-terminated)
|
Returns : |
The direction corresponding to the first strong character.
If no such character is found, then PANGO_DIRECTION_NEUTRAL is returned.
|
Since 1.4
gboolean pango_get_mirror_char (gunichar ch, gunichar *mirrored_ch);
pango_get_mirror_char is deprecated and should not be used in newly-written code.
If ch has the Unicode mirrored property and there is another Unicode
character that typically has a glyph that is the mirror image of ch's
glyph, puts that character in the address pointed to by mirrored_ch.
Use g_unichar_get_mirror_char() instead; the docs for that function
provide full details.
typedef enum {
/* Strong types */
PANGO_BIDI_TYPE_L,
PANGO_BIDI_TYPE_LRE,
PANGO_BIDI_TYPE_LRO,
PANGO_BIDI_TYPE_R,
PANGO_BIDI_TYPE_AL,
PANGO_BIDI_TYPE_RLE,
PANGO_BIDI_TYPE_RLO,
/* Weak types */
PANGO_BIDI_TYPE_PDF,
PANGO_BIDI_TYPE_EN,
PANGO_BIDI_TYPE_ES,
PANGO_BIDI_TYPE_ET,
PANGO_BIDI_TYPE_AN,
PANGO_BIDI_TYPE_CS,
PANGO_BIDI_TYPE_NSM,
PANGO_BIDI_TYPE_BN,
/* Neutral types */
PANGO_BIDI_TYPE_B,
PANGO_BIDI_TYPE_S,
PANGO_BIDI_TYPE_WS,
PANGO_BIDI_TYPE_ON
} PangoBidiType;
The PangoBidiType type represents the bidirectional character type of a Unicode character as specified by the Unicode bidirectional algorithm.
| Left-to-Right | |
| Left-to-Right Embedding | |
| Left-to-Right Override | |
| Right-to-Left | |
| Right-to-Left Arabic | |
| Right-to-Left Embedding | |
| Right-to-Left Override | |
| Pop Directional Format | |
| European Number | |
| European Number Separator | |
| European Number Terminator | |
| Arabic Number | |
| Common Number Separator | |
| Nonspacing Mark | |
| Boundary Neutral | |
| Paragraph Separator | |
| Segment Separator | |
| Whitespace | |
| Other Neutrals |
Since 1.22
PangoBidiType pango_bidi_type_for_unichar (gunichar ch);
Determines the normative bidirectional character type of a character, as specified in the Unicode Character Database.
A simplified version of this function is available as
pango_unichar_get_direction().
|
a Unicode character |
Returns : |
the bidirectional character type, as used in the Unicode bidirectional algorithm. |
Since 1.22
|
|
Pango Reference Manual | |
|---|
|
|
Pango Reference Manual | |
|---|
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
PangoRenderer;
enum PangoRenderPart;
#define PANGO_TYPE_RENDER_PART
PangoRendererClass;
void pango_renderer_draw_layout (PangoRenderer *renderer,
PangoLayout *layout,
int x,
int y);
void pango_renderer_draw_layout_line (PangoRenderer *renderer,
PangoLayoutLine *line,
int x,
int y);
void pango_renderer_draw_glyphs (PangoRenderer *renderer,
PangoFont *font,
PangoGlyphString *glyphs,
int x,
int y);
void pango_renderer_draw_glyph_item (PangoRenderer *renderer,
const char *text,
PangoGlyphItem *glyph_item,
int x,
int y);
void pango_renderer_draw_rectangle (PangoRenderer *renderer,
PangoRenderPart part,
int x,
int y,
int width,
int height);
void pango_renderer_draw_error_underline (PangoRenderer *renderer,
int x,
int y,
int width,
int height);
void pango_renderer_draw_trapezoid (PangoRenderer *renderer,
PangoRenderPart part,
double y1_,
double x11,
double x21,
double y2,
double x12,
double x22);
void pango_renderer_draw_glyph (PangoRenderer *renderer,
PangoFont *font,
PangoGlyph glyph,
double x,
double y);
void pango_renderer_activate (PangoRenderer *renderer);
void pango_renderer_deactivate (PangoRenderer *renderer);
void pango_renderer_part_changed (PangoRenderer *renderer,
PangoRenderPart part);
void pango_renderer_set_color (PangoRenderer *renderer,
PangoRenderPart part,
const PangoColor *color);
PangoColor * pango_renderer_get_color (PangoRenderer *renderer,
PangoRenderPart part);
void pango_renderer_set_matrix (PangoRenderer *renderer,
const PangoMatrix *matrix);
const PangoMatrix * pango_renderer_get_matrix (PangoRenderer *renderer);
PangoLayout * pango_renderer_get_layout (PangoRenderer *renderer);
PangoLayoutLine * pango_renderer_get_layout_line (PangoRenderer *renderer);
PangoRenderer is a base class that contains the necessary logic for
rendering a PangoLayout or PangoLayoutLine. By subclassing
PangoRenderer and overriding operations such as draw_glyphs and
draw_rectangle, renderers for particular font backends and
destinations can be created.
typedef struct {
PangoMatrix *matrix; /* May be NULL */
} PangoRenderer;
PangoRenderer is a base class for objects that are used to render Pango objects such as PangoGlyphString and PangoLayout.
PangoMatrix * |
the current transformation matrix for the Renderer; may
be NULL, which should be treated the same as the identity matrix.
|
Since 1.8
typedef enum
{
PANGO_RENDER_PART_FOREGROUND,
PANGO_RENDER_PART_BACKGROUND,
PANGO_RENDER_PART_UNDERLINE,
PANGO_RENDER_PART_STRIKETHROUGH
} PangoRenderPart;
PangoRenderPart defines different items to render for such purposes as setting colors.
| the text itself | |
| the area behind the text | |
| underlines | |
| strikethrough lines |
Since 1.8
#define PANGO_TYPE_RENDER_PART (pango_render_part_get_type())
The GObject type for PangoRenderPart.
typedef struct {
/* All of the following have default implementations
* and take as coordinates user coordinates in Pango units
*/
void (*draw_glyphs) (PangoRenderer *renderer,
PangoFont *font,
PangoGlyphString *glyphs,
int x,
int y);
void (*draw_rectangle) (PangoRenderer *renderer,
PangoRenderPart part,
int x,
int y,
int width,
int height);
void (*draw_error_underline) (PangoRenderer *renderer,
int x,
int y,
int width,
int height);
/* Nothing is drawn for shaped glyphs unless this is implemented */
void (*draw_shape) (PangoRenderer *renderer,
PangoAttrShape *attr,
int x,
int y);
/* These two must be implemented and take coordinates in
* device space as doubles.
*/
void (*draw_trapezoid) (PangoRenderer *renderer,
PangoRenderPart part,
double y1_,
double x11,
double x21,
double y2,
double x12,
double x22);
void (*draw_glyph) (PangoRenderer *renderer,
PangoFont *font,
PangoGlyph glyph,
double x,
double y);
/* Notification of change in rendering attributes
*/
void (*part_changed) (PangoRenderer *renderer,
PangoRenderPart part);
/* Paired around drawing operations
*/
void (*begin) (PangoRenderer *renderer);
void (*end) (PangoRenderer *renderer);
/* Hooks into the details of layout rendering
*/
void (*prepare_run) (PangoRenderer *renderer,
PangoLayoutRun *run);
/* All of the following have default implementations
* and take as coordinates user coordinates in Pango units
*/
void (*draw_glyph_item) (PangoRenderer *renderer,
const char *text,
PangoGlyphItem *glyph_item,
int x,
int y);
} PangoRendererClass;
Class structure for PangoRenderer.
|
draws a PangoGlyphString |
|
draws a rectangle |
|
draws a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. |
|
draw content for a glyph shaped with PangoAttrShape.
x, y are the coordinates of the left edge of the baseline,
in user coordinates.
|
|
draws a trapezoidal filled area |
|
draws a single glyph |
|
do renderer specific processing when rendering attributes change |
|
Do renderer-specific initialization before drawing |
|
Do renderer-specific cleanup after drawing |
|
updates the renderer for a new run |
|
draws a PangoGlyphItem |
Since 1.8
void pango_renderer_draw_layout (PangoRenderer *renderer, PangoLayout *layout, int x, int y);
Draws layout with the specified PangoRenderer.
|
a PangoRenderer |
|
a PangoLayout |
|
X position of left edge of baseline, in user space coordinates in Pango units. |
|
Y position of left edge of baseline, in user space coordinates in Pango units. |
Since 1.8
void pango_renderer_draw_layout_line (PangoRenderer *renderer, PangoLayoutLine *line, int x, int y);
Draws line with the specified PangoRenderer.
|
a PangoRenderer |
|
a PangoLayoutLine |
|
X position of left edge of baseline, in user space coordinates in Pango units. |
|
Y position of left edge of baseline, in user space coordinates in Pango units. |
Since 1.8
void pango_renderer_draw_glyphs (PangoRenderer *renderer, PangoFont *font, PangoGlyphString *glyphs, int x, int y);
Draws the glyphs in glyphs with the specified PangoRenderer.
|
a PangoRenderer |
|
a PangoFont |
|
a PangoGlyphString |
|
X position of left edge of baseline, in user space coordinates in Pango units. |
|
Y position of left edge of baseline, in user space coordinates in Pango units. |
Since 1.8
void pango_renderer_draw_glyph_item (PangoRenderer *renderer, const char *text, PangoGlyphItem *glyph_item, int x, int y);
Draws the glyphs in glyph_item with the specified PangoRenderer,
embedding the text associated with the glyphs in the output if the
output format supports it (PDF for example).
Note that text is the start of the text for layout, which is then
indexed by glyph_item->item->offset
If text is NULL, this simply calls pango_renderer_draw_glyphs().
The default implementation of this method simply falls back to
pango_renderer_draw_glyphs().
|
a PangoRenderer |
|
the UTF-8 text that glyph_item refers to, or NULL
|
|
a PangoGlyphItem |
|
X position of left edge of baseline, in user space coordinates in Pango units. |
|
Y position of left edge of baseline, in user space coordinates in Pango units. |
Since 1.22
void pango_renderer_draw_rectangle (PangoRenderer *renderer, PangoRenderPart part, int x, int y, int width, int height);
Draws an axis-aligned rectangle in user space coordinates with the specified PangoRenderer.
This should be called while renderer is already active. Use
pango_renderer_activate() to activate a renderer.
|
a PangoRenderer |
|
type of object this rectangle is part of |
|
X position at which to draw rectangle, in user space coordinates in Pango units |
|
Y position at which to draw rectangle, in user space coordinates in Pango units |
|
width of rectangle in Pango units in user space coordinates |
|
height of rectangle in Pango units in user space coordinates |
Since 1.8
void pango_renderer_draw_error_underline (PangoRenderer *renderer, int x, int y, int width, int height);
Draw a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. (The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle)
This should be called while renderer is already active. Use
pango_renderer_activate() to activate a renderer.
|
a PangoRenderer |
|
X coordinate of underline, in Pango units in user coordinate system |
|
Y coordinate of underline, in Pango units in user coordinate system |
|
width of underline, in Pango units in user coordinate system |
|
height of underline, in Pango units in user coordinate system |
Since 1.8
void pango_renderer_draw_trapezoid (PangoRenderer *renderer, PangoRenderPart part, double y1_, double x11, double x21, double y2, double x12, double x22);
Draws a trapezoid with the parallel sides aligned with the X axis using the given PangoRenderer; coordinates are in device space.
|
a PangoRenderer |
|
type of object this trapezoid is part of |
|
Y coordinate of top of trapezoid |
|
X coordinate of left end of top of trapezoid |
|
X coordinate of right end of top of trapezoid |
|
Y coordinate of bottom of trapezoid |
|
X coordinate of left end of bottom of trapezoid |
|
X coordinate of right end of bottom of trapezoid |
Since 1.8
void pango_renderer_draw_glyph (PangoRenderer *renderer, PangoFont *font, PangoGlyph glyph, double x, double y);
Draws a single glyph with coordinates in device space.
|
a PangoRenderer |
|
a PangoFont |
|
the glyph index of a single glyph |
|
X coordinate of left edge of baseline of glyph |
|
Y coordinate of left edge of baseline of glyph |
Since 1.8
void pango_renderer_activate (PangoRenderer *renderer);
Does initial setup before rendering operations on renderer.
pango_renderer_deactivate() should be called when done drawing.
Calls such as pango_renderer_draw_layout() automatically
activate the layout before drawing on it. Calls to
pango_renderer_activate() and pango_renderer_deactivate() can
be nested and the renderer will only be initialized and
deinitialized once.
|
a PangoRenderer |
Since 1.8
void pango_renderer_deactivate (PangoRenderer *renderer);
Cleans up after rendering operations on renderer. See
docs for pango_renderer_activate().
|
a PangoRenderer |
Since 1.8
void pango_renderer_part_changed (PangoRenderer *renderer, PangoRenderPart part);
Informs Pango that the way that the rendering is done
for part has changed in a way that would prevent multiple
pieces being joined together into one drawing call. For
instance, if a subclass of PangoRenderer was to add a stipple
option for drawing underlines, it needs to call
pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE);
When the stipple changes or underlines with different stipples
might be joined together. Pango automatically calls this for
changes to colors. (See pango_renderer_set_color())
|
a PangoRenderer |
|
the part for which rendering has changed. |
Since 1.8
void pango_renderer_set_color (PangoRenderer *renderer, PangoRenderPart part, const PangoColor *color);
Sets the color for part of the rendering.
|
a PangoRenderer |
|
the part to change the color of |
|
the new color or NULL to unset the current color
|
Since 1.8
PangoColor * pango_renderer_get_color (PangoRenderer *renderer, PangoRenderPart part);
Gets the current rendering color for the specified part.
|
a PangoRenderer |
|
the part to get the color for |
Returns : |
the color for the specified part, or NULL
if it hasn't been set and should be inherited from the
environment.
|
Since 1.8
void pango_renderer_set_matrix (PangoRenderer *renderer, const PangoMatrix *matrix);
Sets the transformation matrix that will be applied when rendering.
|
a PangoRenderer |
|
a PangoMatrix, or NULL to unset any existing matrix.
(No matrix set is the same as setting the identity matrix.)
|
Since 1.8
const PangoMatrix * pango_renderer_get_matrix (PangoRenderer *renderer);
Gets the transformation matrix that will be applied when
rendering. See pango_renderer_set_matrix().
|
a PangoRenderer |
Returns : |
the matrix, or NULL if no matrix has been set
(which is the same as the identity matrix). The returned
matrix is owned by Pango and must not be modified or
freed.
|
Since 1.8
PangoLayout * pango_renderer_get_layout (PangoRenderer *renderer);
Gets the layout currently being rendered using renderer.
Calling this function only makes sense from inside a subclass's
methods, like in its draw_shape() for example.
The returned layout should not be modified while still being rendered.
|
a PangoRenderer |
Returns : |
the layout, or NULL if no layout is being
rendered using renderer at this time.
|
Since 1.20
PangoLayoutLine * pango_renderer_get_layout_line (PangoRenderer *renderer);
Gets the layout line currently being rendered using renderer.
Calling this function only makes sense from inside a subclass's
methods, like in its draw_shape() for example.
The returned layout line should not be modified while still being rendered.
|
a PangoRenderer |
Returns : |
the layout line, or NULL if no layout line is being
rendered using renderer at this time.
|
Since 1.20
|
|
Pango Reference Manual | |
|---|
|
|
Pango Reference Manual | |
|---|
GObject
PangoFontMap
PangoFcFontMap
PangoFT2FontMap
PangoXftFontMap
PangoFont
PangoFcFont
PangoXftFont
PangoContext
PangoEngine
PangoEngineLang
PangoEngineShape
PangoFcDecoder
PangoFontFace
PangoFontFamily
PangoFontset
PangoFontsetSimple
PangoLayout
PangoOTInfo
PangoOTRuleset
PangoRenderer
PangoXftRenderer
GInterface
PangoCairoFontMap
PangoCairoFont
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
PangoLayout;
PangoLayoutIter;
PangoLayout * pango_layout_new (PangoContext *context);
PangoLayout * pango_layout_copy (PangoLayout *src);
PangoContext * pango_layout_get_context (PangoLayout *layout);
void pango_layout_context_changed (PangoLayout *layout);
void pango_layout_set_text (PangoLayout *layout,
const char *text,
int length);
const char * pango_layout_get_text (PangoLayout *layout);
void pango_layout_set_markup (PangoLayout *layout,
const char *markup,
int length);
void pango_layout_set_markup_with_accel (PangoLayout *layout,
const char *markup,
int length,
gunichar accel_marker,
gunichar *accel_char);
void pango_layout_set_attributes (PangoLayout *layout,
PangoAttrList *attrs);
PangoAttrList * pango_layout_get_attributes (PangoLayout *layout);
void pango_layout_set_font_description (PangoLayout *layout,
const PangoFontDescription *desc);
const PangoFontDescription * pango_layout_get_font_description
(PangoLayout *layout);
void pango_layout_set_width (PangoLayout *layout,
int width);
int pango_layout_get_width (PangoLayout *layout);
void pango_layout_set_height (PangoLayout *layout,
int height);
int pango_layout_get_height (PangoLayout *layout);
void pango_layout_set_wrap (PangoLayout *layout,
PangoWrapMode wrap);
PangoWrapMode pango_layout_get_wrap (PangoLayout *layout);
gboolean pango_layout_is_wrapped (PangoLayout *layout);
enum PangoWrapMode;
#define PANGO_TYPE_WRAP_MODE
void pango_layout_set_ellipsize (PangoLayout *layout,
PangoEllipsizeMode ellipsize);
PangoEllipsizeMode pango_layout_get_ellipsize (PangoLayout *layout);
gboolean pango_layout_is_ellipsized (PangoLayout *layout);
enum PangoEllipsizeMode;
#define PANGO_TYPE_ELLIPSIZE_MODE
void pango_layout_set_indent (PangoLayout *layout,
int indent);
int pango_layout_get_indent (PangoLayout *layout);
int pango_layout_get_spacing (PangoLayout *layout);
void pango_layout_set_spacing (PangoLayout *layout,
int spacing);
void pango_layout_set_justify (PangoLayout *layout,
gboolean justify);
gboolean pango_layout_get_justify (PangoLayout *layout);
void pango_layout_set_auto_dir (PangoLayout *layout,
gboolean auto_dir);
gboolean pango_layout_get_auto_dir (PangoLayout *layout);
void pango_layout_set_alignment (PangoLayout *layout,
PangoAlignment alignment);
PangoAlignment pango_layout_get_alignment (PangoLayout *layout);
void pango_layout_set_tabs (PangoLayout *layout,
PangoTabArray *tabs);
PangoTabArray* pango_layout_get_tabs (PangoLayout *layout);
void pango_layout_set_single_paragraph_mode
(PangoLayout *layout,
gboolean setting);
gboolean pango_layout_get_single_paragraph_mode
(PangoLayout *layout);
enum PangoAlignment;
#define PANGO_TYPE_ALIGNMENT
int pango_layout_get_unknown_glyphs_count
(PangoLayout *layout);
void pango_layout_get_log_attrs (PangoLayout *layout,
PangoLogAttr **attrs,
gint *n_attrs);
void pango_layout_index_to_pos (PangoLayout *layout,
int index_,
PangoRectangle *pos);
void pango_layout_index_to_line_x (PangoLayout *layout,
int index_,
gboolean trailing,
int *line,
int *x_pos);
gboolean pango_layout_xy_to_index (PangoLayout *layout,
int x,
int y,
int *index_,
int *trailing);
void pango_layout_get_cursor_pos (PangoLayout *layout,
int index_,
PangoRectangle *strong_pos,
PangoRectangle *weak_pos);
void pango_layout_move_cursor_visually (PangoLayout *layout,
gboolean strong,
int old_index,
int old_trailing,
int direction,
int *new_index,
int *new_trailing);
void pango_layout_get_extents (PangoLayout *layout,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
void pango_layout_get_pixel_extents (PangoLayout *layout,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
void pango_layout_get_size (PangoLayout *layout,
int *width,
int *height);
void pango_layout_get_pixel_size (PangoLayout *layout,
int *width,
int *height);
int pango_layout_get_baseline (PangoLayout *layout);
int pango_layout_get_line_count (PangoLayout *layout);
PangoLayoutLine * pango_layout_get_line (PangoLayout *layout,
int line);
PangoLayoutLine * pango_layout_get_line_readonly (PangoLayout *layout,
int line);
GSList * pango_layout_get_lines (PangoLayout *layout);
GSList * pango_layout_get_lines_readonly (PangoLayout *layout);
PangoLayoutIter * pango_layout_get_iter (PangoLayout *layout);
PangoLayoutIter * pango_layout_iter_copy (PangoLayoutIter *iter);
void pango_layout_iter_free (PangoLayoutIter *iter);
gboolean pango_layout_iter_next_run (PangoLayoutIter *iter);
gboolean pango_layout_iter_next_char (PangoLayoutIter *iter);
gboolean pango_layout_iter_next_cluster (PangoLayoutIter *iter);
gboolean pango_layout_iter_next_line (PangoLayoutIter *iter);
gboolean pango_layout_iter_at_last_line (PangoLayoutIter *iter);
int pango_layout_iter_get_index (PangoLayoutIter *iter);
int pango_layout_iter_get_baseline (PangoLayoutIter *iter);
PangoLayoutRun * pango_layout_iter_get_run (PangoLayoutIter *iter);
PangoLayoutRun * pango_layout_iter_get_run_readonly (PangoLayoutIter *iter);
PangoLayoutLine * pango_layout_iter_get_line (PangoLayoutIter *iter);
PangoLayoutLine * pango_layout_iter_get_line_readonly (PangoLayoutIter *iter);
PangoLayout * pango_layout_iter_get_layout (PangoLayoutIter *iter);
void pango_layout_iter_get_char_extents (PangoLayoutIter *iter,
PangoRectangle *logical_rect);
void pango_layout_iter_get_cluster_extents
(PangoLayoutIter *iter,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
void pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
void pango_layout_iter_get_line_yrange (PangoLayoutIter *iter,
int *y0_,
int *y1_);
void pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
void pango_layout_iter_get_layout_extents
(PangoLayoutIter *iter,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
PangoLayoutLine;
typedef PangoLayoutRun;
PangoLayoutLine * pango_layout_line_ref (PangoLayoutLine *line);
void pango_layout_line_unref (PangoLayoutLine *line);
void pango_layout_line_get_extents (PangoLayoutLine *line,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
void pango_layout_line_get_pixel_extents (PangoLayoutLine *layout_line,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
void pango_layout_line_index_to_x (PangoLayoutLine *line,
int index_,
gboolean trailing,
int *x_pos);
gboolean pango_layout_line_x_to_index (PangoLayoutLine *line,
int x_pos,
int *index_,
int *trailing);
void pango_layout_line_get_x_ranges (PangoLayoutLine *line,
int start_index,
int end_index,
int **ranges,
int *n_ranges);
While complete access to the layout capabilities of Pango is provided using the detailed interfaces for itemization and shaping, using that functionality directly involves writing a fairly large amount of code. The objects and functions in this section provide a high-level driver for formatting entire paragraphs of text at once.
typedef struct _PangoLayout PangoLayout;
The PangoLayout structure represents an entire paragraph of text. It is initialized with a PangoContext, UTF-8 string and set of attributes for that string. Once that is done, the set of formatted lines can be extracted from the object, the layout can be rendered, and conversion between logical character positions within the layout's text, and the physical position of the resulting glyphs can be made.
There are also a number of parameters to adjust the formatting of a PangoLayout, which are illustrated in Figure 1, “Adjustable parameters for a PangoLayout”. It is possible, as well, to ignore the 2-D setup, and simply treat the results of a PangoLayout as a list of lines.
The PangoLayout structure is opaque, and has no user-visible fields.
typedef struct _PangoLayoutIter PangoLayoutIter;
A PangoLayoutIter structure can be used to iterate over the visual extents of a PangoLayout.
The PangoLayoutIter structure is opaque, and has no user-visible fields.
PangoLayout * pango_layout_new (PangoContext *context);
Create a new PangoLayout object with attributes initialized to default values for a particular PangoContext.
|
a PangoContext |
Returns : |
the newly allocated PangoLayout, with a reference
count of one, which should be freed with
g_object_unref().
|
PangoLayout * pango_layout_copy (PangoLayout *src);
Does a deep copy-by-value of the src layout. The attribute list,
tab array, and text from the original layout are all copied by
value.
|
a PangoLayout |
Returns : |
the newly allocated PangoLayout, with a reference
count of one, which should be freed with
g_object_unref().
|
PangoContext * pango_layout_get_context (PangoLayout *layout);
Retrieves the PangoContext used for this layout.
|
a PangoLayout |
Returns : |
the PangoContext for the layout. This does not have an additional refcount added, so if you want to keep a copy of this around, you must reference it yourself. |
void pango_layout_context_changed (PangoLayout *layout);
Forces recomputation of any state in the PangoLayout that might depend on the layout's context. This function should be called if you make changes to the context subsequent to creating the layout.
|
a PangoLayout |
void pango_layout_set_text (PangoLayout *layout, const char *text, int length);
Sets the text of the layout.
Note that if you have used
pango_layout_set_markup() or pango_layout_set_markup_with_accel() on
layout before, you may want to call pango_layout_set_attributes() to clear
the attributes set on the layout from the markup as this function does not
clear attributes.
|
a PangoLayout |
|
a valid UTF-8 string |
|
maximum length of text, in bytes. -1 indicates that
the string is nul-terminated and the length should be
calculated. The text will also be truncated on
encountering a nul-termination even when length is
positive.
|
const char * pango_layout_get_text (PangoLayout *layout);
Gets the text in the layout. The returned text should not be freed or modified.
|
a PangoLayout |
Returns : |
the text in the layout.
|
void pango_layout_set_markup (PangoLayout *layout, const char *markup, int length);
Same as pango_layout_set_markup_with_accel(), but
the markup text isn't scanned for accelerators.
|
a PangoLayout |
|
marked-up text |
|
length of marked-up text in bytes, or -1 if markup is
nul-terminated
|
void pango_layout_set_markup_with_accel (PangoLayout *layout, const char *markup, int length, gunichar accel_marker, gunichar *accel_char);
Sets the layout text and attribute list from marked-up text (see markup format). Replaces the current text and attribute list.
If accel_marker is nonzero, the given character will mark the
character following it as an accelerator. For example, accel_marker
might be an ampersand or underscore. All characters marked
as an accelerator will receive a PANGO_UNDERLINE_LOW attribute,
and the first character so marked will be returned in accel_char.
Two accel_marker characters following each other produce a single
literal accel_marker character.
|
a PangoLayout |
|
marked-up text (see markup format) |
|
length of marked-up text in bytes, or -1 if markup is
nul-terminated
|
|
marker for accelerators in the text |
|
return location for first located accelerator, or NULL
|
void pango_layout_set_attributes (PangoLayout *layout, PangoAttrList *attrs);
Sets the text attributes for a layout object.
References attrs, so the caller can unref its reference.
|
a PangoLayout |
|
a PangoAttrList, can be NULL
|
PangoAttrList * pango_layout_get_attributes (PangoLayout *layout);
Gets the attribute list for the layout, if any.
|
a PangoLayout |
Returns : |
a PangoAttrList. |
void pango_layout_set_font_description (PangoLayout *layout, const PangoFontDescription *desc);
Sets the default font description for the layout. If no font description is set on the layout, the font description from the layout's context is used.
|
a PangoLayout |
|
the new PangoFontDescription, or NULL to unset the
current font description
|
const PangoFontDescription * pango_layout_get_font_description (PangoLayout *layout);
Gets the font description for the layout, if any.
|
a PangoLayout |
Returns : |
a pointer to the layout's font description,
or NULL if the font description from the layout's
context is inherited. This value is owned by the layout
and must not be modified or freed.
|
Since 1.8
void pango_layout_set_width (PangoLayout *layout, int width);
Sets the width to which the lines of the PangoLayout should wrap or ellipsized. The default value is -1: no width set.
|
a PangoLayout. |
|
the desired width in Pango units, or -1 to indicate that no wrapping or ellipsization should be performed. |
int pango_layout_get_width (PangoLayout *layout);
Gets the width to which the lines of the PangoLayout should wrap.
|
a PangoLayout |
Returns : |
the width in Pango units, or -1 if no width set. |
void pango_layout_set_height (PangoLayout *layout, int height);
Sets the height to which the PangoLayout should be ellipsized at. There
are two different behaviors, based on whether height is positive or
negative.
If height is positive, it will be the maximum height of the layout. Only
lines would be shown that would fit, and if there is any text omitted,
an ellipsis added. At least one line is included in each paragraph regardless
of how small the height value is. A value of zero will render exactly one
line for the entire layout.
If height is negative, it will be the (negative of) maximum number of lines per
paragraph. That is, the total number of lines shown may well be more than
this value if the layout contains multiple paragraphs of text.
The default value of -1 means that first line of each paragraph is ellipsized.
This behvaior may be changed in the future to act per layout instead of per
paragraph. File a bug against pango at http://bugzilla.gnome.org/ if your
code relies on this behavior.
Height setting only has effect if a positive width is set on
layout and ellipsization mode of layout is not PANGO_ELLIPSIZE_NONE.
The behavior is undefined if a height other than -1 is set and
ellipsization mode is set to PANGO_ELLIPSIZE_NONE, and may change in the
future.
|
a PangoLayout. |
|
the desired height of the layout in Pango units if positive, or desired number of lines if negative. |
Since 1.20
int pango_layout_get_height (PangoLayout *layout);
Gets the height of layout used for ellipsization. See
pango_layout_set_height() for details.
|
a PangoLayout |
Returns : |
the height, in Pango units if positive, or number of lines if negative. |
Since 1.20
void pango_layout_set_wrap (PangoLayout *layout, PangoWrapMode wrap);
Sets the wrap mode; the wrap mode only has effect if a width
is set on the layout with pango_layout_set_width().
To turn off wrapping, set the width to -1.
|
a PangoLayout |
|
the wrap mode |
PangoWrapMode pango_layout_get_wrap (PangoLayout *layout);
Gets the wrap mode for the layout.
Use pango_layout_is_wrapped() to query whether any paragraphs
were actually wrapped.
|
a PangoLayout |
Returns : |
active wrap mode. |
gboolean pango_layout_is_wrapped (PangoLayout *layout);
Queries whether the layout had to wrap any paragraphs.
This returns TRUE if a positive width is set on layout,
ellipsization mode of layout is set to PANGO_ELLIPSIZE_NONE,
and there are paragraphs exceeding the layout width that have
to be wrapped.
|
a PangoLayout |
Returns : |
TRUE if any paragraphs had to be wrapped, FALSE
otherwise.
|
Since 1.16
typedef enum {
PANGO_WRAP_WORD,
PANGO_WRAP_CHAR,
PANGO_WRAP_WORD_CHAR
} PangoWrapMode;
A PangoWrapMode describes how to wrap the lines of a PangoLayout to the desired width.
#define PANGO_TYPE_WRAP_MODE (pango_wrap_mode_get_type())
The GObject type for PangoWrapMode.
void pango_layout_set_ellipsize (PangoLayout *layout, PangoEllipsizeMode ellipsize);
Sets the type of ellipsization being performed for layout.
Depending on the ellipsization mode ellipsize text is
removed from the start, middle, or end of text so they
fit within the width and height of layout set with
pango_layout_set_width() and pango_layout_set_height().
If the layout contains characters such as newlines that
force it to be layed out in multiple paragraphs, then whether
each paragraph is ellipsized separately or the entire layout
is ellipsized as a whole depends on the set height of the layout.
See pango_layout_set_height() for details.
|
a PangoLayout |
|
the new ellipsization mode for layout
|
Since 1.6
PangoEllipsizeMode pango_layout_get_ellipsize (PangoLayout *layout);
Gets the type of ellipsization being performed for layout.
See pango_layout_set_ellipsize()
|
a PangoLayout |
Returns : |
the current ellipsization mode for layout.
Use pango_layout_is_ellipsized() to query whether any paragraphs
were actually ellipsized.
|
Since 1.6
gboolean pango_layout_is_ellipsized (PangoLayout *layout);
Queries whether the layout had to ellipsize any paragraphs.
This returns TRUE if the ellipsization mode for layout
is not PANGO_ELLIPSIZE_NONE, a positive width is set on layout,
and there are paragraphs exceeding that width that have to be
ellipsized.
|
a PangoLayout |
Returns : |
TRUE if any paragraphs had to be ellipsized, FALSE
otherwise.
|
Since 1.16
typedef enum {
PANGO_ELLIPSIZE_NONE,
PANGO_ELLIPSIZE_START,
PANGO_ELLIPSIZE_MIDDLE,
PANGO_ELLIPSIZE_END
} PangoEllipsizeMode;
The PangoEllipsizeMode type describes what sort of (if any) ellipsization should be applied to a line of text. In the ellipsization process characters are removed from the text in order to make it fit to a given width and replaced with an ellipsis.
#define PANGO_TYPE_ELLIPSIZE_MODE (pango_ellipsize_mode_get_type())
The GObject type for PangoEllipsizeMode.
void pango_layout_set_indent (PangoLayout *layout, int indent);
Sets the width in Pango units to indent each paragraph. A negative value
of indent will produce a hanging indentation. That is, the first line will
have the full width, and subsequent lines will be indented by the
absolute value of indent.
The indent setting is ignored if layout alignment is set to
PANGO_ALIGN_CENTER.
|
a PangoLayout. |
|
the amount by which to indent. |
int pango_layout_get_indent (PangoLayout *layout);
Gets the paragraph indent width in Pango units. A negative value indicates a hanging indentation.
|
a PangoLayout |
Returns : |
the indent in Pango units. |
int pango_layout_get_spacing (PangoLayout *layout);
Gets the amount of spacing between the lines of the layout.
|
a PangoLayout |
Returns : |
the spacing in Pango units. |
void pango_layout_set_spacing (PangoLayout *layout, int spacing);
Sets the amount of spacing in Pango unit between the lines of the layout.
|
a PangoLayout. |
|
the amount of spacing |
void pango_layout_set_justify (PangoLayout *layout, gboolean justify);
Sets whether each complete line should be stretched to fill the entire width of the layout. This stretching is typically done by adding whitespace, but for some scripts (such as Arabic), the justification may be done in more complex ways, like extending the characters.
Note that this setting is not implemented and so is ignored in Pango older than 1.18.
|
a PangoLayout |
|
whether the lines in the layout should be justified. |
gboolean pango_layout_get_justify (PangoLayout *layout);
Gets whether each complete line should be stretched to fill the entire width of the layout.
|
a PangoLayout |
Returns : |
the justify. |
void pango_layout_set_auto_dir (PangoLayout *layout, gboolean auto_dir);
Sets whether to calculate the bidirectional base direction
for the layout according to the contents of the layout;
when this flag is on (the default), then paragraphs in
layout that begin with strong right-to-left characters
(Arabic and Hebrew principally), will have right-to-left
layout, paragraphs with letters from other scripts will
have left-to-right layout. Paragraphs with only neutral
characters get their direction from the surrounding paragraphs.
When FALSE, the choice between left-to-right and
right-to-left layout is done according to the base direction
of the layout's PangoContext. (See pango_context_set_base_dir()).
When the auto-computed direction of a paragraph differs from the
base direction of the context, the interpretation of
PANGO_ALIGN_LEFT and PANGO_ALIGN_RIGHT are swapped.
|
a PangoLayout |
|
if TRUE, compute the bidirectional base direction
from the layout's contents.
|
Since 1.4
gboolean pango_layout_get_auto_dir (PangoLayout *layout);
Gets whether to calculate the bidirectional base direction
for the layout according to the contents of the layout.
See pango_layout_set_auto_dir().
|
a PangoLayout |
Returns : |
TRUE if the bidirectional base direction
is computed from the layout's contents, FALSE otherwise.
|
Since 1.4
void pango_layout_set_alignment (PangoLayout *layout, PangoAlignment alignment);
Sets the alignment for the layout: how partial lines are positioned within the horizontal space available.
|
a PangoLayout |
|
the alignment |
PangoAlignment pango_layout_get_alignment (PangoLayout *layout);
Gets the alignment for the layout: how partial lines are positioned within the horizontal space available.
|
a PangoLayout |
Returns : |
the alignment. |
void pango_layout_set_tabs (PangoLayout *layout, PangoTabArray *tabs);
Sets the tabs to use for layout, overriding the default tabs
(by default, tabs are every 8 spaces). If tabs is NULL, the default
tabs are reinstated. tabs is copied into the layout; you must
free your copy of tabs yourself.
|
a PangoLayout |
|
a PangoTabArray, or NULL
|
PangoTabArray* pango_layout_get_tabs (PangoLayout *layout);
Gets the current PangoTabArray used by this layout. If no
PangoTabArray has been set, then the default tabs are in use
and NULL is returned. Default tabs are every 8 spaces.
The return value should be freed with pango_tab_array_free().
|
a PangoLayout |
Returns : |
a copy of the tabs for this layout, or NULL.
|
void pango_layout_set_single_paragraph_mode
(PangoLayout *layout,
gboolean setting);
If setting is TRUE, do not treat newlines and similar characters
as paragraph separators; instead, keep all text in a single paragraph,
and display a glyph for paragraph separator characters. Used when
you want to allow editing of newlines on a single text line.
|
a PangoLayout |
|
new setting |
gboolean pango_layout_get_single_paragraph_mode (PangoLayout *layout);
Obtains the value set by pango_layout_set_single_paragraph_mode().
|
a PangoLayout |
Returns : |
TRUE if the layout does not break paragraphs at
paragraph separator characters, FALSE otherwise.
|
typedef enum {
PANGO_ALIGN_LEFT,
PANGO_ALIGN_CENTER,
PANGO_ALIGN_RIGHT
} PangoAlignment;
A PangoAlignment describes how to align the lines of a PangoLayout within the
available space. If the PangoLayout is set to justify
using pango_layout_set_justify(), this only has effect for partial lines.
#define PANGO_TYPE_ALIGNMENT (pango_alignment_get_type())
The GObject type for PangoAlignment.
int pango_layout_get_unknown_glyphs_count
(PangoLayout *layout);
Counts the number unknown glyphs in layout. That is, zero if
glyphs for all characters in the layout text were found, or more
than zero otherwise.
This function can be used to determine if there are any fonts
available to render all characters in a certain string, or when
used in combination with PANGO_ATTR_FALLBACK, to check if a
certain font supports all the characters in the string.
|
a PangoLayout |
Returns : |
The number of unknown glyphs in layout.
|
Since 1.16
void pango_layout_get_log_attrs (PangoLayout *layout, PangoLogAttr **attrs, gint *n_attrs);
Retrieves an array of logical attributes for each character in
the layout.
|
a PangoLayout |
|
location to store a pointer to an array of logical attributes
This value must be freed with g_free().
|
|
location to store the number of the attributes in the array. (The stored value will be one more than the total number of characters in the layout, since there need to be attributes corresponding to both the position before the first character and the position after the last character.) |
void pango_layout_index_to_pos (PangoLayout *layout, int index_, PangoRectangle *pos);
Converts from an index within a PangoLayout to the onscreen position
corresponding to the grapheme at that index, which is represented
as rectangle. Note that pos->x is always the leading
edge of the grapheme and pos->x + pos->width the trailing
edge of the grapheme. If the directionality of the grapheme is right-to-left,
then pos->width will be negative.
|
a PangoLayout |
|
byte index within layout
|
|
rectangle in which to store the position of the grapheme |
void pango_layout_index_to_line_x (PangoLayout *layout, int index_, gboolean trailing, int *line, int *x_pos);
Converts from byte index_ within the layout to line and X position.
(X position is measured from the left edge of the line)
|
a PangoLayout |
|
the byte index of a grapheme within the layout. |
|
an integer indicating the edge of the grapheme to retrieve the position of. If 0, the trailing edge of the grapheme, if > 0, the leading of the grapheme. |
|
location to store resulting line index. (which will between 0 and pango_layout_get_line_count(layout) - 1) |
|
location to store resulting position within line
(PANGO_SCALE units per device unit)
|
gboolean pango_layout_xy_to_index (PangoLayout *layout, int x, int y, int *index_, int *trailing);
Converts from X and Y position within a layout to the byte
index to the character at that logical position. If the
Y position is not inside the layout, the closest position is chosen
(the position will be clamped inside the layout). If the
X position is not within the layout, then the start or the
end of the line is chosen as described for pango_layout_x_to_index().
If either the X or Y positions were not inside the layout, then the
function returns FALSE; on an exact hit, it returns TRUE.
|
a PangoLayout |
|
the X offset (in Pango units) from the left edge of the layout. |
|
the Y offset (in Pango units) from the top edge of the layout |
|
location to store calculated byte index |
|
location to store a integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the trailing edge of the grapheme. |
Returns : |
TRUE if the coordinates were inside text, FALSE otherwise.
|
void pango_layout_get_cursor_pos (PangoLayout *layout, int index_, PangoRectangle *strong_pos, PangoRectangle *weak_pos);
Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted.
|
a PangoLayout |
|
the byte index of the cursor |
|
location to store the strong cursor position (may be NULL)
|
|
location to store the weak cursor position (may be NULL)
|
void pango_layout_move_cursor_visually (PangoLayout *layout, gboolean strong, int old_index, int old_trailing, int direction, int *new_index, int *new_trailing);
Computes a new cursor position from an old position and
a count of positions to move visually. If direction is positive,
then the new strong cursor position will be one position
to the right of the old cursor position. If direction is negative,
then the new strong cursor position will be one position
to the left of the old cursor position.
In the presence of bidirectional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run.
Motion here is in cursor positions, not in characters, so a
single call to pango_layout_move_cursor_visually() may move the
cursor over multiple characters when multiple characters combine
to form a single grapheme.
|
a PangoLayout. |
|
whether the moving cursor is the strong cursor or the weak cursor. The strong cursor is the cursor corresponding to text insertion in the base direction for the layout. |
|
the byte index of the grapheme for the old index |
|
if 0, the cursor was at the trailing edge of the
grapheme indicated by old_index, if > 0, the cursor
was at the leading edge.
|
|
direction to move cursor. A negative value indicates motion to the left. |
|
location to store the new cursor byte index. A value of -1
indicates that the cursor has been moved off the beginning
of the layout. A value of G_MAXINT indicates that
the cursor has been moved off the end of the layout.
|
|
number of characters to move forward from the location returned
for new_index to get the position where the cursor should
be displayed. This allows distinguishing the position at
the beginning of one line from the position at the end
of the preceding line. new_index is always on the line
where the cursor should be displayed.
|
void pango_layout_get_extents (PangoLayout *layout, PangoRectangle *ink_rect, PangoRectangle *logical_rect);
Computes the logical and ink extents of layout. Logical extents
are usually what you want for positioning things. Note that both extents
may have non-zero x and y. You may want to use those to offset where you
render the layout. Not doing that is a very typical bug that shows up as
right-to-left layouts not being correctly positioned in a layout with
a set width.
The extents are given in layout coordinates and in Pango units; layout coordinates begin at the top left corner of the layout.
|
a PangoLayout |
|
rectangle used to store the extents of the layout as drawn
or NULL to indicate that the result is not needed.
|
|
rectangle used to store the logical extents of the layout
or NULL to indicate that the result is not needed.
|
void pango_layout_get_pixel_extents (PangoLayout *layout, PangoRectangle *ink_rect, PangoRectangle *logical_rect);
Computes the logical and ink extents of layout in device units.
This function just calls pango_layout_get_extents() followed by
two pango_extents_to_pixels() calls, rounding ink_rect and logical_rect
such that the rounded rectangles fully contain the unrounded one (that is,
passes them as first argument to pango_extents_to_pixels()).
|
a PangoLayout |
|
rectangle used to store the extents of the layout as drawn
or NULL to indicate that the result is not needed.
|
|
rectangle used to store the logical extents of the
layout or NULL to indicate that the result is not needed.
|
void pango_layout_get_size (PangoLayout *layout, int *width, int *height);
Determines the logical width and height of a PangoLayout
in Pango units (device units scaled by PANGO_SCALE). This
is simply a convenience function around pango_layout_get_extents().
|
a PangoLayout |
|
location to store the logical width, or NULL
|
|
location to store the logical height, or NULL
|
void pango_layout_get_pixel_size (PangoLayout *layout, int *width, int *height);
Determines the logical width and height of a PangoLayout
in device units. (pango_layout_get_size() returns the width
and height scaled by PANGO_SCALE.) This
is simply a convenience function around
pango_layout_get_pixel_extents().
|
a PangoLayout |
|
location to store the logical width, or NULL
|
|
location to store the logical height, or NULL
|
int pango_layout_get_baseline (PangoLayout *layout);
Gets the Y position of baseline of the first line in layout.
|
a PangoLayout |
Returns : |
baseline of first line, from top of layout.
|
Since 1.22
int pango_layout_get_line_count (PangoLayout *layout);
Retrieves the count of lines for the layout.
|
PangoLayout |
Returns : |
the line count. |
PangoLayoutLine * pango_layout_get_line (PangoLayout *layout, int line);
Retrieves a particular line from a PangoLayout.
Use the faster pango_layout_get_line_readonly() if you do not plan
to modify the contents of the line (glyphs, glyph widths, etc.).
|
a PangoLayout |
|
the index of a line, which must be between 0 and
pango_layout_get_line_count(layout) - 1, inclusive.
|
Returns : |
the requested PangoLayoutLine, or NULL if the
index is out of range. This layout line can
be ref'ed and retained, but will become invalid
if changes are made to the PangoLayout.
|
PangoLayoutLine * pango_layout_get_line_readonly (PangoLayout *layout, int line);
Retrieves a particular line from a PangoLayout.
This is a faster alternative to pango_layout_get_line(),
but the user is not expected
to modify the contents of the line (glyphs, glyph widths, etc.).
|
a PangoLayout |
|
the index of a line, which must be between 0 and
pango_layout_get_line_count(layout) - 1, inclusive.
|
Returns : |
the requested PangoLayoutLine, or NULL if the
index is out of range. This layout line can
be ref'ed and retained, but will become invalid
if changes are made to the PangoLayout.
No changes should be made to the line.
|
Since 1.16
GSList * pango_layout_get_lines (PangoLayout *layout);
Returns the lines of the layout as a list.
Use the faster pango_layout_get_lines_readonly() if you do not plan
to modify the contents of the lines (glyphs, glyph widths, etc.).
|
a PangoLayout |
Returns : |
element-type Pango.LayoutLine): (transfer none. element-type Pango.LayoutLine): (transfer none. |
GSList * pango_layout_get_lines_readonly (PangoLayout *layout);
Returns the lines of the layout as a list.
This is a faster alternative to pango_layout_get_lines(),
but the user is not expected
to modify the contents of the lines (glyphs, glyph widths, etc.).
|
a PangoLayout |
Returns : |
element-type Pango.LayoutLine): (transfer none. element-type Pango.LayoutLine): (transfer none. |
Since 1.16
PangoLayoutIter * pango_layout_get_iter (PangoLayout *layout);
Returns an iterator to iterate over the visual extents of the layout.
|
a PangoLayout |
Returns : |
the new PangoLayoutIter that should be freed using
pango_layout_iter_free().
|
PangoLayoutIter * pango_layout_iter_copy (PangoLayoutIter *iter);
Copies a PangLayoutIter.
|
a PangoLayoutIter, may be NULL
|
Returns : |
the newly allocated PangoLayoutIter, which should
be freed with pango_layout_iter_free(), or NULL if
iter was NULL.
|
Since 1.20
void pango_layout_iter_free (PangoLayoutIter *iter);
Frees an iterator that's no longer in use.
|
a PangoLayoutIter, may be NULL
|
gboolean pango_layout_iter_next_run (PangoLayoutIter *iter);
Moves iter forward to the next run in visual order. If iter was
already at the end of the layout, returns FALSE.
|
a PangoLayoutIter |
Returns : |
whether motion was possible. |
gboolean pango_layout_iter_next_char (PangoLayoutIter *iter);
Moves iter forward to the next character in visual order. If iter was already at
the end of the layout, returns FALSE.
|
a PangoLayoutIter |
Returns : |
whether motion was possible. |
gboolean pango_layout_iter_next_cluster (PangoLayoutIter *iter);
Moves iter forward to the next cluster in visual order. If iter
was already at the end of the layout, returns FALSE.
|
a PangoLayoutIter |
Returns : |
whether motion was possible. |
gboolean pango_layout_iter_next_line (PangoLayoutIter *iter);
Moves iter forward to the start of the next line. If iter is
already on the last line, returns FALSE.
|
a PangoLayoutIter |
Returns : |
whether motion was possible. |
gboolean pango_layout_iter_at_last_line (PangoLayoutIter *iter);
Determines whether iter is on the last line of the layout.
|
a PangoLayoutIter |
Returns : |
TRUE if iter is on the last line.
|
int pango_layout_iter_get_index (PangoLayoutIter *iter);
Gets the current byte index. Note that iterating forward by char
moves in visual order, not logical order, so indexes may not be
sequential. Also, the index may be equal to the length of the text
in the layout, if on the NULL run (see pango_layout_iter_get_run()).
|
a PangoLayoutIter |
Returns : |
current byte index. |
int pango_layout_iter_get_baseline (PangoLayoutIter *iter);
Gets the Y position of the current line's baseline, in layout coordinates (origin at top left of the entire layout).
|
a PangoLayoutIter |
Returns : |
baseline of current line. |
PangoLayoutRun * pango_layout_iter_get_run (PangoLayoutIter *iter);
Gets the current run. When iterating by run, at the end of each
line, there's a position with a NULL run, so this function can return
NULL. The NULL run at the end of each line ensures that all lines have
at least one run, even lines consisting of only a newline.
Use the faster pango_layout_iter_get_run_readonly() if you do not plan
to modify the contents of the run (glyphs, glyph widths, etc.).
|
a PangoLayoutIter |
Returns : |
the current run. |
PangoLayoutRun * pango_layout_iter_get_run_readonly (PangoLayoutIter *iter);
Gets the current run. When iterating by run, at the end of each
line, there's a position with a NULL run, so this function can return
NULL. The NULL run at the end of each line ensures that all lines have
at least one run, even lines consisting of only a newline.
This is a faster alternative to pango_layout_iter_get_run(),
but the user is not expected
to modify the contents of the run (glyphs, glyph widths, etc.).
|
a PangoLayoutIter |
Returns : |
the current run, that should not be modified. |
Since 1.16
PangoLayoutLine * pango_layout_iter_get_line (PangoLayoutIter *iter);
Gets the current line.
Use the faster pango_layout_iter_get_line_readonly() if you do not plan
to modify the contents of the line (glyphs, glyph widths, etc.).
|
a PangoLayoutIter |
Returns : |
the current line. |
PangoLayoutLine * pango_layout_iter_get_line_readonly (PangoLayoutIter *iter);
Gets the current line for read-only access.
This is a faster alternative to pango_layout_iter_get_line(),
but the user is not expected
to modify the contents of the line (glyphs, glyph widths, etc.).
|
a PangoLayoutIter |
Returns : |
the current line, that should not be modified. |
Since 1.16
PangoLayout * pango_layout_iter_get_layout (PangoLayoutIter *iter);
Gets the layout associated with a PangoLayoutIter.
|
a PangoLayoutIter |
Returns : |
the layout associated with iter.
|
Since 1.20
void pango_layout_iter_get_char_extents (PangoLayoutIter *iter, PangoRectangle *logical_rect);
Gets the extents of the current character, in layout coordinates (origin is the top left of the entire layout). Only logical extents can sensibly be obtained for characters; ink extents make sense only down to the level of clusters.
|
a PangoLayoutIter |
|
rectangle to fill with logical extents |
void pango_layout_iter_get_cluster_extents
(PangoLayoutIter *iter,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
Gets the extents of the current cluster, in layout coordinates (origin is the top left of the entire layout).
|
a PangoLayoutIter |
|
rectangle to fill with ink extents, or NULL
|
|
rectangle to fill with logical extents, or NULL
|
void pango_layout_iter_get_run_extents (PangoLayoutIter *iter, PangoRectangle *ink_rect, PangoRectangle *logical_rect);
Gets the extents of the current run in layout coordinates (origin is the top left of the entire layout).
|
a PangoLayoutIter |
|
rectangle to fill with ink extents, or NULL
|
|
rectangle to fill with logical extents, or NULL
|
void pango_layout_iter_get_line_yrange (PangoLayoutIter *iter, int *y0_, int *y1_);
Divides the vertical space in the PangoLayout being iterated over
between the lines in the layout, and returns the space belonging to
the current line. A line's range includes the line's logical
extents, plus half of the spacing above and below the line, if
pango_layout_set_spacing() has been called to set layout spacing.
The Y positions are in layout coordinates (origin at top left of the
entire layout).
|
a PangoLayoutIter |
|
start of line |
|
end of line |
void pango_layout_iter_get_line_extents (PangoLayoutIter *iter, PangoRectangle *ink_rect, PangoRectangle *logical_rect);
Obtains the extents of the current line. ink_rect or logical_rect
can be NULL if you aren't interested in them. Extents are in layout
coordinates (origin is the top-left corner of the entire
PangoLayout). Thus the extents returned by this function will be
the same width/height but not at the same x/y as the extents
returned from pango_layout_line_get_extents().
|
a PangoLayoutIter |
|
rectangle to fill with ink extents, or NULL
|
|
rectangle to fill with logical extents, or NULL
|
void pango_layout_iter_get_layout_extents
(PangoLayoutIter *iter,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
Obtains the extents of the PangoLayout being iterated
over. ink_rect or logical_rect can be NULL if you
aren't interested in them.
|
a PangoLayoutIter |
|
rectangle to fill with ink extents, or NULL
|
|
rectangle to fill with logical extents, or NULL
|
typedef struct {
PangoLayout *layout;
gint start_index; /* start of line as byte index into layout->text */
gint length; /* length of line in bytes */
GSList *runs;
guint is_paragraph_start : 1; /* TRUE if this is the first line of the paragraph */
guint resolved_dir : 3; /* Resolved PangoDirection of line */
} PangoLayoutLine;
The PangoLayoutLine structure represents one of the lines resulting
from laying out a paragraph via PangoLayout. PangoLayoutLine
structures are obtained by calling pango_layout_get_line() and
are only valid until the text, attributes, or settings of the
parent PangoLayout are modified.
Routines for rendering PangoLayout objects are provided in code specific to each rendering system.
PangoLayout * |
the parent layout for this line |
gint |
the start of the line as byte index into layout->text
|
gint |
the length of the line in bytes |
GSList * |
a list containing the runs of the line in visual order |
guint |
%TRUE if this is the first line of the paragraph |
guint |
the resolved PangoDirection of the line |
typedef PangoGlyphItem PangoLayoutRun;
The PangoLayoutRun structure represents a single run within a PangoLayoutLine; it is simply an alternate name for PangoGlyphItem. See the PangoGlyphItem docs for details on the fields.
PangoLayoutLine * pango_layout_line_ref (PangoLayoutLine *line);
Increase the reference count of a PangoLayoutLine by one.
|
a PangoLayoutLine, may be NULL
|
Returns : |
the line passed in. |
Since 1.10
void pango_layout_line_unref (PangoLayoutLine *line);
Decrease the reference count of a PangoLayoutLine by one. If the result is zero, the line and all associated memory will be freed.
|
a PangoLayoutLine |
void pango_layout_line_get_extents (PangoLayoutLine *line, PangoRectangle *ink_rect, PangoRectangle *logical_rect);
Computes the logical and ink extents of a layout line. See
pango_font_get_glyph_extents() for details about the interpretation
of the rectangles.
|
a PangoLayoutLine |
|
rectangle used to store the extents of the glyph string
as drawn, or NULL
|
|
rectangle used to store the logical extents of the glyph
string, or NULL
|
void pango_layout_line_get_pixel_extents (PangoLayoutLine *layout_line, PangoRectangle *ink_rect, PangoRectangle *logical_rect);
Computes the logical and ink extents of layout_line in device units.
This function just calls pango_layout_line_get_extents() followed by
two pango_extents_to_pixels() calls, rounding ink_rect and logical_rect
such that the rounded rectangles fully contain the unrounded one (that is,
passes them as first argument to pango_extents_to_pixels()).
|
a PangoLayoutLine |
|
rectangle used to store the extents of the glyph string
as drawn, or NULL
|
|
rectangle used to store the logical extents of the glyph
string, or NULL
|
void pango_layout_line_index_to_x (PangoLayoutLine *line, int index_, gboolean trailing, int *x_pos);
Converts an index within a line to a X position.
|
a PangoLayoutLine |
|
byte offset of a grapheme within the layout |
|
an integer indicating the edge of the grapheme to retrieve the position of. If > 0, the trailing edge of the grapheme, if 0, the leading of the grapheme. |
|
location to store the x_offset (in Pango unit) |
gboolean pango_layout_line_x_to_index (PangoLayoutLine *line, int x_pos, int *index_, int *trailing);
Converts from x offset to the byte index of the corresponding
character within the text of the layout. If x_pos is outside the line,
index_ and trailing will point to the very first or very last position
in the line. This determination is based on the resolved direction
of the paragraph; for example, if the resolved direction is
right-to-left, then an X position to the right of the line (after it)
results in 0 being stored in index_ and trailing. An X position to the
left of the line results in index_ pointing to the (logical) last
grapheme in the line and trailing being set to the number of characters
in that grapheme. The reverse is true for a left-to-right line.
|
a PangoLayoutLine |
|
the X offset (in Pango units) from the left edge of the line. |
|
location to store calculated byte index for the grapheme in which the user clicked. |
|
location to store an integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the leading edge of the grapheme. |
Returns : |
FALSE if x_pos was outside the line, TRUE if inside
|
void pango_layout_line_get_x_ranges (PangoLayoutLine *line, int start_index, int end_index, int **ranges, int *n_ranges);
Gets a list of visual ranges corresponding to a given logical range. This list is not necessarily minimal - there may be consecutive ranges which are adjacent. The ranges will be sorted from left to right. The ranges are with respect to the left edge of the entire layout, not with respect to the line.
|
a PangoLayoutLine |
|
Start byte index of the logical range. If this value is less than the start index for the line, then the first range will extend all the way to the leading edge of the layout. Otherwise it will start at the leading edge of the first character. |
|
Ending byte index of the logical range. If this value is greater than the end index for the line, then the last range will extend all the way to the trailing edge of the layout. Otherwise, it will end at the trailing edge of the last character. |
|
out): (array length=n_ranges): (transfer=full. out): (array length=n_ranges): (transfer=full. |
|
The number of ranges stored in ranges.
|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Prerequisites | ||||
PangoCairoFont;
PangoCairoFontMap;
PangoFontMap * pango_cairo_font_map_get_default (void);
void pango_cairo_font_map_set_default (PangoCairoFontMap *fontmap);
PangoFontMap * pango_cairo_font_map_new (void);
PangoFontMap * pango_cairo_font_map_new_for_font_type
(cairo_font_type_t fonttype);
cairo_font_type_t pango_cairo_font_map_get_font_type (PangoCairoFontMap *fontmap);
void pango_cairo_font_map_set_resolution (PangoCairoFontMap *fontmap,
double dpi);
double pango_cairo_font_map_get_resolution (PangoCairoFontMap *fontmap);
PangoContext * pango_cairo_font_map_create_context (PangoCairoFontMap *fontmap);
cairo_scaled_font_t * pango_cairo_font_get_scaled_font (PangoCairoFont *font);
void pango_cairo_context_set_resolution (PangoContext *context,
double dpi);
double pango_cairo_context_get_resolution (PangoContext *context);
void pango_cairo_context_set_font_options
(PangoContext *context,
const cairo_font_options_t *options);
const cairo_font_options_t * pango_cairo_context_get_font_options
(PangoContext *context);
void (*PangoCairoShapeRendererFunc) (cairo_t *cr,
PangoAttrShape *attr,
gboolean do_path,
gpointer data);
void pango_cairo_context_set_shape_renderer
(PangoContext *context,
PangoCairoShapeRendererFunc func,
gpointer data,
GDestroyNotify dnotify);
PangoCairoShapeRendererFunc pango_cairo_context_get_shape_renderer
(PangoContext *context,
gpointer *data);
PangoContext * pango_cairo_create_context (cairo_t *cr);
void pango_cairo_update_context (cairo_t *cr,
PangoContext *context);
PangoLayout * pango_cairo_create_layout (cairo_t *cr);
void pango_cairo_update_layout (cairo_t *cr,
PangoLayout *layout);
void pango_cairo_show_glyph_string (cairo_t *cr,
PangoFont *font,
PangoGlyphString *glyphs);
void pango_cairo_show_glyph_item (cairo_t *cr,
const char *text,
PangoGlyphItem *glyph_item);
void pango_cairo_show_layout_line (cairo_t *cr,
PangoLayoutLine *line);
void pango_cairo_show_layout (cairo_t *cr,
PangoLayout *layout);
void pango_cairo_show_error_underline (cairo_t *cr,
double x,
double y,
double width,
double height);
void pango_cairo_glyph_string_path (cairo_t *cr,
PangoFont *font,
PangoGlyphString *glyphs);
void pango_cairo_layout_line_path (cairo_t *cr,
PangoLayoutLine *line);
void pango_cairo_layout_path (cairo_t *cr,
PangoLayout *layout);
void pango_cairo_error_underline_path (cairo_t *cr,
double x,
double y,
double width,
double height);
The Cairo library is a vector graphics library with a powerful rendering model. It has such features as anti-aliased primitives, alpha-compositing, and gradients. Multiple backends for Cairo are available, to allow rendering to images, to PDF files, and to the screen on X and on other windowing systems. The functions in this section allow using Pango to render to Cairo surfaces.
Using Pango with Cairo is straightforward. A PangoContext created
with pango_cairo_font_map_create_context() can be used on any
Cairo context (cairo_t), but needs to be updated to match the
current transformation matrix and target surface of the Cairo context
using pango_cairo_update_context(). The convenience functions
pango_cairo_create_layout() and pango_cairo_update_layout() handle
the common case where the program doesn't need to manipulate the
properties of the PangoContext.
When you get the metrics of a layout or of a piece of a layout using
functions such as pango_layout_get_extents(), the reported metrics
are in user-space coordinates. If a piece of text is 10 units long,
and you call cairo_scale (cr, 2.0), it still is more-or-less 10
units long. However, the results will be affected by hinting
(that is, the process of adjusting the text to look good on the
pixel grid), so you shouldn't assume they are completely independent
of the current transformation matrix. Note that the basic metrics
functions in Pango report results in integer Pango units. To get
to the floating point units used in Cairo divide by PANGO_SCALE.
Example 1. Using Pango with Cairo
#include <math.h>
#include <pango/pangocairo.h>
static void
draw_text (cairo_t *cr)
{
#define RADIUS 150
#define N_WORDS 10
#define FONT "Sans Bold 27"
PangoLayout *layout;
PangoFontDescription *desc;
int i;
/* Center coordinates on the middle of the region we are drawing
*/
cairo_translate (cr, RADIUS, RADIUS);
/* Create a PangoLayout, set the font and text */
layout = pango_cairo_create_layout (cr);
pango_layout_set_text (layout, "Text", -1);
desc = pango_font_description_from_string (FONT);
pango_layout_set_font_description (layout, desc);
pango_font_description_free (desc);
/* Draw the layout N_WORDS times in a circle */
for (i = 0; i < N_WORDS; i++)
{
int width, height;
double angle = (360. * i) / N_WORDS;
double red;
cairo_save (cr);
/* Gradient from red at angle == 60 to blue at angle == 240 */
red = (1 + cos ((angle - 60) * G_PI / 180.)) / 2;
cairo_set_source_rgb (cr, red, 0, 1.0 - red);
cairo_rotate (cr, angle * G_PI / 180.);
/* Inform Pango to re-layout the text with the new transformation */
pango_cairo_update_layout (cr, layout);
pango_layout_get_size (layout, &width, &height);
cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS);
pango_cairo_show_layout (cr, layout);
cairo_restore (cr);
}
/* free the layout object */
g_object_unref (layout);
}
int main (int argc, char **argv)
{
cairo_t *cr;
char *filename;
cairo_status_t status;
cairo_surface_t *surface;
if (argc != 2)
{
g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n");
return 1;
}
filename = argv[1];
surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
2 * RADIUS, 2 * RADIUS);
cr = cairo_create (surface);
cairo_set_source_rgb (cr, 1.0, 1.0, 1.0);
cairo_paint (cr);
draw_text (cr);
cairo_destroy (cr);
status = cairo_surface_write_to_png (surface, filename);
cairo_surface_destroy (surface);
if (status != CAIRO_STATUS_SUCCESS)
{
g_printerr ("Could not save png to '%s'\n", filename);
return 1;
}
return 0;
}
typedef struct _PangoCairoFont PangoCairoFont;
PangoCairoFont is an interface exported by fonts for use with Cairo. The actual type of the font will depend on the particular font technology Cairo was compiled to use.
Since 1.18
typedef struct _PangoCairoFontMap PangoCairoFontMap;
PangoCairoFontMap is an interface exported by font maps for use with Cairo. The actual type of the font map will depend on the particular font technology Cairo was compiled to use.
Since 1.10
PangoFontMap * pango_cairo_font_map_get_default (void);
Gets a default PangoCairoFontMap to use with Cairo.
Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use; You generally should only use the PangoFontMap and PangoCairoFontMap interfaces on the returned object.
The default Cairo fontmap can be changed by using
pango_cairo_font_map_set_default(). This can be used to
change the Cairo font backend that the default fontmap
uses for example.
Returns : |
the default Cairo fontmap for Pango. This object is owned by Pango and must not be freed. |
Since 1.10
void pango_cairo_font_map_set_default (PangoCairoFontMap *fontmap);
Sets a default PangoCairoFontMap to use with Cairo.
This can be used to change the Cairo font backend that the default fontmap uses for example. The old default font map is unreffed and the new font map referenced.
A value of NULL for fontmap will cause the current default
font map to be released and a new default font
map to be created on demand, using pango_cairo_font_map_new().
|
The new default font map, or NULL
|
Since 1.22
PangoFontMap * pango_cairo_font_map_new (void);
Creates a new PangoCairoFontMap object; a fontmap is used
to cache information about available fonts, and holds
certain global parameters such as the resolution.
In most cases, you can use pango_cairo_font_map_get_default()
instead.
Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use; You generally should only use the PangoFontMap and PangoCairoFontMap interfaces on the returned object.
Returns : |
the newly allocated PangoFontMap, which should
be freed with g_object_unref().
|
Since 1.10
PangoFontMap * pango_cairo_font_map_new_for_font_type (cairo_font_type_t fonttype);
Creates a new PangoCairoFontMap object of the type suitable
to be used with cairo font backend of type fonttype.
In most cases one should simply use @pango_cairo_font_map_new(),
or in fact in most of those cases, just use
@pango_cairo_font_map_get_default().
|
desired cairo_font_type_t |
Returns : |
the newly allocated PangoFontMap of suitable type
which should be freed with g_object_unref(),
or NULL if the requested cairo font backend is
not supported / compiled in.
|
Since 1.18
cairo_font_type_t pango_cairo_font_map_get_font_type (PangoCairoFontMap *fontmap);
Gets the type of Cairo font backend that fontmap uses.
|
a PangoCairoFontMap |
Returns : |
the cairo_font_type_t cairo font backend type |
Since 1.18
void pango_cairo_font_map_set_resolution (PangoCairoFontMap *fontmap, double dpi);
Sets the resolution for the fontmap. This is a scale factor between points specified in a PangoFontDescription and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3).
|
a PangoCairoFontMap |
|
the resolution in "dots per inch". (Physical inches aren't actually involved; the terminology is conventional.) |
Since 1.10
double pango_cairo_font_map_get_resolution (PangoCairoFontMap *fontmap);
Gets the resolution for the fontmap. See pango_cairo_font_map_set_resolution()
|
a PangoCairoFontMap |
Returns : |
the resolution in "dots per inch" |
Since 1.10
PangoContext * pango_cairo_font_map_create_context (PangoCairoFontMap *fontmap);
pango_cairo_font_map_create_context has been deprecated since version 1.22 and should not be used in newly-written code. Use pango_font_map_create_context() instead.
Create a PangoContext for the given fontmap.
|
a PangoCairoFontMap |
Returns : |
the newly created context; free with g_object_unref().
|
Since 1.10
cairo_scaled_font_t * pango_cairo_font_get_scaled_font (PangoCairoFont *font);
Gets the cairo_scaled_font_t used by font.
The scaled font can be referenced and kept using
cairo_scaled_font_reference().
|
a PangoFont from a PangoCairoFontMap |
Returns : |
the cairo_scaled_font_t used by font,
or NULL if font is NULL.
|
Since 1.18
void pango_cairo_context_set_resolution (PangoContext *context, double dpi);
Sets the resolution for the context. This is a scale factor between points specified in a PangoFontDescription and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3).
|
a PangoContext, from a pangocairo font map |
|
the resolution in "dots per inch". (Physical inches aren't actually involved; the terminology is conventional.) A 0 or negative value means to use the resolution from the font map. |
Since 1.10
double pango_cairo_context_get_resolution (PangoContext *context);
Gets the resolution for the context. See pango_cairo_context_set_resolution()
|
a PangoContext, from a pangocairo font map |
Returns : |
the resolution in "dots per inch". A negative value will be returned if no resolution has previously been set. |
Since 1.10
void pango_cairo_context_set_font_options
(PangoContext *context,
const cairo_font_options_t *options);
Sets the font options used when rendering text with this context.
These options override any options that pango_cairo_update_context()
derives from the target surface.
|
a PangoContext, from a pangocairo font map |
|
a cairo_font_options_t, or NULL to unset any previously set
options. A copy is made.
|
Since 1.10
const cairo_font_options_t * pango_cairo_context_get_font_options (PangoContext *context);
Retrieves any font rendering options previously set with
pango_cairo_font_map_set_font_options(). This function does not report options
that are derived from the target surface by pango_cairo_update_context()
|
a PangoContext, from a pangocairo font map |
Returns : |
the font options previously set on the context, or NULL
if no options have been set. This value is owned by the context
and must not be modified or freed.
|
Since 1.10
void (*PangoCairoShapeRendererFunc) (cairo_t *cr, PangoAttrShape *attr, gboolean do_path, gpointer data);
Function type for rendering attributes of type PANGO_ATTR_SHAPE
with Pango's Cairo renderer.
|
a Cairo context with current point set to where the shape should be rendered |
|
the PANGO_ATTR_SHAPE to render
|
|
whether only the shape path should be appended to current
path of cr and no filling/stroking done. This will be set
to TRUE when called from pango_cairo_layout_path() and
pango_cairo_layout_line_path() rendering functions.
|
|
user data passed to pango_cairo_context_set_shape_renderer()
|
void pango_cairo_context_set_shape_renderer
(PangoContext *context,
PangoCairoShapeRendererFunc func,
gpointer data,
GDestroyNotify dnotify);
Sets callback function for context to use for rendering attributes
of type PANGO_ATTR_SHAPE. See PangoCairoShapeRendererFunc for
details.
|
a PangoContext, from a pangocairo font map |
|
Callback function for rendering attributes of type
PANGO_ATTR_SHAPE, or NULL to disable shape rendering.
|
|
User data that will be passed to func.
|
|
Callback that will be called when the
context is freed to release data, or NULL.
|
Since 1.18
PangoCairoShapeRendererFunc pango_cairo_context_get_shape_renderer (PangoContext *context, gpointer *data);
Sets callback function for context to use for rendering attributes
of type PANGO_ATTR_SHAPE. See PangoCairoShapeRendererFunc for
details.
Retrieves callback function and associated user data for rendering
attributes of type PANGO_ATTR_SHAPE as set by
pango_cairo_context_set_shape_renderer(), if any.
|
a PangoContext, from a pangocairo font map |
|
Pointer to gpointer to return user data |
Returns : |
the shape rendering callback previously set on the context, or NULL
if no shape rendering callback have been set.
|
Since 1.18
PangoContext * pango_cairo_create_context (cairo_t *cr);
Creates a context object set up to match the current transformation
and target surface of the Cairo context. This context can then be
used to create a layout using pango_layout_new().
This function is a convenience function that creates a context using
the default font map, then updates it to cr. If you just need to
create a layout for use with cr and do not need to access PangoContext
directly, you can use pango_cairo_create_layout() instead.
|
a Cairo context |
Returns : |
the newly created PangoContext. Free with
g_object_unref().
|
Since 1.22
void pango_cairo_update_context (cairo_t *cr, PangoContext *context);
Updates a PangoContext previously created for use with Cairo to
match the current transformation and target surface of a Cairo
context. If any layouts have been created for the context,
it's necessary to call pango_layout_context_changed() on those
layouts.
|
a Cairo context |
|
a PangoContext, from a pangocairo font map |
Since 1.10
PangoLayout * pango_cairo_create_layout (cairo_t *cr);
Creates a layout object set up to match the current transformation
and target surface of the Cairo context. This layout can then be
used for text measurement with functions like
pango_layout_get_size() or drawing with functions like
pango_cairo_show_layout(). If you change the transformation
or target surface for cr, you need to call pango_cairo_update_layout()
This function is the most convenient way to use Cairo with Pango, however it is slightly inefficient since it creates a separate PangoContext object for each layout. This might matter in an application that was laying out large amounts of text.
|
a Cairo context |
Returns : |
the newly created PangoLayout. Free with
g_object_unref().
|
Since 1.10
void pango_cairo_update_layout (cairo_t *cr, PangoLayout *layout);
Updates the private PangoContext of a PangoLayout created with
pango_cairo_create_layout() to match the current transformation
and target surface of a Cairo context.
|
a Cairo context |
|
a PangoLayout, from pango_cairo_create_layout()
|
Since 1.10
void pango_cairo_show_glyph_string (cairo_t *cr, PangoFont *font, PangoGlyphString *glyphs);
Draws the glyphs in glyphs in the specified cairo context.
The origin of the glyphs (the left edge of the baseline) will
be drawn at the current point of the cairo context.
|
a Cairo context |
|
a PangoFont from a PangoCairoFontMap |
|
a PangoGlyphString |
Since 1.10
void pango_cairo_show_glyph_item (cairo_t *cr, const char *text, PangoGlyphItem *glyph_item);
Draws the glyphs in glyph_item in the specified cairo context,
embedding the text associated with the glyphs in the output if the
output format supports it (PDF for example), otherwise it acts
similar to pango_cairo_show_glyph_string().
The origin of the glyphs (the left edge of the baseline) will be drawn at the current point of the cairo context.
Note that text is the start of the text for layout, which is then
indexed by glyph_item->item->offset
|
a Cairo context |
|
the UTF-8 text that glyph_item refers to
|
|
a PangoGlyphItem |
Since 1.22
void pango_cairo_show_layout_line (cairo_t *cr, PangoLayoutLine *line);
Draws a PangoLayoutLine in the specified cairo context. The origin of the glyphs (the left edge of the line) will be drawn at the current point of the cairo context.
|
a Cairo context |
|
a PangoLayoutLine |
Since 1.10
void pango_cairo_show_layout (cairo_t *cr, PangoLayout *layout);
Draws a PangoLayoutLine in the specified cairo context. The top-left corner of the PangoLayout will be drawn at the current point of the cairo context.
|
a Cairo context |
|
a Pango layout |
Since 1.10
void pango_cairo_show_error_underline (cairo_t *cr, double x, double y, double width, double height);
Draw a squiggly line in the specified cairo context that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. (The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle)
|
a Cairo context |
|
The X coordinate of one corner of the rectangle |
|
The Y coordinate of one corner of the rectangle |
|
Non-negative width of the rectangle |
|
Non-negative height of the rectangle |
Since 1.14
void pango_cairo_glyph_string_path (cairo_t *cr, PangoFont *font, PangoGlyphString *glyphs);
Adds the glyphs in glyphs to the current path in the specified
cairo context. The origin of the glyphs (the left edge of the baseline)
will be at the current point of the cairo context.
|
a Cairo context |
|
a PangoFont from a PangoCairoFontMap |
|
a PangoGlyphString |
Since 1.10
void pango_cairo_layout_line_path (cairo_t *cr, PangoLayoutLine *line);
Adds the text in PangoLayoutLine to the current path in the specified cairo context. The origin of the glyphs (the left edge of the line) will be at the current point of the cairo context.
|
a Cairo context |
|
a PangoLayoutLine |
Since 1.10
void pango_cairo_layout_path (cairo_t *cr, PangoLayout *layout);
Adds the text in a PangoLayout to the current path in the specified cairo context. The top-left corner of the PangoLayout will be at the current point of the cairo context.
|
a Cairo context |
|
a Pango layout |
Since 1.10
void pango_cairo_error_underline_path (cairo_t *cr, double x, double y, double width, double height);
Add a squiggly line to the current path in the specified cairo context that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. (The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle)
|
a Cairo context |
|
The X coordinate of one corner of the rectangle |
|
The Y coordinate of one corner of the rectangle |
|
Non-negative width of the rectangle |
|
Non-negative height of the rectangle |
Since 1.14
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|
Text Attribute MarkupText Attribute Markup — Simple markup language to encode text with attributes |
Frequently, you want to display some text to the user with attributes applied to part of the text (for example, you might want bold or italicized words). With the base Pango interfaces, you could create a PangoAttrList and apply it to the text; the problem is that you'd need to apply attributes to some numeric range of characters, for example "characters 12-17." This is broken from an internationalization standpoint; once the text is translated, the word you wanted to italicize could be in a different position.
The solution is to include the text attributes in the string to be translated. Pango provides this feature with a small markup language. You can parse a marked-up string into the string text plus a PangoAttrList using the function pango_parse_markup().
A simple example of a marked-up string might be:
"<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!"
The root tag of a marked-up document is <markup>, but pango_parse_markup() allows you to omit this tag, so you will most likely never need to use it. The most general markup tag is <span>, then there are some convenience tags. <span> has the following attributes:
<span> attributes
font[1], font_desc |
A font description string, such as "Sans Italic 12". See pango_font_description_from_string() for a description of the format of the string representation . Note that any other span attributes will override this description. So if you have "Sans Italic" and also a style="normal" attribute, you will get Sans normal, not italic. |
font_family, face |
A font family name |
font_size[1], size |
Font size in 1024ths of a point, or one of the absolute sizes
'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large',
'xx-large', or one of the relative sizes 'smaller' or 'larger'.
If you want to specify a absolute size, it's usually easier
to take advantage of the ability to specify a partial
font description using 'font'; you can use
|
font_style[1], style |
One of 'normal', 'oblique', 'italic' |
font_weight[1], weight |
One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight |
font_variant[1], variant |
One of 'normal' or 'smallcaps' |
font_stretch[1], stretch |
One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded' |
foreground, fgcolor[1], color |
An RGB color specification such as '#00FF00' or a color name such as 'red' |
background, bgcolor[1] |
An RGB color specification such as '#00FF00' or a color name such as 'red' |
underline |
One of 'none', 'single', 'double', 'low', 'error' |
underline_color |
The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red' |
rise |
Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript. |
strikethrough |
'true' or 'false' whether to strike through the text |
strikethrough_color |
The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red' |
fallback |
'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback. |
lang |
A language code, indicating the text language |
letter_spacing |
Inter-letter spacing in 1024ths of a point. |
gravity |
One of 'south', 'east', 'north', 'west', 'auto'. |
gravity_hint |
One of 'natural', 'strong', 'line'. |
The following convenience tags are provided:
Convenience tags
b |
Bold |
big |
Makes font relatively larger, equivalent to <span size="larger"> |
i |
Italic |
s |
Strikethrough |
sub |
Subscript |
sup |
Superscript |
small |
Makes font relatively smaller, equivalent to <span size="smaller"> |
tt |
Monospace font |
u |
Underline |
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | ||||
PangoFcFont;
PangoFcFontClass;
#define PANGO_RENDER_TYPE_FC
FT_Face pango_fc_font_lock_face (PangoFcFont *font);
void pango_fc_font_unlock_face (PangoFcFont *font);
gboolean pango_fc_font_has_char (PangoFcFont *font,
gunichar wc);
guint pango_fc_font_get_glyph (PangoFcFont *font,
gunichar wc);
PangoGlyph pango_fc_font_get_unknown_glyph (PangoFcFont *font,
gunichar wc);
void pango_fc_font_kern_glyphs (PangoFcFont *font,
PangoGlyphString *glyphs);
"fontmap" PangoFcFontMap* : Read / Write "pattern" gpointer : Read / Write / Construct Only
PangoFcFont is a base class for font implementation using the Fontconfig and FreeType libraries. It is used in the Xft and FreeType backends shipped with Pango, but can also be used when creating new backends. Any backend deriving from this base class will take advantage of the wide range of shapers implemented using FreeType that come with Pango.
typedef struct _PangoFcFont PangoFcFont;
PangoFcFont is a base class for font implementations
using the Fontconfig and FreeType libraries and is used in
conjunction with PangoFcFontMap. When deriving from this
class, you need to implement all of its virtual functions
other than shutdown() along with the get_glyph_extents()
virtual function from PangoFont.
typedef struct {
FT_Face (*lock_face) (PangoFcFont *font);
void (*unlock_face) (PangoFcFont *font);
gboolean (*has_char) (PangoFcFont *font,
gunichar wc);
guint (*get_glyph) (PangoFcFont *font,
gunichar wc);
PangoGlyph (*get_unknown_glyph) (PangoFcFont *font,
gunichar wc);
void (*shutdown) (PangoFcFont *font);
} PangoFcFontClass;
Class structure for PangoFcFont.
|
Returns the FT_Face of the font and increases the reference count for the face by one. |
|
Decreases the reference count for the FT_Face of the font by one. When the count is zero, the PangoFcFont subclass is allowed to free the FT_Face. |
|
Return TRUE if the the font contains a glyph
corresponding to the specified character.
|
|
Gets the glyph that corresponds to the given Unicode character. |
|
Gets the glyph that should be used to
display an unknown-glyph indication for the specified
Unicode character.
May be NULL.
|
|
Performs any font-specific shutdown code that
needs to be done when pango_fc_font_map_shutdown is called.
May be NULL.
|
#define PANGO_RENDER_TYPE_FC "PangoRenderFc"
A string constant used to identify shape engines that work
with the fontconfig based backends. See the engine_type field
of PangoEngineInfo.
FT_Face pango_fc_font_lock_face (PangoFcFont *font);
Gets the FreeType FT_Face associated with a font,
This face will be kept around until you call
pango_fc_font_unlock_face().
|
a PangoFcFont. |
Returns : |
the FreeType FT_Face associated with font.
|
Since 1.4
void pango_fc_font_unlock_face (PangoFcFont *font);
Releases a font previously obtained with
pango_fc_font_lock_face().
|
a PangoFcFont. |
Since 1.4
gboolean pango_fc_font_has_char (PangoFcFont *font, gunichar wc);
Determines whether font has a glyph for the codepoint wc.
|
a PangoFcFont |
|
Unicode codepoint to look up |
Returns : |
TRUE if font has the requested codepoint.
|
Since 1.4
guint pango_fc_font_get_glyph (PangoFcFont *font, gunichar wc);
Gets the glyph index for a given Unicode character
for font. If you only want to determine
whether the font has the glyph, use pango_fc_font_has_char().
|
a PangoFcFont |
|
Unicode character to look up |
Returns : |
the glyph index, or 0, if the Unicode character doesn't exist in the font. |
Since 1.4
PangoGlyph pango_fc_font_get_unknown_glyph (PangoFcFont *font, gunichar wc);
pango_fc_font_get_unknown_glyph is deprecated and should not be used in newly-written code.
Returns the index of a glyph suitable for drawing wc as an
unknown character.
Use PANGO_GET_UNKNOWN_GLYPH() instead.
|
a PangoFcFont |
|
the Unicode character for which a glyph is needed. |
Returns : |
a glyph index into font.
|
Since 1.4
void pango_fc_font_kern_glyphs (PangoFcFont *font, PangoGlyphString *glyphs);
Adjust each adjacent pair of glyphs in glyphs according to
kerning information in font.
|
a PangoFcFont |
|
a PangoGlyphString |
Since 1.4
"fontmap" property"fontmap" PangoFcFontMap* : Read / Write
The PangoFc font map this font is associated with (Since: 1.26).
"pattern" property"pattern" gpointer : Read / Write / Construct Only
The fontconfig pattern for this font.
The base class for font maps; creating a new Fontconfig-based backend involves deriving from both PangoFcFontMap and PangoFcFont. . |
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
PangoContext;
PangoItem;
PangoAnalysis;
#define PANGO_ANALYSIS_FLAG_CENTERED_BASELINE
#define PANGO_TYPE_DIRECTION
GList * pango_itemize (PangoContext *context,
const char *text,
int start_index,
int length,
PangoAttrList *attrs,
PangoAttrIterator *cached_iter);
GList * pango_itemize_with_base_dir (PangoContext *context,
PangoDirection base_dir,
const char *text,
int start_index,
int length,
PangoAttrList *attrs,
PangoAttrIterator *cached_iter);
void pango_item_free (PangoItem *item);
PangoItem * pango_item_copy (PangoItem *item);
PangoItem * pango_item_new (void);
PangoItem * pango_item_split (PangoItem *orig,
int split_index,
int split_offset);
GList * pango_reorder_items (GList *logical_items);
PangoContext * pango_context_new (void);
void pango_context_set_font_map (PangoContext *context,
PangoFontMap *font_map);
PangoFontMap * pango_context_get_font_map (PangoContext *context);
PangoFontDescription * pango_context_get_font_description
(PangoContext *context);
void pango_context_set_font_description (PangoContext *context,
const PangoFontDescription *desc);
PangoLanguage * pango_context_get_language (PangoContext *context);
void pango_context_set_language (PangoContext *context,
PangoLanguage *language);
PangoDirection pango_context_get_base_dir (PangoContext *context);
void pango_context_set_base_dir (PangoContext *context,
PangoDirection direction);
PangoGravity pango_context_get_base_gravity (PangoContext *context);
void pango_context_set_base_gravity (PangoContext *context,
PangoGravity gravity);
PangoGravity pango_context_get_gravity (PangoContext *context);
PangoGravityHint pango_context_get_gravity_hint (PangoContext *context);
void pango_context_set_gravity_hint (PangoContext *context,
PangoGravityHint hint);
const PangoMatrix * pango_context_get_matrix (PangoContext *context);
void pango_context_set_matrix (PangoContext *context,
const PangoMatrix *matrix);
PangoFont * pango_context_load_font (PangoContext *context,
const PangoFontDescription *desc);
PangoFontset * pango_context_load_fontset (PangoContext *context,
const PangoFontDescription *desc,
PangoLanguage *language);
PangoFontMetrics * pango_context_get_metrics (PangoContext *context,
const PangoFontDescription *desc,
PangoLanguage *language);
void pango_context_list_families (PangoContext *context,
PangoFontFamily ***families,
int *n_families);
void pango_break (const gchar *text,
int length,
PangoAnalysis *analysis,
PangoLogAttr *attrs,
int attrs_len);
void pango_get_log_attrs (const char *text,
int length,
int level,
PangoLanguage *language,
PangoLogAttr *log_attrs,
int attrs_len);
void pango_find_paragraph_boundary (const gchar *text,
gint length,
gint *paragraph_delimiter_index,
gint *next_paragraph_start);
void pango_default_break (const gchar *text,
int length,
PangoAnalysis *analysis,
PangoLogAttr *attrs,
int attrs_len);
PangoLogAttr;
void pango_shape (const gchar *text,
gint length,
const PangoAnalysis *analysis,
PangoGlyphString *glyphs);
The Pango rendering pipeline takes a string of Unicode characters and converts it into glyphs. The functions described in this section accomplish various steps of this process.
typedef struct _PangoContext PangoContext;
The PangoContext structure stores global information used to control the itemization process.
typedef struct {
gint offset;
gint length;
gint num_chars;
PangoAnalysis analysis;
} PangoItem;
The PangoItem structure stores information about a segment of text. It contains the following fields:
gint |
the offset of the segment from the beginning of the string in bytes. |
gint |
the length of the segment in bytes. |
gint |
the length of the segment in characters. |
PangoAnalysis |
the properties of the segment. |
typedef struct {
PangoEngineShape *shape_engine;
PangoEngineLang *lang_engine;
PangoFont *font;
guint8 level;
guint8 gravity; /* PangoGravity */
guint8 flags;
guint8 script; /* PangoScript */
PangoLanguage *language;
GSList *extra_attrs;
} PangoAnalysis;
The PangoAnalysis structure stores information about the properties of a segment of text. It has the following fields:
PangoEngineShape * |
the engine for doing rendering-system-dependent processing. |
PangoEngineLang * |
the engine for doing rendering-system-independent processing. |
PangoFont * |
the font for this segment. |
guint8 |
the bidirectional level for this segment. |
guint8 |
the glyph orientation for this segment (A PangoGravity). |
guint8 |
boolean flags for this segment (currently only one) (Since: 1.16). |
guint8 |
the detected script for this segment (A PangoScript) (Since: 1.18). |
PangoLanguage * |
the detected language for this segment. |
GSList * |
extra attributes for this segment. |
#define PANGO_ANALYSIS_FLAG_CENTERED_BASELINE (1 << 0)
Whether the segment should be shifted to center around the baseline. Used in vertical writing directions mostly. Since: 1.16
#define PANGO_TYPE_DIRECTION (pango_direction_get_type())
The GObject type for PangoDirection.
GList * pango_itemize (PangoContext *context, const char *text, int start_index, int length, PangoAttrList *attrs, PangoAttrIterator *cached_iter);
Breaks a piece of text into segments with consistent
directional level and shaping engine. Each byte of text will
be contained in exactly one of the items in the returned list;
the generated list of items will be in logical order (the start
offsets of the items are ascending).
cached_iter should be an iterator over attrs currently positioned at a
range before or containing start_index; cached_iter will be advanced to
the range covering the position just after start_index + length.
(i.e. if itemizing in a loop, just keep passing in the same cached_iter).
|
a structure holding information that affects the itemization process. |
|
the text to itemize. |
|
first byte in text to process
|
|
the number of bytes (not characters) to process
after start_index.
This must be >= 0.
|
|
the set of attributes that apply to text.
|
|
Cached attribute iterator, or NULL
|
Returns : |
a GList of PangoItem structures. |
GList * pango_itemize_with_base_dir (PangoContext *context, PangoDirection base_dir, const char *text, int start_index, int length, PangoAttrList *attrs, PangoAttrIterator *cached_iter);
Like pango_itemize(), but the base direction to use when
computing bidirectional levels (see pango_context_set_base_dir()),
is specified explicitly rather than gotten from the PangoContext.
|
a structure holding information that affects the itemization process. |
|
base direction to use for bidirectional processing |
|
the text to itemize. |
|
first byte in text to process
|
|
the number of bytes (not characters) to process
after start_index.
This must be >= 0.
|
|
the set of attributes that apply to text.
|
|
Cached attribute iterator, or NULL
|
Returns : |
a GList of PangoItem structures. The items should be
freed using pango_item_free() probably in combination with g_list_foreach(),
and the list itself using g_list_free().
|
Since 1.4
void pango_item_free (PangoItem *item);
Free a PangoItem and all associated memory.
PangoItem * pango_item_copy (PangoItem *item);
Copy an existing PangoItem structure.
|
a PangoItem, may be NULL
|
Returns : |
the newly allocated PangoItem, which should
be freed with pango_item_free(), or NULL if
item was NULL.
|
PangoItem * pango_item_new (void);
Creates a new PangoItem structure initialized to default values.
Returns : |
the newly allocated PangoItem, which should
be freed with pango_item_free().
|
PangoItem * pango_item_split (PangoItem *orig, int split_index, int split_offset);
Modifies orig to cover only the text after split_index, and
returns a new item that covers the text before split_index that
used to be in orig. You can think of split_index as the length of
the returned item. split_index may not be 0, and it may not be
greater than or equal to the length of orig (that is, there must
be at least one byte assigned to each item, you can't create a
zero-length item). split_offset is the length of the first item in
chars, and must be provided because the text used to generate the
item isn't available, so pango_item_split() can't count the char
length of the split items itself.
|
a PangoItem |
|
byte index of position to split item, relative to the start of the item |
|
number of chars between start of orig and split_index
|
Returns : |
new item representing text before split_index, which
should be freed with pango_item_free().
|
GList * pango_reorder_items (GList *logical_items);
From a list of items in logical order and the associated directional levels, produce a list in visual order. The original list is unmodified.
PangoContext * pango_context_new (void);
Creates a new PangoContext initialized to default values.
This function is not particularly useful as it should always
be followed by a pango_context_set_font_map() call, and the
function pango_font_map_create_context() does these two steps
together and hence users are recommended to use that.
If you are using Pango as part of a higher-level system,
that system may have it's own way of create a PangoContext.
For instance, the GTK+ toolkit has, among others,
gdk_pango_context_get_for_screen(), and
gtk_widget_get_pango_context(). Use those instead.
Returns : |
the newly allocated PangoContext, which should
be freed with g_object_unref().
|
void pango_context_set_font_map (PangoContext *context, PangoFontMap *font_map);
Sets the font map to be searched when fonts are looked-up in this context. This is only for internal use by Pango backends, a PangoContext obtained via one of the recommended methods should already have a suitable font map.
|
a PangoContext |
|
the PangoFontMap to set. |
PangoFontMap * pango_context_get_font_map (PangoContext *context);
Gets the PangoFontmap used to look up fonts for this context.
|
a PangoContext |
Returns : |
the font map for the PangoContext. This value is owned by Pango and should not be unreferenced. |
Since 1.6
PangoFontDescription * pango_context_get_font_description (PangoContext *context);
Retrieve the default font description for the context.
|
a PangoContext |
Returns : |
a pointer to the context's default font description. This value must not be modified or freed. |
void pango_context_set_font_description (PangoContext *context, const PangoFontDescription *desc);
Set the default font description for the context
|
a PangoContext |
|
the new pango font description |
PangoLanguage * pango_context_get_language (PangoContext *context);
Retrieves the global language tag for the context.
|
a PangoContext |
Returns : |
the global language tag. |
void pango_context_set_language (PangoContext *context, PangoLanguage *language);
Sets the global language tag for the context. The default language
for the locale of the running process can be found using
pango_language_get_default().
|
a PangoContext |
|
the new language tag. |
PangoDirection pango_context_get_base_dir (PangoContext *context);
Retrieves the base direction for the context. See
pango_context_set_base_dir().
|
a PangoContext |
Returns : |
the base direction for the context. |
void pango_context_set_base_dir (PangoContext *context, PangoDirection direction);
Sets the base direction for the context.
The base direction is used in applying the Unicode bidirectional
algorithm; if the direction is PANGO_DIRECTION_LTR or
PANGO_DIRECTION_RTL, then the value will be used as the paragraph
direction in the Unicode bidirectional algorithm. A value of
PANGO_DIRECTION_WEAK_LTR or PANGO_DIRECTION_WEAK_RTL is used only
for paragraphs that do not contain any strong characters themselves.
|
a PangoContext |
|
the new base direction |
PangoGravity pango_context_get_base_gravity (PangoContext *context);
Retrieves the base gravity for the context. See
pango_context_set_base_gravity().
|
a PangoContext |
Returns : |
the base gravity for the context. |
Since 1.16
void pango_context_set_base_gravity (PangoContext *context, PangoGravity gravity);
Sets the base gravity for the context.
The base gravity is used in laying vertical text out.
|
a PangoContext |
|
the new base gravity |
Since 1.16
PangoGravity pango_context_get_gravity (PangoContext *context);
Retrieves the gravity for the context. This is similar to
pango_context_get_base_gravity(), except for when the base gravity
is PANGO_GRAVITY_AUTO for which pango_gravity_get_for_matrix() is used
to return the gravity from the current context matrix.
|
a PangoContext |
Returns : |
the resolved gravity for the context. |
Since 1.16
PangoGravityHint pango_context_get_gravity_hint (PangoContext *context);
Retrieves the gravity hint for the context. See
pango_context_set_gravity_hint() for details.
|
a PangoContext |
Returns : |
the gravity hint for the context. |
Since 1.16
void pango_context_set_gravity_hint (PangoContext *context, PangoGravityHint hint);
Sets the gravity hint for the context.
The gravity hint is used in laying vertical text out, and is only relevant
if gravity of the context as returned by pango_context_get_gravity()
is set PANGO_GRAVITY_EAST or PANGO_GRAVITY_WEST.
|
a PangoContext |
|
the new gravity hint |
Since 1.16
const PangoMatrix * pango_context_get_matrix (PangoContext *context);
Gets the transformation matrix that will be applied when
rendering with this context. See pango_context_set_matrix().
|
a PangoContext |
Returns : |
the matrix, or NULL if no matrix has been set
(which is the same as the identity matrix). The returned
matrix is owned by Pango and must not be modified or
freed.
|
Since 1.6
void pango_context_set_matrix (PangoContext *context, const PangoMatrix *matrix);
Sets the transformation matrix that will be applied when rendering with this context. Note that reported metrics are in the user space coordinates before the application of the matrix, not device-space coordinates after the application of the matrix. So, they don't scale with the matrix, though they may change slightly for different matrices, depending on how the text is fit to the pixel grid.
|
a PangoContext |
|
a PangoMatrix, or NULL to unset any existing matrix.
(No matrix set is the same as setting the identity matrix.)
|
Since 1.6
PangoFont * pango_context_load_font (PangoContext *context, const PangoFontDescription *desc);
Loads the font in one of the fontmaps in the context
that is the closest match for desc.
|
a PangoContext |
|
a PangoFontDescription describing the font to load |
Returns : |
the font loaded, or NULL if no font matched.
|
PangoFontset * pango_context_load_fontset (PangoContext *context, const PangoFontDescription *desc, PangoLanguage *language);
Load a set of fonts in the context that can be used to render
a font matching desc.
|
a PangoContext |
|
a PangoFontDescription describing the fonts to load |
|
a PangoLanguage the fonts will be used for |
Returns : |
the fontset, or NULL if no font matched.
|
PangoFontMetrics * pango_context_get_metrics (PangoContext *context, const PangoFontDescription *desc, PangoLanguage *language);
Get overall metric information for a particular font description. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be retrieved that correspond to the script(s) used by that language.
The PangoFontDescription is interpreted in the same way as
by pango_itemize(), and the family name may be a comma separated
list of figures. If characters from multiple of these families
would be used to render the string, then the returned fonts would
be a composite of the metrics for the fonts loaded for the
individual families.
|
a PangoContext |
|
a PangoFontDescription structure. NULL means that the font
description from the context will be used.
|
|
language tag used to determine which script to get the metrics
for. NULL means that the language tag from the context will
be used. If no language tag is set on the context, metrics
for the default language (as determined by
pango_language_get_default()) will be returned.
|
Returns : |
a PangoFontMetrics object. The caller must call pango_font_metrics_unref()
when finished using the object.
|
void pango_context_list_families (PangoContext *context, PangoFontFamily ***families, int *n_families);
List all families for a context.
|
a PangoContext |
|
location to store a pointer to an array of PangoFontFamily *.
This array should be freed with g_free().
|
|
location to store the number of elements in descs
|
void pango_break (const gchar *text, int length, PangoAnalysis *analysis, PangoLogAttr *attrs, int attrs_len);
Determines possible line, word, and character breaks
for a string of Unicode text with a single analysis. For most
purposes you may want to use pango_get_log_attrs().
|
the text to process |
|
length of text in bytes (may be -1 if text is nul-terminated)
|
|
PangoAnalysis structure from pango_itemize()
|
|
an array to store character information in |
|
size of the array passed as attrs
|
void pango_get_log_attrs (const char *text,
int length,
int level,
PangoLanguage *language,
PangoLogAttr *log_attrs,
int attrs_len);
Computes a PangoLogAttr for each character in text. The log_attrs
array must have one PangoLogAttr for each position in text; if
text contains N characters, it has N+1 positions, including the
last position at the end of the text. text should be an entire
paragraph; logical attributes can't be computed without context
(for example you need to see spaces on either side of a word to know
the word is a word).
|
text to process |
|
length in bytes of text
|
|
embedding level, or -1 if unknown |
|
language tag |
|
array with one PangoLogAttr per character in text, plus one extra, to be filled in
|
|
length of log_attrs array
|
void pango_find_paragraph_boundary (const gchar *text, gint length, gint *paragraph_delimiter_index, gint *next_paragraph_start);
Locates a paragraph boundary in text. A boundary is caused by
delimiter characters, such as a newline, carriage return, carriage
return-newline pair, or Unicode paragraph separator character. The
index of the run of delimiters is returned in
paragraph_delimiter_index. The index of the start of the paragraph
(index after all delimiters) is stored in next_paragraph_start.
If no delimiters are found, both paragraph_delimiter_index and
next_paragraph_start are filled with the length of text (an index one
off the end).
|
UTF-8 text |
|
length of text in bytes, or -1 if nul-terminated
|
|
return location for index of delimiter |
|
return location for start of next paragraph |
void pango_default_break (const gchar *text, int length, PangoAnalysis *analysis, PangoLogAttr *attrs, int attrs_len);
This is the default break algorithm, used if no language
engine overrides it. Normally you should use pango_break()
instead. Unlike pango_break(),
analysis can be NULL, but only do that if you know what
you're doing. If you need an analysis to pass to pango_break(),
you need to pango_itemize(). In most cases however you should
simply use pango_get_log_attrs().
|
text to break |
|
length of text in bytes (may be -1 if text is nul-terminated)
|
|
a PangoAnalysis for the text
|
|
logical attributes to fill in |
|
size of the array passed as attrs
|
typedef struct {
guint is_line_break : 1; /* Can break line in front of character */
guint is_mandatory_break : 1; /* Must break line in front of character */
guint is_char_break : 1; /* Can break here when doing char wrap */
guint is_white : 1; /* Whitespace character */
/* Cursor can appear in front of character (i.e. this is a grapheme
* boundary, or the first character in the text).
*/
guint is_cursor_position : 1;
/* Note that in degenerate cases, you could have both start/end set on
* some text, most likely for sentences (e.g. no space after a period, so
* the next sentence starts right away).
*/
guint is_word_start : 1; /* first character in a word */
guint is_word_end : 1; /* is first non-word char after a word */
/* There are two ways to divide sentences. The first assigns all
* intersentence whitespace/control/format chars to some sentence,
* so all chars are in some sentence; is_sentence_boundary denotes
* the boundaries there. The second way doesn't assign
* between-sentence spaces, etc. to any sentence, so
* is_sentence_start/is_sentence_end mark the boundaries of those
* sentences.
*/
guint is_sentence_boundary : 1;
guint is_sentence_start : 1; /* first character in a sentence */
guint is_sentence_end : 1; /* first non-sentence char after a sentence */
/* If set, backspace deletes one character rather than
* the entire grapheme cluster.
*/
guint backspace_deletes_character : 1;
/* Only few space variants (U+0020 and U+00A0) have variable
* width during justification.
*/
guint is_expandable_space : 1;
/* Word boundary as defined by UAX#29 */
guint is_word_boundary : 1; /* is NOT in the middle of a word */
} PangoLogAttr;
The PangoLogAttr structure stores information about the attributes of a single character.
guint |
if set, can break line in front of character |
guint |
if set, must break line in front of character |
guint |
if set, can break here when doing character wrapping |
guint |
is whitespace character |
guint |
if set, cursor can appear in front of character. i.e. this is a grapheme boundary, or the first character in the text. This flag implements Unicode's Grapheme Cluster Boundaries semantics. |
guint |
is first character in a word |
guint |
is first non-word char after a word
Note that in degenerate cases, you could have both is_word_start
and is_word_end set for some character.
|
guint |
is a sentence boundary.
There are two ways to divide sentences. The first assigns all
inter-sentence whitespace/control/format chars to some sentence,
so all chars are in some sentence; is_sentence_boundary denotes
the boundaries there. The second way doesn't assign
between-sentence spaces, etc. to any sentence, so
is_sentence_start/is_sentence_end mark the boundaries
of those sentences.
|
guint |
is first character in a sentence |
guint |
is first char after a sentence.
Note that in degenerate cases, you could have both is_sentence_start
and is_sentence_end set for some character. (e.g. no space after a
period, so the next sentence starts right away)
|
guint |
if set, backspace deletes one character
rather than the entire grapheme cluster. This
field is only meaningful on grapheme
boundaries (where is_cursor_position is
set). In some languages, the full grapheme
(e.g. letter + diacritics) is considered a
unit, while in others, each decomposed
character in the grapheme is a unit. In the
default implementation of pango_break(), this
bit is set on all grapheme boundaries except
those following Latin, Cyrillic or Greek base
characters.
|
guint |
is a whitespace character that can possibly be expanded for justification purposes. (Since: 1.18) |
guint |
is a word boundary. More specifically, means that this is not a position in the middle of a word. For example, both sides of a punctuation mark are considered word boundaries. This flag is particularly useful when selecting text word-by-word. This flag implements Unicode's Word Boundaries semantics. (Since: 1.22) |
void pango_shape (const gchar *text, gint length, const PangoAnalysis *analysis, PangoGlyphString *glyphs);
Given a segment of text and the corresponding
PangoAnalysis structure returned from pango_itemize(),
convert the characters into glyphs. You may also pass
in only a substring of the item from pango_itemize().
|
the text to process |
|
the length (in bytes) of text
|
|
PangoAnalysis structure from pango_itemize()
|
|
glyph string in which to store results |
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
#define PANGO_SCALE #define PANGO_PIXELS (d) #define PANGO_PIXELS_FLOOR (d) #define PANGO_PIXELS_CEIL (d) #define PANGO_UNITS_ROUND (d) double pango_units_to_double (int i); int pango_units_from_double (double d); PangoRectangle; #define PANGO_ASCENT (rect) #define PANGO_DESCENT (rect) #define PANGO_LBEARING (rect) #define PANGO_RBEARING (rect) void pango_extents_to_pixels (PangoRectangle *inclusive, PangoRectangle *nearest); PangoMatrix; #define PANGO_TYPE_MATRIX #define PANGO_MATRIX_INIT PangoMatrix * pango_matrix_copy (const PangoMatrix *matrix); void pango_matrix_free (PangoMatrix *matrix); void pango_matrix_translate (PangoMatrix *matrix, double tx, double ty); void pango_matrix_scale (PangoMatrix *matrix, double scale_x, double scale_y); void pango_matrix_rotate (PangoMatrix *matrix, double degrees); void pango_matrix_concat (PangoMatrix *matrix, const PangoMatrix *new_matrix); void pango_matrix_transform_point (const PangoMatrix *matrix, double *x, double *y); void pango_matrix_transform_distance (const PangoMatrix *matrix, double *dx, double *dy); void pango_matrix_transform_rectangle (const PangoMatrix *matrix, PangoRectangle *rect); void pango_matrix_transform_pixel_rectangle (const PangoMatrix *matrix, PangoRectangle *rect); double pango_matrix_get_font_scale_factor (const PangoMatrix *matrix); typedef PangoGlyph; #define PANGO_GLYPH_EMPTY #define PANGO_GLYPH_INVALID_INPUT #define PANGO_GLYPH_UNKNOWN_FLAG #define PANGO_GET_UNKNOWN_GLYPH (wc) PangoGlyphInfo; PangoGlyphGeometry; typedef PangoGlyphUnit; PangoGlyphVisAttr; PangoGlyphString; PangoGlyphItem; PangoGlyphItemIter; #define PANGO_TYPE_GLYPH_STRING PangoGlyphString * pango_glyph_string_new (void); PangoGlyphString * pango_glyph_string_copy (PangoGlyphString *string); void pango_glyph_string_set_size (PangoGlyphString *string, gint new_len); void pango_glyph_string_free (PangoGlyphString *string); void pango_glyph_string_extents (PangoGlyphString *glyphs, PangoFont *font, PangoRectangle *ink_rect, PangoRectangle *logical_rect); void pango_glyph_string_extents_range (PangoGlyphString *glyphs, int start, int end, PangoFont *font, PangoRectangle *ink_rect, PangoRectangle *logical_rect); int pango_glyph_string_get_width (PangoGlyphString *glyphs); void pango_glyph_string_index_to_x (PangoGlyphString *glyphs, char *text, int length, PangoAnalysis *analysis, int index_, gboolean trailing, int *x_pos); void pango_glyph_string_x_to_index (PangoGlyphString *glyphs, char *text, int length, PangoAnalysis *analysis, int x_pos, int *index_, int *trailing); void pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs, const char *text, int length, int embedding_level, int *logical_widths); #define PANGO_TYPE_GLYPH_ITEM PangoGlyphItem * pango_glyph_item_copy (PangoGlyphItem *orig); void pango_glyph_item_free (PangoGlyphItem *glyph_item); PangoGlyphItem * pango_glyph_item_split (PangoGlyphItem *orig, const char *text, int split_index); GSList * pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item, const char *text, PangoAttrList *list); void pango_glyph_item_letter_space (PangoGlyphItem *glyph_item, const char *text, PangoLogAttr *log_attrs, int letter_spacing); void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item, const char *text, int *logical_widths); #define PANGO_TYPE_GLYPH_ITEM_ITER PangoGlyphItemIter * pango_glyph_item_iter_copy (PangoGlyphItemIter *orig); void pango_glyph_item_iter_free (PangoGlyphItemIter *iter); gboolean pango_glyph_item_iter_init_start (PangoGlyphItemIter *iter, PangoGlyphItem *glyph_item, const char *text); gboolean pango_glyph_item_iter_init_end (PangoGlyphItemIter *iter, PangoGlyphItem *glyph_item, const char *text); gboolean pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter); gboolean pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter);
pango_shape() produces a string of glyphs which
can be measured or drawn to the screen. The following
structures are used to store information about
glyphs.
#define PANGO_SCALE 1024
The PANGO_SCALE macro represents the scale between dimensions used
for Pango distances and device units. (The definition of device
units is dependent on the output device; it will typically be pixels
for a screen, and points for a printer.) PANGO_SCALE is currently
1024, but this may be changed in the future.
When setting font sizes, device units are always considered to be points (as in "12 point font"), rather than pixels.
#define PANGO_PIXELS(d) (((int)(d) + 512) >> 10)
Converts a dimension to device units by rounding.
|
a dimension in Pango units. |
Returns : |
rounded dimension in device units. |
#define PANGO_PIXELS_FLOOR(d) (((int)(d)) >> 10)
Converts a dimension to device units by flooring.
|
a dimension in Pango units. |
Returns : |
floored dimension in device units. |
Since 1.14
#define PANGO_PIXELS_CEIL(d) (((int)(d) + 1023) >> 10)
Converts a dimension to device units by ceiling.
|
a dimension in Pango units. |
Returns : |
ceiled dimension in device units. |
Since 1.14
#define PANGO_UNITS_ROUND(d)
Rounds a dimension to whole device units, but does not convert it to device units.
|
a dimension in Pango units. |
Returns : |
rounded dimension in Pango units. |
Since 1.18
double pango_units_to_double (int i);
Converts a number in Pango units to floating-point: divides
it by PANGO_SCALE.
|
value in Pango units |
Returns : |
the double value. |
Since 1.16
int pango_units_from_double (double d);
Converts a floating-point number to Pango units: multiplies
it by PANGO_SCALE and rounds to nearest integer.
|
double floating-point value |
Returns : |
the value in Pango units. |
Since 1.16
typedef struct {
int x;
int y;
int width;
int height;
} PangoRectangle;
The PangoRectangle structure represents a rectangle. It is frequently
used to represent the logical or ink extents of a single glyph or section
of text. (See, for instance, pango_font_get_glyph_extents())
int |
X coordinate of the left side of the rectangle. |
int |
Y coordinate of the the top side of the rectangle. |
int |
width of the rectangle. |
int |
height of the rectangle. |
#define PANGO_ASCENT(rect) (-(rect).y)
Extracts the ascent from a PangoRectangle representing glyph extents. The ascent is the distance from the baseline to the highest point of the character. This is positive if the glyph ascends above the baseline.
|
a PangoRectangle |
#define PANGO_DESCENT(rect) ((rect).y + (rect).height)
Extracts the descent from a PangoRectangle representing glyph extents. The descent is the distance from the baseline to the lowest point of the character. This is positive if the glyph descends below the baseline.
|
a PangoRectangle |
#define PANGO_LBEARING(rect) ((rect).x)
Extracts the left bearing from a PangoRectangle representing glyph extents. The left bearing is the distance from the horizontal origin to the farthest left point of the character. This is positive for characters drawn completely to the right of the glyph origin.
|
a PangoRectangle |
#define PANGO_RBEARING(rect) ((rect).x + (rect).width)
Extracts the right bearing from a PangoRectangle representing glyph extents. The right bearing is the distance from the horizontal origin to the farthest right point of the character. This is positive except for characters drawn completely to the left of the horizontal origin.
|
a PangoRectangle |
void pango_extents_to_pixels (PangoRectangle *inclusive, PangoRectangle *nearest);
Converts extents from Pango units to device units, dividing by the
PANGO_SCALE factor and performing rounding.
The inclusive rectangle is converted by flooring the x/y coordinates and extending
width/height, such that the final rectangle completely includes the original
rectangle.
The nearest rectangle is converted by rounding the coordinates
of the rectangle to the nearest device unit (pixel).
The rule to which argument to use is: if you want the resulting device-space
rectangle to completely contain the original rectangle, pass it in as inclusive.
If you want two touching-but-not-overlapping rectangles stay
touching-but-not-overlapping after rounding to device units, pass them in
as nearest.
|
rectangle to round to pixels inclusively, or NULL.
|
|
rectangle to round to nearest pixels, or NULL.
|
Since 1.16
typedef struct {
double xx;
double xy;
double yx;
double yy;
double x0;
double y0;
} PangoMatrix;
A structure specifying a transformation between user-space coordinates and device coordinates. The transformation is given by
x_device = x_user * matrix->xx + y_user * matrix->xy + matrix->x0; y_device = x_user * matrix->yx + y_user * matrix->yy + matrix->y0;
double |
1st component of the transformation matrix |
double |
2nd component of the transformation matrix |
double |
3rd component of the transformation matrix |
double |
4th component of the transformation matrix |
double |
x translation |
double |
y translation |
Since 1.6
#define PANGO_TYPE_MATRIX (pango_matrix_get_type ())
The GObject type for PangoMatrix
#define PANGO_MATRIX_INIT { 1., 0., 0., 1., 0., 0. }
Constant that can be used to initialize a PangoMatrix to the identity transform.
PangoMatrix matrix = PANGO_MATRIX_INIT; pango_matrix_rotate (&matrix, 45.);
Since 1.6
PangoMatrix * pango_matrix_copy (const PangoMatrix *matrix);
Copies a PangoMatrix.
|
a PangoMatrix, may be NULL
|
Returns : |
the newly allocated PangoMatrix, which should
be freed with pango_matrix_free(), or NULL if
matrix was NULL.
|
Since 1.6
void pango_matrix_free (PangoMatrix *matrix);
Free a PangoMatrix created with pango_matrix_copy().
|
a PangoMatrix, may be NULL
|
Since 1.6
void pango_matrix_translate (PangoMatrix *matrix, double tx, double ty);
Changes the transformation represented by matrix to be the
transformation given by first translating by (tx, ty)
then applying the original transformation.
|
a PangoMatrix |
|
amount to translate in the X direction |
|
amount to translate in the Y direction |
Since 1.6
void pango_matrix_scale (PangoMatrix *matrix, double scale_x, double scale_y);
Changes the transformation represented by matrix to be the
transformation given by first scaling by sx in the X direction
and sy in the Y direction then applying the original
transformation.
|
a PangoMatrix |
|
amount to scale by in X direction |
|
amount to scale by in Y direction |
Since 1.6
void pango_matrix_rotate (PangoMatrix *matrix, double degrees);
Changes the transformation represented by matrix to be the
transformation given by first rotating by degrees degrees
counter-clockwise then applying the original transformation.
|
a PangoMatrix |
|
degrees to rotate counter-clockwise |
Since 1.6
void pango_matrix_concat (PangoMatrix *matrix, const PangoMatrix *new_matrix);
Changes the transformation represented by matrix to be the
transformation given by first applying transformation
given by new_matrix then applying the original transformation.
|
a PangoMatrix |
|
a PangoMatrix |
Since 1.6
void pango_matrix_transform_point (const PangoMatrix *matrix, double *x, double *y);
Transforms the point (x, y) by matrix.
|
a PangoMatrix, or NULL
|
|
in/out X position |
|
in/out Y position |
Since 1.16
void pango_matrix_transform_distance (const PangoMatrix *matrix, double *dx, double *dy);
Transforms the distance vector (dx,dy) by matrix. This is
similar to pango_matrix_transform_point() except that the translation
components of the transformation are ignored. The calculation of
the returned vector is as follows:
dx2 = dx1 * xx + dy1 * xy; dy2 = dx1 * yx + dy1 * yy;
Affine transformations are position invariant, so the same vector
always transforms to the same vector. If (x1,y1) transforms
to (x2,y2) then (x1+dx1,y1+dy1) will transform to
(x1+dx2,y1+dy2) for all values of x1 and x2.
|
a PangoMatrix, or NULL
|
|
in/out X component of a distance vector |
|
yn/out Y component of a distance vector |
Since 1.16
void pango_matrix_transform_rectangle (const PangoMatrix *matrix, PangoRectangle *rect);
First transforms rect using matrix, then calculates the bounding box
of the transformed rectangle. The rectangle should be in Pango units.
This function is useful for example when you want to draw a rotated
PangoLayout to an image buffer, and want to know how large the image
should be and how much you should shift the layout when rendering.
If you have a rectangle in device units (pixels), use
pango_matrix_transform_pixel_rectangle().
If you have the rectangle in Pango units and want to convert to
transformed pixel bounding box, it is more accurate to transform it first
(using this function) and pass the result to pango_extents_to_pixels(),
first argument, for an inclusive rounded rectangle.
However, there are valid reasons that you may want to convert
to pixels first and then transform, for example when the transformed
coordinates may overflow in Pango units (large matrix translation for
example).
|
a PangoMatrix, or NULL
|
|
in/out bounding box in Pango units, or NULL
|
Since 1.16
void pango_matrix_transform_pixel_rectangle
(const PangoMatrix *matrix,
PangoRectangle *rect);
First transforms the rect using matrix, then calculates the bounding box
of the transformed rectangle. The rectangle should be in device units
(pixels).
This function is useful for example when you want to draw a rotated
PangoLayout to an image buffer, and want to know how large the image
should be and how much you should shift the layout when rendering.
For better accuracy, you should use pango_matrix_transform_rectangle() on
original rectangle in Pango units and convert to pixels afterward
using pango_extents_to_pixels()'s first argument.
|
a PangoMatrix, or NULL
|
|
in/out bounding box in device units, or NULL
|
Since 1.16
double pango_matrix_get_font_scale_factor (const PangoMatrix *matrix);
Returns the scale factor of a matrix on the height of the font. That is, the scale factor in the direction perpendicular to the vector that the X coordinate is mapped to.
|
a PangoMatrix, may be NULL
|
Returns : |
the scale factor of matrix on the height of the font,
or 1.0 if matrix is NULL.
|
Since 1.12
typedef guint32 PangoGlyph;
A PangoGlyph represents a single glyph in the output form of a string.
#define PANGO_GLYPH_EMPTY ((PangoGlyph)0x0FFFFFFF)
The PANGO_GLYPH_EMPTY macro represents a PangoGlyph value that has a
special meaning, which is a zero-width empty glyph. This is useful for
example in shaper modules, to use as the glyph for various zero-width
Unicode characters (those passing pango_is_zero_width()).
#define PANGO_GLYPH_INVALID_INPUT ((PangoGlyph)0xFFFFFFFF)
The PANGO_GLYPH_EMPTY macro represents a PangoGlyph value that has a
special meaning of invalid input. PangoLayout produces one such glyph
per invalid input UTF-8 byte and such a glyph is rendered as a crossed
box.
Note that this value is defined such that it has the PANGO_GLYPH_UNKNOWN_FLAG
on.
Since 1.20
#define PANGO_GLYPH_UNKNOWN_FLAG ((PangoGlyph)0x10000000)
The PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to
a gunichar value of a valid Unicode character, to produce a PangoGlyph
value, representing an unknown-character glyph for the respective gunichar.
#define PANGO_GET_UNKNOWN_GLYPH(wc) ((PangoGlyph)(wc)|PANGO_GLYPH_UNKNOWN_FLAG)
Returns a PangoGlyph value that means no glyph was found for wc.
The way this unknown glyphs are rendered is backend specific. For example,
a box with the hexadecimal Unicode code-point of the character written in it
is what is done in the most common backends.
|
a Unicode character |
typedef struct {
PangoGlyph glyph;
PangoGlyphGeometry geometry;
PangoGlyphVisAttr attr;
} PangoGlyphInfo;
The PangoGlyphInfo structure represents a single glyph together with positioning information and visual attributes. It contains the following fields.
PangoGlyph |
the glyph itself. |
PangoGlyphGeometry |
the positional information about the glyph. |
PangoGlyphVisAttr |
the visual attributes of the glyph. |
typedef struct {
PangoGlyphUnit width;
PangoGlyphUnit x_offset;
PangoGlyphUnit y_offset;
} PangoGlyphGeometry;
The PangoGlyphGeometry structure contains width and positioning information for a single glyph.
PangoGlyphUnit |
the logical width to use for the the character. |
PangoGlyphUnit |
horizontal offset from nominal character position. |
PangoGlyphUnit |
vertical offset from nominal character position. |
typedef gint32 PangoGlyphUnit;
The PangoGlyphUnit type is used to store dimensions within
Pango. Dimensions are stored in 1/PANGO_SCALE of a device unit.
(A device unit might be a pixel for screen display, or
a point on a printer.) PANGO_SCALE is currently 1024, and
may change in the future (unlikely though), but you should not
depend on its exact value. The PANGO_PIXELS() macro can be used
to convert from glyph units into device units with correct rounding.
typedef struct {
guint is_cluster_start : 1;
} PangoGlyphVisAttr;
The PangoGlyphVisAttr is used to communicate information between the shaping phase and the rendering phase. More attributes may be added in the future.
guint |
set for the first logical glyph in each cluster. (Clusters are stored in visual order, within the cluster, glyphs are always ordered in logical order, since visual order is meaningless; that is, in Arabic text, accent glyphs follow the glyphs for the base character.) |
typedef struct {
gint num_glyphs;
PangoGlyphInfo *glyphs;
/* This is a memory inefficient way of representing the information
* here - each value gives the byte index within the text
* corresponding to the glyph string of the start of the cluster to
* which the glyph belongs.
*/
gint *log_clusters;
} PangoGlyphString;
The PangoGlyphString structure is used to store strings of glyphs with geometry and visual attribute information. The storage for the glyph information is owned by the structure which simplifies memory management.
gint |
the number of glyphs in the string. |
PangoGlyphInfo * |
an array of PangoGlyphInfo structures of length num_glyphs.
|
gint * |
for each glyph, byte index of the starting character for the cluster. The indices are relative to the start of the text corresponding to the PangoGlyphString. |
typedef struct {
PangoItem *item;
PangoGlyphString *glyphs;
} PangoGlyphItem;
A PangoGlyphItem is a pair of a PangoItem and the glyphs resulting from shaping the text corresponding to an item. As an example of the usage of PangoGlyphItem, the results of shaping text with PangoLayout is a list of PangoLayoutLine, each of which contains a list of PangoGlyphItem.
PangoItem * |
a PangoItem structure that provides information about a segment of text. |
PangoGlyphString * |
the glyphs obtained by shaping the text
corresponding to item.
|
typedef struct {
PangoGlyphItem *glyph_item;
const gchar *text;
int start_glyph;
int start_index;
int start_char;
int end_glyph;
int end_index;
int end_char;
} PangoGlyphItemIter;
A PangoGlyphItemIter is an iterator over the clusters in a
PangoGlyphItem. The forward direction of the
iterator is the logical direction of text. That is, with increasing
start_index and start_char values. If glyph_item is right-to-left
(that is, if glyph_item->item->analysis.levelstart_glyph decreases as the iterator moves forward. Moreover,
in right-to-left cases, start_glyph is greater than end_glyph.
An iterator should be initialized using either of
pango_glyph_item_iter_init_start() and
pango_glyph_item_iter_init_end(), for forward and backward iteration
respectively, and walked over using any desired mixture of
pango_glyph_item_iter_next_cluster() and
pango_glyph_item_iter_prev_cluster(). A common idiom for doing a
forward iteration over the clusters is:
PangoGlyphItemIter cluster_iter;
gboolean have_cluster;
for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
glyph_item, text);
have_cluster;
have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
{
...
}
Note that text is the start of the text for layout, which is then
indexed by glyph_item->item->offsetglyph_item. The start_index and end_index values can directly
index into text. The start_glyph, end_glyph, start_char, and end_char
values however are zero-based for the glyph_item. For each cluster, the
item pointed at by the start variables is included in the cluster while
the one pointed at by end variables is not.
None of the members of a PangoGlyphItemIter should be modified manually.
PangoGlyphItem * |
the PangoGlyphItem this iterator iterates over |
const gchar * |
the UTF-8 text that glyph_item refers to
|
int |
starting glyph of the cluster |
int |
starting text index of the cluster |
int |
starting number of characters of the cluster |
int |
ending glyph of the cluster |
int |
ending text index of the cluster |
int |
ending number of characters of the cluster |
Since 1.22
#define PANGO_TYPE_GLYPH_STRING (pango_glyph_string_get_type ())
The GObject type for PangoGlyphString.
PangoGlyphString * pango_glyph_string_new (void);
Create a new PangoGlyphString.
Returns : |
the newly allocated PangoGlyphString, which
should be freed with pango_glyph_string_free().
|
PangoGlyphString * pango_glyph_string_copy (PangoGlyphString *string);
Copy a glyph string and associated storage.
|
a PangoGlyphString, may be NULL
|
Returns : |
the newly allocated PangoGlyphString, which
should be freed with pango_glyph_string_free(),
or NULL if string was NULL.
|
void pango_glyph_string_set_size (PangoGlyphString *string, gint new_len);
Resize a glyph string to the given length.
|
a PangoGlyphString. |
|
the new length of the string. |
void pango_glyph_string_free (PangoGlyphString *string);
Free a glyph string and associated storage.
|
a PangoGlyphString, may be NULL
|
void pango_glyph_string_extents (PangoGlyphString *glyphs, PangoFont *font, PangoRectangle *ink_rect, PangoRectangle *logical_rect);
Compute the logical and ink extents of a glyph string. See the documentation
for pango_font_get_glyph_extents() for details about the interpretation
of the rectangles.
|
a PangoGlyphString |
|
a PangoFont |
|
rectangle used to store the extents of the glyph string as drawn
or NULL to indicate that the result is not needed.
|
|
rectangle used to store the logical extents of the glyph string
or NULL to indicate that the result is not needed.
|
void pango_glyph_string_extents_range (PangoGlyphString *glyphs, int start, int end, PangoFont *font, PangoRectangle *ink_rect, PangoRectangle *logical_rect);
Computes the extents of a sub-portion of a glyph string. The extents are relative to the start of the glyph string range (the origin of their coordinate system is at the start of the range, not at the start of the entire glyph string).
|
a PangoGlyphString |
|
start index |
|
end index (the range is the set of bytes with indices such that start <= index < end) |
|
a PangoFont |
|
rectangle used to store the extents of the glyph string range as drawn
or NULL to indicate that the result is not needed.
|
|
rectangle used to store the logical extents of the glyph string range
or NULL to indicate that the result is not needed.
|
int pango_glyph_string_get_width (PangoGlyphString *glyphs);
Computes the logical width of the glyph string as can also be computed
using pango_glyph_string_extents(). However, since this only computes the
width, it's much faster. This is in fact only a convenience function that
computes the sum of geometry.width for each glyph in the glyphs.
|
a PangoGlyphString |
Returns : |
the logical width of the glyph string. |
Since 1.14
void pango_glyph_string_index_to_x (PangoGlyphString *glyphs, char *text, int length, PangoAnalysis *analysis, int index_, gboolean trailing, int *x_pos);
Converts from character position to x position. (X position is measured from the left edge of the run). Character positions are computed by dividing up each cluster into equal portions.
|
the glyphs return from pango_shape()
|
|
the text for the run |
|
the number of bytes (not characters) in text.
|
|
the analysis information return from pango_itemize()
|
|
the byte index within text
|
|
whether we should compute the result for the beginning (FALSE)
or end (TRUE) of the character.
|
|
location to store result |
void pango_glyph_string_x_to_index (PangoGlyphString *glyphs, char *text, int length, PangoAnalysis *analysis, int x_pos, int *index_, int *trailing);
Convert from x offset to character position. Character positions are computed by dividing up each cluster into equal portions. In scripts where positioning within a cluster is not allowed (such as Thai), the returned value may not be a valid cursor position; the caller must combine the result with the logical attributes for the text to compute the valid cursor position.
|
the glyphs returned from pango_shape()
|
|
the text for the run |
|
the number of bytes (not characters) in text. |
|
the analysis information return from pango_itemize()
|
|
the x offset (in Pango units) |
|
location to store calculated byte index within text
|
|
location to store a boolean indicating whether the user clicked on the leading or trailing edge of the character. |
void pango_glyph_string_get_logical_widths
(PangoGlyphString *glyphs,
const char *text,
int length,
int embedding_level,
int *logical_widths);
Given a PangoGlyphString resulting from pango_shape() and the corresponding
text, determine the screen width corresponding to each character. When
multiple characters compose a single cluster, the width of the entire
cluster is divided equally among the characters.
See also pango_glyph_item_get_logical_widths().
|
a PangoGlyphString |
|
the text corresponding to the glyphs |
|
the length of text, in bytes
|
|
the embedding level of the string |
|
an array whose length is the number of characters in text (equal to g_utf8_strlen (text, length) unless text has NUL bytes) to be filled in with the resulting character widths. |
#define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
The GObject type for PangoGlyphItem.
Since 1.20
PangoGlyphItem * pango_glyph_item_copy (PangoGlyphItem *orig);
Make a deep copy of an existing PangoGlyphItem structure.
|
a PangoGlyphItem, may be NULL
|
Returns : |
the newly allocated PangoGlyphItem, which should
be freed with pango_glyph_item_free(), or NULL
if orig was NULL.
|
Since 1.20
void pango_glyph_item_free (PangoGlyphItem *glyph_item);
Frees a PangoGlyphItem and resources to which it points.
|
a PangoGlyphItem, may be NULL
|
Since 1.6
PangoGlyphItem * pango_glyph_item_split (PangoGlyphItem *orig, const char *text, int split_index);
Modifies orig to cover only the text after split_index, and
returns a new item that covers the text before split_index that
used to be in orig. You can think of split_index as the length of
the returned item. split_index may not be 0, and it may not be
greater than or equal to the length of orig (that is, there must
be at least one byte assigned to each item, you can't create a
zero-length item).
This function is similar in function to pango_item_split() (and uses
it internally.)
|
a PangoItem |
|
text to which positions in orig apply
|
|
byte index of position to split item, relative to the start of the item |
Returns : |
the newly allocated item representing text before
split_index, which should be freed
with pango_glyph_item_free().
|
Since 1.2
GSList * pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item, const char *text, PangoAttrList *list);
Splits a shaped item (PangoGlyphItem) into multiple items based
on an attribute list. The idea is that if you have attributes
that don't affect shaping, such as color or underline, to avoid
affecting shaping, you filter them out (pango_attr_list_filter()),
apply the shaping process and then reapply them to the result using
this function.
All attributes that start or end inside a cluster are applied to that cluster; for instance, if half of a cluster is underlined and the other-half strikethrough, then the cluster will end up with both underline and strikethrough attributes. In these cases, it may happen that item->extra_attrs for some of the result items can have multiple attributes of the same type.
This function takes ownership of glyph_item; it will be reused
as one of the elements in the list.
|
a shaped item |
|
text that list applies to
|
|
a PangoAttrList |
Returns : |
a list of glyph items resulting from splitting
glyph_item. Free the elements using pango_glyph_item_free(),
the list using g_slist_free().
|
Since 1.2
void pango_glyph_item_letter_space (PangoGlyphItem *glyph_item, const char *text, PangoLogAttr *log_attrs, int letter_spacing);
Adds spacing between the graphemes of glyph_item to
give the effect of typographic letter spacing.
|
a PangoGlyphItem |
|
text that glyph_item corresponds to
(glyph_item->item->offset is an offset from the
start of text)
|
|
logical attributes for the item (the first logical attribute refers to the position before the first character in the item) |
|
amount of letter spacing to add in Pango units. May be negative, though too large negative values will give ugly results. |
Since 1.6
void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item, const char *text, int *logical_widths);
Given a PangoGlyphItem and the corresponding text, determine the screen width corresponding to each character. When multiple characters compose a single cluster, the width of the entire cluster is divided equally among the characters.
See also pango_glyph_string_get_logical_widths().
|
a PangoGlyphItem |
|
text that glyph_item corresponds to
(glyph_item->item->offset is an offset from the
start of text)
|
|
an array whose length is the number of characters in glyph_item (equal to glyph_item->item->num_chars) to be filled in with the resulting character widths. |
Since 1.26
#define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
The GObject type for PangoGlyphItemIter.
Since 1.22
PangoGlyphItemIter * pango_glyph_item_iter_copy (PangoGlyphItemIter *orig);
Make a shallow copy of an existing PangoGlyphItemIter structure.
|
a PangoGlyphItemIter, may be NULL
|
Returns : |
the newly allocated PangoGlyphItemIter, which should
be freed with pango_glyph_item_iter_free(), or NULL
if orig was NULL.
|
Since 1.22
void pango_glyph_item_iter_free (PangoGlyphItemIter *iter);
Frees a PangoGlyphItemIter created by pango_glyph_item_iter_copy().
|
a PangoGlyphItemIter, may be NULL
|
Since 1.22
gboolean pango_glyph_item_iter_init_start (PangoGlyphItemIter *iter, PangoGlyphItem *glyph_item, const char *text);
Initializes a PangoGlyphItemIter structure to point to the first cluster in a glyph item. See PangoGlyphItemIter for details of cluster orders.
|
a PangoGlyphItemIter |
|
the glyph item to iterate over |
|
text corresponding to the glyph item |
Returns : |
FALSE if there are no clusters in the glyph item
|
Since 1.22
gboolean pango_glyph_item_iter_init_end (PangoGlyphItemIter *iter, PangoGlyphItem *glyph_item, const char *text);
Initializes a PangoGlyphItemIter structure to point to the last cluster in a glyph item. See PangoGlyphItemIter for details of cluster orders.
|
a PangoGlyphItemIter |
|
the glyph item to iterate over |
|
text corresponding to the glyph item |
Returns : |
FALSE if there are no clusters in the glyph item
|
Since 1.22
gboolean pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter);
Advances the iterator to the next cluster in the glyph item. See PangoGlyphItemIter for details of cluster orders.
|
a PangoGlyphItemIter |
Returns : |
TRUE if the iterator was advanced, FALSE if we were already on the
last cluster.
|
Since 1.22
gboolean pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter);
Moves the iterator to the preceding cluster in the glyph item. See PangoGlyphItemIter for details of cluster orders.
|
a PangoGlyphItemIter |
Returns : |
TRUE if the iterator was moved, FALSE if we were already on the
first cluster.
|
Since 1.22
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
PangoEngineShape;
PangoEngineShapeClass;
#define PANGO_ENGINE_TYPE_SHAPE
#define PANGO_ENGINE_SHAPE_DEFINE_TYPE (name, prefix, class_init, instance_init)
The shape engines are rendering-system dependent
engines that convert character strings into glyph strings.
These engines are used in pango_shape().
typedef struct _PangoEngineShape 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 handle shaping Arabic for Fontconfig-based backends.
typedef struct {
void (*script_shape) (PangoEngineShape *engine,
PangoFont *font,
const char *text,
int length,
const PangoAnalysis *analysis,
PangoGlyphString *glyphs);
PangoCoverageLevel (*covers) (PangoEngineShape *engine,
PangoFont *font,
PangoLanguage *language,
gunichar wc);
} PangoEngineShapeClass;
Class structure for PangoEngineShape
|
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
glyphs->glyphs[i].attr.is_cluster_start
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 PANGO_GLYPH_EMPTY, which
is guaranteed never to render. If the shaping fails for any reason,
the shaper should return with an empty (zero-size) glyph string.
If the shaper has not set the size on the glyph string yet, simply
returning signals the failure too.
|
|
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. |
#define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape"
A string constant defining the engine type for shaping engines. These engines derive from PangoEngineShape.
#define PANGO_ENGINE_SHAPE_DEFINE_TYPE(name, prefix, class_init, instance_init)
Outputs the necessary code for GObject type registration for a PangoEngineShape class defined in a module. Two static symbols are defined.
static GTypeprefix_type; static voidprefix_register_type (GTypeModule module);
The prefix, _register_type()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:
PangoEngine *engine = g_object_new (prefix_type, NULL);
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
PangoFcFontMap;
PangoFcFontMapClass;
PangoContext * pango_fc_font_map_create_context (PangoFcFontMap *fcfontmap);
PangoFcDecoder * (*PangoFcDecoderFindFunc) (FcPattern *pattern,
gpointer user_data);
void pango_fc_font_map_add_decoder_find_func
(PangoFcFontMap *fcfontmap,
PangoFcDecoderFindFunc findfunc,
gpointer user_data,
GDestroyNotify dnotify);
PangoFcDecoder * pango_fc_font_map_find_decoder (PangoFcFontMap *fcfontmap,
FcPattern *pattern);
void pango_fc_font_map_cache_clear (PangoFcFontMap *fcfontmap);
void pango_fc_font_map_shutdown (PangoFcFontMap *fcfontmap);
PangoFontDescription * pango_fc_font_description_from_pattern
(FcPattern *pattern,
gboolean include_size);
#define PANGO_FC_GRAVITY
#define PANGO_FC_VERSION
#define PANGO_FC_PRGNAME
PangoFcFontsetKey;
gpointer pango_fc_fontset_key_get_context_key
(const PangoFcFontsetKey *key);
const PangoFontDescription * pango_fc_fontset_key_get_description
(const PangoFcFontsetKey *key);
PangoLanguage * pango_fc_fontset_key_get_language (const PangoFcFontsetKey *key);
const PangoMatrix * pango_fc_fontset_key_get_matrix (const PangoFcFontsetKey *key);
double pango_fc_fontset_key_get_absolute_size
(const PangoFcFontsetKey *key);
double pango_fc_fontset_key_get_resolution (const PangoFcFontsetKey *key);
PangoFcFontKey;
gpointer pango_fc_font_key_get_context_key (const PangoFcFontKey *key);
const PangoMatrix * pango_fc_font_key_get_matrix (const PangoFcFontKey *key);
const FcPattern * pango_fc_font_key_get_pattern (const PangoFcFontKey *key);
GObject +----PangoFontMap +----PangoFcFontMap +----PangoFT2FontMap +----PangoXftFontMap
PangoFcFontMap is a base class for font map implementations using the Fontconfig and FreeType libraries. It is used in the Xft and FreeType backends shipped with Pango, but can also be used when creating new backends. Any backend deriving from this base class will take advantage of the wide range of shapers implemented using FreeType that come with Pango.
typedef struct _PangoFcFontMap PangoFcFontMap;
PangoFcFontMap is a base class for font map implementations
using the Fontconfig and FreeType libraries. To create a new
backend using Fontconfig and FreeType, you derive from this class
and implement a new_font() virtual function that creates an
instance deriving from PangoFcFont.
typedef struct {
/* Deprecated in favor of fontset_key_substitute */
void (*default_substitute) (PangoFcFontMap *fontmap,
FcPattern *pattern);
/* Deprecated in favor of create_font */
PangoFcFont *(*new_font) (PangoFcFontMap *fontmap,
FcPattern *pattern);
double (*get_resolution) (PangoFcFontMap *fcfontmap,
PangoContext *context);
gconstpointer (*context_key_get) (PangoFcFontMap *fcfontmap,
PangoContext *context);
gpointer (*context_key_copy) (PangoFcFontMap *fcfontmap,
gconstpointer key);
void (*context_key_free) (PangoFcFontMap *fcfontmap,
gpointer key);
guint32 (*context_key_hash) (PangoFcFontMap *fcfontmap,
gconstpointer key);
gboolean (*context_key_equal) (PangoFcFontMap *fcfontmap,
gconstpointer key_a,
gconstpointer key_b);
void (*fontset_key_substitute)(PangoFcFontMap *fontmap,
PangoFcFontsetKey *fontsetkey,
FcPattern *pattern);
PangoFcFont *(*create_font) (PangoFcFontMap *fontmap,
PangoFcFontKey *fontkey);
} PangoFcFontMapClass;
Class structure for PangoFcFontMap.
|
Substitutes in default values for
unspecified fields in a FcPattern. This will be called
prior to creating a font for the pattern. May be NULL.
Deprecated in favor of @font_key_substitute().
|
|
Creates a new PangoFcFont for the specified
pattern of the appropriate type for this font map. The
pattern argument must be passed to the "pattern" property
of PangoFcFont when you call g_object_new(). Deprecated
in favor of @create_font().
|
|
Gets the resolution (the scale factor
between logical and absolute font sizes) that the backend
will use for a particular fontmap and context. context
may be null.
|
|
Gets an opaque key holding backend
specific options for the context that will affect
fonts created by create_font(). The result must point to
persistant storage owned by the fontmap. This key
is used to index hash tables used to look up fontsets
and fonts.
|
|
Copies a context key. Pango uses this
to make a persistant copy of the value returned from
context_key_get.
|
|
Frees a context key copied with
context_key_copy.
|
|
Gets a hash value for a context key |
|
Compares two context keys for equality. |
|
Substitutes in default values for
unspecified fields in a FcPattern. This will be called
prior to creating a font for the pattern. May be NULL.
(Since: 1.24)
|
|
Creates a new PangoFcFont for the specified
pattern of the appropriate type for this font map using
information from the font key that is passed in. The
pattern member of font_key can be retrieved using
pango_fc_font_key_get_pattern() and must be passed to
the "pattern" property of PangoFcFont when you call
g_object_new(). If NULL, new_font() is used.
(Since: 1.24)
|
PangoContext * pango_fc_font_map_create_context (PangoFcFontMap *fcfontmap);
pango_fc_font_map_create_context has been deprecated since version 1.22 and should not be used in newly-written code. Use pango_font_map_create_context() instead.
Creates a new context for this fontmap. This function is intended only for backend implementations deriving from PangoFcFontmap; it is possible that a backend will store additional information needed for correct operation on the PangoContext after calling this function.
|
a PangoFcFontMap |
Returns : |
a new PangoContext |
Since 1.4
PangoFcDecoder * (*PangoFcDecoderFindFunc) (FcPattern *pattern, gpointer user_data);
Callback function passed to pango_fc_font_map_add_decoder_find_func().
|
a fully resolved FcPattern specifying the font on the system |
|
user data passed to pango_fc_font_map_add_decoder_find_func()
|
Returns : |
a new reference to a custom decoder for this pattern,
or NULL if the default decoder handling should be used.
|
void pango_fc_font_map_add_decoder_find_func
(PangoFcFontMap *fcfontmap,
PangoFcDecoderFindFunc findfunc,
gpointer user_data,
GDestroyNotify dnotify);
This function saves a callback method in the PangoFcFontMap that will be called whenever new fonts are created. If the function returns a PangoFcDecoder, that decoder will be used to determine both coverage via a FcCharSet and a one-to-one mapping of characters to glyphs. This will allow applications to have application-specific encodings for various fonts.
|
The PangoFcFontMap to add this method to. |
|
The PangoFcDecoderFindFunc callback function |
|
User data. |
|
A GDestroyNotify callback that will be called when the fontmap is finalized and the decoder is released. |
Since 1.6.
PangoFcDecoder * pango_fc_font_map_find_decoder (PangoFcFontMap *fcfontmap, FcPattern *pattern);
Finds the decoder to use for pattern. Decoders can be added to
a font map using pango_fc_font_map_add_decoder_find_func().
|
The PangoFcFontMap to use. |
|
The FcPattern to find the decoder for. |
Returns : |
a newly created PangoFcDecoder object or NULL if
no decoder is set for pattern.
|
Since 1.26.
void pango_fc_font_map_cache_clear (PangoFcFontMap *fcfontmap);
Clear all cached information and fontsets for this font map;
this should be called whenever there is a change in the
output of the default_substitute() virtual function of the
font map, or if fontconfig has been reinitialized to new
configuration.
|
a PangoFcFontmap |
Since 1.4
void pango_fc_font_map_shutdown (PangoFcFontMap *fcfontmap);
Clears all cached information for the fontmap and marks
all fonts open for the fontmap as dead. (See the shutdown()
virtual function of PangoFcFont.) This function might be used
by a backend when the underlying windowing system for the font
map exits. This function is only intended to be called
only for backend implementations deriving from PangoFcFontmap.
|
a PangoFcFontmap |
Since 1.4
PangoFontDescription * pango_fc_font_description_from_pattern (FcPattern *pattern, gboolean include_size);
Creates a PangoFontDescription that matches the specified
Fontconfig pattern as closely as possible. Many possible Fontconfig
pattern values, such as FC_RASTERIZER or FC_DPI, don't make sense in
the context of PangoFontDescription, so will be ignored.
|
a FcPattern |
|
if TRUE, the pattern will include the size from
the pattern; otherwise the resulting pattern will be unsized.
(only FC_SIZE is examined, not FC_PIXEL_SIZE)
|
Returns : |
a new PangoFontDescription. Free with
pango_font_description_free().
|
Since 1.4
#define PANGO_FC_GRAVITY "pangogravity"
String representing a fontconfig property name that Pango sets on any
fontconfig pattern it passes to fontconfig if a PangoGravity other
than PangoGravitySouth is desired.
The property will have a PangoGravity value as a string, like "east". This can be used to write fontconfig configuration rules to choose different fonts for horizontal and vertical writing directions.
Since 1.20
#define PANGO_FC_VERSION "pangoversion"
String representing a fontconfig property name that Pango sets on any fontconfig pattern it passes to fontconfig.
The property will have an integer value equal to what
pango_version() returns.
This can be used to write fontconfig configuration rules that only affect
certain pango versions (or only pango-using applications, or only
non-pango-using applications).
Since 1.20
#define PANGO_FC_PRGNAME "pangoprgname"
String representing a fontconfig property name that Pango sets on any fontconfig pattern it passes to fontconfig.
The property will have a string equal to what
g_get_prgname() returns.
This can be used to write fontconfig configuration rules that only affect
certain applications.
Since 1.24
typedef struct _PangoFcFontsetKey PangoFcFontsetKey;
An opaque structure containing all the information needed for loading a fontset with the PangoFc fontmap.
Since 1.24
gpointer pango_fc_fontset_key_get_context_key (const PangoFcFontsetKey *key);
Gets the context key member of key.
|
the font key |
Returns : |
the context key, which is owned by key and should not be modified.
|
Since 1.24
const PangoFontDescription * pango_fc_fontset_key_get_description (const PangoFcFontsetKey *key);
Gets the font description of key.
|
the fontset key |
Returns : |
the font description, which is owned by key and should not be modified.
|
Since 1.24
PangoLanguage * pango_fc_fontset_key_get_language (const PangoFcFontsetKey *key);
Gets the language member of key.
|
the fontset key |
Returns : |
the language |
Since 1.24
const PangoMatrix * pango_fc_fontset_key_get_matrix (const PangoFcFontsetKey *key);
Gets the matrix member of key.
|
the fontset key |
Returns : |
the matrix, which is owned by key and should not be modified.
|
Since 1.24
double pango_fc_fontset_key_get_absolute_size
(const PangoFcFontsetKey *key);
Gets the absolute font size of key in Pango units. This is adjusted
for both resolution and transformation matrix.
|
the fontset key |
Returns : |
the pixel size of key.
|
Since 1.24
double pango_fc_fontset_key_get_resolution (const PangoFcFontsetKey *key);
Gets the resolution of key
|
the fontset key |
Returns : |
the resolution of key
|
Since 1.24
typedef struct _PangoFcFontKey PangoFcFontKey;
An opaque structure containing all the information needed for loading a font with the PangoFc fontmap.
Since 1.24
gpointer pango_fc_font_key_get_context_key (const PangoFcFontKey *key);
Gets the context key member of key.
|
the font key |
Returns : |
the context key, which is owned by key and should not be modified.
|
Since 1.24
const PangoMatrix * pango_fc_font_key_get_matrix (const PangoFcFontKey *key);
Gets the matrix member of key.
|
the font key |
Returns : |
the matrix, which is owned by key and should not be modified.
|
Since 1.24
const FcPattern * pango_fc_font_key_get_pattern (const PangoFcFontKey *key);
Gets the fontconfig pattern member of key.
|
the font key |
Returns : |
the pattern, which is owned by key and should not be modified.
|
Since 1.24
The base class for fonts; creating a new Fontconfig-based backend involves deriving from both PangoFcFontMap and PangoFcFont. |
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
enum PangoCoverageLevel; #define PANGO_TYPE_COVERAGE_LEVEL PangoCoverage; PangoCoverage * pango_coverage_new (void); PangoCoverage * pango_coverage_ref (PangoCoverage *coverage); void pango_coverage_unref (PangoCoverage *coverage); PangoCoverage * pango_coverage_copy (PangoCoverage *coverage); PangoCoverageLevel pango_coverage_get (PangoCoverage *coverage, int index_); void pango_coverage_max (PangoCoverage *coverage, PangoCoverage *other); void pango_coverage_set (PangoCoverage *coverage, int index_, PangoCoverageLevel level); void pango_coverage_to_bytes (PangoCoverage *coverage, guchar **bytes, int *n_bytes); PangoCoverage * pango_coverage_from_bytes (guchar *bytes, int n_bytes);
It is often necessary in Pango to determine if a particular font can represent a particular character, and also how well it can represent that character. The PangoCoverage is a data structure that is used to represent that information.
typedef enum {
PANGO_COVERAGE_NONE,
PANGO_COVERAGE_FALLBACK,
PANGO_COVERAGE_APPROXIMATE,
PANGO_COVERAGE_EXACT
} PangoCoverageLevel;
Used to indicate how well a font can represent a particular Unicode character point for a particular script.
| The character is not representable with the font. | |
| The character is represented in a way that may be comprehensible but is not the correct graphical form. For instance, a Hangul character represented as a a sequence of Jamos, or a Latin transliteration of a Cyrillic word. | |
| The character is represented as basically the correct graphical form, but with a stylistic variant inappropriate for the current script. | |
| The character is represented as the correct graphical form. |
#define PANGO_TYPE_COVERAGE_LEVEL (pango_coverage_level_get_type())
The GObject type for PangoCoverageLevel.
typedef struct _PangoCoverage PangoCoverage;
The PangoCoverage structure represents a map from Unicode characters to PangoCoverageLevel. It is an opaque structure with no public fields.
PangoCoverage * pango_coverage_new (void);
Create a new PangoCoverage
Returns : |
the newly allocated PangoCoverage,
initialized to PANGO_COVERAGE_NONE
with a reference count of one, which
should be freed with pango_coverage_unref().
|
PangoCoverage * pango_coverage_ref (PangoCoverage *coverage);
Increase the reference count on the PangoCoverage by one
|
a PangoCoverage |
Returns : |
coverage
|
void pango_coverage_unref (PangoCoverage *coverage);
Decrease the reference count on the PangoCoverage by one. If the result is zero, free the coverage and all associated memory.
|
a PangoCoverage |
PangoCoverage * pango_coverage_copy (PangoCoverage *coverage);
Copy an existing PangoCoverage. (This function may now be unnecessary since we refcount the structure. File a bug if you use it.)
|
a PangoCoverage |
Returns : |
the newly allocated PangoCoverage,
with a reference count of one, which
should be freed with pango_coverage_unref().
|
PangoCoverageLevel pango_coverage_get (PangoCoverage *coverage, int index_);
Determine whether a particular index is covered by coverage
|
a PangoCoverage |
|
the index to check |
Returns : |
the coverage level of coverage for character index_.
|
void pango_coverage_max (PangoCoverage *coverage, PangoCoverage *other);
Set the coverage for each index in coverage to be the max (better)
value of the current coverage for the index and the coverage for
the corresponding index in other.
|
a PangoCoverage |
|
another PangoCoverage |
void pango_coverage_set (PangoCoverage *coverage, int index_, PangoCoverageLevel level);
Modify a particular index within coverage
|
a PangoCoverage |
|
the index to modify |
|
the new level for index_
|
void pango_coverage_to_bytes (PangoCoverage *coverage, guchar **bytes, int *n_bytes);
Convert a PangoCoverage structure into a flat binary format
|
a PangoCoverage |
|
location to store result (must be freed with g_free())
|
|
location to store size of result |
PangoCoverage * pango_coverage_from_bytes (guchar *bytes, int n_bytes);
Convert data generated from pango_converage_to_bytes() back
to a PangoCoverage
|
binary data representing a PangoCoverage |
|
the size of bytes in bytes
|
Returns : |
a newly allocated PangoCoverage, or NULL if
the data was invalid.
|
|
|
Pango Reference Manual |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
PangoFcDecoder;
PangoFcDecoderClass;
FcCharSet * pango_fc_decoder_get_charset (PangoFcDecoder *decoder,
PangoFcFont *fcfont);
PangoGlyph pango_fc_decoder_get_glyph (PangoFcDecoder *decoder,
PangoFcFont *fcfont,
guint32 wc);
PangoFcDecoder represents a decoder that an application provides for handling a font that is encoded in a custom way.
typedef struct _PangoFcDecoder PangoFcDecoder;
PangoFcDecoder is a virtual base class that implementations will
inherit from. It's the interface that is used to define a custom
encoding for a font. These objects are created in your code from a
function callback that was originally registered with
pango_fc_font_map_add_decoder_find_func(). Pango requires
information about the supported charset for a font as well as the
individual character to glyph conversions. Pango gets that
information via the get_charset and get_glyph callbacks into your
object implementation.
Since 1.6
typedef struct {
FcCharSet *(*get_charset) (PangoFcDecoder *decoder,
PangoFcFont *fcfont);
PangoGlyph (*get_glyph) (PangoFcDecoder *decoder,
PangoFcFont *fcfont,
guint32 wc);
} PangoFcDecoderClass;
Class structure for PangoFcDecoder.
|
This returns an FcCharset given a PangoFcFont that includes a list of supported characters in the font. The FcCharSet that is returned should be an internal reference to your code. Pango will not free this structure. It is important that you make this callback fast because this callback is called separately for each character to determine Unicode coverage. |
|
This returns a single PangoGlyph for a given Unicode code point. |
Since 1.6
FcCharSet * pango_fc_decoder_get_charset (PangoFcDecoder *decoder, PangoFcFont *fcfont);
Generates an FcCharSet of supported characters for the fcfont given. The returned FcCharSet will be a reference to an internal value stored by the PangoFcDecoder and must not be modified or freed.
|
a PangoFcDecoder |
|
the PangoFcFont to query. |
Returns : |
the FcCharset for fcfont; must not be modified
or freed.
|
Since 1.6
PangoGlyph pango_fc_decoder_get_glyph (PangoFcDecoder *decoder, PangoFcFont *fcfont, guint32 wc);
Generates a PangoGlyph for the given Unicode point using the custom decoder. For complex scripts where there can be multiple glyphs for a single character, the decoder will return whatever glyph is most convenient for it. (Usually whatever glyph is directly in the fonts character map table.)
|
a PangoFcDecoder |
|
a PangoFcFont to query. |
|
the Unicode code point to convert to a single PangoGlyph. |
Returns : |
the glyph index, or 0 if the glyph isn't covered by the font. |
Since 1.6
|
|
Pango Reference Manual | |
|---|
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Known Derived Interfaces | ||||
PangoFontDescription;
#define PANGO_TYPE_FONT_DESCRIPTION
enum PangoStyle;
#define PANGO_TYPE_STYLE
enum PangoWeight;
#define PANGO_TYPE_WEIGHT
enum PangoVariant;
#define PANGO_TYPE_VARIANT
enum PangoStretch;
#define PANGO_TYPE_STRETCH
enum PangoFontMask;
#define PANGO_TYPE_FONT_MASK
PangoFontDescription * pango_font_description_new (void);
PangoFontDescription * pango_font_description_copy (const PangoFontDescription *desc);
PangoFontDescription * pango_font_description_copy_static
(const PangoFontDescription *desc);
guint pango_font_description_hash (const PangoFontDescription *desc);
gboolean pango_font_description_equal (const PangoFontDescription *desc1,
const PangoFontDescription *desc2);
void pango_font_description_free (PangoFontDescription *desc);
void pango_font_descriptions_free (PangoFontDescription **descs,
int n_descs);
void pango_font_description_set_family (PangoFontDescription *desc,
const char *family);
void pango_font_description_set_family_static
(PangoFontDescription *desc,
const char *family);
const char * pango_font_description_get_family (const PangoFontDescription *desc);
void pango_font_description_set_style (PangoFontDescription *desc,
PangoStyle style);
PangoStyle pango_font_description_get_style (const PangoFontDescription *desc);
void pango_font_description_set_variant (PangoFontDescription *desc,
PangoVariant variant);
PangoVariant pango_font_description_get_variant (const PangoFontDescription *desc);
void pango_font_description_set_weight (PangoFontDescription *desc,
PangoWeight weight);
PangoWeight pango_font_description_get_weight (const PangoFontDescription *desc);
void pango_font_description_set_stretch (PangoFontDescription *desc,
PangoStretch stretch);
PangoStretch pango_font_description_get_stretch (const PangoFontDescription *desc);
void pango_font_description_set_size (PangoFontDescription *desc,
gint size);
gint pango_font_description_get_size (const PangoFontDescription *desc);
void pango_font_description_set_absolute_size
(PangoFontDescription *desc,
double size);
gboolean pango_font_description_get_size_is_absolute
(const PangoFontDescription *desc);
void pango_font_description_set_gravity (PangoFontDescription *desc,
PangoGravity gravity);
PangoGravity pango_font_description_get_gravity (const PangoFontDescription *desc);
PangoFontMask pango_font_description_get_set_fields
(const PangoFontDescription *desc);
void pango_font_description_unset_fields (PangoFontDescription *desc,
PangoFontMask to_unset);
void pango_font_description_merge (PangoFontDescription *desc,
const PangoFontDescription *desc_to_merge,
gboolean replace_existing);
void pango_font_description_merge_static (PangoFontDescription *desc,
const PangoFontDescription *desc_to_merge,
gboolean replace_existing);
gboolean pango_font_description_better_match (const PangoFontDescription *desc,
const PangoFontDescription *old_match,
const PangoFontDescription *new_match);
PangoFontDescription * pango_font_description_from_string
(const char *str);
char * pango_font_description_to_string (const PangoFontDescription *desc);
char * pango_font_description_to_filename (const PangoFontDescription *desc);
PangoFontMetrics;
#define PANGO_TYPE_FONT_METRICS
PangoFontMetrics * pango_font_metrics_ref (PangoFontMetrics *metrics);
void pango_font_metrics_unref (PangoFontMetrics *metrics);
int pango_font_metrics_get_ascent (PangoFontMetrics *metrics);
int pango_font_metrics_get_descent (PangoFontMetrics *metrics);
int pango_font_metrics_get_approximate_char_width
(PangoFontMetrics *metrics);
int pango_font_metrics_get_approximate_digit_width
(PangoFontMetrics *metrics);
int pango_font_metrics_get_underline_thickness
(PangoFontMetrics *metrics);
int pango_font_metrics_get_underline_position
(PangoFontMetrics *metrics);
int pango_font_metrics_get_strikethrough_thickness
(PangoFontMetrics *metrics);
int pango_font_metrics_get_strikethrough_position
(PangoFontMetrics *metrics);
PangoFont;
#define PANGO_TYPE_FONT
#define PANGO_FONT (object)
#define PANGO_IS_FONT (object)
PangoEngineShape * pango_font_find_shaper (PangoFont *font,
PangoLanguage *language,
guint32 ch);
PangoFontDescription * pango_font_describe (PangoFont *font);
PangoFontDescription * pango_font_describe_with_absolute_size
(PangoFont *font);
PangoCoverage * pango_font_get_coverage (PangoFont *font,
PangoLanguage *language);
void pango_font_get_glyph_extents (PangoFont *font,
PangoGlyph glyph,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
PangoFontMetrics * pango_font_get_metrics (PangoFont *font,
PangoLanguage *language);
PangoFontMap * pango_font_get_font_map (PangoFont *font);
PangoFontFamily;
#define PANGO_TYPE_FONT_FAMILY
#define PANGO_FONT_FAMILY (object)
#define PANGO_IS_FONT_FAMILY (object)
const char * pango_font_family_get_name (PangoFontFamily *family);
gboolean pango_font_family_is_monospace (PangoFontFamily *family);
void pango_font_family_list_faces (PangoFontFamily *family,
PangoFontFace ***faces,
int *n_faces);
PangoFontFace;
#define PANGO_TYPE_FONT_FACE
#define PANGO_FONT_FACE (object)
#define PANGO_IS_FONT_FACE (object)
const char * pango_font_face_get_face_name (PangoFontFace *face);
void pango_font_face_list_sizes (PangoFontFace *face,
int **sizes,
int *n_sizes);
PangoFontDescription * pango_font_face_describe (PangoFontFace *face);
gboolean pango_font_face_is_synthesized (PangoFontFace *face);
PangoFontMap;
#define PANGO_TYPE_FONT_MAP
#define PANGO_FONT_MAP (object)
#define PANGO_IS_FONT_MAP (object)
PangoFontMapClass;
#define PANGO_FONT_MAP_CLASS (klass)
#define PANGO_IS_FONT_MAP_CLASS (klass)
#define PANGO_FONT_MAP_GET_CLASS (obj)
PangoContext * pango_font_map_create_context (PangoFontMap *fontmap);
PangoFont * pango_font_map_load_font (PangoFontMap *fontmap,
PangoContext *context,
const PangoFontDescription *desc);
PangoFontset * pango_font_map_load_fontset (PangoFontMap *fontmap,
PangoContext *context,
const PangoFontDescription *desc,
PangoLanguage *language);
void pango_font_map_list_families (PangoFontMap *fontmap,
PangoFontFamily ***families,
int *n_families);
const char * pango_font_map_get_shape_engine_type
(PangoFontMap *fontmap);
PangoFontset;
#define PANGO_TYPE_FONTSET
PangoFontsetClass;
PangoFont * pango_fontset_get_font (PangoFontset *fontset,
guint wc);
PangoFontMetrics * pango_fontset_get_metrics (PangoFontset *fontset);
gboolean (*PangoFontsetForeachFunc) (PangoFontset *fontset,
PangoFont *font,
gpointer data);
void pango_fontset_foreach (PangoFontset *fontset,
PangoFontsetForeachFunc func,
gpointer data);
PangoFontsetSimple;
#define PANGO_TYPE_FONTSET_SIMPLE
PangoFontsetSimple * pango_fontset_simple_new (PangoLanguage *language);
void pango_fontset_simple_append (PangoFontsetSimple *fontset,
PangoFont *font);
int pango_fontset_simple_size (PangoFontsetSimple *fontset);
GObject +----PangoFont +----PangoFcFont
GObject +----PangoFontFamily
GObject +----PangoFontFace
GObject +----PangoFontMap +----PangoFcFontMap
GObject +----PangoFontset +----PangoFontsetSimple
GObject +----PangoFontset +----PangoFontsetSimple
PangoFont is required by PangoCairoFont.
PangoFontMap is required by PangoCairoFontMap.
Pango supports a flexible architecture where a particular rendering architecture can supply an implementation of fonts. The PangoFont structure represents an abstract rendering-system-independent font. Pango provides routines to list available fonts, and to load a font of a given description.
typedef struct _PangoFontDescription PangoFontDescription;
The PangoFontDescription structure represents the description of an ideal font. These structures are used both to list what fonts are available on the system and also for specifying the characteristics of a font to load.
#define PANGO_TYPE_FONT_DESCRIPTION (pango_font_description_get_type ())
The GObject type for PangoFontDescription.
typedef enum {
PANGO_STYLE_NORMAL,
PANGO_STYLE_OBLIQUE,
PANGO_STYLE_ITALIC
} PangoStyle;
An enumeration specifying the various slant styles possible for a font.
typedef enum {
PANGO_WEIGHT_THIN = 100,
PANGO_WEIGHT_ULTRALIGHT = 200,
PANGO_WEIGHT_LIGHT = 300,
PANGO_WEIGHT_BOOK = 380,
PANGO_WEIGHT_NORMAL = 400,
PANGO_WEIGHT_MEDIUM = 500,
PANGO_WEIGHT_SEMIBOLD = 600,
PANGO_WEIGHT_BOLD = 700,
PANGO_WEIGHT_ULTRABOLD = 800,
PANGO_WEIGHT_HEAVY = 900,
PANGO_WEIGHT_ULTRAHEAVY = 1000
} PangoWeight;
An enumeration specifying the weight (boldness) of a font. This is a numerical value ranging from 100 to 900, but there are some predefined values:
| the thin weight (= 100; Since: 1.24) | |
| the ultralight weight (= 200) | |
| the light weight (= 300) | |
| the book weight (= 380; Since: 1.24) | |
| the default weight (= 400) | |
| the normal weight (= 500; Since: 1.24) | |
| the semibold weight (= 600) | |
| the bold weight (= 700) | |
| the ultrabold weight (= 800) | |
| the heavy weight (= 900) | |
| the ultraheavy weight (= 1000; Since: 1.24) |
#define PANGO_TYPE_WEIGHT (pango_weight_get_type())
The GObject type for PangoWeight.
typedef enum {
PANGO_VARIANT_NORMAL,
PANGO_VARIANT_SMALL_CAPS
} PangoVariant;
An enumeration specifying capitalization variant of the font.
#define PANGO_TYPE_VARIANT (pango_variant_get_type())
The GObject type for PangoVariant.
typedef enum {
PANGO_STRETCH_ULTRA_CONDENSED,
PANGO_STRETCH_EXTRA_CONDENSED,
PANGO_STRETCH_CONDENSED,
PANGO_STRETCH_SEMI_CONDENSED,
PANGO_STRETCH_NORMAL,
PANGO_STRETCH_SEMI_EXPANDED,
PANGO_STRETCH_EXPANDED,
PANGO_STRETCH_EXTRA_EXPANDED,
PANGO_STRETCH_ULTRA_EXPANDED
} PangoStretch;
An enumeration specifying the width of the font relative to other designs within a family.
| ultra condensed width | |
| extra condensed width | |
| condensed width | |
| semi condensed width | |
| the normal width | |
| semi expanded width | |
| expanded width | |
| extra expanded width | |
| ultra expanded width |
#define PANGO_TYPE_STRETCH (pango_stretch_get_type())
The GObject type for PangoStretch.
typedef enum {
PANGO_FONT_MASK_FAMILY = 1 << 0,
PANGO_FONT_MASK_STYLE = 1 << 1,
PANGO_FONT_MASK_VARIANT = 1 << 2,
PANGO_FONT_MASK_WEIGHT = 1 << 3,
PANGO_FONT_MASK_STRETCH = 1 << 4,
PANGO_FONT_MASK_SIZE = 1 << 5,
PANGO_FONT_MASK_GRAVITY = 1 << 6
} PangoFontMask;
The bits in a PangoFontMask correspond to fields in a PangoFontDescription that have been set.
| the font family is specified. | |
| the font style is specified. | |
| the font variant is specified. | |
| the font weight is specified. | |
| the font stretch is specified. | |
| the font size is specified. | |
| the font gravity is specified (Since: 1.16.) |
#define PANGO_TYPE_FONT_MASK (pango_font_mask_get_type())
The GObject type for PangoFontMask.
PangoFontDescription * pango_font_description_new (void);
Creates a new font description structure with all fields unset.
Returns : |
the newly allocated PangoFontDescription, which
should be freed using pango_font_description_free().
|
PangoFontDescription * pango_font_description_copy (const PangoFontDescription *desc);
Make a copy of a PangoFontDescription.
|
a PangoFontDescription, may be NULL
|
Returns : |
the newly allocated PangoFontDescription, which should
be freed with pango_font_description_free(), or NULL
if desc was NULL.
|
PangoFontDescription * pango_font_description_copy_static (const PangoFontDescription *desc);
Like pango_font_description_copy(), but only a shallow copy is made
of the family name and other allocated fields. The result can only
be used until desc is modified or freed. This is meant to be used
when the copy is only needed temporarily.
|
a PangoFontDescription, may be NULL
|
Returns : |
the newly allocated PangoFontDescription, which should
be freed with pango_font_description_free(), or NULL
if desc was NULL.
|
guint pango_font_description_hash (const PangoFontDescription *desc);
Computes a hash of a PangoFontDescription structure suitable
to be used, for example, as an argument to g_hash_table_new().
The hash value is independent of desc->mask.
|
a PangoFontDescription |
Returns : |
the hash value. |
gboolean pango_font_description_equal (const PangoFontDescription *desc1, const PangoFontDescription *desc2);
Compares two font descriptions for equality. Two font descriptions
are considered equal if the fonts they describe are provably identical.
This means that their masks do not have to match, as long as other fields
are all the same. (Two font descriptions may result in identical fonts
being loaded, but still compare FALSE.)
|
a PangoFontDescription |
|
another PangoFontDescription |
Returns : |
TRUE if the two font descriptions are identical,
FALSE otherwise.
|
void pango_font_description_free (PangoFontDescription *desc);
Frees a font description.
|
a PangoFontDescription, may be NULL
|
void pango_font_descriptions_free (PangoFontDescription **descs, int n_descs);
Frees an array of font descriptions.
|
a pointer to an array of PangoFontDescription, may be NULL
|
|
number of font descriptions in descs
|
void pango_font_description_set_family (PangoFontDescription *desc, const char *family);
Sets the family name field of a font description. The family name represents a family of related font styles, and will resolve to a particular PangoFontFamily. In some uses of PangoFontDescription, it is also possible to use a comma separated list of family names for this field.
|
a PangoFontDescription. |
|
a string representing the family name. |
void pango_font_description_set_family_static
(PangoFontDescription *desc,
const char *family);
Like pango_font_description_set_family(), except that no
copy of family is made. The caller must make sure that the
string passed in stays around until desc has been freed
or the name is set again. This function can be used if
family is a static string such as a C string literal, or
if desc is only needed temporarily.
|
a PangoFontDescription |
|
a string representing the family name. |
const char * pango_font_description_get_family (const PangoFontDescription *desc);
Gets the family name field of a font description. See
pango_font_description_set_family().
|
a PangoFontDescription. |
Returns : |
the family name field for the font description, or
NULL if not previously set. This has the same life-time
as the font description itself and should not be freed.
|
void pango_font_description_set_style (PangoFontDescription *desc, PangoStyle style);
Sets the style field of a PangoFontDescription. The PangoStyle enumeration describes whether the font is slanted and the manner in which it is slanted; it can be either PANGO_STYLE_NORMAL, PANGO_STYLE_ITALIC, or PANGO_STYLE_OBLIQUE. Most fonts will either have a italic style or an oblique style, but not both, and font matching in Pango will match italic specifications with oblique fonts and vice-versa if an exact match is not found.
|
a PangoFontDescription |
|
the style for the font description |
PangoStyle pango_font_description_get_style (const PangoFontDescription *desc);
Gets the style field of a PangoFontDescription. See
pango_font_description_set_style().
|
a PangoFontDescription |
Returns : |
the style field for the font description.
Use pango_font_description_get_set_fields() to find out if
the field was explicitly set or not.
|
void pango_font_description_set_variant (PangoFontDescription *desc, PangoVariant variant);
Sets the variant field of a font description. The PangoVariant
can either be PANGO_VARIANT_NORMAL or PANGO_VARIANT_SMALL_CAPS.
|
a PangoFontDescription |
|
the variant type for the font description. |
PangoVariant pango_font_description_get_variant (const PangoFontDescription *desc);
Gets the variant field of a PangoFontDescription. See
pango_font_description_set_variant().
|
a PangoFontDescription. |
Returns : |
the variant field for the font description. Use
pango_font_description_get_set_fields() to find out if
the field was explicitly set or not.
|
void pango_font_description_set_weight (PangoFontDescription *desc, PangoWeight weight);
Sets the weight field of a font description. The weight field specifies how bold or light the font should be. In addition to the values of the PangoWeight enumeration, other intermediate numeric values are possible.
|
a PangoFontDescription |
|
the weight for the font description. |
PangoWeight pango_font_description_get_weight (const PangoFontDescription *desc);
Gets the weight field of a font description. See
pango_font_description_set_weight().
|
a PangoFontDescription |
Returns : |
the weight field for the font description. Use
pango_font_description_get_set_fields() to find out if
the field was explicitly set or not.
|
void pango_font_description_set_stretch (PangoFontDescription *desc, PangoStretch stretch);
Sets the stretch field of a font description. The stretch field specifies how narrow or wide the font should be.
|
a PangoFontDescription |
|
the stretch for the font description |
PangoStretch pango_font_description_get_stretch (const PangoFontDescription *desc);
Gets the stretch field of a font description.
See pango_font_description_set_stretch().
|
a PangoFontDescription. |
Returns : |
the stretch field for the font description. Use
pango_font_description_get_set_fields() to find out if
the field was explicitly set or not.
|
void pango_font_description_set_size (PangoFontDescription *desc, gint size);
Sets the size field of a font description in fractional points. This is mutually
exclusive with pango_font_description_set_absolute_size().
|
a PangoFontDescription |
|
the size of the font in points, scaled by PANGO_SCALE. (That is,
a size value of 10 * PANGO_SCALE is a 10 point font. The conversion
factor between points and device units depends on system configuration
and the output device. For screen display, a logical DPI of 96 is
common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 13.3
pixel font. Use pango_font_description_set_absolute_size() if you need
a particular size in device units.
|
gint pango_font_description_get_size (const PangoFontDescription *desc);
Gets the size field of a font description.
See pango_font_description_set_size().
|
a PangoFontDescription |
Returns : |
the size field for the font description in points or device units.
You must call pango_font_description_get_size_is_absolute()
to find out which is the case. Returns 0 if the size field has not
previously been set or it has been set to 0 explicitly.
Use pango_font_description_get_set_fields() to
find out if the field was explicitly set or not.
|
void pango_font_description_set_absolute_size
(PangoFontDescription *desc,
double size);
Sets the size field of a font description, in device units. This is mutually
exclusive with pango_font_description_set_size() which sets the font size
in points.
|
a PangoFontDescription |
|
the new size, in Pango units. There are PANGO_SCALE Pango units in one
device unit. For an output backend where a device unit is a pixel, a size
value of 10 * PANGO_SCALE gives a 10 pixel font.
|
Since 1.8
gboolean pango_font_description_get_size_is_absolute (const PangoFontDescription *desc);
Determines whether the size of the font is in points (not absolute) or device units (absolute).
See pango_font_description_set_size() and pango_font_description_set_absolute_size().
|
a PangoFontDescription |
Returns : |
whether the size for the font description is in
points or device units. Use pango_font_description_get_set_fields() to
find out if the size field of the font description was explicitly set or not.
|
Since 1.8
void pango_font_description_set_gravity (PangoFontDescription *desc, PangoGravity gravity);
Sets the gravity field of a font description. The gravity field
specifies how the glyphs should be rotated. If gravity is
PANGO_GRAVITY_AUTO, this actually unsets the gravity mask on
the font description.
This function is seldom useful to the user. Gravity should normally be set on a PangoContext.
|
a PangoFontDescription |
|
the gravity for the font description. |
Since 1.16
PangoGravity pango_font_description_get_gravity (const PangoFontDescription *desc);
Gets the gravity field of a font description. See
pango_font_description_set_gravity().
|
a PangoFontDescription |
Returns : |
the gravity field for the font description. Use
pango_font_description_get_set_fields() to find out if
the field was explicitly set or not.
|
Since 1.16
PangoFontMask pango_font_description_get_set_fields (const PangoFontDescription *desc);
Determines which fields in a font description have been set.
|
a PangoFontDescription |
Returns : |
a bitmask with bits set corresponding to the
fields in desc that have been set.
|
void pango_font_description_unset_fields (PangoFontDescription *desc, PangoFontMask to_unset);
Unsets some of the fields in a PangoFontDescription. The unset fields will get back to their default values.
|
a PangoFontDescription |
|
bitmask of fields in the desc to unset.
|
void pango_font_description_merge (PangoFontDescription *desc, const PangoFontDescription *desc_to_merge, gboolean replace_existing);
Merges the fields that are set in desc_to_merge into the fields in
desc. If replace_existing is FALSE, only fields in desc that
are not already set are affected. If TRUE, then fields that are
already set will be replaced as well.
If desc_to_merge is NULL, this function performs nothing.
|
a PangoFontDescription |
|
the PangoFontDescription to merge from, or NULL
|
|
if TRUE, replace fields in desc with the
corresponding values from desc_to_merge, even if they
are already exist.
|
void pango_font_description_merge_static (PangoFontDescription *desc, const PangoFontDescription *desc_to_merge, gboolean replace_existing);
Like pango_font_description_merge(), but only a shallow copy is made
of the family name and other allocated fields. desc can only be
used until desc_to_merge is modified or freed. This is meant
to be used when the merged font description is only needed temporarily.
|
a PangoFontDescription |
|
the PangoFontDescription to merge from |
|
if TRUE, replace fields in desc with the
corresponding values from desc_to_merge, even if they
are already exist.
|
gboolean pango_font_description_better_match (const PangoFontDescription *desc, const PangoFontDescription *old_match, const PangoFontDescription *new_match);
Determines if the style attributes of new_match are a closer match
for desc than those of old_match are, or if old_match is NULL,
determines if new_match is a match at all.
Approximate matching is done for
weight and style; other style attributes must match exactly.
Style attributes are all attributes other than family and size-related
attributes. Approximate matching for style considers PANGO_STYLE_OBLIQUE
and PANGO_STYLE_ITALIC as matches, but not as good a match as when the
styles are equal.
Note that old_match must match desc.
|
a PangoFontDescription |
|
a PangoFontDescription, or NULL
|
|
a PangoFontDescription |
Returns : |
TRUE if new_match is a better match
|
PangoFontDescription * pango_font_description_from_string (const char *str);
Creates a new font description from a string representation in the
form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is a
comma separated list of families optionally terminated by a comma,
STYLE_OPTIONS is a whitespace separated list of words where each WORD
describes one of style, variant, weight, stretch, or gravity, and SIZE
is a decimal number (size in points) or optionally followed by the
unit modifier "px" for absolute size. Any one of the options may
be absent. If FAMILY-LIST is absent, then the family_name field of
the resulting font description will be initialized to NULL. If
STYLE-OPTIONS is missing, then all style options will be set to the
default values. If SIZE is missing, the size in the resulting font
description will be set to 0.
|
string representation of a font description. |
Returns : |
a new PangoFontDescription. |
char * pango_font_description_to_string (const PangoFontDescription *desc);
Creates a string representation of a font description. See
pango_font_description_from_string() for a description of the
format of the string representation. The family list in the
string description will only have a terminating comma if the
last word of the list is a valid style option.
|
a PangoFontDescription |
Returns : |
a new string that must be freed with g_free().
|
char * pango_font_description_to_filename (const PangoFontDescription *desc);
Creates a filename representation of a font description. The
filename is identical to the result from calling
pango_font_description_to_string(), but with underscores instead of
characters that are untypical in filenames, and in lower case only.
|
a PangoFontDescription |
Returns : |
a new string that must be freed with g_free().
|
typedef struct {
guint ref_count;
int ascent;
int descent;
int approximate_char_width;
int approximate_digit_width;
int underline_position;
int underline_thickness;
int strikethrough_position;
int strikethrough_thickness;
} PangoFontMetrics;
A PangoFontMetrics structure holds the overall metric information for a font (possibly restricted to a script). The fields of this structure are private to implementations of a font backend. See the documentation of the corresponding getters for documentation of their meaning.
guint |
reference count. Used internally. See pango_font_metrics_ref()
and pango_font_metrics_unref().
|
int |
the distance from the baseline to the highest point of the glyphs of the font. This is positive in practically all fonts. |
int |
the distance from the baseline to the lowest point of the glyphs of the font. This is positive in practically all fonts. |
int |
approximate average width of the regular glyphs of
the font. Note that for this calculation, East Asian characters
(those passing g_unichar_iswide()) are counted as double-width.
This produces a more uniform value for this measure across languages
and results in more uniform and more expected UI sizes.
|
int |
approximate average width of the glyphs for digits of the font. |
int |
position of the underline. This is normally negative. |
int |
thickness of the underline. |
int |
position of the strikethrough line. This is normally positive. |
int |
thickness of the strikethrough line. |
#define PANGO_TYPE_FONT_METRICS (pango_font_metrics_get_type ())
The GObject type for PangoFontMetrics.
PangoFontMetrics * pango_font_metrics_ref (PangoFontMetrics *metrics);
Increase the reference count of a font metrics structure by one.
|
a PangoFontMetrics structure, may be NULL
|
Returns : |
metrics
|
void pango_font_metrics_unref (PangoFontMetrics *metrics);
Decrease the reference count of a font metrics structure by one. If the result is zero, frees the structure and any associated memory.
|
a PangoFontMetrics structure, may be NULL
|
int pango_font_metrics_get_ascent (PangoFontMetrics *metrics);
Gets the ascent from a font metrics structure. The ascent is the distance from the baseline to the logical top of a line of text. (The logical top may be above or below the top of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.)
|
a PangoFontMetrics structure |
Returns : |
the ascent, in Pango units. |
int pango_font_metrics_get_descent (PangoFontMetrics *metrics);
Gets the descent from a font metrics structure. The descent is the distance from the baseline to the logical bottom of a line of text. (The logical bottom may be above or below the bottom of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.)
|
a PangoFontMetrics structure |
Returns : |
the descent, in Pango units. |
int pango_font_metrics_get_approximate_char_width
(PangoFontMetrics *metrics);
Gets the approximate character width for a font metrics structure. This is merely a representative value useful, for example, for determining the initial size for a window. Actual characters in text will be wider and narrower than this.
|
a PangoFontMetrics structure |
Returns : |
the character width, in Pango units. |
int pango_font_metrics_get_approximate_digit_width
(PangoFontMetrics *metrics);
Gets the approximate digit width for a font metrics structure.
This is merely a representative value useful, for example, for
determining the initial size for a window. Actual digits in
text can be wider or narrower than this, though this value
is generally somewhat more accurate than the result of
pango_font_metrics_get_approximate_char_width() for digits.
|
a PangoFontMetrics structure |
Returns : |
the digit width, in Pango units. |
int pango_font_metrics_get_underline_thickness
(PangoFontMetrics *metrics);
Gets the suggested thickness to draw for the underline.
|
a PangoFontMetrics structure |
Returns : |
the suggested underline thickness, in Pango units. |
Since 1.6
int pango_font_metrics_get_underline_position
(PangoFontMetrics *metrics);
Gets the suggested position to draw the underline. The value returned is the distance above the baseline of the top of the underline. Since most fonts have underline positions beneath the baseline, this value is typically negative.
|
a PangoFontMetrics structure |
Returns : |
the suggested underline position, in Pango units. |
Since 1.6
int pango_font_metrics_get_strikethrough_thickness
(PangoFontMetrics *metrics);
Gets the suggested thickness to draw for the strikethrough.
|
a PangoFontMetrics structure |
Returns : |
the suggested strikethrough thickness, in Pango units. |
Since 1.6
int pango_font_metrics_get_strikethrough_position
(PangoFontMetrics *metrics);
Gets the suggested position to draw the strikethrough. The value returned is the distance above the baseline of the top of the strikethrough.
|
a PangoFontMetrics structure |
Returns : |
the suggested strikethrough position, in Pango units. |
Since 1.6
typedef struct _PangoFont PangoFont;
The PangoFont structure is used to represent
a font in a rendering-system-independent matter.
To create an implementation of a PangoFont,
the rendering-system specific code should allocate
a larger structure that contains a nested
PangoFont, fill in the klass member of
the nested PangoFont with a pointer to
a appropriate PangoFontClass, then call
pango_font_init() on the structure.
The PangoFont structure contains one member which the implementation fills in.
#define PANGO_FONT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT, PangoFont))
Casts a GObject to a PangoFont.
|
a GObject. |
#define PANGO_IS_FONT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT))
Returns TRUE if object is a PangoFont.
|
a GObject. |
PangoEngineShape * pango_font_find_shaper (PangoFont *font, PangoLanguage *language, guint32 ch);
Finds the best matching shaper for a font for a particular language tag and character point.
|
a PangoFont |
|
the language tag |
|
a Unicode character. |
Returns : |
the best matching shaper. |
PangoFontDescription * pango_font_describe (PangoFont *font);
Returns a description of the font, with font size set in points.
Use pango_font_describe_with_absolute_size() if you want the font
size in device units.
|
a PangoFont |
Returns : |
a newly-allocated PangoFontDescription object. |
PangoFontDescription * pango_font_describe_with_absolute_size (PangoFont *font);
Returns a description of the font, with absolute font size set
(in device units). Use pango_font_describe() if you want the font
size in points.
|
a PangoFont |
Returns : |
a newly-allocated PangoFontDescription object. |
Since 1.14
PangoCoverage * pango_font_get_coverage (PangoFont *font, PangoLanguage *language);
Computes the coverage map for a given font and language tag.
|
a PangoFont |
|
the language tag |
Returns : |
a newly-allocated PangoCoverage object. |
void pango_font_get_glyph_extents (PangoFont *font, PangoGlyph glyph, PangoRectangle *ink_rect, PangoRectangle *logical_rect);
Gets the logical and ink extents of a glyph within a font. The
coordinate system for each rectangle has its origin at the
base line and horizontal origin of the character with increasing
coordinates extending to the right and down. The macros PANGO_ASCENT(),
PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert
from the extents rectangle to more traditional font metrics. The units
of the rectangles are in 1/PANGO_SCALE of a device unit.
If font is NULL, this function gracefully sets some sane values in the
output variables and returns.
PangoFontMetrics * pango_font_get_metrics (PangoFont *font, PangoLanguage *language);
Gets overall metric information for a font. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be retrieved that correspond to the script(s) used by that language.
If font is NULL, this function gracefully sets some sane values in the
output variables and returns.
|
a PangoFont |
|
language tag used to determine which script to get the metrics
for, or NULL to indicate to get the metrics for the entire
font.
|
Returns : |
a PangoFontMetrics object. The caller must call pango_font_metrics_unref()
when finished using the object.
|
PangoFontMap * pango_font_get_font_map (PangoFont *font);
Gets the font map for which the font was created.
Note that the font maintains a weak reference
to the font map, so if all references to font map are dropped, the font
map will be finalized even if there are fonts created with the font
map that are still alive. In that case this function will return NULL.
It is the responsibility of the user to ensure that the font map is kept
alive. In most uses this is not an issue as a PangoContext holds
a reference to the font map.
|
a PangoFont, or NULL
|
Returns : |
the PangoFontMap for the font, or NULL if font is NULL.
|
Since 1.10
typedef struct _PangoFontFamily PangoFontFamily;
The PangoFontFamily structure is used to represent a family of related font faces. The faces in a family share a common design, but differ in slant, weight, width and other aspects.
#define PANGO_TYPE_FONT_FAMILY (pango_font_family_get_type ())
The GObject type for PangoFontFamily.
#define PANGO_FONT_FAMILY(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FAMILY, PangoFontFamily))
Casts a GObject to a PangoFontFamily.
|
a GObject. |
#define PANGO_IS_FONT_FAMILY(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FAMILY))
Returns TRUE if object is a PangoFontFamily.
|
a GObject. |
const char * pango_font_family_get_name (PangoFontFamily *family);
Gets the name of the family. The name is unique among all fonts for the font backend and can be used in a PangoFontDescription to specify that a face from this family is desired.
|
a PangoFontFamily |
Returns : |
the name of the family. This string is owned by the family object and must not be modified or freed. |
gboolean pango_font_family_is_monospace (PangoFontFamily *family);
A monospace font is a font designed for text display where the the
characters form a regular grid. For Western languages this would
mean that the advance width of all characters are the same, but
this categorization also includes Asian fonts which include
double-width characters: characters that occupy two grid cells.
g_unichar_iswide() returns a result that indicates whether a
character is typically double-width in a monospace font.
The best way to find out the grid-cell size is to call
pango_font_metrics_get_approximate_digit_width(), since the results
of pango_font_metrics_get_approximate_char_width() may be affected
by double-width characters.
|
a PangoFontFamily |
Returns : |
TRUE if the family is monospace.
|
Since 1.4
void pango_font_family_list_faces (PangoFontFamily *family, PangoFontFace ***faces, int *n_faces);
Lists the different font faces that make up family. The faces
in a family share a common design, but differ in slant, weight,
width and other aspects.
|
a PangoFontFamily |
|
location to store an array of pointers to PangoFontFace
objects, or NULL. This array should be freed with g_free()
when it is no longer needed.
|
|
location to store number of elements in faces.
|
typedef struct _PangoFontFace PangoFontFace;
The PangoFontFace structure is used to represent a group of fonts with the same family, slant, weight, width, but varying sizes.
#define PANGO_TYPE_FONT_FACE (pango_font_face_get_type ())
The GObject type for PangoFontFace.
#define PANGO_FONT_FACE(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FACE, PangoFontFace))
Casts a GObject to a PangoFontFace.
|
a GObject. |
#define PANGO_IS_FONT_FACE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FACE))
Returns TRUE if object is a PangoFontFace.
|
a GObject. |
const char * pango_font_face_get_face_name (PangoFontFace *face);
Gets a name representing the style of this face among the different faces in the PangoFontFamily for the face. This name is unique among all faces in the family and is suitable for displaying to users.
|
a PangoFontFace. |
Returns : |
the face name for the face. This string is owned by the face object and must not be modified or freed. |
void pango_font_face_list_sizes (PangoFontFace *face, int **sizes, int *n_sizes);
List the available sizes for a font. This is only applicable to bitmap
fonts. For scalable fonts, stores NULL at the location pointed to by
sizes and 0 at the location pointed to by n_sizes. The sizes returned
are in Pango units and are sorted in ascending order.
|
a PangoFontFace. |
|
location to store a pointer to an array of int. This array
should be freed with g_free().
|
|
location to store the number of elements in sizes
|
Since 1.4
PangoFontDescription * pango_font_face_describe (PangoFontFace *face);
Returns the family, style, variant, weight and stretch of a PangoFontFace. The size field of the resulting font description will be unset.
|
a PangoFontFace |
Returns : |
a newly-created PangoFontDescription structure
holding the description of the face. Use pango_font_description_free()
to free the result.
|
gboolean pango_font_face_is_synthesized (PangoFontFace *face);
Returns whether a PangoFontFace is synthesized by the underlying font rendering engine from another face, perhaps by shearing, emboldening, or lightening it.
|
a PangoFontFace |
Returns : |
whether face is synthesized.
|
Since 1.18
typedef struct _PangoFontMap PangoFontMap;
The PangoFontMap represents the set of fonts available for a
particular rendering system. This is a virtual object with
implementations being specific to particular rendering systems. To
create an implementation of a PangoFontMap, the rendering-system
specific code should allocate a larger structure that contains a nested
PangoFontMap, fill in the klass member of the nested PangoFontMap with a
pointer to a appropriate PangoFontMapClass, then call
pango_font_map_init() on the structure.
The PangoFontMap structure contains one member which the implementation fills in.
#define PANGO_TYPE_FONT_MAP (pango_font_map_get_type ())
The GObject type for PangoFontMap.
#define PANGO_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_MAP, PangoFontMap))
Casts a GObject to a PangoFontMap.
|
a GObject. |
#define PANGO_IS_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_MAP))
Returns TRUE if object is a PangoFontMap.
|
a GObject. |
typedef struct {
GObjectClass parent_class;
PangoFont * (*load_font) (PangoFontMap *fontmap,
PangoContext *context,
const PangoFontDescription *desc);
void (*list_families) (PangoFontMap *fontmap,
PangoFontFamily ***families,
int *n_families);
PangoFontset *(*load_fontset) (PangoFontMap *fontmap,
PangoContext *context,
const PangoFontDescription *desc,
PangoLanguage *language);
const char *shape_engine_type;
} PangoFontMapClass;
The PangoFontMapClass structure holds the virtual functions for a particular PangoFontMap implementation.
GObjectClass |
parent GObjectClass. |
|
a function to load a font with a given description. See
pango_font_map_load_font().
|
|
A function to list available font families. See
pango_font_map_list_families().
|
|
a function to load a fontset with a given given description
suitable for a particular language. See
pango_font_map_load_fontset().
|
const char * |
the type of rendering-system-dependent engines that can handle fonts of this fonts loaded with this fontmap. |
#define PANGO_FONT_MAP_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_FONT_MAP, PangoFontMapClass))
Casts a GObject to a PangoFontMapClass.
|
a GObject. |
#define PANGO_IS_FONT_MAP_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_FONT_MAP))
Returns TRUE if klass is a subtype of PangoFontMapClass.
|
a GObject. |
#define PANGO_FONT_MAP_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_FONT_MAP, PangoFontMapClass))
Returns the type of a PangoFontMap.
|
a PangoFontMap. |
PangoContext * pango_font_map_create_context (PangoFontMap *fontmap);
Creates a PangoContext connected to fontmap. This is equivalent
to pango_context_new() followed by pango_context_set_font_map().
If you are using Pango as part of a higher-level system,
that system may have it's own way of create a PangoContext.
For instance, the GTK+ toolkit has, among others,
gdk_pango_context_get_for_screen(), and
gtk_widget_get_pango_context(). Use those instead.
|
a PangoFontMap |
Returns : |
the newly allocated PangoContext, which should
be freed with g_object_unref().
|
Since 1.22
PangoFont * pango_font_map_load_font (PangoFontMap *fontmap, PangoContext *context, const PangoFontDescription *desc);
Load the font in the fontmap that is the closest match for desc.
|
a PangoFontMap |
|
the PangoContext the font will be used with |
|
a PangoFontDescription describing the font to load |
Returns : |
the font loaded, or NULL if no font matched.
|
PangoFontset * pango_font_map_load_fontset (PangoFontMap *fontmap, PangoContext *context, const PangoFontDescription *desc, PangoLanguage *language);
Load a set of fonts in the fontmap that can be used to render
a font matching desc.
|
a PangoFontMap |
|
the PangoContext the font will be used with |
|
a PangoFontDescription describing the font to load |
|
a PangoLanguage the fonts will be used for |
Returns : |
the fontset, or NULL if no font matched.
|
void pango_font_map_list_families (PangoFontMap *fontmap, PangoFontFamily ***families, int *n_families);
List all families for a fontmap.
|
a PangoFontMap |
|
location to store a pointer to an array of PangoFontFamily *.
This array should be freed with g_free().
|
|
location to store the number of elements in families
|
const char * pango_font_map_get_shape_engine_type
(PangoFontMap *fontmap);
Returns the render ID for shape engines for this fontmap.
See the render_type field of
PangoEngineInfo.
|
a PangoFontMap |
Returns : |
the ID string for shape engines for this fontmap. Owned by Pango, should not be modified or freed. |
Since 1.4
typedef struct _PangoFontset PangoFontset;
A PangoFontset represents a set of PangoFont to use when rendering text. It is the result of resolving a PangoFontDescription against a particular PangoContext. It has operations for finding the component font for a particular Unicode character, and for finding a composite set of metrics for the entire fontset.
#define PANGO_TYPE_FONTSET (pango_fontset_get_type ())
The GObject type for PangoFontset.
typedef struct {
GObjectClass parent_class;
PangoFont * (*get_font) (PangoFontset *fontset,
guint wc);
PangoFontMetrics *(*get_metrics) (PangoFontset *fontset);
PangoLanguage * (*get_language) (PangoFontset *fontset);
void (*foreach) (PangoFontset *fontset,
PangoFontsetForeachFunc func,
gpointer data);
} PangoFontsetClass;
The PangoFontsetClass structure holds the virtual functions for a particular PangoFontset implementation.
GObjectClass |
parent GObjectClass. |
|
a function to get the font in the fontset that contains the
best glyph for the given Unicode character; see pango_fontset_get_font().
|
|
a function to get overall metric information for the fonts
in the fontset; see pango_fontset_get_metrics().
|
|
a function to get the language of the fontset. |
|
a function to loop over the fonts in the fontset. See
pango_fontset_foreach().
|
PangoFont * pango_fontset_get_font (PangoFontset *fontset, guint wc);
Returns the font in the fontset that contains the best glyph for the
Unicode character wc.
|
a PangoFontset |
|
a Unicode character |
Returns : |
a PangoFont. The caller must call g_object_unref when finished with the font. |
PangoFontMetrics * pango_fontset_get_metrics (PangoFontset *fontset);
Get overall metric information for the fonts in the fontset.
|
a PangoFontset |
Returns : |
a PangoFontMetrics object. The caller must call pango_font_metrics_unref()
when finished using the object.
|
gboolean (*PangoFontsetForeachFunc) (PangoFontset *fontset, PangoFont *font, gpointer data);
A callback function used by pango_fontset_foreach() when enumerating
the fonts in a fontset.
|
a PangoFontset |
|
a font from fontset
|
|
callback data |
Returns : |
if TRUE, stop iteration and return immediately.
|
Since 1.4
void pango_fontset_foreach (PangoFontset *fontset, PangoFontsetForeachFunc func, gpointer data);
Iterates through all the fonts in a fontset, calling func for
each one. If func returns TRUE, that stops the iteration.
|
a PangoFontset |
|
Callback function |
|
data to pass to the callback function |
Since 1.4
typedef struct _PangoFontsetSimple PangoFontsetSimple;
PangoFontsetSimple is a implementation of the abstract PangoFontset base class in terms of an array of fonts, which the creator provides when constructing the PangoFontsetSimple.
#define PANGO_TYPE_FONTSET_SIMPLE (pango_fontset_simple_get_type ())
The GObject type for PangoFontsetSimple.
PangoFontsetSimple * pango_fontset_simple_new (PangoLanguage *language);
Creates a new PangoFontsetSimple for the given language.
|
a PangoLanguage tag |
Returns : |
the newly allocated PangoFontsetSimple, which should
be freed with g_object_unref().
|
void pango_fontset_simple_append (PangoFontsetSimple *fontset, PangoFont *font);
Adds a font to the fontset.
|
a PangoFontsetSimple. |
|
a PangoFont. |
int pango_fontset_simple_size (PangoFontsetSimple *fontset);
Returns the number of fonts in the fontset.
|
a PangoFontsetSimple. |
Returns : |
the size of fontset.
|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
#define PANGO_RENDER_TYPE_ATSUI CGFontRef pango_atsui_font_get_cgfont (PangoATSUIFont *font);
The macros and functions in this section are used to access fonts natively on MacOS systems using the ATSUI text rendering subsystem.
#define PANGO_RENDER_TYPE_ATSUI "PangoRenderATSUI"
A string constant identifying the ATSUI renderer. The associated quark (see
g_quark_from_string()) is used to identify the renderer in pango_find_map().
|
|
Pango Reference Manual | |
|---|
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
PangoTabArray;
#define PANGO_TYPE_TAB_ARRAY
enum PangoTabAlign;
#define PANGO_TYPE_TAB_ALIGN
PangoTabArray * pango_tab_array_new (gint initial_size,
gboolean positions_in_pixels);
PangoTabArray * pango_tab_array_new_with_positions (gint size,
gboolean positions_in_pixels,
PangoTabAlign first_alignment,
gint first_position,
...);
PangoTabArray * pango_tab_array_copy (PangoTabArray *src);
void pango_tab_array_free (PangoTabArray *tab_array);
gint pango_tab_array_get_size (PangoTabArray *tab_array);
void pango_tab_array_resize (PangoTabArray *tab_array,
gint new_size);
void pango_tab_array_set_tab (PangoTabArray *tab_array,
gint tab_index,
PangoTabAlign alignment,
gint location);
void pango_tab_array_get_tab (PangoTabArray *tab_array,
gint tab_index,
PangoTabAlign *alignment,
gint *location);
void pango_tab_array_get_tabs (PangoTabArray *tab_array,
PangoTabAlign **alignments,
gint **locations);
gboolean pango_tab_array_get_positions_in_pixels
(PangoTabArray *tab_array);
Functions in this section are used to deal with PangoTabArray objects that can be used to set tab stop positions in a PangoLayout.
typedef struct _PangoTabArray PangoTabArray;
A PangoTabArray struct contains an array of tab stops. Each tab stop has an alignment and a position.
#define PANGO_TYPE_TAB_ARRAY (pango_tab_array_get_type ())
The GObject type for PangoTabArray.
typedef enum
{
PANGO_TAB_LEFT
/* These are not supported now, but may be in the
* future.
*
* PANGO_TAB_RIGHT,
* PANGO_TAB_CENTER,
* PANGO_TAB_NUMERIC
*/
} PangoTabAlign;
A PangoTabAlign specifies where a tab stop appears relative to the text.
#define PANGO_TYPE_TAB_ALIGN (pango_tab_align_get_type())
The GObject type for PangoTabAlign.
PangoTabArray * pango_tab_array_new (gint initial_size, gboolean positions_in_pixels);
Creates an array of initial_size tab stops. Tab stops are specified in
pixel units if positions_in_pixels is TRUE, otherwise in Pango
units. All stops are initially at position 0.
|
Initial number of tab stops to allocate, can be 0 |
|
whether positions are in pixel units |
Returns : |
the newly allocated PangoTabArray, which should
be freed with pango_tab_array_free().
|
PangoTabArray * pango_tab_array_new_with_positions (gint size, gboolean positions_in_pixels, PangoTabAlign first_alignment, gint first_position, ...);
This is a convenience function that creates a PangoTabArray
and allows you to specify the alignment and position of each
tab stop. You must provide an alignment
and position for size tab stops.
|
number of tab stops in the array |
|
whether positions are in pixel units |
|
alignment of first tab stop |
|
position of first tab stop |
|
additional alignment/position pairs |
Returns : |
the newly allocated PangoTabArray, which should
be freed with pango_tab_array_free().
|
PangoTabArray * pango_tab_array_copy (PangoTabArray *src);
Copies a PangoTabArray
|
PangoTabArray to copy |
Returns : |
the newly allocated PangoTabArray, which should
be freed with pango_tab_array_free().
|
void pango_tab_array_free (PangoTabArray *tab_array);
Frees a tab array and associated resources.
|
a PangoTabArray |
gint pango_tab_array_get_size (PangoTabArray *tab_array);
Gets the number of tab stops in tab_array.
|
a PangoTabArray |
Returns : |
the number of tab stops in the array. |
void pango_tab_array_resize (PangoTabArray *tab_array, gint new_size);
Resizes a tab array. You must subsequently initialize any tabs that were added as a result of growing the array.
|
a PangoTabArray |
|
new size of the array |
void pango_tab_array_set_tab (PangoTabArray *tab_array, gint tab_index, PangoTabAlign alignment, gint location);
Sets the alignment and location of a tab stop.
alignment must always be PANGO_TAB_LEFT in the current
implementation.
|
a PangoTabArray |
|
the index of a tab stop |
|
tab alignment |
|
tab location in Pango units |
void pango_tab_array_get_tab (PangoTabArray *tab_array, gint tab_index, PangoTabAlign *alignment, gint *location);
Gets the alignment and position of a tab stop.
|
a PangoTabArray |
|
tab stop index |
|
location to store alignment, or NULL
|
|
location to store tab position, or NULL
|
void pango_tab_array_get_tabs (PangoTabArray *tab_array, PangoTabAlign **alignments, gint **locations);
If non-NULL, alignments and locations are filled with allocated
arrays of length pango_tab_array_get_size(). You must free the
returned array.
|
a PangoTabArray |
|
location to store an array of tab stop alignments, or NULL
|
|
location to store an array of tab positions, or NULL
|
gboolean pango_tab_array_get_positions_in_pixels (PangoTabArray *tab_array);
Returns TRUE if the tab positions are in pixels, FALSE if they are
in Pango units.
|
a PangoTabArray |
Returns : |
whether positions are in pixels. |
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
enum PangoAttrType; #define PANGO_TYPE_ATTR_TYPE PangoAttrClass; PangoAttribute; #define PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING #define PANGO_ATTR_INDEX_TO_TEXT_END PangoAttrString; PangoAttrLanguage; PangoAttrColor; PangoAttrInt; PangoAttrFloat; PangoAttrFontDesc; PangoAttrShape; PangoAttrSize; gboolean pango_parse_markup (const char *markup_text, int length, gunichar accel_marker, PangoAttrList **attr_list, char **text, gunichar *accel_char, GError **error); PangoAttrType pango_attr_type_register (const gchar *name); const char * pango_attr_type_get_name (PangoAttrType type); void pango_attribute_init (PangoAttribute *attr, const PangoAttrClass *klass); PangoAttribute * pango_attribute_copy (const PangoAttribute *attr); gboolean pango_attribute_equal (const PangoAttribute *attr1, const PangoAttribute *attr2); void pango_attribute_destroy (PangoAttribute *attr); PangoAttribute * pango_attr_language_new (PangoLanguage *language); PangoAttribute * pango_attr_family_new (const char *family); PangoAttribute * pango_attr_style_new (PangoStyle style); PangoAttribute * pango_attr_variant_new (PangoVariant variant); PangoAttribute * pango_attr_stretch_new (PangoStretch stretch); PangoAttribute * pango_attr_weight_new (PangoWeight weight); PangoAttribute * pango_attr_size_new (int size); PangoAttribute * pango_attr_size_new_absolute (int size); PangoAttribute * pango_attr_font_desc_new (const PangoFontDescription *desc); PangoAttribute * pango_attr_foreground_new (guint16 red, guint16 green, guint16 blue); PangoAttribute * pango_attr_background_new (guint16 red, guint16 green, guint16 blue); PangoAttribute * pango_attr_strikethrough_new (gboolean strikethrough); PangoAttribute * pango_attr_strikethrough_color_new (guint16 red, guint16 green, guint16 blue); PangoAttribute * pango_attr_underline_new (PangoUnderline underline); PangoAttribute * pango_attr_underline_color_new (guint16 red, guint16 green, guint16 blue); enum PangoUnderline; #define PANGO_TYPE_UNDERLINE PangoAttribute * pango_attr_shape_new (const PangoRectangle *ink_rect, const PangoRectangle *logical_rect); PangoAttribute * pango_attr_shape_new_with_data (const PangoRectangle *ink_rect, const PangoRectangle *logical_rect, gpointer data, PangoAttrDataCopyFunc copy_func, GDestroyNotify destroy_func); gpointer (*PangoAttrDataCopyFunc) (gconstpointer data); PangoAttribute * pango_attr_scale_new (double scale_factor); #define PANGO_SCALE_XX_SMALL #define PANGO_SCALE_X_SMALL #define PANGO_SCALE_SMALL #define PANGO_SCALE_MEDIUM #define PANGO_SCALE_LARGE #define PANGO_SCALE_X_LARGE #define PANGO_SCALE_XX_LARGE PangoAttribute * pango_attr_rise_new (int rise); PangoAttribute * pango_attr_letter_spacing_new (int letter_spacing); PangoAttribute * pango_attr_fallback_new (gboolean enable_fallback); PangoAttribute * pango_attr_gravity_new (PangoGravity gravity); PangoAttribute * pango_attr_gravity_hint_new (PangoGravityHint hint); PangoColor; #define PANGO_TYPE_COLOR gboolean pango_color_parse (PangoColor *color, const char *spec); PangoColor * pango_color_copy (const PangoColor *src); void pango_color_free (PangoColor *color); gchar * pango_color_to_string (const PangoColor *color); PangoAttrList; #define PANGO_TYPE_ATTR_LIST PangoAttrList * pango_attr_list_new (void); PangoAttrList * pango_attr_list_ref (PangoAttrList *list); void pango_attr_list_unref (PangoAttrList *list); PangoAttrList * pango_attr_list_copy (PangoAttrList *list); void pango_attr_list_insert (PangoAttrList *list, PangoAttribute *attr); void pango_attr_list_insert_before (PangoAttrList *list, PangoAttribute *attr); void pango_attr_list_change (PangoAttrList *list, PangoAttribute *attr); void pango_attr_list_splice (PangoAttrList *list, PangoAttrList *other, gint pos, gint len); PangoAttrList * pango_attr_list_filter (PangoAttrList *list, PangoAttrFilterFunc func, gpointer data); gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute, gpointer data); PangoAttrIterator * pango_attr_list_get_iterator (PangoAttrList *list); PangoAttrIterator; PangoAttrIterator * pango_attr_iterator_copy (PangoAttrIterator *iterator); gboolean pango_attr_iterator_next (PangoAttrIterator *iterator); void pango_attr_iterator_range (PangoAttrIterator *iterator, gint *start, gint *end); PangoAttribute * pango_attr_iterator_get (PangoAttrIterator *iterator, PangoAttrType type); void pango_attr_iterator_get_font (PangoAttrIterator *iterator, PangoFontDescription *desc, PangoLanguage **language, GSList **extra_attrs); GSList * pango_attr_iterator_get_attrs (PangoAttrIterator *iterator); void pango_attr_iterator_destroy (PangoAttrIterator *iterator);
Attributed text is used in a number of places in Pango. It is used as the input to the itemization process and also when creating a PangoLayout. The data types and functions in this section are used to represent and manipulate sets of attributes applied to a portion of text.
typedef enum
{
PANGO_ATTR_INVALID, /* 0 is an invalid attribute type */
PANGO_ATTR_LANGUAGE, /* PangoAttrLanguage */
PANGO_ATTR_FAMILY, /* PangoAttrString */
PANGO_ATTR_STYLE, /* PangoAttrInt */
PANGO_ATTR_WEIGHT, /* PangoAttrInt */
PANGO_ATTR_VARIANT, /* PangoAttrInt */
PANGO_ATTR_STRETCH, /* PangoAttrInt */
PANGO_ATTR_SIZE, /* PangoAttrSize */
PANGO_ATTR_FONT_DESC, /* PangoAttrFontDesc */
PANGO_ATTR_FOREGROUND, /* PangoAttrColor */
PANGO_ATTR_BACKGROUND, /* PangoAttrColor */
PANGO_ATTR_UNDERLINE, /* PangoAttrInt */
PANGO_ATTR_STRIKETHROUGH, /* PangoAttrInt */
PANGO_ATTR_RISE, /* PangoAttrInt */
PANGO_ATTR_SHAPE, /* PangoAttrShape */
PANGO_ATTR_SCALE, /* PangoAttrFloat */
PANGO_ATTR_FALLBACK, /* PangoAttrInt */
PANGO_ATTR_LETTER_SPACING, /* PangoAttrInt */
PANGO_ATTR_UNDERLINE_COLOR, /* PangoAttrColor */
PANGO_ATTR_STRIKETHROUGH_COLOR,/* PangoAttrColor */
PANGO_ATTR_ABSOLUTE_SIZE, /* PangoAttrSize */
PANGO_ATTR_GRAVITY, /* PangoAttrInt */
PANGO_ATTR_GRAVITY_HINT /* PangoAttrInt */
} PangoAttrType;
The PangoAttrType
distinguishes between different types of attributes. Along with the
predefined values, it is possible to allocate additional values
for custom attributes using pango_attr_type_register(). The predefined
values are given below. The type of structure used to store the
attribute is listed in parentheses after the description.
| does not happen | |
| language (PangoAttrLanguage) | |
| font family name list (PangoAttrString) | |
| font slant style (PangoAttrInt) | |
| font weight (PangoAttrInt) | |
| font variant (normal or small caps) (PangoAttrInt) | |
| font stretch (PangoAttrInt) | |
font size in points scaled by PANGO_SCALE (PangoAttrInt)
|
|
| font description (PangoAttrFontDesc) | |
| foreground color (PangoAttrColor) | |
| background color (PangoAttrColor) | |
| whether the text has an underline (PangoAttrInt) | |
| whether the text is struck-through (PangoAttrInt) | |
| baseline displacement (PangoAttrInt) | |
| shape (PangoAttrShape) | |
| font size scale factor (PangoAttrFloat) | |
| whether fallback is enabled (PangoAttrInt) | |
| letter spacing (PangoAttrInt) | |
| underline color (PangoAttrColor) | |
| strikethrough color (PangoAttrColor) | |
font size in pixels scaled by PANGO_SCALE (PangoAttrInt)
|
|
| base text gravity (PangoAttrInt) | |
| gravity hint (PangoAttrInt) |
#define PANGO_TYPE_ATTR_TYPE (pango_attr_type_get_type())
The GObject type for PangoAttrType.
typedef struct {
PangoAttrType type;
PangoAttribute * (*copy) (const PangoAttribute *attr);
void (*destroy) (PangoAttribute *attr);
gboolean (*equal) (const PangoAttribute *attr1, const PangoAttribute *attr2);
} PangoAttrClass;
The PangoAttrClass structure stores the type and operations for a particular type of attribute. The functions in this structure should not be called directly. Instead, one should use the wrapper functions provided for PangoAttribute.
PangoAttrType |
the type ID for this attribute |
|
function to duplicate an attribute of this type (see pango_attribute_copy())
|
|
function to free an attribute of this type (see pango_attribute_destroy())
|
|
function to check two attributes of this type for equality (see pango_attribute_equal())
|
typedef struct {
const PangoAttrClass *klass;
guint start_index; /* in bytes */
guint end_index; /* in bytes. The character at this index is not included */
} PangoAttribute;
The PangoAttribute structure represents the common portions of all
attributes. Particular types of attributes include this structure
as their initial portion. The common portion of the attribute holds
the range to which the value in the type-specific part of the attribute
applies and should be initialized using pango_attribute_init().
By default an attribute will have an all-inclusive range of [0,G_MAXUINT].
const PangoAttrClass * |
the class structure holding information about the type of the attribute |
guint |
the start index of the range (in bytes). |
guint |
end index of the range (in bytes). The character at this index is not included in the range. |
#define PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING 0
This value can be used to set the start_index member of a PangoAttribute such that the attribute covers from the beginning of the text.
Since: 1.24#define PANGO_ATTR_INDEX_TO_TEXT_END G_MAXUINT
This value can be used to set the end_index member of a PangoAttribute such that the attribute covers to the end of the text.
Since: 1.24typedef struct {
PangoAttribute attr;
char *value;
} PangoAttrString;
The PangoAttrString structure is used to represent attributes with a string value.
PangoAttribute |
the common portion of the attribute |
char * |
the string which is the value of the attribute |
typedef struct {
PangoAttribute attr;
PangoLanguage *value;
} PangoAttrLanguage;
The PangoAttrLanguage structure is used to represent attributes that are languages.
PangoAttribute |
the common portion of the attribute |
PangoLanguage * |
the PangoLanguage which is the value of the attribute |
typedef struct {
PangoAttribute attr;
PangoColor color;
} PangoAttrColor;
The PangoAttrColor structure is used to represent attributes that are colors.
PangoAttribute |
the common portion of the attribute |
PangoColor |
the PangoColor which is the value of the attribute |
typedef struct {
PangoAttribute attr;
int value;
} PangoAttrInt;
The PangoAttrInt structure is used to represent attributes with an integer or enumeration value.
PangoAttribute |
the common portion of the attribute |
int |
the value of the attribute |
typedef struct {
PangoAttribute attr;
double value;
} PangoAttrFloat;
The PangoAttrFloat structure is used to represent attributes with a float or double value.
PangoAttribute |
the common portion of the attribute |
double |
the value of the attribute |
typedef struct {
PangoAttribute attr;
PangoFontDescription *desc;
} PangoAttrFontDesc;
The PangoAttrFontDesc structure is used to store an attribute that sets all aspects of the font description at once.
PangoAttribute |
the common portion of the attribute |
PangoFontDescription * |
the font description which is the value of this attribute |
typedef struct {
PangoAttribute attr;
PangoRectangle ink_rect;
PangoRectangle logical_rect;
gpointer data;
PangoAttrDataCopyFunc copy_func;
GDestroyNotify destroy_func;
} PangoAttrShape;
The PangoAttrShape structure is used to represent attributes which impose shape restrictions.
PangoAttribute |
the common portion of the attribute |
PangoRectangle |
the ink rectangle to restrict to |
PangoRectangle |
the logical rectangle to restrict to |
gpointer |
user data set (see pango_attr_shape_new_with_data())
|
PangoAttrDataCopyFunc |
copy function for the user data |
GDestroyNotify |
destroy function for the user data |
typedef struct {
PangoAttribute attr;
int size;
guint absolute : 1;
} PangoAttrSize;
The PangoAttrShape structure is used to represent attributes which set font size.
PangoAttribute |
the common portion of the attribute |
int |
size of font, in units of 1/PANGO_SCALE of a point (for
PANGO_ATTR_SIZE) or of a device uni (for PANGO_ATTR_ABSOLUTE_SIZE)
|
guint |
whether the font size is in device units or points.
This field is only present for compatibility with Pango-1.8.0
(PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will
be FALSE for PANGO_ATTR_SIZE and TRUE for PANGO_ATTR_ABSOLUTE_SIZE.
|
gboolean pango_parse_markup (const char *markup_text, int length, gunichar accel_marker, PangoAttrList **attr_list, char **text, gunichar *accel_char, GError **error);
Parses marked-up text (see markup format) to create a plain-text string and an attribute list.
If accel_marker is nonzero, the given character will mark the
character following it as an accelerator. For example, accel_marker
might be an ampersand or underscore. All characters marked
as an accelerator will receive a PANGO_UNDERLINE_LOW attribute,
and the first character so marked will be returned in accel_char.
Two accel_marker characters following each other produce a single
literal accel_marker character.
If any error happens, none of the output arguments are touched except
for error.
|
markup to parse (see markup format) |
|
length of markup_text, or -1 if nul-terminated
|
|
character that precedes an accelerator, or 0 for none |
|
address of return location for a PangoAttrList, or NULL
|
|
address of return location for text with tags stripped, or NULL
|
|
address of return location for accelerator char, or NULL
|
|
address of return location for errors, or NULL
|
Returns : |
FALSE if error is set, otherwise TRUE
|
PangoAttrType pango_attr_type_register (const gchar *name);
Allocate a new attribute type ID. The attribute type name can be accessed
later by using pango_attr_type_get_name().
|
an identifier for the type |
Returns : |
the new type ID. |
const char * pango_attr_type_get_name (PangoAttrType type);
Fetches the attribute type name passed in when registering the type using
pango_attr_type_register().
The returned value is an interned string (see g_intern_string() for what
that means) that should not be modified or freed.
|
an attribute type ID to fetch the name for |
Returns : |
the type ID name (which may be NULL), or NULL if type is
a built-in Pango attribute type or invalid.
|
Since 1.22
void pango_attribute_init (PangoAttribute *attr, const PangoAttrClass *klass);
Initializes attr's klass to klass,
it's start_index to PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING
and end_index to PANGO_ATTR_INDEX_TO_TEXT_END
such that the attribute applies
to the entire text by default.
|
a PangoAttribute |
|
a PangoAttributeClass |
Since 1.20
PangoAttribute * pango_attribute_copy (const PangoAttribute *attr);
Make a copy of an attribute.
|
a PangoAttribute |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
gboolean pango_attribute_equal (const PangoAttribute *attr1, const PangoAttribute *attr2);
Compare two attributes for equality. This compares only the actual value of the two attributes and not the ranges that the attributes apply to.
|
a PangoAttribute |
|
another PangoAttribute |
Returns : |
TRUE if the two attributes have the same value.
|
void pango_attribute_destroy (PangoAttribute *attr);
Destroy a PangoAttribute and free all associated memory.
|
a PangoAttribute. |
PangoAttribute * pango_attr_language_new (PangoLanguage *language);
Create a new language tag attribute.
|
language tag |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_family_new (const char *family);
Create a new font family attribute.
|
the family or comma separated list of families |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_style_new (PangoStyle style);
Create a new font slant style attribute.
|
the slant style |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_variant_new (PangoVariant variant);
Create a new font variant attribute (normal or small caps)
|
the variant |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_stretch_new (PangoStretch stretch);
Create a new font stretch attribute
|
the stretch |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_weight_new (PangoWeight weight);
Create a new font weight attribute.
|
the weight |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_size_new (int size);
Create a new font-size attribute in fractional points.
|
the font size, in PANGO_SCALEths of a point.
|
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_size_new_absolute (int size);
Create a new font-size attribute in device units.
|
the font size, in PANGO_SCALEths of a device unit.
|
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
Since 1.8
PangoAttribute * pango_attr_font_desc_new (const PangoFontDescription *desc);
Create a new font description attribute. This attribute allows setting family, style, weight, variant, stretch, and size simultaneously.
|
the font description |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_foreground_new (guint16 red, guint16 green, guint16 blue);
Create a new foreground color attribute.
|
the red value (ranging from 0 to 65535) |
|
the green value |
|
the blue value |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_background_new (guint16 red, guint16 green, guint16 blue);
Create a new background color attribute.
|
the red value (ranging from 0 to 65535) |
|
the green value |
|
the blue value |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_strikethrough_new (gboolean strikethrough);
Create a new strike-through attribute.
|
TRUE if the text should be struck-through.
|
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_strikethrough_color_new (guint16 red, guint16 green, guint16 blue);
Create a new strikethrough color attribute. This attribute modifies the color of strikethrough lines. If not set, strikethrough lines will use the foreground color.
|
the red value (ranging from 0 to 65535) |
|
the green value |
|
the blue value |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
Since 1.8
PangoAttribute * pango_attr_underline_new (PangoUnderline underline);
Create a new underline-style attribute.
|
the underline style. |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_underline_color_new (guint16 red, guint16 green, guint16 blue);
Create a new underline color attribute. This attribute modifies the color of underlines. If not set, underlines will use the foreground color.
|
the red value (ranging from 0 to 65535) |
|
the green value |
|
the blue value |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
Since 1.8
typedef enum {
PANGO_UNDERLINE_NONE,
PANGO_UNDERLINE_SINGLE,
PANGO_UNDERLINE_DOUBLE,
PANGO_UNDERLINE_LOW,
PANGO_UNDERLINE_ERROR
} PangoUnderline;
the PangoUnderline enumeration is used to specify whether text should be underlined, and if so, the type of underlining.
| no underline should be drawn | |
| a single underline should be drawn | |
| a double underline should be drawn | |
a single underline should be drawn at a position
beneath the ink extents of the text being
underlined. This should be used only for underlining
single characters, such as for keyboard
accelerators. PANGO_UNDERLINE_SINGLE should
be used for extended portions of text.
|
|
| a wavy underline should be drawn below. This underline is typically used to indicate an error such as a possilble mispelling; in some cases a contrasting color may automatically be used. This type of underlining is available since Pango 1.4. |
#define PANGO_TYPE_UNDERLINE (pango_underline_get_type())
The GObject type for PangoUnderline.
PangoAttribute * pango_attr_shape_new (const PangoRectangle *ink_rect, const PangoRectangle *logical_rect);
Create a new shape attribute. A shape is used to impose a particular ink and logical rectangle on the result of shaping a particular glyph. This might be used, for instance, for embedding a picture or a widget inside a PangoLayout.
|
ink rectangle to assign to each character |
|
logical rectangle to assign to each character |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_shape_new_with_data (const PangoRectangle *ink_rect, const PangoRectangle *logical_rect, gpointer data, PangoAttrDataCopyFunc copy_func, GDestroyNotify destroy_func);
Like pango_attr_shape_new(), but a user data pointer is also
provided; this pointer can be accessed when later
rendering the glyph.
|
ink rectangle to assign to each character |
|
logical rectangle to assign to each character |
|
user data pointer |
|
function to copy data when the attribute
is copied. If NULL, data is simply copied
as a pointer.
|
|
function to free data when the attribute
is freed, or NULL
|
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
Since 1.8
gpointer (*PangoAttrDataCopyFunc) (gconstpointer data);
A copy function passed to attribute new functions that take user data.
|
the user data |
Returns : |
a new copy of data.
|
PangoAttribute * pango_attr_scale_new (double scale_factor);
Create a new font size scale attribute. The base font for the
affected text will have its size multiplied by scale_factor.
|
factor to scale the font |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
#define PANGO_SCALE_XX_SMALL ((double)0.5787037037037)
The scale factor for three shrinking steps (1 / (1.2 * 1.2 * 1.2)).
#define PANGO_SCALE_X_SMALL ((double)0.6444444444444)
The scale factor for two shrinking steps (1 / (1.2 * 1.2)).
#define PANGO_SCALE_SMALL ((double)0.8333333333333)
The scale factor for one shrinking step (1 / 1.2).
#define PANGO_SCALE_LARGE ((double)1.2)
The scale factor for one magnification step (1.2).
#define PANGO_SCALE_X_LARGE ((double)1.4399999999999)
The scale factor for two magnification steps (1.2 * 1.2).
#define PANGO_SCALE_XX_LARGE ((double)1.728)
The scale factor for three magnification steps (1.2 * 1.2 * 1.2).
PangoAttribute * pango_attr_rise_new (int rise);
Create a new baseline displacement attribute.
|
the amount that the text should be displaced vertically, in Pango units. Positive values displace the text upwards. |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
PangoAttribute * pango_attr_letter_spacing_new (int letter_spacing);
Create a new letter-spacing attribute.
|
amount of extra space to add between graphemes of the text, in Pango units. |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
Since 1.6
PangoAttribute * pango_attr_fallback_new (gboolean enable_fallback);
Create a new font fallback attribute.
If fallback is disabled, characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text.
|
TRUE if we should fall back on other fonts
for characters the active font is missing.
|
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
Since 1.4
PangoAttribute * pango_attr_gravity_new (PangoGravity gravity);
Create a new gravity attribute.
|
the gravity value; should not be PANGO_GRAVITY_AUTO.
|
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
Since 1.16
PangoAttribute * pango_attr_gravity_hint_new (PangoGravityHint hint);
Create a new gravity hint attribute.
|
the gravity hint value. |
Returns : |
the newly allocated PangoAttribute, which should be
freed with pango_attribute_destroy().
|
Since 1.16
typedef struct {
guint16 red;
guint16 green;
guint16 blue;
} PangoColor;
The PangoColor structure is used to represent a color in an uncalibrated RGB color-space.
guint16 |
The red component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity. |
guint16 |
The green component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity. |
guint16 |
The blue component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity. |
gboolean pango_color_parse (PangoColor *color, const char *spec);
Fill in the fields of a color from a string specification. The
string can either one of a large set of standard names. (Taken
from the X11 rgb.txt file), or it can be a hex value in the
form '#rgb' '#rrggbb' '#rrrgggbbb' or '#rrrrggggbbbb' where
'r', 'g' and 'b' are hex digits of the red, green, and blue
components of the color, respectively. (White in the four
forms is '#fff' '#ffffff' '#fffffffff' and '#ffffffffffff')
|
a PangoColor structure in which to store the result, or NULL
|
|
a string specifying the new color |
Returns : |
TRUE if parsing of the specifier succeeded,
otherwise false.
|
PangoColor * pango_color_copy (const PangoColor *src);
Creates a copy of src, which should be freed with
pango_color_free(). Primarily used by language bindings,
not that useful otherwise (since colors can just be copied
by assignment in C).
|
color to copy, may be NULL
|
Returns : |
the newly allocated PangoColor, which should
be freed with pango_color_free(), or NULL
if src was NULL.
|
void pango_color_free (PangoColor *color);
Frees a color allocated by pango_color_copy().
|
an allocated PangoColor, may be NULL
|
gchar * pango_color_to_string (const PangoColor *color);
Returns a textual specification of color in the hexadecimal form
#rrrrggggbbbb, where r,
g and b are hex digits representing
the red, green, and blue components respectively.
|
a PangoColor |
Returns : |
a newly-allocated text string that must be freed with g_free().
|
Since 1.16
typedef struct _PangoAttrList PangoAttrList;
The PangoAttrList structure represents a list of attributes
that apply to a section of text. The attributes are, in general,
allowed to overlap in an arbitrary fashion, however, if the
attributes are manipulated only through pango_attr_list_change(),
the overlap between properties will meet stricter criteria.
Since the PangoAttrList structure is stored as a linear list, it is not suitable for storing attributes for large amounts of text. In general, you should not use a single PangoAttrList for more than one paragraph of text.
#define PANGO_TYPE_ATTR_LIST pango_attr_list_get_type ()
The GObject type for PangoAttrList.
PangoAttrList * pango_attr_list_new (void);
Create a new empty attribute list with a reference count of one.
Returns : |
the newly allocated PangoAttrList, which should
be freed with pango_attr_list_unref().
|
PangoAttrList * pango_attr_list_ref (PangoAttrList *list);
Increase the reference count of the given attribute list by one.
|
a PangoAttrList, may be NULL
|
Returns : |
The attribute list passed in |
Since 1.10
void pango_attr_list_unref (PangoAttrList *list);
Decrease the reference count of the given attribute list by one. If the result is zero, free the attribute list and the attributes it contains.
|
a PangoAttrList, may be NULL
|
PangoAttrList * pango_attr_list_copy (PangoAttrList *list);
Copy list and return an identical new list.
|
a PangoAttrList, may be NULL
|
Returns : |
the newly allocated PangoAttrList, with a
reference count of one, which should
be freed with pango_attr_list_unref().
Returns NULL if list was NULL.
|
void pango_attr_list_insert (PangoAttrList *list, PangoAttribute *attr);
Insert the given attribute into the PangoAttrList. It will
be inserted after all other attributes with a matching
start_index.
|
a PangoAttrList |
|
the attribute to insert. Ownership of this value is assumed by the list. |
void pango_attr_list_insert_before (PangoAttrList *list, PangoAttribute *attr);
Insert the given attribute into the PangoAttrList. It will
be inserted before all other attributes with a matching
start_index.
|
a PangoAttrList |
|
the attribute to insert. Ownership of this value is assumed by the list. |
void pango_attr_list_change (PangoAttrList *list, PangoAttribute *attr);
Insert the given attribute into the PangoAttrList. It will replace any attributes of the same type on that segment and be merged with any adjoining attributes that are identical.
This function is slower than pango_attr_list_insert() for
creating a attribute list in order (potentially much slower
for large lists). However, pango_attr_list_insert() is not
suitable for continually changing a set of attributes
since it never removes or combines existing attributes.
|
a PangoAttrList |
|
the attribute to insert. Ownership of this value is assumed by the list. |
void pango_attr_list_splice (PangoAttrList *list, PangoAttrList *other, gint pos, gint len);
This function opens up a hole in list, fills it in with attributes from
the left, and then merges other on top of the hole.
This operation is equivalent to stretching every attribute
that applies at position pos in list by an amount len,
and then calling pango_attr_list_change() with a copy
of each attribute in other in sequence (offset in position by pos).
This operation proves useful for, for instance, inserting a pre-edit string in the middle of an edit buffer.
|
a PangoAttrList |
|
another PangoAttrList |
|
the position in list at which to insert other
|
|
the length of the spliced segment. (Note that this
must be specified since the attributes in other
may only be present at some subsection of this range)
|
PangoAttrList * pango_attr_list_filter (PangoAttrList *list, PangoAttrFilterFunc func, gpointer data);
Given a PangoAttrList and callback function, removes any elements
of list for which func returns TRUE and inserts them into
a new list.
|
a PangoAttrList |
|
callback function; returns TRUE if an attribute
should be filtered out.
|
|
Data to be passed to func
|
Returns : |
the new PangoAttrList or NULL if
no attributes of the given types were found.
|
Since 1.2
gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute, gpointer data);
A predicate function used by pango_attr_list_filter()
to filter out a subset of attributes for a list.
|
a PangoAttribute |
|
callback data passed to pango_attr_list_filter()
|
Returns : |
%TRUE if the attribute should be filtered out |
PangoAttrIterator * pango_attr_list_get_iterator (PangoAttrList *list);
Create a iterator initialized to the beginning of the list.
list must not be modified until this iterator is freed.
|
a PangoAttrList |
Returns : |
the newly allocated PangoAttrIterator, which should
be freed with pango_attr_iterator_destroy().
|
typedef struct _PangoAttrIterator PangoAttrIterator;
The PangoAttrIterator structure is used to represent an
iterator through a PangoAttrList. A new iterator is created
with pango_attr_list_get_iterator(). Once the iterator
is created, it can be advanced through the style changes
in the text using pango_attr_iterator_next(). At each
style change, the range of the current style segment and the
attributes currently in effect can be queried.
PangoAttrIterator * pango_attr_iterator_copy (PangoAttrIterator *iterator);
Copy a PangoAttrIterator
|
a PangoAttrIterator. |
Returns : |
the newly allocated PangoAttrIterator, which should
be freed with pango_attr_iterator_destroy().
|
gboolean pango_attr_iterator_next (PangoAttrIterator *iterator);
Advance the iterator until the next change of style.
|
a PangoAttrIterator |
Returns : |
FALSE if the iterator is at the end of the list, otherwise TRUE
|
void pango_attr_iterator_range (PangoAttrIterator *iterator, gint *start, gint *end);
Get the range of the current segment. Note that the
stored return values are signed, not unsigned like
the values in PangoAttribute. To deal with this API
oversight, stored return values that wouldn't fit into
a signed integer are clamped to G_MAXINT.
|
a PangoAttrIterator |
|
location to store the start of the range |
|
location to store the end of the range |
PangoAttribute * pango_attr_iterator_get (PangoAttrIterator *iterator, PangoAttrType type);
Find the current attribute of a particular type at the iterator location. When multiple attributes of the same type overlap, the attribute whose range starts closest to the current location is used.
|
a PangoAttrIterator |
|
the type of attribute to find. |
Returns : |
the current attribute of the given type, or NULL
if no attribute of that type applies to the current
location.
|
void pango_attr_iterator_get_font (PangoAttrIterator *iterator, PangoFontDescription *desc, PangoLanguage **language, GSList **extra_attrs);
Get the font and other attributes at the current iterator position.
|
a PangoAttrIterator |
|
a PangoFontDescription to fill in with the current values.
The family name in this structure will be set using
pango_font_description_set_family_static() using values from
an attribute in the PangoAttrList associated with the iterator,
so if you plan to keep it around, you must call:
pango_font_description_set_family (desc, pango_font_description_get_family (desc)).
|
|
if non-NULL, location to store language tag for item, or NULL
if none is found.
|
|
element type Pango.Attribute): (transfer full. element type Pango.Attribute): (transfer full. |
GSList * pango_attr_iterator_get_attrs (PangoAttrIterator *iterator);
Gets a list of all attributes at the current position of the iterator.
|
a PangoAttrIterator |
Returns : |
element-type Pango.Attribute): (transfer full. element-type Pango.Attribute): (transfer full. |
Since 1.2
void pango_attr_iterator_destroy (PangoAttrIterator *iterator);
Destroy a PangoAttrIterator and free all associated memory.
|
a PangoAttrIterator. |
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
PangoEngineLang;
PangoEngineLangClass;
#define PANGO_ENGINE_TYPE_LANG
#define PANGO_ENGINE_LANG_DEFINE_TYPE (name, prefix, class_init, instance_init)
The language engines are rendering-system independent
engines that determine line, word, and character breaks for character strings.
These engines are used in pango_break().
typedef struct _PangoEngineLang 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.
typedef struct {
void (*script_break) (PangoEngineLang *engine,
const char *text,
int len,
PangoAnalysis *analysis,
PangoLogAttr *attrs,
int attrs_len);
} PangoEngineLangClass;
Class structure for PangoEngineLang
|
Provides a custom implementation of pango_break().
If NULL, pango_default_break() is used instead. If not NULL, for
Pango versions before 1.16 (module interface version before 1.6.0),
this was called instead of pango_default_break(), but in newer versions,
pango_default_break() is always called and this is called after that to
allow tailoring the breaking results.
|
#define PANGO_ENGINE_TYPE_LANG "PangoEngineLang"
A string constant defining the engine type for language engines. These engines derive from PangoEngineLang.
#define PANGO_ENGINE_LANG_DEFINE_TYPE(name, prefix, class_init, instance_init)
Outputs the necessary code for GObject type registration for a PangoEngineLang class defined in a module. Two static symbols are defined.
static GTypeprefix_type; static voidprefix_register_type (GTypeModule module);
The prefix, _register_type()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:
PangoEngine *engine = g_object_new (prefix_type, NULL);
|
|
Pango Reference Manual | |
|---|
|
|
|
Pango Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
Deprecated X font backendDeprecated X font backend — Font handling and rendering with the deprecated X font backend |
#define PANGO_RENDER_TYPE_X PangoContext * pango_x_get_context (Display *display); void pango_x_context_set_funcs (PangoContext *context, PangoGetGCFunc get_gc_func, PangoFreeGCFunc free_gc_func); GC (*PangoGetGCFunc) (PangoContext *context, PangoColor *color, GC base_gc); void (*PangoFreeGCFunc) (PangoContext *context, GC gc); void pango_x_render (Display *display, Drawable d, GC gc, PangoFont *font, PangoGlyphString *glyphs, gint x, gint y); void pango_x_render_layout_line (Display *display, Drawable drawable, GC gc, PangoLayoutLine *line, int x, int y); void pango_x_render_layout (Display *display, Drawable drawable, GC gc, PangoLayout *layout, int x, int y); typedef PangoXSubfont; #define PANGO_X_MAKE_GLYPH (subfont,index_) #define PANGO_X_GLYPH_SUBFONT (glyph) #define PANGO_X_GLYPH_INDEX (glyph) PangoFont * pango_x_load_font (Display *display, const gchar *spec); PangoGlyph pango_x_get_unknown_glyph (PangoFont *font); gboolean pango_x_has_glyph (PangoFont *font, PangoGlyph glyph); int pango_x_list_subfonts (PangoFont *font, char **charsets, int n_charsets, PangoXSubfont **subfont_ids, int **subfont_charsets); PangoFontMap * pango_x_font_map_for_display (Display *display); void pango_x_shutdown_display (Display *display); PangoXFontCache * pango_x_font_map_get_font_cache (PangoFontMap *font_map); char * pango_x_font_subfont_xlfd (PangoFont *font, PangoXSubfont subfont_id); gboolean pango_x_find_first_subfont (PangoFont *font, char **charsets, int n_charsets, PangoXSubfont *rfont); PangoGlyph pango_x_font_get_unknown_glyph (PangoFont *font, gunichar wc); gboolean pango_x_apply_ligatures (PangoFont *font, PangoXSubfont subfont, gunichar **glyphs, int *n_glyphs, int **clusters); void pango_x_fallback_shape (PangoFont *font, PangoGlyphString *glyphs, const char *text, int n_chars); PangoXFontCache; PangoXFontCache * pango_x_font_cache_new (Display *display); void pango_x_font_cache_free (PangoXFontCache *cache); XFontStruct * pango_x_font_cache_load (PangoXFontCache *cache, const char *xlfd); void pango_x_font_cache_unload (PangoXFontCache *cache, XFontStruct *fs);
The functions and macros in this section are for use with the old X font backend which used server-side bitmap fonts. This font backend is no longer supported, and attempts to use it will produce unpredictable results. Use the Xft or Cairo backend instead.
#define PANGO_RENDER_TYPE_X "PangoRenderX"
PANGO_RENDER_TYPE_X is deprecated and should not be used in newly-written code.
A string constant identifying the X renderer. The associated quark (see
g_quark_from_string()) is used to identify the renderer in pango_find_map().
PangoContext * pango_x_get_context (Display *display);
pango_x_get_context has been deprecated since version 1.22 and should not be used in newly-written code. Use pango_x_font_map_for_display() followed by
pango_font_map_create_context() instead.
Retrieves a PangoContext appropriate for rendering with X fonts on the given display.
|
an X display (As returned by XOpenDisplay().)
|
Returns : |
the new PangoContext. |
void pango_x_context_set_funcs (PangoContext *context, PangoGetGCFunc get_gc_func, PangoFreeGCFunc free_gc_func);
pango_x_context_set_funcs is deprecated and should not be used in newly-written code.
Sets the functions that will be used to get GC's in various colors when rendering layouts with this context.
|
a PangoContext. |
|
function called to create a new GC for a given color. |
|
function called to free a GC created with get_gc_func.
|
GC (*PangoGetGCFunc) (PangoContext *context, PangoColor *color, GC base_gc);
PangoGetGCFunc is deprecated and should not be used in newly-written code.
Specifies the type of the function used to create a new GC for a given color.
|
a PangoContext. |
|
the color to create a new GC for. |
|
the GC to base the new GC on. |
Returns : |
the new GC. |
void (*PangoFreeGCFunc) (PangoContext *context, GC gc);
PangoFreeGCFunc is deprecated and should not be used in newly-written code.
Specifies the type of the function used to free a GC created with the corresponding PangoGetGCFunc function.
|
a PangoContext. |
|
the GC to free. |
void pango_x_render (Display *display,
Drawable d,
GC gc,
PangoFont *font,
PangoGlyphString *glyphs,
gint x,
gint y);
pango_x_render is deprecated and should not be used in newly-written code.
Renders a PangoGlyphString onto an X drawable.
|
the X display. |
|
the drawable on which to draw string. |
|
the graphics context. |
|
the font in which to draw the string. |
|
the glyph string to draw. |
|
the x position of start of string (in pixels). |
|
the y position of baseline (in pixels). |
void pango_x_render_layout_line (Display *display,
Drawable drawable,
GC gc,
PangoLayoutLine *line,
int x,
int y);
pango_x_render_layout_line is deprecated and should not be used in newly-written code.
Renders a PangoLayoutLine onto an X drawable.
|
the X display. |
|
the drawable on which to draw. |
|
GC to use for uncolored drawing. |
|
a PangoLayoutLine. |
|
the x position of start of string (in pixels). |
|
the y position of baseline (in pixels). |
void pango_x_render_layout (Display *display,
Drawable drawable,
GC gc,
PangoLayout *layout,
int x,
int y);
pango_x_render_layout is deprecated and should not be used in newly-written code.
Renders a PangoLayout onto an X drawable.
|
the X display. |
|
the drawable on which to draw. |
|
GC to use for uncolored drawing. |
|
a PangoLayout. |
|
the x position of the left of the layout (in pixels). |
|
the y position of the top of the layout (in pixels). |
typedef guint16 PangoXSubfont;
PangoXSubfont is deprecated and should not be used in newly-written code.
The PangoXSubFont type is an integer ID that identifies one particular X font within the fonts referenced in a PangoFont.
#define PANGO_X_MAKE_GLYPH(subfont,index_) ((subfont)<<16 | (index_))
PANGO_X_MAKE_GLYPH is deprecated and should not be used in newly-written code.
Make a glyph index from a PangoXSubFont index and a index of a character with the corresponding X font.
|
a PangoXSubfont index |
|
the index of a character within an X font. |
#define PANGO_X_GLYPH_SUBFONT(glyph) ((glyph)>>16)
PANGO_X_GLYPH_SUBFONT is deprecated and should not be used in newly-written code.
Extract the subfont index from a glyph index.
|
a PangoGlyphIndex |
#define PANGO_X_GLYPH_INDEX(glyph) ((glyph) & 0xffff)
PANGO_X_GLYPH_INDEX is deprecated and should not be used in newly-written code.
Extract the character index within the X font from a glyph index.
|
a PangoGlyphIndex |
PangoFont * pango_x_load_font (Display *display, const gchar *spec);
pango_x_load_font is deprecated and should not be used in newly-written code.
Loads up a logical font based on a "fontset" style text specification. This is not remotely useful (Pango API's generally work in terms of PangoFontDescription) and the result may not work correctly in all circumstances. Use of this function should be avoided.
|
the X display. |
|
a comma-separated list of XLFD's. |
Returns : |
a new PangoFont. |
PangoGlyph pango_x_get_unknown_glyph (PangoFont *font);
pango_x_get_unknown_glyph is deprecated and should not be used in newly-written code.
Returns the index of a glyph suitable for drawing unknown characters;
you should generally use PANGO_GET_UNKNOWN_GLYPH() instead,
since that may return a glyph that provides a better representation
of a particular char. (E.g., by showing hex digits, or a glyph
representative of a certain Unicode range.)
|
a PangoFont. |
Returns : |
a glyph index into font.
|
gboolean pango_x_has_glyph (PangoFont *font, PangoGlyph glyph);
pango_x_has_glyph is deprecated and should not be used in newly-written code.
Checks if the given glyph is present in a X font.
|
a PangoFont which must be from the X backend. |
|
the index of a glyph in the font. (Formed using the PANGO_X_MAKE_GLYPH macro) |
Returns : |
TRUE if the glyph is present.
|
int pango_x_list_subfonts (PangoFont *font, char **charsets, int n_charsets, PangoXSubfont **subfont_ids, int **subfont_charsets);
pango_x_list_subfonts is deprecated and should not be used in newly-written code.
Lists the subfonts of a given font. The result is ordered first by charset, and then within each charset, by the order of fonts in the font specification.
|
a PangoFont. |
|
the charsets to list subfonts for. |
|
the number of charsets in charsets.
|
|
location to store a pointer to an array of subfont IDs for each found subfont;
the result must be freed using g_free().
|
|
location to store a pointer to an array of subfont IDs for each found subfont;
the result must be freed using g_free().
|
Returns : |
length of the arrays stored in subfont_ids and
subfont_charsets.
|
PangoFontMap * pango_x_font_map_for_display (Display *display);
pango_x_font_map_for_display is deprecated and should not be used in newly-written code.
Returns a PangoXFontMap for display. Font maps are cached and should
not be freed. If the font map for a display is no longer needed, it can
be released with pango_x_shutdown_display().
|
an X Display. |
Returns : |
a PangoXFontMap for display.
|
void pango_x_shutdown_display (Display *display);
pango_x_shutdown_display is deprecated and should not be used in newly-written code.
Free cached resources for the given X display structure.
|
an X Display |
PangoXFontCache * pango_x_font_map_get_font_cache (PangoFontMap *font_map);
pango_x_font_map_get_font_cache is deprecated and should not be used in newly-written code.
Obtains the font cache associated with the given font map.
|
a PangoXFontMap. |
Returns : |
the PangoXFontCache of font_map.
|
char * pango_x_font_subfont_xlfd (PangoFont *font, PangoXSubfont subfont_id);
pango_x_font_subfont_xlfd is deprecated and should not be used in newly-written code.
Determines the X Logical Font Description for the specified subfont.
gboolean pango_x_find_first_subfont (PangoFont *font, char **charsets, int n_charsets, PangoXSubfont *rfont);
pango_x_find_first_subfont is deprecated and should not be used in newly-written code.
Looks for subfonts with the charset charset,
in font, and puts the first one in *rfont.
|
A PangoFont. |
|
An array of charsets. |
|
The number of charsets in charsets.
|
|
A pointer to a PangoXSubfont. |
Returns : |
TRUE if *rfont now contains a font.
|
PangoGlyph pango_x_font_get_unknown_glyph (PangoFont *font, gunichar wc);
pango_x_font_get_unknown_glyph is deprecated and should not be used in newly-written code.
Returns the index of a glyph suitable for drawing wc as an
unknown character.
Use PANGO_GET_UNKNOWN_GLYPH() instead.
|
a PangoFont. |
|
the Unicode character for which a glyph is needed. |
Returns : |
a glyph index into font.
|
gboolean pango_x_apply_ligatures (PangoFont *font, PangoXSubfont subfont, gunichar **glyphs, int *n_glyphs, int **clusters);
pango_x_apply_ligatures is deprecated and should not be used in newly-written code.
Previously did subfont-specific ligation. Now a no-op.
|
unused |
|
unused |
|
unused |
|
unused |
|
unused |
Returns : |
FALSE, always.
|
void pango_x_fallback_shape (PangoFont *font, PangoGlyphString *glyphs, const char *text, int n_chars);
pango_x_fallback_shape is deprecated and should not be used in newly-written code.
This is a simple fallback shaper, that can be used
if no subfont that supports a given script is found.
For every character in text, it puts the unknown glyph.
|
A PangoFont. |
|
A pointer to a PangoGlyphString. |
|
UTF-8 string. |
|
Number of UTF-8 seqs in text.
|
typedef struct _PangoXFontCache PangoXFontCache;
PangoXFontCache is deprecated and should not be used in newly-written code.
A PangoXFontCache caches XFontStructs for a single display by their XLFD name.
PangoXFontCache * pango_x_font_cache_new (Display *display);
pango_x_font_cache_new is deprecated and should not be used in newly-written code.
Creates a font cache for the specified display.
|
an X display. |
Returns : |
The newly allocated PangoXFontCache, which should be
freed with pango_x_font_cache_free().
|
void pango_x_font_cache_free (PangoXFontCache *cache);
pango_x_font_cache_free is deprecated and should not be used in newly-written code.
Frees a PangoXFontCache and all associated memory. All fonts loaded through this font cache will be freed along with the cache.
|
a PangoXFontCache |
XFontStruct * pango_x_font_cache_load (PangoXFontCache *cache, const char *xlfd);
pango_x_font_cache_load is deprecated and should not be used in newly-written code.
Loads a XFontStruct from a X Logical Font Description. The result may be newly loaded, or it may have been previously stored.
|
a PangoXFontCache |
|
the X Logical Font Description to load. |
Returns : |
The font structure, or NULL if the font could
not be loaded. In order to free this structure, you must call
pango_x_font_cache_unload().
|
void pango_x_font_cache_unload (PangoXFontCache *cache, XFontStruct *fs);
pango_x_font_cache_unload is deprecated and should not be used in newly-written code.
Frees a font structure previously loaded with pango_x_font_cache_load().
|
a PangoXFontCache |
|
the font structure to unload |
Pango Reference Manual |
|---|
for Pango 1.26.0