| Pango Reference Manual | |||
|---|---|---|---|
| <<< Previous Page | Home | Up | Next Page >>> |
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.
struct 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_X |
struct 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 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 processing |
| PangoEngineLang *lang_engine; | the engine for doing rendering-system-independent processing |
| guint8 level; | the bidrectional level for this segment. |
struct 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". |
typedef 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_LTR | The text is written left-to-right |
| PANGO_DIRECTION_RTL | The text is written right-to-left |
| PANGO_DIRECTION_TTB_LTR | The text is written vertically top-to-bottom, with the rows ordered from left to right. |
| PANGO_DIRECTION_TTB_RTL | The text is written vertically top-to-bottom, with the rows ordered from right to left. |
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.
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).
| context : | a structure holding information that affects the itemization process. |
| text : | the text to itemize. |
| start_index : | first byte in text to process |
| length : | the number of bytes (not characters) to process after start_index. This must be >= 0. |
| attrs : | the set of attributes that apply to text. |
| cached_iter : | Cached attribute iterator, or NULL |
| Returns : | a GList of PangoItem structures. |
void pango_item_free (PangoItem *item); |
Free a PangoItem and all associated memory.
| item : | a PangoItem |
PangoItem* pango_item_copy (PangoItem *item); |
Copy an existing PangoItem structure.
PangoItem* pango_item_new (void); |
Creates a new PangoItem structure initialized to default values.
| Returns : | the new PangoItem |
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.) |
PangoContext* pango_context_new (void); |
Creates a new PangoContext initialized to default value.
| Returns : | the new PangoContext |
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. |
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. |
void pango_context_set_font_description
(PangoContext *context,
const PangoFontDescription *desc); |
Set the default font description for the context
| context : | a PangoContext |
| desc : | the new pango font description |
PangoDirection pango_context_get_base_dir (PangoContext *context); |
Retrieves the base direction for the context.
| context : | |
| Returns : | the base direction for the context. |
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 |
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(). |
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. |
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. |
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 descs |
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 descs |
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 text |
| analysis : | PangoAnalysis structure from PangoItemize |
| attrs : | an array to store character information in |
void pango_get_log_attrs (const char *text,
int length,
int level,
const char *language,
PangoLogAttr *log_attrs); |
Computes a PangoLogAttr for each character in text
| text : | text to process |
| length : | length in bytes of text |
| level : | embedding level, or -1 if unknown |
| language : | language code |
| log_attrs : | array with one PangoLogAttr per character in text, to be filled in |
struct 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.
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 text |
| analysis : | PangoAnalysis structure from PangoItemize |
| glyphs : | glyph string in which to store results |
void pango_justify (PangoGlyphString *glyphs, gint new_line_width, gint min_kashida_width); |
| glyphs : | |
| new_line_width : | |
| min_kashida_width : |