Rendering3PANGO LibraryRenderingFunctions to run the rendering pipeline.Synopsis
struct PangoContext;
struct PangoItem;
struct PangoAnalysis;
struct PangoLangRange;
enum PangoDirection;
GList* pango_itemize (PangoContext *context,
const char *text,
gint length,
PangoAttrList *attrs);
void pango_item_free (PangoItem *item);
PangoItem* pango_item_copy (PangoItem *item);
PangoItem* pango_item_new (void);
GList* pango_reorder_items (GList *logical_items);
PangoContext* pango_context_new (void);
void pango_context_add_font_map (PangoContext *context,
PangoFontMap *font_map);
PangoFontDescription* pango_context_get_font_description
(PangoContext *context);
void pango_context_set_font_description
(PangoContext *context,
const PangoFontDescription *desc);
PangoDirection pango_context_get_base_dir (PangoContext *context);
void pango_context_set_base_dir (PangoContext *context,
PangoDirection direction);
char* pango_context_get_lang (PangoContext *context);
void pango_context_set_lang (PangoContext *context,
const char *lang);
PangoFont* pango_context_load_font (PangoContext *context,
const PangoFontDescription *desc);
void pango_context_list_families (PangoContext *context,
gchar ***families,
int *n_families);
void pango_context_list_fonts (PangoContext *context,
const char *family,
PangoFontDescription ***descs,
int *n_descs);
void pango_break (const gchar *text,
gint length,
PangoAnalysis *analysis,
PangoLogAttr *attrs);
struct PangoLogAttr;
void pango_shape (const gchar *text,
gint length,
PangoAnalysis *analysis,
PangoGlyphString *glyphs);
void pango_justify (PangoGlyphString *glyphs,
gint new_line_width,
gint min_kashida_width);
Description
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.
Detailsstruct PangoContextstruct PangoContext;
The PangoContext structure stores global information
used to control the itemization process. It contains
the following fields:
gchar *lang;the global default language in the standard form
"fr" or "fr_FR". (This may be overriden
with the lang_info parameter to pango_itemize().)gchar *render_type;a string identifier for the rendering system to use,
for instance PANGO_RENDER_TYPE_Xstruct PangoItemstruct PangoItem
{
gint offset;
gint length;
gint num_chars;
GSList *extra_attrs;
PangoAnalysis analysis;
};
The PangoItem structure stores information about
a segment of text. It contains the following fields:
gint offset;the offset of the segment from the beginning of the
string in bytes.gint length;the length of the segment in bytes.gint num_chars;the length of the segment in characters.gint analysis;the properties of the segment.struct PangoAnalysisstruct PangoAnalysis
{
PangoEngineShape *shape_engine;
PangoEngineLang *lang_engine;
PangoFont *font;
guint8 level;
};
The PangoAnalysis structure stores information about
the properties of a segment of text. It has the following
fields:
PangoEngineShape *shape_engine;the engine for doing rendering-system-dependent processingPangoEngineLang *lang_engine;the engine for doing rendering-system-independent processingguint8 level;the bidrectional level for this segment.struct PangoLangRangestruct PangoLangRange
{
gint start;
gint length;
gchar *lang;
};
The PangoLangRange structure stores language tagging
information for a range of character positions of text.
It contains the following fields:
gint start;the start position of this tagged range in bytes.gint length;the length of this tagged range in bytes.gchar *lang;the language for this range, in the standard form
"fr" or "fr_FR".enum PangoDirectiontypedef enum {
PANGO_DIRECTION_LTR,
PANGO_DIRECTION_RTL,
PANGO_DIRECTION_TTB_LTR,
PANGO_DIRECTION_TTB_RTL
} PangoDirection;
The PangoDirection type represents the direction of writing
for text.
PANGO_DIRECTION_LTRThe text is written left-to-right
PANGO_DIRECTION_RTLThe text is written right-to-left
PANGO_DIRECTION_TTB_LTRThe text is written vertically
top-to-bottom, with the rows ordered from
left to right.
PANGO_DIRECTION_TTB_RTLThe text is written vertically
top-to-bottom, with the rows ordered from
right to left.
pango_itemize ()GList* pango_itemize (PangoContext *context,
const char *text,
gint length,
PangoAttrList *attrs);
Breaks a piece of text into segments with consistent
directional level and shaping engine.context : a structure holding information that affects
the itemization process.
text : the text to itemize.
length : the number of bytes (not characters) in text.
This must be >= 0.
attrs : the set of attributes that apply to text.
Returns :a GList of PangoItem structures.
pango_item_free ()void pango_item_free (PangoItem *item);
Free a PangoItem and all associated memory.item : a PangoItem
pango_item_copy ()PangoItem* pango_item_copy (PangoItem *item);
Copy an existing PangoItem structure.item : a PangoItem
Returns : the new PangoItem
pango_item_new ()PangoItem* pango_item_new (void);
Creates a new PangoItem structure initialized to default values.Returns : the new PangoItem
pango_reorder_items ()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.logical_items : a GList of PangoItem in logical order.
Returns :a GList of PangoItem structures in visual order.
(Please mail otaylorredhat.com if you use this function.
It is not a particularly convenient interface, and the code
is duplicated elsewhere in Pango for that reason.)
pango_context_new ()PangoContext* pango_context_new (void);
Creates a new PangoContext initialized to default value.Returns : the new PangoContext
pango_context_add_font_map ()void pango_context_add_font_map (PangoContext *context,
PangoFontMap *font_map);
Add a font map to the list of font maps that are searched for fonts
when fonts are looked-up in this context.context : a PangoContext
font_map : the PangoFontMap to add.
pango_context_get_font_description ()PangoFontDescription* pango_context_get_font_description
(PangoContext *context);
Retrieve the default font description for the context.context : a PangoContext
Returns : a pointer to the context's default font description.
This value must not be modified or freed.
pango_context_set_font_description ()void pango_context_set_font_description
(PangoContext *context,
const PangoFontDescription *desc);
Set the default font description for the contextcontext : a PangoContext
desc : the new pango font description
pango_context_get_base_dir ()PangoDirection pango_context_get_base_dir (PangoContext *context);
Retrieves the base direction for the context.context :Returns : the base direction for the context.
pango_context_set_base_dir ()void pango_context_set_base_dir (PangoContext *context,
PangoDirection direction);
Sets the base direction for the context.context : a PangoContext
direction : the new base direction
pango_context_get_lang ()char* pango_context_get_lang (PangoContext *context);
Retrieves the global language tag for the context.context : a PangoContext
Returns : the global language tag. This value must be freed with g_free().
pango_context_set_lang ()void pango_context_set_lang (PangoContext *context,
const char *lang);
Sets the global language tag for the context.context : a PangoContext
lang : the new language tag.
pango_context_load_font ()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.context : a PangoContext
desc : a PangoFontDescription describing the font to load
Returns :the font loaded, or NULL if no font matched.
pango_context_list_families ()void pango_context_list_families (PangoContext *context,
gchar ***families,
int *n_families);
List all families for a context.context : a PangoContext
families : location to store a pointer to an array of strings.
This array should be freed with pango_font_map_free_families().
n_families : location to store the number of elements in descspango_context_list_fonts ()void pango_context_list_fonts (PangoContext *context,
const char *family,
PangoFontDescription ***descs,
int *n_descs);
Lists all fonts in all fontmaps for this context, or all
fonts in a particular family.context : a PangoContext
family : the family for which to list the fonts, or NULL
to list fonts in all families.
descs : location to store a pointer to an array of pointers to
PangoFontDescription. This array should be freed
with pango_font_descriptions_free()
n_descs : location to store the number of elements in descspango_break ()void pango_break (const gchar *text,
gint length,
PangoAnalysis *analysis,
PangoLogAttr *attrs);
Determines possible line, word, and character breaks
for a string of Unicode text.text : the text to process
length : the length (in bytes) of textanalysis : PangoAnalysis structure from PangoItemize
attrs : an array to store character information in
struct PangoLogAttrstruct PangoLogAttr
{
guint is_break : 1; /* Break in front of character */
guint is_white : 1;
guint is_char_stop : 1;
guint is_word_stop : 1;
};
The PangoLogAttr structure stores information
about the attributes of a single character.
pango_shape ()void pango_shape (const gchar *text,
gint length,
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().text : the text to process
length : the length (in bytes) of textanalysis : PangoAnalysis structure from PangoItemize
glyphs : glyph string in which to store results
pango_justify ()void pango_justify (PangoGlyphString *glyphs,
gint new_line_width,
gint min_kashida_width);glyphs :new_line_width :min_kashida_width :