Pango Reference Manual

Home , Bidirectional text, Fontconfig, FreeType, Pango, Xft

May 17, 2009 Pango Reference Manual

ii Contents

1 Basic Pango Interfaces 1 1.1 Rendering ...... 1 1.2 Glyph Storage ...... 13 1.3 Fonts ...... 32 1.4 Text Attributes ...... 59 1.5 Tab Stops ...... 79 1.6 Text Attribute Markup ...... 83 1.7 Layout Objects ...... 85 1.8 Scripts and Languages ...... 109 1.9 Bidirectional Text ...... 118 1.10 Vertical Text ...... 121

2 Rendering with Pango 125 2.1 Win32 Fonts and Rendering ...... 125 2.2 FreeType Fonts and Rendering ...... 132 2.3 Xft Fonts and Rendering ...... 140 2.4 Cairo Rendering ...... 149 2.5 ATSUI Fonts ...... 161 2.6 Deprecated X font backend ...... 162

3 Low Level Functionality 175 3.1 PangoRenderer ...... 175 3.2 PangoFcFontMap ...... 183 3.3 PangoFcFont ...... 190 3.4 PangoFcDecoder ...... 194 3.5 OpenType Font Handling ...... 195 3.6 Coverage Maps ...... 210 3.7 Engines ...... 213 3.8 PangoEngineLang ...... 216 3.9 PangoEngineShape ...... 217 3.10 Modules ...... 219 3.11 Miscellaneous Utilities ...... 221 3.12 Version Checking ...... 226

4 Pango Tools 229 4.1 pango-querymodules ...... 229

5 Object Hierarchy 231

Index 233

iii

List of Figures

1 Basic Pango Interfaces 1.1 Adjustable parameters for a PangoLayout ...... 88

2 Rendering with Pango 2.1 Output of ...... 153

Chapter 1

Basic Pango Interfaces

1.1 Rendering

Name Rendering – Functions to run the rendering pipeline

Synopsis 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);

1 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING 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);

Object Hierarchy GObject +----PangoContext

2 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING

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.

Details PangoContext typedef struct _PangoContext PangoContext;

The PangoContext structure stores global information used to control the itemization process.

PangoItem 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 ﬁelds: 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. PangoAnalysis analysis; the properties of the segment.

PangoAnalysis 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 ﬁelds: PangoEngineShape* shape_engine; the engine for doing rendering-system-dependent processing. PangoEngineLang* lang_engine; the engine for doing rendering-system-independent processing. PangoFont* font; the font for this segment. guint8 level; the bidirectional level for this segment. guint8 gravity; the glyph orientation for this segment (A PangoGravity). guint8 flags; boolean ﬂags for this segment (currently only one) (Since: 1.16). guint8 script; the detected script for this segment (A PangoScript) (Since: 1.18).

3 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING

PangoLanguage* language; the detected language for this segment. GSList* extra_attrs; extra attributes for this segment.

PANGO_ANALYSIS_FLAG_CENTERED_BASELINE

#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

PANGO_TYPE_DIRECTION

#define PANGO_TYPE_DIRECTION(pango_direction_get_type())

The GObject type for PangoDirection. pango_itemize ()

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). context : a structure holding information that affects the itemization process. text : the text to itemize. start_index : ﬁrst 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. pango_itemize_with_base_dir ()

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 speciﬁed explicitly rather than gotten from the PangoContext. context : a structure holding information that affects the itemization process.

4 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING base_dir : base direction to use for bidirectional processing text : the text to itemize. start_index : ﬁrst 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. 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 pango_item_free () void pango_item_free(PangoItem *item);

Free a PangoItem and all associated memory. item : a PangoItem, may be NULL pango_item_copy ()

PangoItem * pango_item_copy(PangoItem *item);

Copy an existing PangoItem structure. item : a PangoItem, may be NULL Returns : the newly allocated PangoItem, which should be freed with pango_item_free(), or NULL if item was NULL. pango_item_new ()

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(). pango_item_split ()

PangoItem * pango_item_split(PangoItem *orig, int split_index, int split_offset);

Modiﬁes 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 ﬁrst 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. orig : a PangoItem split_index : byte index of position to split item, relative to the start of the item split_offset : 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().

5 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING 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 unmodiﬁed. logical_items : a GList of PangoItem in logical order. Returns : a GList of PangoItem structures in visual order. (Please open a bug 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 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(). pango_context_set_font_map () 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. context : a PangoContext font_map : the PangoFontMap to set. pango_context_get_font_map ()

PangoFontMap * pango_context_get_font_map(PangoContext *context);

Gets the PangoFontmap used to look up fonts for this context. context : a PangoContext Returns : the font map for the PangoContext. This value is owned by Pango and should not be unrefer- enced. Since 1.6 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 modiﬁed or freed.

6 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING pango_context_set_font_description () 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 pango_context_get_language ()

PangoLanguage * pango_context_get_language(PangoContext *context);

Retrieves the global language tag for the context. context : a PangoContext

Returns : the global language tag. pango_context_set_language () 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(). context : a PangoContext language : the new language tag. pango_context_get_base_dir ()

PangoDirection pango_context_get_base_dir(PangoContext *context);

Retrieves the base direction for the context. See pango_context_set_base_dir(). context : a PangoContext

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. 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. context : a PangoContext direction : the new base direction

7 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING pango_context_get_base_gravity ()

PangoGravity pango_context_get_base_gravity(PangoContext *context);

Retrieves the base gravity for the context. See pango_context_set_base_gravity(). context : a PangoContext Returns : the base gravity for the context. Since 1.16 pango_context_set_base_gravity () 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. context : a PangoContext gravity : the new base gravity Since 1.16 pango_context_get_gravity ()

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. context : a PangoContext Returns : the resolved gravity for the context. Since 1.16 pango_context_get_gravity_hint ()

PangoGravityHint pango_context_get_gravity_hint(PangoContext *context);

Retrieves the gravity hint for the context. See pango_context_set_gravity_hint() for details. context : a PangoContext Returns : the gravity hint for the context. Since 1.16 pango_context_set_gravity_hint () 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. context : a PangoContext hint : the new gravity hint Since 1.16

8 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING pango_context_get_matrix () 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(). context : 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 modiﬁed or freed. Since 1.6 pango_context_set_matrix () 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 ﬁt to the pixel grid. context : a PangoContext matrix : a PangoMatrix, or NULL to unset any existing matrix. (No matrix set is the same as setting the identity matrix.) Since 1.6 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_load_fontset ()

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. context : a PangoContext desc : a PangoFontDescription describing the fonts to load language : a PangoLanguage the fonts will be used for Returns : the fontset, or NULL if no font matched.

9 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING pango_context_get_metrics ()

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 ﬁgures. 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. context : a PangoContext desc : a PangoFontDescription structure. NULL means that the font description from the context will be used. language : 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 ﬁnished using the object. pango_context_list_families () void pango_context_list_families(PangoContext *context, PangoFontFamily *** ←- families, int *n_families);

List all families for a context. context : a PangoContext families : location to store a pointer to an array of PangoFontFamily *. This array should be freed with g_free(). n_families : location to store the number of elements in descs pango_break () 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(). text : the text to process length : length of text in bytes (may be -1 if text is nul-terminated) analysis : PangoAnalysis structure from pango_itemize() attrs : an array to store character information in attrs_len : size of the array passed as attrs

10 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING pango_get_log_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 Pan- goLogAttr 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 : text to process length : length in bytes of text level : embedding level, or -1 if unknown language : language tag log_attrs : array with one PangoLogAttr per character in text, plus one extra, to be ﬁlled in attrs_len : length of log_attrs array pango_ﬁnd_paragraph_boundary () 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 ﬁlled with the length of text (an index one off the end). text : UTF-8 text length : length of text in bytes, or -1 if nul-terminated paragraph_delimiter_index : return location for index of delimiter next_paragraph_start : return location for start of next paragraph pango_default_break () 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().

11 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING text : text to break length : length of text in bytes (may be -1 if text is nul-terminated) analysis : a PangoAnalysis for the text attrs : logical attributes to ﬁll in attrs_len : size of the array passed as attrs

PangoLogAttr 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 isa 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 aftera period, so * the next sentence starts right away). */

guint is_word_start : 1; /* first character ina word */ guint is_word_end : 1; /* is first non-word char aftera 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 ina sentence */ guint is_sentence_end : 1; /* first non-sentence char aftera sentence */

/* If set, backspace deletes one character rather than * the entire grapheme cluster. */ guint backspace_deletes_character : 1;

/* Only few space variants(U+0020 andU+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 ofa word */ } PangoLogAttr;

The PangoLogAttr structure stores information about the attributes of a single character. guint is_line_break : 1; if set, can break line in front of character guint is_mandatory_break : 1; if set, must break line in front of character

12 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE guint is_char_break : 1; if set, can break here when doing character wrapping guint is_white : 1; is whitespace character guint is_cursor_position : 1; 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_word_start : 1; is first character in a word guint is_word_end : 1; 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_sentence_boundary : 1; 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_sentence_start : 1; is first character in a sentence guint is_sentence_end : 1; 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 backspace_deletes_character : 1; if set, backspace deletes one character rather than the entire grapheme cluster. This field is only meaningful on grapheme boundaries (where is_cursor_po- sition 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_expandable_space : 1; is a whitespace character that can possibly be expanded for justification purposes. (Since: 1.18) guint is_word_boundary : 1; 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) pango_shape () 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(). text : the text to process length : the length (in bytes) of text analysis : PangoAnalysis structure from pango_itemize() glyphs : glyph string in which to store results

1.2 Glyph Storage

Name Glyph Storage – Structures for storing information about glyphs

13 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE

Synopsis

#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,

14 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE

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); #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);

15 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE

Description 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.

Details PANGO_SCALE

#define PANGO_SCALE 1024

The PANGO_SCALE macro represents the scale between dimensions used for Pango distances and device units. (The deﬁnition 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.

PANGO_PIXELS()

#define PANGO_PIXELS(d) (((int)(d) + 512) >> 10)

Converts a dimension to device units by rounding. d : a dimension in Pango units. Returns : rounded dimension in device units.

PANGO_PIXELS_FLOOR()

#define PANGO_PIXELS_FLOOR(d) (((int)(d)) >> 10)

Converts a dimension to device units by ﬂooring. d : a dimension in Pango units. Returns : ﬂoored dimension in device units. Since 1.14

PANGO_PIXELS_CEIL()

#define PANGO_PIXELS_CEIL(d) (((int)(d) + 1023) >> 10)

Converts a dimension to device units by ceiling. d : a dimension in Pango units. Returns : ceiled dimension in device units. Since 1.14

PANGO_UNITS_ROUND()

#define PANGO_UNITS_ROUND(d)

Rounds a dimension to whole device units, but does not convert it to device units. d : a dimension in Pango units. Returns : rounded dimension in Pango units. Since 1.18

16 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE pango_units_to_double () double pango_units_to_double(inti);

Converts a number in Pango units to ﬂoating-point: divides it by PANGO_SCALE. i : value in Pango units Returns : the double value. Since 1.16 pango_units_from_double () int pango_units_from_double(doubled);

Converts a ﬂoating-point number to Pango units: multiplies it by PANGO_SCALE and rounds to nearest integer. d : double ﬂoating-point value Returns : the value in Pango units. Since 1.16

PangoRectangle typedef struct{ intx; inty; 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; X coordinate of the left side of the rectangle. int y; Y coordinate of the the top side of the rectangle. int width; width of the rectangle. int height; height of the rectangle.

PANGO_ASCENT()

#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. rect : a PangoRectangle

PANGO_DESCENT()

#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. rect : a PangoRectangle

17 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE

PANGO_LBEARING()

#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. rect : a PangoRectangle

PANGO_RBEARING()

#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. rect : a PangoRectangle pango_extents_to_pixels () void pango_extents_to_pixels(PangoRectangle * ←- inclusive, PangoRectangle *nearest) ←- ;

Converts extents from Pango units to device units, dividing by the PANGO_SCALE factor and per- forming rounding. The inclusive rectangle is converted by ﬂooring the x/y coordinates and extending width/height, such that the ﬁnal 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. inclusive : rectangle to round to pixels inclusively, or NULL. nearest : rectangle to round to nearest pixels, or NULL.

Since 1.16

PangoMatrix 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 xx; 1st component of the transformation matrix

18 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE double xy; 2nd component of the transformation matrix double yx; 3rd component of the transformation matrix double yy; 4th component of the transformation matrix double x0; x translation double y0; y translation Since 1.6

PANGO_TYPE_MATRIX

#define PANGO_TYPE_MATRIX(pango_matrix_get_type ())

The GObject type for PangoMatrix

PANGO_MATRIX_INIT

#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 pango_matrix_copy ()

PangoMatrix * pango_matrix_copy(const PangoMatrix * ←- matrix);

Copies a PangoMatrix. matrix : 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 pango_matrix_free () void pango_matrix_free(PangoMatrix *matrix); Free a PangoMatrix created with pango_matrix_copy(). matrix : a PangoMatrix, may be NULL Since 1.6 pango_matrix_translate () void pango_matrix_translate(PangoMatrix *matrix, double tx, double ty);

Changes the transformation represented by matrix to be the transformation given by ﬁrst translating by (tx, ty) then applying the original transformation. matrix : a PangoMatrix tx : amount to translate in the X direction ty : amount to translate in the Y direction Since 1.6

19 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE pango_matrix_scale () void pango_matrix_scale(PangoMatrix *matrix, double scale_x, double scale_y);

Changes the transformation represented by matrix to be the transformation given by ﬁrst scaling by sx in the X direction and sy in the Y direction then applying the original transformation. matrix : a PangoMatrix scale_x : amount to scale by in X direction scale_y : amount to scale by in Y direction

Since 1.6 pango_matrix_rotate () void pango_matrix_rotate(PangoMatrix *matrix, double degrees);

Changes the transformation represented by matrix to be the transformation given by ﬁrst rotating by degrees degrees counter-clockwise then applying the original transformation. matrix : a PangoMatrix degrees : degrees to rotate counter-clockwise

Since 1.6 pango_matrix_concat () void pango_matrix_concat(PangoMatrix *matrix, const PangoMatrix * ←- new_matrix);

Changes the transformation represented by matrix to be the transformation given by ﬁrst applying transformation given by new_matrix then applying the original transformation. matrix : a PangoMatrix new_matrix : a PangoMatrix

Since 1.6 pango_matrix_transform_point () void pango_matrix_transform_point(const PangoMatrix * ←- matrix, double *x, double *y);

Transforms the point (x, y) by matrix. matrix : a PangoMatrix, or NULL x : in/out X position y : in/out Y position

Since 1.16

20 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE pango_matrix_transform_distance () 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;

Afﬁne 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. matrix : a PangoMatrix, or NULL dx : in/out X component of a distance vector dy : yn/out Y component of a distance vector Since 1.16 pango_matrix_transform_rectangle () 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). matrix : a PangoMatrix, or NULL rect : in/out bounding box in Pango units, or NULL Since 1.16 pango_matrix_transform_pixel_rectangle () 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 ﬁrst argument.

21 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE matrix : a PangoMatrix, or NULL rect : in/out bounding box in device units, or NULL Since 1.16 pango_matrix_get_font_scale_factor () 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. matrix : 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

PangoGlyph typedef guint32 PangoGlyph;

A PangoGlyph represents a single glyph in the output form of a string.

PANGO_GLYPH_EMPTY

#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()).

PANGO_GLYPH_INVALID_INPUT

#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 deﬁned such that it has the PANGO_GLYPH_UNKNOWN_FLAG on. Since 1.20

PANGO_GLYPH_UNKNOWN_FLAG

#define PANGO_GLYPH_UNKNOWN_FLAG((PangoGlyph)0x10000000)

The PANGO_GLYPH_UNKNOWN_FLAG macro is a ﬂag 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.

PANGO_GET_UNKNOWN_GLYPH()

#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 speciﬁc. 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. wc : a Unicode character

22 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE

PangoGlyphInfo 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 ﬁelds.

PangoGlyph glyph; the glyph itself.

PangoGlyphGeometry geometry; the positional information about the glyph.

PangoGlyphVisAttr attr; the visual attributes of the glyph.

PangoGlyphGeometry typedef struct{ PangoGlyphUnit width; PangoGlyphUnit x_offset; PangoGlyphUnit y_offset; } PangoGlyphGeometry;

The PangoGlyphGeometry structure contains width and positioning information for a single glyph.

PangoGlyphUnit width; the logical width to use for the the character.

PangoGlyphUnit x_offset; horizontal offset from nominal character position.

PangoGlyphUnit y_offset; vertical offset from nominal character position.

PangoGlyphUnit 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.

PangoGlyphVisAttr 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 is_cluster_start : 1; set for the ﬁrst 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 meaning- less; that is, in Arabic text, accent glyphs follow the glyphs for the base character.)

23 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE

PangoGlyphString typedef struct{ gint num_glyphs;

PangoGlyphInfo *glyphs;

/* This isa 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 simpliﬁes memory management. gint num_glyphs; the number of glyphs in the string. PangoGlyphInfo* glyphs; an array of PangoGlyphInfo structures of length num_glyphs. gint* log_clusters; 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.

PangoGlyphItem 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* item; a PangoItem structure that provides information about a segment of text. PangoGlyphString* glyphs; the glyphs obtained by shaping the text corresponding to item.

PangoGlyphItemIter 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.level is odd), then start_g- lyph 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:

24 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE

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->offset to get to the text of glyph_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 modiﬁed manually.

PangoGlyphItem* glyph_item; the PangoGlyphItem this iterator iterates over const gchar* text; the UTF-8 text that glyph_item refers to int start_glyph; starting glyph of the cluster int start_index; starting text index of the cluster int start_char; starting number of characters of the cluster int end_glyph; ending glyph of the cluster int end_index; ending text index of the cluster int end_char; ending number of characters of the cluster

Since 1.22

PANGO_TYPE_GLYPH_STRING

#define PANGO_TYPE_GLYPH_STRING(pango_glyph_string_get_type ())

The GObject type for PangoGlyphString. pango_glyph_string_new ()

PangoGlyphString * pango_glyph_string_new(void);

Create a new PangoGlyphString.

Returns : the newly allocated PangoGlyphString, which should be freed with pango_glyph_string_free(). pango_glyph_string_copy ()

PangoGlyphString * pango_glyph_string_copy(PangoGlyphString *string ←- );

Copy a glyph string and associated storage. string : 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.

25 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE pango_glyph_string_set_size () void pango_glyph_string_set_size(PangoGlyphString *string ←- , gint new_len);

Resize a glyph string to the given length. string : a PangoGlyphString. new_len : the new length of the string. pango_glyph_string_free () void pango_glyph_string_free(PangoGlyphString *string ←- );

Free a glyph string and associated storage. string : a PangoGlyphString, may be NULL pango_glyph_string_extents () 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. glyphs : a PangoGlyphString font : a PangoFont ink_rect : rectangle used to store the extents of the glyph string as drawn or NULL to indicate that the result is not needed. logical_rect : rectangle used to store the logical extents of the glyph string or NULL to indicate that the result is not needed. pango_glyph_string_extents_range () 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). glyphs : a PangoGlyphString start : start index

26 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE end : end index (the range is the set of bytes with indices such that start <= index < end) font : a PangoFont ink_rect : rectangle used to store the extents of the glyph string range as drawn or NULL to indicate that the result is not needed. logical_rect : rectangle used to store the logical extents of the glyph string range or NULL to indicate that the result is not needed. pango_glyph_string_get_width () 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. glyphs : a PangoGlyphString Returns : the logical width of the glyph string. Since 1.14 pango_glyph_string_index_to_x () 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. glyphs : the glyphs return from pango_shape() text : the text for the run length : the number of bytes (not characters) in text. analysis : the analysis information return from pango_itemize() index_ : the byte index within text trailing : whether we should compute the result for the beginning (FALSE) or end (TRUE) of the character. x_pos : location to store result pango_glyph_string_x_to_index () void pango_glyph_string_x_to_index(PangoGlyphString *glyphs ←- , char *text, int length, PangoAnalysis *analysis, int x_pos, int *index_, int *trailing);

27 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE

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. glyphs : the glyphs returned from pango_shape() text : the text for the run length : the number of bytes (not characters) in text. analysis : the analysis information return from pango_itemize() x_pos : the x offset (in Pango units) index_ : location to store calculated byte index within text trailing : location to store a boolean indicating whether the user clicked on the leading or trailing edge of the character. pango_glyph_string_get_logical_widths () 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. glyphs : a PangoGlyphString text : the text corresponding to the glyphs length : the length of text, in bytes embedding_level : the embedding level of the string logical_widths : an array whose length is g_utf8_strlen (text, length) to be ﬁlled in with the resulting character widths.

PANGO_TYPE_GLYPH_ITEM

#define PANGO_TYPE_GLYPH_ITEM(pango_glyph_item_get_type ())

The GObject type for PangoGlyphItem. Since 1.20 pango_glyph_item_copy ()

PangoGlyphItem * pango_glyph_item_copy(PangoGlyphItem *orig);

Make a deep copy of an existing PangoGlyphItem structure. orig : 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

28 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE pango_glyph_item_free () void pango_glyph_item_free(PangoGlyphItem * ←- glyph_item);

Frees a PangoGlyphItem and resources to which it points. glyph_item : a PangoGlyphItem, may be NULL

Since 1.6 pango_glyph_item_split ()

PangoGlyphItem * pango_glyph_item_split(PangoGlyphItem *orig, const char *text, int split_index);

Modiﬁes 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.) orig : a PangoItem text : text to which positions in orig apply split_index : 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 pango_glyph_item_apply_attrs ()

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 ﬁlter them out (pango_attr_list_ﬁlter()), 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. glyph_item : a shaped item text : text that list applies to list : 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

29 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE pango_glyph_item_letter_space () 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. glyph_item : a PangoGlyphItem text : text that glyph_item corresponds to (glyph_item->item->offset is an offset from the start of text) log_attrs : logical attributes for the item (the ﬁrst logical attribute refers to the position before the ﬁrst character in the item) letter_spacing : amount of letter spacing to add in Pango units. May be negative, though too large negative values will give ugly results.

Since 1.6

PANGO_TYPE_GLYPH_ITEM_ITER

#define PANGO_TYPE_GLYPH_ITEM_ITER(pango_glyph_item_iter_get_type ())

The GObject type for PangoGlyphItemIter. Since 1.22 pango_glyph_item_iter_copy ()

PangoGlyphItemIter * pango_glyph_item_iter_copy(PangoGlyphItemIter *orig ←- );

Make a shallow copy of an existing PangoGlyphItemIter structure. orig : 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 pango_glyph_item_iter_free () void pango_glyph_item_iter_free(PangoGlyphItemIter *iter ←- );

Frees a PangoGlyphItemIter created by pango_glyph_item_iter_copy(). iter : a PangoGlyphItemIter, may be NULL

Since 1.22

30 CHAPTER 1. BASIC PANGO INTERFACES 1.2. GLYPH STORAGE pango_glyph_item_iter_init_start () gboolean pango_glyph_item_iter_init_start(PangoGlyphItemIter *iter ←- , PangoGlyphItem * ←- glyph_item, const char *text); Initializes a PangoGlyphItemIter structure to point to the ﬁrst cluster in a glyph item. See Pango- GlyphItemIter for details of cluster orders. iter : a PangoGlyphItemIter glyph_item : the glyph item to iterate over text : text corresponding to the glyph item Returns : FALSE if there are no clusters in the glyph item Since 1.22 pango_glyph_item_iter_init_end () 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 Pango- GlyphItemIter for details of cluster orders. iter : a PangoGlyphItemIter glyph_item : the glyph item to iterate over text : text corresponding to the glyph item Returns : FALSE if there are no clusters in the glyph item Since 1.22 pango_glyph_item_iter_next_cluster () 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. iter : a PangoGlyphItemIter Returns : TRUE if the iterator was advanced, FALSE if we were already on the last cluster. Since 1.22 pango_glyph_item_iter_prev_cluster () 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. iter : a PangoGlyphItemIter Returns : TRUE if the iterator was moved, FALSE if we were already on the ﬁrst cluster. Since 1.22

31 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS

1.3 Fonts

Name Fonts – Structures representing abstract fonts

Synopsis 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);

32 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS

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

33 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS

#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);

34 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS

Object Hierarchy GObject +----PangoFont +----PangoFcFont

GObject +----PangoFontFamily

GObject +----PangoFontFace

GObject +----PangoFontMap +----PangoFcFontMap

GObject +----PangoFontset +----PangoFontsetSimple

Known Derived Interfaces PangoFont is required by PangoCairoFont. PangoFontMap is required by PangoCairoFontMap.

Description Pango supports a ﬂexible 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.

Details PangoFontDescription 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.

PANGO_TYPE_FONT_DESCRIPTION

#define PANGO_TYPE_FONT_DESCRIPTION(pango_font_description_get_type ())

The GObject type for PangoFontDescription. enum PangoStyle typedef enum{ PANGO_STYLE_NORMAL, PANGO_STYLE_OBLIQUE, PANGO_STYLE_ITALIC } PangoStyle;

An enumeration specifying the various slant styles possible for a font.

35 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS

PANGO_STYLE_NORMAL the font is upright.

PANGO_STYLE_OBLIQUE the font is slanted, but in a roman style.

PANGO_STYLE_ITALIC the font is slanted in an italic style.

PANGO_TYPE_STYLE

#define PANGO_TYPE_STYLE(pango_style_get_type())

The GObject type for PangoStyle. enum PangoWeight 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 predeﬁned values:

PANGO_WEIGHT_THIN the thin weight (= 100; Since: 1.24)

PANGO_WEIGHT_ULTRALIGHT the ultralight weight (= 200)

PANGO_WEIGHT_LIGHT the light weight (= 300)

PANGO_WEIGHT_BOOK the book weight (= 380; Since: 1.24)

PANGO_WEIGHT_NORMAL the default weight (= 400)

PANGO_WEIGHT_MEDIUM the normal weight (= 500; Since: 1.24)

PANGO_WEIGHT_SEMIBOLD the semibold weight (= 600)

PANGO_WEIGHT_BOLD the bold weight (= 700)

PANGO_WEIGHT_ULTRABOLD the ultrabold weight (= 800)

PANGO_WEIGHT_HEAVY the heavy weight (= 900)

PANGO_WEIGHT_ULTRAHEAVY the ultraheavy weight (= 1000; Since: 1.24)

PANGO_TYPE_WEIGHT

#define PANGO_TYPE_WEIGHT(pango_weight_get_type())

The GObject type for PangoWeight.

36 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS enum PangoVariant typedef enum{ PANGO_VARIANT_NORMAL, PANGO_VARIANT_SMALL_CAPS } PangoVariant;

An enumeration specifying capitalization variant of the font.

PANGO_VARIANT_NORMAL A normal font.

PANGO_VARIANT_SMALL_CAPS A font with the lower case characters replaced by smaller variants of the capital characters.

PANGO_TYPE_VARIANT

#define PANGO_TYPE_VARIANT(pango_variant_get_type())

The GObject type for PangoVariant. enum PangoStretch 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.

PANGO_STRETCH_ULTRA_CONDENSED ultra condensed width

PANGO_STRETCH_EXTRA_CONDENSED extra condensed width

PANGO_STRETCH_CONDENSED condensed width

PANGO_STRETCH_SEMI_CONDENSED semi condensed width

PANGO_STRETCH_NORMAL the normal width

PANGO_STRETCH_SEMI_EXPANDED semi expanded width

PANGO_STRETCH_EXPANDED expanded width

PANGO_STRETCH_EXTRA_EXPANDED extra expanded width

PANGO_STRETCH_ULTRA_EXPANDED ultra expanded width

PANGO_TYPE_STRETCH

#define PANGO_TYPE_STRETCH(pango_stretch_get_type())

The GObject type for PangoStretch.

37 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS enum PangoFontMask 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. PANGO_FONT_MASK_FAMILY the font family is specified. PANGO_FONT_MASK_STYLE the font style is specified. PANGO_FONT_MASK_VARIANT the font variant is specified. PANGO_FONT_MASK_WEIGHT the font weight is specified. PANGO_FONT_MASK_STRETCH the font stretch is specified. PANGO_FONT_MASK_SIZE the font size is specified. PANGO_FONT_MASK_GRAVITY the font gravity is specified (Since: 1.16.)

PANGO_TYPE_FONT_MASK

#define PANGO_TYPE_FONT_MASK(pango_font_mask_get_type())

The GObject type for PangoFontMask. pango_font_description_new ()

PangoFontDescription * pango_font_description_new(void);

Creates a new font description structure with all ﬁelds unset. Returns : the newly allocated PangoFontDescription, which should be freed using pango_font_description_free(). pango_font_description_copy ()

PangoFontDescription * pango_font_description_copy(const ←- PangoFontDescription *desc);

Make a copy of a PangoFontDescription. desc : 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. pango_font_description_copy_static ()

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 ﬁelds. The result can only be used until desc is modiﬁed or freed. This is meant to be used when the copy is only needed temporarily.

38 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS desc : 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. pango_font_description_hash () 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. desc : a PangoFontDescription

Returns : the hash value. pango_font_description_equal () 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 ﬁelds are all the same. (Two font descriptions may result in identical fonts being loaded, but still compare FALSE.) desc1 : a PangoFontDescription desc2 : another PangoFontDescription

Returns : TRUE if the two font descriptions are identical, FALSE otherwise. pango_font_description_free () void pango_font_description_free(PangoFontDescription * ←- desc);

Frees a font description. desc : a PangoFontDescription, may be NULL pango_font_descriptions_free () void pango_font_descriptions_free(PangoFontDescription ** ←- descs, int n_descs);

Frees an array of font descriptions. descs : a pointer to an array of PangoFontDescription, may be NULL n_descs : number of font descriptions in descs

39 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_description_set_family () void pango_font_description_set_family(PangoFontDescription * ←- desc, const char *family);

Sets the family name ﬁeld 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 ﬁeld. desc : a PangoFontDescription. family : a string representing the family name. pango_font_description_set_family_static () 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. desc : a PangoFontDescription family : a string representing the family name. pango_font_description_get_family () const char * pango_font_description_get_family(const ←- PangoFontDescription *desc);

Gets the family name ﬁeld of a font description. See pango_font_description_set_family(). desc : a PangoFontDescription.

Returns : the family name ﬁeld 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. pango_font_description_set_style () void pango_font_description_set_style(PangoFontDescription * ←- desc, PangoStyle style);

Sets the style ﬁeld 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 speciﬁcations with oblique fonts and vice-versa if an exact match is not found. desc : a PangoFontDescription style : the style for the font description

40 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_description_get_style ()

PangoStyle pango_font_description_get_style(const ←- PangoFontDescription *desc);

Gets the style ﬁeld of a PangoFontDescription. See pango_font_description_set_style(). desc : 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. pango_font_description_set_variant () void pango_font_description_set_variant(PangoFontDescription * ←- desc, PangoVariant variant);

Sets the variant ﬁeld of a font description. The PangoVariant can either be PANGO_VARIANT_NORMAL or PANGO_VARIANT_SMALL_CAPS. desc : a PangoFontDescription variant : the variant type for the font description. pango_font_description_get_variant ()

PangoVariant pango_font_description_get_variant(const ←- PangoFontDescription *desc);

Gets the variant ﬁeld of a PangoFontDescription. See pango_font_description_set_variant(). desc : 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. pango_font_description_set_weight () 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. desc : a PangoFontDescription weight : the weight for the font description. pango_font_description_get_weight ()

PangoWeight pango_font_description_get_weight(const ←- PangoFontDescription *desc);

Gets the weight ﬁeld of a font description. See pango_font_description_set_weight(). desc : 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.

41 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_description_set_stretch () 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. desc : a PangoFontDescription stretch : the stretch for the font description pango_font_description_get_stretch ()

PangoStretch pango_font_description_get_stretch(const ←- PangoFontDescription *desc);

Gets the stretch ﬁeld of a font description. See pango_font_description_set_stretch(). desc : 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. pango_font_description_set_size () void pango_font_description_set_size(PangoFontDescription * ←- desc, gint size);

Sets the size ﬁeld of a font description in fractional points. This is mutually exclusive with pango_font_description_set_absolute_size(). desc : a PangoFontDescription size : 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 con- ﬁguration 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. pango_font_description_get_size () gint pango_font_description_get_size(const ←- PangoFontDescription *desc);

Gets the size ﬁeld of a font description. See pango_font_description_set_size(). desc : 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.

42 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_description_set_absolute_size () void pango_font_description_set_absolute_size (PangoFontDescription * ←- desc, double size);

Sets the size ﬁeld of a font description, in device units. This is mutually exclusive with pango_font_description_set_size() which sets the font size in points. desc : a PangoFontDescription size : 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 pango_font_description_get_size_is_absolute () 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(). desc : 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 pango_font_description_set_gravity () 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. desc : a PangoFontDescription gravity : the gravity for the font description. Since 1.16 pango_font_description_get_gravity ()

PangoGravity pango_font_description_get_gravity(const ←- PangoFontDescription *desc);

Gets the gravity field of a font description. See pango_font_description_set_gravity(). desc : 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

43 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_description_get_set_ﬁelds ()

PangoFontMask pango_font_description_get_set_fields (const ←- PangoFontDescription ←- *desc);

Determines which ﬁelds in a font description have been set. desc : a PangoFontDescription

Returns : a bitmask with bits set corresponding to the ﬁelds in desc that have been set. pango_font_description_unset_ﬁelds () 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. desc : a PangoFontDescription to_unset : bitmask of fields in the desc to unset. pango_font_description_merge () 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. desc : a PangoFontDescription desc_to_merge : the PangoFontDescription to merge from, or NULL replace_existing : if TRUE, replace fields in desc with the corresponding values from desc_to_me- rge, even if they are already exist. pango_font_description_merge_static () 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 ﬁelds. desc can only be used until desc_to_merge is modiﬁed or freed. This is meant to be used when the merged font description is only needed temporarily. desc : a PangoFontDescription

44 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS desc_to_merge : the PangoFontDescription to merge from replace_existing : if TRUE, replace ﬁelds in desc with the corresponding values from desc_to_me- rge, even if they are already exist. pango_font_description_better_match () 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_m- atch 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. desc : a PangoFontDescription old_match : a PangoFontDescription, or NULL new_match : a PangoFontDescription

Returns : TRUE if new_match is a better match pango_font_description_from_string ()

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 modiﬁer "px" for absolute size. Any one of the options may be absent. If FAMILY- LIST is absent, then the family_name ﬁeld 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. str : string representation of a font description.

Returns : a new PangoFontDescription. pango_font_description_to_string () 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. desc : a PangoFontDescription

Returns : a new string that must be freed with g_free().

45 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_description_to_ﬁlename () 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 untypi- cal in filenames, and in lower case only. desc : a PangoFontDescription

Returns : a new string that must be freed with g_free().

PangoFontMetrics 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 ﬁelds of this structure are private to implementations of a font backend. See the documentation of the corresponding getters for documentation of their meaning. guint ref_count; reference count. Used internally. See pango_font_metrics_ref() and pango_font_metrics_unref(). int ascent; the distance from the baseline to the highest point of the glyphs of the font. This is positive in practically all fonts. int descent; the distance from the baseline to the lowest point of the glyphs of the font. This is positive in practically all fonts. int approximate_char_width; 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_digit_width; approximate average width of the glyphs for digits of the font. int underline_position; position of the underline. This is normally negative. int underline_thickness; thickness of the underline. int strikethrough_position; position of the strikethrough line. This is normally positive. int strikethrough_thickness; thickness of the strikethrough line.

PANGO_TYPE_FONT_METRICS

#define PANGO_TYPE_FONT_METRICS(pango_font_metrics_get_type ())

The GObject type for PangoFontMetrics.

46 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_metrics_ref ()

PangoFontMetrics * pango_font_metrics_ref(PangoFontMetrics * ←- metrics);

Increase the reference count of a font metrics structure by one. metrics : a PangoFontMetrics structure, may be NULL

Returns : metrics pango_font_metrics_unref () 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. metrics : a PangoFontMetrics structure, may be NULL pango_font_metrics_get_ascent () 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 ﬁgure where the ink will be.) metrics : a PangoFontMetrics structure

Returns : the ascent, in Pango units. pango_font_metrics_get_descent () 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 ﬁgure where the ink will be.) metrics : a PangoFontMetrics structure

Returns : the descent, in Pango units. pango_font_metrics_get_approximate_char_width () 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. metrics : a PangoFontMetrics structure

Returns : the character width, in Pango units.

47 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_metrics_get_approximate_digit_width () 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. metrics : a PangoFontMetrics structure

Returns : the digit width, in Pango units. pango_font_metrics_get_underline_thickness () int pango_font_metrics_get_underline_thickness (PangoFontMetrics * ←- metrics);

Gets the suggested thickness to draw for the underline. metrics : a PangoFontMetrics structure

Returns : the suggested underline thickness, in Pango units.

Since 1.6 pango_font_metrics_get_underline_position () 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. metrics : a PangoFontMetrics structure

Returns : the suggested underline position, in Pango units.

Since 1.6 pango_font_metrics_get_strikethrough_thickness () int pango_font_metrics_get_strikethrough_thickness (PangoFontMetrics * ←- metrics);

Gets the suggested thickness to draw for the strikethrough. metrics : a PangoFontMetrics structure

Returns : the suggested strikethrough thickness, in Pango units.

Since 1.6

48 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_metrics_get_strikethrough_position () 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. metrics : a PangoFontMetrics structure Returns : the suggested strikethrough position, in Pango units. Since 1.6

PangoFont 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.

PANGO_TYPE_FONT

#define PANGO_TYPE_FONT(pango_font_get_type ())

The GObject type for PangoFont.

PANGO_FONT()

#define PANGO_FONT(object)(G_TYPE_CHECK_INSTANCE_CAST((object), ←- PANGO_TYPE_FONT, PangoFont))

Casts a GObject to a PangoFont. object : a GObject.

PANGO_IS_FONT()

#define PANGO_IS_FONT(object)(G_TYPE_CHECK_INSTANCE_TYPE((object), ←- PANGO_TYPE_FONT))

Returns TRUE if object is a PangoFont. object : a GObject. pango_font_ﬁnd_shaper ()

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. font : a PangoFont language : the language tag ch : a Unicode character. Returns : the best matching shaper.

49 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_describe ()

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. font : a PangoFont Returns : a newly-allocated PangoFontDescription object. pango_font_describe_with_absolute_size ()

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. font : a PangoFont Returns : a newly-allocated PangoFontDescription object. Since 1.14 pango_font_get_coverage ()

PangoCoverage * pango_font_get_coverage(PangoFont *font, PangoLanguage *language) ←- ;

Computes the coverage map for a given font and language tag. font : a PangoFont language : the language tag Returns : a newly-allocated PangoCoverage object. pango_font_get_glyph_extents () 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. font : a PangoFont glyph : the glyph index ink_rect : rectangle used to store the extents of the glyph as drawn or NULL to indicate that the result is not needed. logical_rect : rectangle used to store the logical extents of the glyph or NULL to indicate that the result is not needed.

50 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_get_metrics ()

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. font : a PangoFont language : 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 ﬁnished using the object. pango_font_get_font_map ()

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 ﬁnalized 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. font : a PangoFont, or NULL

Returns : the PangoFontMap for the font, or NULL if font is NULL.

Since 1.10

PangoFontFamily 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.

PANGO_TYPE_FONT_FAMILY

#define PANGO_TYPE_FONT_FAMILY(pango_font_family_get_type ())

The GObject type for PangoFontFamily.

PANGO_FONT_FAMILY()

#define PANGO_FONT_FAMILY(object)(G_TYPE_CHECK_INSTANCE_CAST((object) ←- , PANGO_TYPE_FONT_FAMILY, PangoFontFamily))

Casts a GObject to a PangoFontFamily. object : a GObject.

51 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS

PANGO_IS_FONT_FAMILY()

#define PANGO_IS_FONT_FAMILY(object)(G_TYPE_CHECK_INSTANCE_TYPE((object) ←- , PANGO_TYPE_FONT_FAMILY))

Returns TRUE if object is a PangoFontFamily. object : a GObject. pango_font_family_get_name () 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. family : a PangoFontFamily Returns : the name of the family. This string is owned by the family object and must not be modiﬁed or freed. pango_font_family_is_monospace () 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 ﬁnd 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. family : a PangoFontFamily Returns : TRUE if the family is monospace. Since 1.4 pango_font_family_list_faces () 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. family : a PangoFontFamily faces : 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. n_faces : location to store number of elements in faces.

PangoFontFace 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.

52 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS

PANGO_TYPE_FONT_FACE

#define PANGO_TYPE_FONT_FACE(pango_font_face_get_type ())

The GObject type for PangoFontFace.

PANGO_FONT_FACE()

#define PANGO_FONT_FACE(object)(G_TYPE_CHECK_INSTANCE_CAST((object), ←- PANGO_TYPE_FONT_FACE, PangoFontFace))

Casts a GObject to a PangoFontFace. object : a GObject.

PANGO_IS_FONT_FACE()

#define PANGO_IS_FONT_FACE(object)(G_TYPE_CHECK_INSTANCE_TYPE((object), ←- PANGO_TYPE_FONT_FACE))

Returns TRUE if object is a PangoFontFace. object : a GObject. pango_font_face_get_face_name () 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. face : a PangoFontFace. Returns : the face name for the face. This string is owned by the face object and must not be modiﬁed or freed. pango_font_face_list_sizes () 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. face : a PangoFontFace. sizes : location to store a pointer to an array of int. This array should be freed with g_free(). n_sizes : location to store the number of elements in sizes Since 1.4 pango_font_face_describe ()

PangoFontDescription * pango_font_face_describe(PangoFontFace *face);

Returns the family, style, variant, weight and stretch of a PangoFontFace. The size ﬁeld of the resulting font description will be unset. face : a PangoFontFace Returns : a newly-created PangoFontDescription structure holding the description of the face. Use pango_font_description_free() to free the result.

53 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_face_is_synthesized () 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. face : a PangoFontFace

Returns : whether face is synthesized.

Since 1.18

PangoFontMap 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.

PANGO_TYPE_FONT_MAP

#define PANGO_TYPE_FONT_MAP(pango_font_map_get_type ())

The GObject type for PangoFontMap.

PANGO_FONT_MAP()

#define PANGO_FONT_MAP(object)(G_TYPE_CHECK_INSTANCE_CAST((object), ←- PANGO_TYPE_FONT_MAP, PangoFontMap))

Casts a GObject to a PangoFontMap. object : a GObject.

PANGO_IS_FONT_MAP()

#define PANGO_IS_FONT_MAP(object)(G_TYPE_CHECK_INSTANCE_TYPE((object), ←- PANGO_TYPE_FONT_MAP))

Returns TRUE if object is a PangoFontMap. object : a GObject.

PangoFontMapClass 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,

54 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS

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_class; parent GObjectClass. load_font () a function to load a font with a given description. See pango_font_map_load_font(). list_families () A function to list available font families. See pango_font_map_list_families(). load_fontset () a function to load a fontset with a given given description suitable for a particular language. See pango_font_map_load_fontset(). const char* shape_engine_type; the type of rendering-system-dependent engines that can handle fonts of this fonts loaded with this fontmap.

PANGO_FONT_MAP_CLASS()

#define PANGO_FONT_MAP_CLASS(klass)(G_TYPE_CHECK_CLASS_CAST((klass), ←- PANGO_TYPE_FONT_MAP, PangoFontMapClass))

Casts a GObject to a PangoFontMapClass. klass : a GObject.

PANGO_IS_FONT_MAP_CLASS()

#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. klass : a GObject.

PANGO_FONT_MAP_GET_CLASS()

#define PANGO_FONT_MAP_GET_CLASS(obj)(G_TYPE_INSTANCE_GET_CLASS((obj), ←- PANGO_TYPE_FONT_MAP, PangoFontMapClass))

Returns the type of a PangoFontMap. obj : a PangoFontMap. pango_font_map_create_context ()

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. fontmap : a PangoFontMap Returns : the newly allocated PangoContext, which should be freed with g_object_unref(). Since 1.22

55 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_font_map_load_font ()

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. fontmap : a PangoFontMap context : the PangoContext the font will be used with desc : a PangoFontDescription describing the font to load Returns : the font loaded, or NULL if no font matched. pango_font_map_load_fontset ()

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. fontmap : a PangoFontMap context : the PangoContext the font will be used with desc : a PangoFontDescription describing the font to load language : a PangoLanguage the fonts will be used for Returns : the fontset, or NULL if no font matched. pango_font_map_list_families () void pango_font_map_list_families(PangoFontMap *fontmap, PangoFontFamily *** ←- families, int *n_families);

List all families for a fontmap. fontmap : a PangoFontMap families : location to store a pointer to an array of PangoFontFamily *. This array should be freed with g_free(). n_families : location to store the number of elements in families pango_font_map_get_shape_engine_type () 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 ﬁeld of PangoEngine- Info. fontmap : a PangoFontMap

56 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS

Returns : the ID string for shape engines for this fontmap. Owned by Pango, should not be modiﬁed or freed.

Since 1.4

PangoFontset 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 ﬁnding the component font for a particular Unicode character, and for ﬁnding a composite set of metrics for the entire fontset.

PANGO_TYPE_FONTSET

#define PANGO_TYPE_FONTSET(pango_fontset_get_type ())

The GObject type for PangoFontset.

PangoFontsetClass 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_class; parent GObjectClass. get_font () a function to get the font in the fontset that contains the best glyph for the given Unicode character; see pango_fontset_get_font(). get_metrics () a function to get overall metric information for the fonts in the fontset; see pango_fontset_get_metrics(). get_language () a function to get the language of the fontset. foreach () a function to loop over the fonts in the fontset. See pango_fontset_foreach(). pango_fontset_get_font ()

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. fontset : a PangoFontset wc : a Unicode character

Returns : a PangoFont. The caller must call g_object_unref when ﬁnished with the font.

57 CHAPTER 1. BASIC PANGO INTERFACES 1.3. FONTS pango_fontset_get_metrics ()

PangoFontMetrics * pango_fontset_get_metrics(PangoFontset *fontset);

Get overall metric information for the fonts in the fontset. fontset : a PangoFontset

Returns : a PangoFontMetrics object. The caller must call pango_font_metrics_unref() when ﬁnished using the object.

PangoFontsetForeachFunc () gboolean( *PangoFontsetForeachFunc)(PangoFontset *fontset, PangoFont *font, gpointer data);

A callback function used by pango_fontset_foreach() when enumerating the fonts in a fontset. fontset : a PangoFontset font : a font from fontset data : callback data

Returns : if TRUE, stop iteration and return immediately.

Since 1.4 pango_fontset_foreach () 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. fontset : a PangoFontset func : Callback function data : data to pass to the callback function

Since 1.4

PangoFontsetSimple 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.

PANGO_TYPE_FONTSET_SIMPLE

#define PANGO_TYPE_FONTSET_SIMPLE(pango_fontset_simple_get_type ())

The GObject type for PangoFontsetSimple.

58 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES pango_fontset_simple_new ()

PangoFontsetSimple * pango_fontset_simple_new(PangoLanguage *language) ←- ;

Creates a new PangoFontsetSimple for the given language. language : a PangoLanguage tag Returns : the newly allocated PangoFontsetSimple, which should be freed with g_object_unref(). pango_fontset_simple_append () void pango_fontset_simple_append(PangoFontsetSimple * ←- fontset, PangoFont *font);

Adds a font to the fontset. fontset : a PangoFontsetSimple. font : a PangoFont. pango_fontset_simple_size () int pango_fontset_simple_size(PangoFontsetSimple * ←- fontset);

Returns the number of fonts in the fontset. fontset : a PangoFontsetSimple. Returns : the size of fontset.

1.4 Text Attributes

Name Text Attributes – Font and other attributes for annotating text

Synopsis 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,

59 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES

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

60 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES 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);

Description 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.

Details enum PangoAttrType typedef enum { PANGO_ATTR_INVALID,/* 0 is an invalid attribute type */ PANGO_ATTR_LANGUAGE,/* PangoAttrLanguage */ PANGO_ATTR_FAMILY,/* PangoAttrString */ PANGO_ATTR_STYLE,/* PangoAttrInt */

61 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES

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 predeﬁned values, it is possible to allocate additional values for custom attributes using pango_attr_type_register(). The predeﬁned values are given below. The type of structure used to store the attribute is listed in parentheses after the description. PANGO_ATTR_INVALID does not happen PANGO_ATTR_LANGUAGE language (PangoAttrLanguage) PANGO_ATTR_FAMILY font family name list (PangoAttrString) PANGO_ATTR_STYLE font slant style (PangoAttrInt) PANGO_ATTR_WEIGHT font weight (PangoAttrInt) PANGO_ATTR_VARIANT font variant (normal or small caps) (PangoAttrInt) PANGO_ATTR_STRETCH font stretch (PangoAttrInt) PANGO_ATTR_SIZE font size in points scaled by PANGO_SCALE(PangoAttrInt) PANGO_ATTR_FONT_DESC font description (PangoAttrFontDesc) PANGO_ATTR_FOREGROUND foreground color (PangoAttrColor) PANGO_ATTR_BACKGROUND background color (PangoAttrColor) PANGO_ATTR_UNDERLINE whether the text has an underline (PangoAttrInt) PANGO_ATTR_STRIKETHROUGH whether the text is struck-through (PangoAttrInt) PANGO_ATTR_RISE baseline displacement (PangoAttrInt) PANGO_ATTR_SHAPE shape (PangoAttrShape) PANGO_ATTR_SCALE font size scale factor (PangoAttrFloat) PANGO_ATTR_FALLBACK whether fallback is enabled (PangoAttrInt) PANGO_ATTR_LETTER_SPACING letter spacing (PangoAttrInt) PANGO_ATTR_UNDERLINE_COLOR underline color (PangoAttrColor) PANGO_ATTR_STRIKETHROUGH_COLOR strikethrough color (PangoAttrColor) PANGO_ATTR_ABSOLUTE_SIZE font size in pixels scaled by PANGO_SCALE(PangoAttrInt) PANGO_ATTR_GRAVITY base text gravity (PangoAttrInt) PANGO_ATTR_GRAVITY_HINT gravity hint (PangoAttrInt)

62 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES

PANGO_TYPE_ATTR_TYPE

#define PANGO_TYPE_ATTR_TYPE(pango_attr_type_get_type())

The GObject type for PangoAttrType.

PangoAttrClass 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 type; the type ID for this attribute copy () function to duplicate an attribute of this type (see pango_attribute_copy()) destroy () function to free an attribute of this type (see pango_attribute_destroy()) equal () function to check two attributes of this type for equality (see pango_attribute_equal())

PangoAttribute 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-speciﬁc 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* klass; the class structure holding information about the type of the attribute guint start_index; the start index of the range (in bytes). guint end_index; end index of the range (in bytes). The character at this index is not included in the range.

PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING

#define PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING0

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

PANGO_ATTR_INDEX_TO_TEXT_END

#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.24

63 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES

PangoAttrString typedef struct{ PangoAttribute attr; char *value; } PangoAttrString;

The PangoAttrString structure is used to represent attributes with a string value. PangoAttribute attr; the common portion of the attribute char* value; the string which is the value of the attribute

PangoAttrLanguage typedef struct{ PangoAttribute attr; PangoLanguage *value; } PangoAttrLanguage;

The PangoAttrLanguage structure is used to represent attributes that are languages. PangoAttribute attr; the common portion of the attribute PangoLanguage* value; the PangoLanguage which is the value of the attribute

PangoAttrColor typedef struct{ PangoAttribute attr; PangoColor color; } PangoAttrColor;

The PangoAttrColor structure is used to represent attributes that are colors. PangoAttribute attr; the common portion of the attribute PangoColor color; the PangoColor which is the value of the attribute

PangoAttrInt typedef struct{ PangoAttribute attr; int value; } PangoAttrInt;

The PangoAttrInt structure is used to represent attributes with an integer or enumeration value. PangoAttribute attr; the common portion of the attribute int value; the value of the attribute

PangoAttrFloat typedef struct{ PangoAttribute attr; double value; } PangoAttrFloat;

The PangoAttrFloat structure is used to represent attributes with a ﬂoat or double value. PangoAttribute attr; the common portion of the attribute double value; the value of the attribute

64 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES

PangoAttrFontDesc 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 attr; the common portion of the attribute

PangoFontDescription* desc; the font description which is the value of this attribute

PangoAttrShape 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 attr; the common portion of the attribute

PangoRectangle ink_rect; the ink rectangle to restrict to

PangoRectangle logical_rect; the logical rectangle to restrict to gpointer data; user data set (see pango_attr_shape_new_with_data())

PangoAttrDataCopyFunc copy_func; copy function for the user data

GDestroyNotify destroy_func; destroy function for the user data

PangoAttrSize typedef struct{ PangoAttribute attr; int size; guint absolute : 1; } PangoAttrSize;

The PangoAttrShape structure is used to represent attributes which set font size.

PangoAttribute attr; the common portion of the attribute int size; 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 absolute : 1; whether the font size is in device units or points. This ﬁeld 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.

65 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES pango_parse_markup () 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 ﬁrst 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_text : markup to parse (see markup format) length : length of markup_text, or -1 if nul-terminated accel_marker : character that precedes an accelerator, or 0 for none attr_list : address of return location for a PangoAttrList, or NULL text : address of return location for text with tags stripped, or NULL accel_char : address of return location for accelerator char, or NULL error : address of return location for errors, or NULL

Returns : FALSE if error is set, otherwise TRUE pango_attr_type_register ()

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(). name : an identiﬁer for the type

Returns : the new type ID. pango_attr_type_get_name () 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 modiﬁed or freed. type : 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

66 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES pango_attribute_init () 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. attr : a PangoAttribute klass : a PangoAttributeClass

Since 1.20 pango_attribute_copy ()

PangoAttribute * pango_attribute_copy(const PangoAttribute * ←- attr);

Make a copy of an attribute. attr : a PangoAttribute

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attribute_equal () 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. attr1 : a PangoAttribute attr2 : another PangoAttribute

Returns : TRUE if the two attributes have the same value. pango_attribute_destroy () void pango_attribute_destroy(PangoAttribute *attr);

Destroy a PangoAttribute and free all associated memory. attr : a PangoAttribute. pango_attr_language_new ()

PangoAttribute * pango_attr_language_new(PangoLanguage *language) ←- ;

Create a new language tag attribute. language : language tag

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

67 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES pango_attr_family_new ()

PangoAttribute * pango_attr_family_new(const char *family);

Create a new font family attribute. family : the family or comma separated list of families

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_style_new ()

PangoAttribute * pango_attr_style_new(PangoStyle style);

Create a new font slant style attribute. style : the slant style

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_variant_new ()

PangoAttribute * pango_attr_variant_new(PangoVariant variant);

Create a new font variant attribute (normal or small caps) variant : the variant

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_stretch_new ()

PangoAttribute * pango_attr_stretch_new(PangoStretch stretch);

Create a new font stretch attribute stretch : the stretch

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_weight_new ()

PangoAttribute * pango_attr_weight_new(PangoWeight weight);

Create a new font weight attribute. weight : the weight

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_size_new ()

PangoAttribute * pango_attr_size_new(int size);

Create a new font-size attribute in fractional points. size : the font size, in PANGO_SCALEths of a point.

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

68 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES pango_attr_size_new_absolute ()

PangoAttribute * pango_attr_size_new_absolute(int size);

Create a new font-size attribute in device units. size : 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 pango_attr_font_desc_new ()

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. desc : the font description Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_foreground_new ()

PangoAttribute * pango_attr_foreground_new(guint16 red, guint16 green, guint16 blue);

Create a new foreground color attribute. red : the red value (ranging from 0 to 65535) green : the green value blue : the blue value Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_background_new ()

PangoAttribute * pango_attr_background_new(guint16 red, guint16 green, guint16 blue);

Create a new background color attribute. red : the red value (ranging from 0 to 65535) green : the green value blue : the blue value Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_strikethrough_new ()

PangoAttribute * pango_attr_strikethrough_new(gboolean strikethrough);

Create a new strike-through attribute. strikethrough : TRUE if the text should be struck-through. Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

69 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES pango_attr_strikethrough_color_new ()

PangoAttribute * pango_attr_strikethrough_color_new(guint16 red, guint16 green, guint16 blue);

Create a new strikethrough color attribute. This attribute modiﬁes the color of strikethrough lines. If not set, strikethrough lines will use the foreground color. red : the red value (ranging from 0 to 65535) green : the green value blue : the blue value Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). Since 1.8 pango_attr_underline_new ()

PangoAttribute * pango_attr_underline_new(PangoUnderline underline ←- );

Create a new underline-style attribute. underline : the underline style. Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_underline_color_new ()

PangoAttribute * pango_attr_underline_color_new(guint16 red, guint16 green, guint16 blue);

Create a new underline color attribute. This attribute modiﬁes the color of underlines. If not set, underlines will use the foreground color. red : the red value (ranging from 0 to 65535) green : the green value blue : the blue value Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). Since 1.8 enum PangoUnderline 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. PANGO_UNDERLINE_NONE no underline should be drawn PANGO_UNDERLINE_SINGLE a single underline should be drawn

70 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES

PANGO_UNDERLINE_DOUBLE a double underline should be drawn

PANGO_UNDERLINE_LOW 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.

PANGO_UNDERLINE_ERROR 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.

PANGO_TYPE_UNDERLINE

#define PANGO_TYPE_UNDERLINE(pango_underline_get_type())

The GObject type for PangoUnderline. pango_attr_shape_new ()

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_rect : ink rectangle to assign to each character logical_rect : logical rectangle to assign to each character

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). pango_attr_shape_new_with_data ()

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_rect : ink rectangle to assign to each character logical_rect : logical rectangle to assign to each character data : user data pointer copy_func : function to copy data when the attribute is copied. If NULL, data is simply copied as a pointer. destroy_func : 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

71 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES

PangoAttrDataCopyFunc () gpointer( *PangoAttrDataCopyFunc)(gconstpointer data);

A copy function passed to attribute new functions that take user data. data : the user data

Returns : a new copy of data. pango_attr_scale_new ()

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. scale_factor : factor to scale the font

Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

PANGO_SCALE_XX_SMALL

#define PANGO_SCALE_XX_SMALL((double)0.5787037037037)

The scale factor for three shrinking steps (1 / (1.2 * 1.2 * 1.2)).

PANGO_SCALE_X_SMALL

#define PANGO_SCALE_X_SMALL((double)0.6444444444444)

The scale factor for two shrinking steps (1 / (1.2 * 1.2)).

PANGO_SCALE_SMALL

#define PANGO_SCALE_SMALL((double)0.8333333333333)

The scale factor for one shrinking step (1 / 1.2).

PANGO_SCALE_MEDIUM

#define PANGO_SCALE_MEDIUM((double)1.0)

The scale factor for normal size (1.0).

PANGO_SCALE_LARGE

#define PANGO_SCALE_LARGE((double)1.2)

The scale factor for one magniﬁcation step (1.2).

PANGO_SCALE_X_LARGE

#define PANGO_SCALE_X_LARGE((double)1.4399999999999)

The scale factor for two magniﬁcation steps (1.2 * 1.2).

72 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES

PANGO_SCALE_XX_LARGE

#define PANGO_SCALE_XX_LARGE((double)1.728)

The scale factor for three magniﬁcation steps (1.2 * 1.2 * 1.2). pango_attr_rise_new ()

PangoAttribute * pango_attr_rise_new(int rise);

Create a new baseline displacement attribute. rise : 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(). pango_attr_letter_spacing_new ()

PangoAttribute * pango_attr_letter_spacing_new(int letter_spacing);

Create a new letter-spacing attribute. letter_spacing : 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 pango_attr_fallback_new ()

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. enable_fallback : 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 pango_attr_gravity_new ()

PangoAttribute * pango_attr_gravity_new(PangoGravity gravity);

Create a new gravity attribute. gravity : 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 pango_attr_gravity_hint_new ()

PangoAttribute * pango_attr_gravity_hint_new(PangoGravityHint hint);

Create a new gravity hint attribute. hint : the gravity hint value. Returns : the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy(). Since 1.16

73 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES

PangoColor 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 red; The red component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity. guint16 green; The green component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity. guint16 blue; The blue component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity.

PANGO_TYPE_COLOR

#define PANGO_TYPE_COLOR pango_color_get_type()

The GObject type for PangoColor. pango_color_parse () 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’) color : a PangoColor structure in which to store the result, or NULL spec : a string specifying the new color

Returns : TRUE if parsing of the speciﬁer succeeded, otherwise false. pango_color_copy ()

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). src : 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. pango_color_free () void pango_color_free(PangoColor *color);

Frees a color allocated by pango_color_copy(). color : an allocated PangoColor, may be NULL

74 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES pango_color_to_string () gchar * pango_color_to_string(const PangoColor *color) ←- ;

Returns a textual speciﬁcation of color in the hexadecimal form #rrrrggggbbbb, where r, g and b are hex digits representing the red, green, and blue components respectively. color : a PangoColor

Returns : a newly-allocated text string that must be freed with g_free().

Since 1.16

PangoAttrList 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.

PANGO_TYPE_ATTR_LIST

#define PANGO_TYPE_ATTR_LIST pango_attr_list_get_type()

The GObject type for PangoAttrList. pango_attr_list_new ()

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(). pango_attr_list_ref ()

PangoAttrList * pango_attr_list_ref(PangoAttrList *list);

Increase the reference count of the given attribute list by one. list : a PangoAttrList, may be NULL

Returns : The attribute list passed in

Since 1.10 pango_attr_list_unref () 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. list : a PangoAttrList, may be NULL

75 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES pango_attr_list_copy ()

PangoAttrList * pango_attr_list_copy(PangoAttrList *list);

Copy list and return an identical new list. 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. pango_attr_list_insert () 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. list : a PangoAttrList attr : the attribute to insert. Ownership of this value is assumed by the list. pango_attr_list_insert_before () 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. list : a PangoAttrList attr : the attribute to insert. Ownership of this value is assumed by the list. pango_attr_list_change () 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. list : a PangoAttrList attr : the attribute to insert. Ownership of this value is assumed by the list. pango_attr_list_splice () void pango_attr_list_splice(PangoAttrList *list, PangoAttrList *other, gint pos, gint len);

This function opens up a hole in list, ﬁlls 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.

76 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES list : a PangoAttrList other : another PangoAttrList pos : the position in list at which to insert other len : the length of the spliced segment. (Note that this must be speciﬁed since the attributes in other may only be present at some subsection of this range) pango_attr_list_ﬁlter ()

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. list : a PangoAttrList func : callback function; returns TRUE if an attribute should be ﬁltered out. data : Data to be passed to func

Returns : the new PangoAttrList or NULL if no attributes of the given types were found.

Since 1.2

PangoAttrFilterFunc () 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. attribute : a PangoAttribute data : callback data passed to pango_attr_list_filter()

Returns : %TRUE if the attribute should be ﬁltered out pango_attr_list_get_iterator ()

PangoAttrIterator * pango_attr_list_get_iterator(PangoAttrList *list);

Create a iterator initialized to the beginning of the list. list must not be modiﬁed until this iterator is freed. list : a PangoAttrList

Returns : the newly allocated PangoAttrIterator, which should be freed with pango_attr_iterator_destroy().

PangoAttrIterator 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.

77 CHAPTER 1. BASIC PANGO INTERFACES 1.4. TEXT ATTRIBUTES pango_attr_iterator_copy ()

PangoAttrIterator * pango_attr_iterator_copy(PangoAttrIterator * ←- iterator);

Copy a PangoAttrIterator iterator : a PangoAttrIterator.

Returns : the newly allocated PangoAttrIterator, which should be freed with pango_attr_iterator_destroy(). pango_attr_iterator_next () gboolean pango_attr_iterator_next(PangoAttrIterator * ←- iterator);

Advance the iterator until the next change of style. iterator : a PangoAttrIterator

Returns : FALSE if the iterator is at the end of the list, otherwise TRUE pango_attr_iterator_range () 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 ﬁt into a signed integer are clamped to G_MAXINT. iterator : a PangoAttrIterator start : location to store the start of the range end : location to store the end of the range pango_attr_iterator_get ()

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. iterator : a PangoAttrIterator type : the type of attribute to ﬁnd.

Returns : the current attribute of the given type, or NULL if no attribute of that type applies to the current location.

78 CHAPTER 1. BASIC PANGO INTERFACES 1.5. TAB STOPS pango_attr_iterator_get_font () 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. iterator : a PangoAttrIterator desc : a PangoFontDescription to ﬁll 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 Pan- goAttrList associated with the iterator, so if you plan to keep it around, you must call: pango_fo- nt_description_set_family (desc, pango_font_description_get_family (des- c)). language : if non-NULL, location to store language tag for item, or NULL if none is found. extra_attrs : element type Pango.Attribute): (transfer full. element type Pango.Attribute): (transfer full. pango_attr_iterator_get_attrs ()

GSList * pango_attr_iterator_get_attrs(PangoAttrIterator * ←- iterator);

Gets a list of all attributes at the current position of the iterator. iterator : a PangoAttrIterator Returns : element-type Pango.Attribute): (transfer full. element-type Pango.Attribute): (transfer full. Since 1.2 pango_attr_iterator_destroy () void pango_attr_iterator_destroy(PangoAttrIterator * ←- iterator);

Destroy a PangoAttrIterator and free all associated memory. iterator : a PangoAttrIterator.

1.5 Tab Stops

Name Tab Stops – Structures for storing tab stops

Synopsis 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,

79 CHAPTER 1. BASIC PANGO INTERFACES 1.5. TAB STOPS

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);

Description Functions in this section are used to deal with PangoTabArray objects that can be used to set tab stop positions in a PangoLayout.

Details PangoTabArray typedef struct _PangoTabArray PangoTabArray;

A PangoTabArray struct contains an array of tab stops. Each tab stop has an alignment and a position.

PANGO_TYPE_TAB_ARRAY

#define PANGO_TYPE_TAB_ARRAY(pango_tab_array_get_type ())

The GObject type for PangoTabArray. enum PangoTabAlign 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 speciﬁes where a tab stop appears relative to the text. PANGO_TAB_LEFT the tab stop appears to the left of the text.

80 CHAPTER 1. BASIC PANGO INTERFACES 1.5. TAB STOPS

PANGO_TYPE_TAB_ALIGN

#define PANGO_TYPE_TAB_ALIGN(pango_tab_align_get_type())

The GObject type for PangoTabAlign. pango_tab_array_new ()

PangoTabArray * pango_tab_array_new(gint initial_size, gboolean ←- positions_in_pixels) ←- ;

Creates an array of initial_size tab stops. Tab stops are speciﬁed in pixel units if positions_in- _pixels is TRUE, otherwise in Pango units. All stops are initially at position 0. initial_size : Initial number of tab stops to allocate, can be 0 positions_in_pixels : whether positions are in pixel units Returns : the newly allocated PangoTabArray, which should be freed with pango_tab_array_free(). pango_tab_array_new_with_positions ()

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. size : number of tab stops in the array positions_in_pixels : whether positions are in pixel units first_alignment : alignment of ﬁrst tab stop first_position : position of ﬁrst tab stop ... : additional alignment/position pairs Returns : the newly allocated PangoTabArray, which should be freed with pango_tab_array_free(). pango_tab_array_copy ()

PangoTabArray * pango_tab_array_copy(PangoTabArray *src);

Copies a PangoTabArray src : PangoTabArray to copy Returns : the newly allocated PangoTabArray, which should be freed with pango_tab_array_free(). pango_tab_array_free () void pango_tab_array_free(PangoTabArray *tab_array ←- );

Frees a tab array and associated resources. tab_array : a PangoTabArray

81 CHAPTER 1. BASIC PANGO INTERFACES 1.5. TAB STOPS pango_tab_array_get_size () gint pango_tab_array_get_size(PangoTabArray *tab_array ←- );

Gets the number of tab stops in tab_array. tab_array : a PangoTabArray

Returns : the number of tab stops in the array. pango_tab_array_resize () 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. tab_array : a PangoTabArray new_size : new size of the array pango_tab_array_set_tab () 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. tab_array : a PangoTabArray tab_index : the index of a tab stop alignment : tab alignment location : tab location in Pango units pango_tab_array_get_tab () 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. tab_array : a PangoTabArray tab_index : tab stop index alignment : location to store alignment, or NULL location : location to store tab position, or NULL

82 CHAPTER 1. BASIC PANGO INTERFACES 1.6. TEXT ATTRIBUTE MARKUP pango_tab_array_get_tabs () void pango_tab_array_get_tabs(PangoTabArray *tab_array ←- , PangoTabAlign ** ←- alignments, gint **locations);

If non-NULL, alignments and locations are ﬁlled with allocated arrays of length pango_tab_array_get_size(). You must free the returned array. tab_array : a PangoTabArray alignments : location to store an array of tab stop alignments, or NULL locations : location to store an array of tab positions, or NULL pango_tab_array_get_positions_in_pixels () 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. tab_array : a PangoTabArray

Returns : whether positions are in pixels.

1.6 Text Attribute Markup

Name Text Attribute Markup – Simple markup language to encode text with attributes

Pango Text Attribute Markup Language 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 PangoAt- trList using the function pango_parse_markup(). A simple example of a marked-up string might be: "Blue text is cool!" The root tag of a marked-up document is , 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 , then there are some convenience tags. has the following attributes: ATTRIBUTES font1, 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

1 Since 1.21

83 CHAPTER 1. BASIC PANGO INTERFACES 1.6. TEXT ATTRIBUTE MARKUP font_size1, 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=’12.5’ rather than size=’12800’. font_style1, style One of ’normal’, ’oblique’, ’italic’ font_weight1, weight One of ’ultralight’, ’light’, ’normal’, ’bold’, ’ultrabold’, ’heavy’, or a numeric weight font_variant1, variant One of ’normal’ or ’smallcaps’ font_stretch1, stretch One of ’ultracondensed’, ’extracondensed’, ’condensed’, ’semicondensed’, ’normal’, ’semiexpanded’, ’expanded’, ’extraexpanded’, ’ultraexpanded’ foreground, fgcolor1, color An RGB color specification such as ’#00FF00’ or a color name such as ’red’ background, bgcolor1 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 i Italic s Strikethrough sub Subscript sup Superscript small Makes font relatively smaller, equivalent to tt Monospace font u Underline

84 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS

1.7 Layout Objects

Name Layout Objects – High-level layout driver objects

Synopsis 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);

85 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS 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);

86 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS 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_,

87 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS

int *trailing); void pango_layout_line_get_x_ranges (PangoLayoutLine *line, int start_index, int end_index, int **ranges, int *n_ranges);

Object Hierarchy GObject +----PangoLayout

Description 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.

Details PangoLayout typedef struct _PangoLayout PangoLayout;

The PangoLayout structure represents an entire paragraph of text. It is initialized with a Pango- Context, 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 illus- trated in Figure 1.1. It is possible, as well, to ignore the 2-D setup, and simply treat the results of a PangoLayout as a list of lines.

Figure 1.1 Adjustable parameters for a PangoLayout

The PangoLayout structure is opaque, and has no user-visible ﬁelds.

PangoLayoutIter 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 ﬁelds.

88 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_new ()

PangoLayout * pango_layout_new(PangoContext *context);

Create a new PangoLayout object with attributes initialized to default values for a particular Pango- Context. context : a PangoContext

Returns : the newly allocated PangoLayout, with a reference count of one, which should be freed with g_object_unref(). pango_layout_copy ()

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. src : a PangoLayout

Returns : the newly allocated PangoLayout, with a reference count of one, which should be freed with g_object_unref(). pango_layout_get_context ()

PangoContext * pango_layout_get_context(PangoLayout *layout);

Retrieves the PangoContext used for this layout. 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. pango_layout_context_changed () 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. layout : a PangoLayout pango_layout_set_text () 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. layout : a PangoLayout text : a valid UTF-8 string length : 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.

89 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_get_text () const char * pango_layout_get_text(PangoLayout *layout);

Gets the text in the layout. The returned text should not be freed or modiﬁed. layout : a PangoLayout

Returns : the text in the layout. pango_layout_set_markup () 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. layout : a PangoLayout markup : marked-up text length : length of marked-up text in bytes, or -1 if markup is nul-terminated pango_layout_set_markup_with_accel () 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 ﬁrst character so marked will be returned in accel_char. Two accel_marker characters following each other produce a single literal accel_marker character. layout : a PangoLayout markup : marked-up text (see markup format) length : length of marked-up text in bytes, or -1 if markup is nul-terminated accel_marker : marker for accelerators in the text accel_char : return location for ﬁrst located accelerator, or NULL pango_layout_set_attributes () 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. layout : a PangoLayout attrs : a PangoAttrList, can be NULL

90 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_get_attributes ()

PangoAttrList * pango_layout_get_attributes(PangoLayout *layout);

Gets the attribute list for the layout, if any. layout : a PangoLayout

Returns : a PangoAttrList. pango_layout_set_font_description () 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. layout : a PangoLayout desc : the new PangoFontDescription, or NULL to unset the current font description pango_layout_get_font_description () const PangoFontDescription * pango_layout_get_font_description (PangoLayout *layout);

Gets the font description for the layout, if any. layout : 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 modiﬁed or freed.

Since 1.8 pango_layout_set_width () 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. layout : a PangoLayout. width : the desired width in Pango units, or -1 to indicate that no wrapping or ellipsization should be performed. pango_layout_get_width () int pango_layout_get_width(PangoLayout *layout);

Gets the width to which the lines of the PangoLayout should wrap. layout : a PangoLayout

Returns : the width in Pango units, or -1 if no width set.

91 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_set_height () 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. layout : a PangoLayout. height : the desired height of the layout in Pango units if positive, or desired number of lines if negative.

Since 1.20 pango_layout_get_height () int pango_layout_get_height(PangoLayout *layout);

Gets the height of layout used for ellipsization. See pango_layout_set_height() for details. layout : a PangoLayout

Returns : the height, in Pango units if positive, or number of lines if negative.

Since 1.20 pango_layout_set_wrap () 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. layout : a PangoLayout wrap : the wrap mode pango_layout_get_wrap ()

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. layout : a PangoLayout

Returns : active wrap mode.

92 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_is_wrapped () 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. layout : a PangoLayout Returns : TRUE if any paragraphs had to be wrapped, FALSE otherwise. Since 1.16 enum PangoWrapMode 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. PANGO_WRAP_WORD wrap lines at word boundaries. PANGO_WRAP_CHAR wrap lines at character boundaries. PANGO_WRAP_WORD_CHAR wrap lines at word boundaries, but fall back to character boundaries if there is not enough space for a full word.

PANGO_TYPE_WRAP_MODE

#define PANGO_TYPE_WRAP_MODE(pango_wrap_mode_get_type())

The GObject type for PangoWrapMode. pango_layout_set_ellipsize () 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 ﬁt 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. layout : a PangoLayout ellipsize : the new ellipsization mode for layout Since 1.6 pango_layout_get_ellipsize ()

PangoEllipsizeMode pango_layout_get_ellipsize(PangoLayout *layout); Gets the type of ellipsization being performed for layout. See pango_layout_set_ellipsize() layout : 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

93 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_is_ellipsized () 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. layout : a PangoLayout Returns : TRUE if any paragraphs had to be ellipsized, FALSE otherwise. Since 1.16 enum PangoEllipsizeMode 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 ﬁt to a given width and replaced with an ellipsis. PANGO_ELLIPSIZE_NONE No ellipsization PANGO_ELLIPSIZE_START Omit characters at the start of the text PANGO_ELLIPSIZE_MIDDLE Omit characters in the middle of the text PANGO_ELLIPSIZE_END Omit characters at the end of the text

PANGO_TYPE_ELLIPSIZE_MODE

#define PANGO_TYPE_ELLIPSIZE_MODE(pango_ellipsize_mode_get_type())

The GObject type for PangoEllipsizeMode. pango_layout_set_indent () 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 ﬁrst 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. layout : a PangoLayout. indent : the amount by which to indent. pango_layout_get_indent () int pango_layout_get_indent(PangoLayout *layout);

Gets the paragraph indent width in Pango units. A negative value indicates a hanging indentation. layout : a PangoLayout Returns : the indent in Pango units.

94 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_get_spacing () int pango_layout_get_spacing(PangoLayout *layout);

Gets the amount of spacing between the lines of the layout. layout : a PangoLayout Returns : the spacing in Pango units. pango_layout_set_spacing () void pango_layout_set_spacing(PangoLayout *layout, int spacing);

Sets the amount of spacing in Pango unit between the lines of the layout. layout : a PangoLayout. spacing : the amount of spacing pango_layout_set_justify () 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. layout : a PangoLayout justify : whether the lines in the layout should be justified. pango_layout_get_justify () gboolean pango_layout_get_justify(PangoLayout *layout);

Gets whether each complete line should be stretched to ﬁll the entire width of the layout. layout : a PangoLayout Returns : the justify. pango_layout_set_auto_dir () 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 ﬂag 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. layout : a PangoLayout auto_dir : if TRUE, compute the bidirectional base direction from the layout’s contents. Since 1.4

95 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_get_auto_dir () 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(). layout : a PangoLayout

Returns : TRUE if the bidirectional base direction is computed from the layout’s contents, FALSE otherwise.

Since 1.4 pango_layout_set_alignment () 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. layout : a PangoLayout alignment : the alignment pango_layout_get_alignment ()

PangoAlignment pango_layout_get_alignment(PangoLayout *layout);

Gets the alignment for the layout: how partial lines are positioned within the horizontal space available. layout : a PangoLayout

Returns : the alignment. pango_layout_set_tabs () 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. layout : a PangoLayout tabs : a PangoTabArray, or NULL pango_layout_get_tabs ()

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(). layout : a PangoLayout

Returns : a copy of the tabs for this layout, or NULL.

96 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_set_single_paragraph_mode () 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. layout : a PangoLayout setting : new setting pango_layout_get_single_paragraph_mode () gboolean pango_layout_get_single_paragraph_mode (PangoLayout *layout);

Obtains the value set by pango_layout_set_single_paragraph_mode(). layout : a PangoLayout Returns : TRUE if the layout does not break paragraphs at paragraph separator characters, FALSE otherwise. enum PangoAlignment 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. PANGO_ALIGN_LEFT Put all available space on the right PANGO_ALIGN_CENTER Center the line within the available space PANGO_ALIGN_RIGHT Put all available space on the left

PANGO_TYPE_ALIGNMENT

#define PANGO_TYPE_ALIGNMENT(pango_alignment_get_type())

The GObject type for PangoAlignment. pango_layout_get_unknown_glyphs_count () 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. layout : a PangoLayout Returns : The number of unknown glyphs in layout. Since 1.16

97 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_get_log_attrs () 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. layout : a PangoLayout attrs : location to store a pointer to an array of logical attributes This value must be freed with g_free(). n_attrs : 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 ﬁrst character and the position after the last character.) pango_layout_index_to_pos () 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. layout : a PangoLayout index_ : byte index within layout pos : rectangle in which to store the position of the grapheme pango_layout_index_to_line_x () 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) layout : a PangoLayout index_ : the byte index of a grapheme within the layout. trailing : 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. line : location to store resulting line index. (which will between 0 and pango_layout_get_line_count(layout) - 1) x_pos : location to store resulting position within line (PANGO_SCALE units per device unit)

98 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_xy_to_index () gboolean pango_layout_xy_to_index(PangoLayout *layout, intx, inty, 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. layout : a PangoLayout x : the X offset (in Pango units) from the left edge of the layout. y : the Y offset (in Pango units) from the top edge of the layout index_ : location to store calculated byte index trailing : 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. pango_layout_get_cursor_pos () 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. layout : a PangoLayout index_ : the byte index of the cursor strong_pos : location to store the strong cursor position (may be NULL) weak_pos : location to store the weak cursor position (may be NULL) pango_layout_move_cursor_visually () void pango_layout_move_cursor_visually(PangoLayout *layout, gboolean strong, int old_index, int old_trailing, int direction, int *new_index, int *new_trailing);

99 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS

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. layout : a PangoLayout. strong : 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. old_index : the byte index of the grapheme for the old index old_trailing : 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 : direction to move cursor. A negative value indicates motion to the left. new_index : 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. new_trailing : 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. pango_layout_get_extents () 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. layout : a PangoLayout ink_rect : rectangle used to store the extents of the layout as drawn or NULL to indicate that the result is not needed. logical_rect : rectangle used to store the logical extents of the layout or NULL to indicate that the result is not needed. pango_layout_get_pixel_extents () void pango_layout_get_pixel_extents(PangoLayout *layout, PangoRectangle *ink_rect ←- , PangoRectangle * ←- logical_rect);

100 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS

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 ﬁrst argument to pango_extents_to_pixels()). layout : a PangoLayout ink_rect : rectangle used to store the extents of the layout as drawn or NULL to indicate that the result is not needed. logical_rect : rectangle used to store the logical extents of the layout or NULL to indicate that the result is not needed. pango_layout_get_size () 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(). layout : a PangoLayout width : location to store the logical width, or NULL height : location to store the logical height, or NULL pango_layout_get_pixel_size () 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(). layout : a PangoLayout width : location to store the logical width, or NULL height : location to store the logical height, or NULL pango_layout_get_baseline () int pango_layout_get_baseline(PangoLayout *layout);

Gets the Y position of baseline of the ﬁrst line in layout. layout : a PangoLayout Returns : baseline of ﬁrst line, from top of layout. Since 1.22 pango_layout_get_line_count () int pango_layout_get_line_count(PangoLayout *layout);

Retrieves the count of lines for the layout. layout : PangoLayout Returns : the line count.

101 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_get_line ()

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.). layout : a PangoLayout line : 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. pango_layout_get_line_readonly ()

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.). layout : a PangoLayout line : 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 pango_layout_get_lines ()

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.). layout : a PangoLayout Returns : element-type Pango.LayoutLine): (transfer none. element-type Pango.LayoutLine): (transfer none. pango_layout_get_lines_readonly ()

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.). layout : a PangoLayout Returns : element-type Pango.LayoutLine): (transfer none. element-type Pango.LayoutLine): (transfer none. Since 1.16

102 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_get_iter ()

PangoLayoutIter * pango_layout_get_iter(PangoLayout *layout);

Returns an iterator to iterate over the visual extents of the layout. layout : a PangoLayout Returns : the new PangoLayoutIter that should be freed using pango_layout_iter_free(). pango_layout_iter_copy ()

PangoLayoutIter * pango_layout_iter_copy(PangoLayoutIter *iter);

Copies a PangLayoutIter. iter : 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 pango_layout_iter_free () void pango_layout_iter_free(PangoLayoutIter *iter);

Frees an iterator that’s no longer in use. iter : a PangoLayoutIter, may be NULL pango_layout_iter_next_run () 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. iter : a PangoLayoutIter Returns : whether motion was possible. pango_layout_iter_next_char () 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. iter : a PangoLayoutIter Returns : whether motion was possible. pango_layout_iter_next_cluster () 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. iter : a PangoLayoutIter Returns : whether motion was possible.

103 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_iter_next_line () 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. iter : a PangoLayoutIter

Returns : whether motion was possible. pango_layout_iter_at_last_line () gboolean pango_layout_iter_at_last_line(PangoLayoutIter *iter);

Determines whether iter is on the last line of the layout. iter : a PangoLayoutIter

Returns : TRUE if iter is on the last line. pango_layout_iter_get_index () 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()). iter : a PangoLayoutIter

Returns : current byte index. pango_layout_iter_get_baseline () 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). iter : a PangoLayoutIter

Returns : baseline of current line. pango_layout_iter_get_run ()

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.). iter : a PangoLayoutIter

Returns : the current run.

104 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_iter_get_run_readonly ()

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.). iter : a PangoLayoutIter Returns : the current run, that should not be modiﬁed. Since 1.16 pango_layout_iter_get_line ()

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.). iter : a PangoLayoutIter Returns : the current line. pango_layout_iter_get_line_readonly ()

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.). iter : a PangoLayoutIter Returns : the current line, that should not be modiﬁed. Since 1.16 pango_layout_iter_get_layout ()

PangoLayout * pango_layout_iter_get_layout(PangoLayoutIter *iter); Gets the layout associated with a PangoLayoutIter. iter : a PangoLayoutIter Returns : the layout associated with iter. Since 1.20 pango_layout_iter_get_char_extents () 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. iter : a PangoLayoutIter logical_rect : rectangle to ﬁll with logical extents

105 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_iter_get_cluster_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). iter : a PangoLayoutIter ink_rect : rectangle to ﬁll with ink extents, or NULL logical_rect : rectangle to ﬁll with logical extents, or NULL pango_layout_iter_get_run_extents () 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). iter : a PangoLayoutIter ink_rect : rectangle to ﬁll with ink extents, or NULL logical_rect : rectangle to ﬁll with logical extents, or NULL pango_layout_iter_get_line_yrange () 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). iter : a PangoLayoutIter y0_ : start of line y1_ : end of line pango_layout_iter_get_line_extents () 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(). iter : a PangoLayoutIter ink_rect : rectangle to ﬁll with ink extents, or NULL logical_rect : rectangle to ﬁll with logical extents, or NULL

106 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_iter_get_layout_extents () 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. iter : a PangoLayoutIter ink_rect : rectangle to ﬁll with ink extents, or NULL logical_rect : rectangle to ﬁll with logical extents, or NULL

PangoLayoutLine 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* layout; the parent layout for this line gint start_index; the start of the line as byte index into layout->text gint length; the length of the line in bytes GSList* runs; a list containing the runs of the line in visual order guint is_paragraph_start : 1; %TRUE if this is the first line of the paragraph guint resolved_dir : 3; the resolved PangoDirection of the line

PangoLayoutRun 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 ﬁelds. pango_layout_line_ref ()

PangoLayoutLine * pango_layout_line_ref(PangoLayoutLine *line);

Increase the reference count of a PangoLayoutLine by one. line : a PangoLayoutLine, may be NULL Returns : the line passed in. Since 1.10

107 CHAPTER 1. BASIC PANGO INTERFACES 1.7. LAYOUT OBJECTS pango_layout_line_unref () 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. line : a PangoLayoutLine pango_layout_line_get_extents () 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. line : a PangoLayoutLine ink_rect : rectangle used to store the extents of the glyph string as drawn, or NULL logical_rect : rectangle used to store the logical extents of the glyph string, or NULL pango_layout_line_get_pixel_extents () 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 ﬁrst argument to pango_extents_to_pixels()). layout_line : a PangoLayoutLine ink_rect : rectangle used to store the extents of the glyph string as drawn, or NULL logical_rect : rectangle used to store the logical extents of the glyph string, or NULL pango_layout_line_index_to_x () 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. line : a PangoLayoutLine index_ : byte offset of a grapheme within the layout trailing : 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. x_pos : location to store the x_offset (in Pango unit)

108 CHAPTER 1. BASIC PANGO INTERFACES 1.8. SCRIPTS AND LANGUAGES pango_layout_line_x_to_index () 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 ﬁrst 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. line : a PangoLayoutLine x_pos : the X offset (in Pango units) from the left edge of the line. index_ : location to store calculated byte index for the grapheme in which the user clicked. trailing : 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 pango_layout_line_get_x_ranges () 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. line : a PangoLayoutLine start_index : Start byte index of the logical range. If this value is less than the start index for the line, then the ﬁrst range will extend all the way to the leading edge of the layout. Otherwise it will start at the leading edge of the ﬁrst character. end_index : 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. ranges : out): (array length=n_ranges): (transfer=full. out): (array length=n_ranges): (transfer=full. n_ranges : The number of ranges stored in ranges.

1.8 Scripts and Languages

Name

Scripts and Languages – Identifying writing systems and languages

109 CHAPTER 1. BASIC PANGO INTERFACES 1.8. SCRIPTS AND LANGUAGES

Synopsis 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);

Description 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.

Details enum PangoScript 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 */

110 CHAPTER 1. BASIC PANGO INTERFACES 1.8. SCRIPTS AND LANGUAGES

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 */

111 CHAPTER 1. BASIC PANGO INTERFACES 1.8. SCRIPTS AND LANGUAGES

} PangoScript;

The PangoScript enumeration identiﬁes different writing systems. The values correspond to the names as deﬁned in the Unicode standard. Note that new types may be added in the future. Applica- tions should be ready to handle unknown values. This enumeration is interchangeable with GUnicode- Script. See Unicode Standard Annex #24: Script names.

PANGO_SCRIPT_INVALID_CODE a value never returned from pango_script_for_unichar()

PANGO_SCRIPT_COMMON a character used by multiple different scripts

PANGO_SCRIPT_INHERITED a mark glyph that takes its script from the base glyph to which it is at- tached

PANGO_SCRIPT_ARABIC Arabic

PANGO_SCRIPT_ARMENIAN Armenian

PANGO_SCRIPT_BENGALI Bengali

PANGO_SCRIPT_BOPOMOFO Bopomofo

PANGO_SCRIPT_CHEROKEE Cherokee

PANGO_SCRIPT_COPTIC Coptic

PANGO_SCRIPT_CYRILLIC Cyrillic

PANGO_SCRIPT_DESERET Deseret

PANGO_SCRIPT_DEVANAGARI Devanagari

PANGO_SCRIPT_ETHIOPIC Ethiopic

PANGO_SCRIPT_GEORGIAN Georgian

PANGO_SCRIPT_GOTHIC Gothic

PANGO_SCRIPT_GREEK Greek

PANGO_SCRIPT_GUJARATI Gujarati

PANGO_SCRIPT_GURMUKHI Gurmukhi

PANGO_SCRIPT_HAN Han

PANGO_SCRIPT_HANGUL Hangul

PANGO_SCRIPT_HEBREW Hebrew

PANGO_SCRIPT_HIRAGANA Hiragana

PANGO_SCRIPT_KANNADA Kannada

PANGO_SCRIPT_KATAKANA Katakana

PANGO_SCRIPT_KHMER Khmer

PANGO_SCRIPT_LAO Lao

PANGO_SCRIPT_LATIN Latin

PANGO_SCRIPT_MALAYALAM Malayalam

PANGO_SCRIPT_MONGOLIAN Mongolian

PANGO_SCRIPT_MYANMAR Myanmar

PANGO_SCRIPT_OGHAM Ogham

112 CHAPTER 1. BASIC PANGO INTERFACES 1.8. SCRIPTS AND LANGUAGES

PANGO_SCRIPT_OLD_ITALIC Old Italic PANGO_SCRIPT_ORIYA Oriya PANGO_SCRIPT_RUNIC Runic PANGO_SCRIPT_SINHALA Sinhala PANGO_SCRIPT_SYRIAC Syriac PANGO_SCRIPT_TAMIL Tamil PANGO_SCRIPT_TELUGU Telugu PANGO_SCRIPT_THAANA Thaana PANGO_SCRIPT_THAI Thai PANGO_SCRIPT_TIBETAN Tibetan PANGO_SCRIPT_CANADIAN_ABORIGINAL Canadian Aboriginal PANGO_SCRIPT_YI Yi PANGO_SCRIPT_TAGALOG Tagalog PANGO_SCRIPT_HANUNOO Hanunoo PANGO_SCRIPT_BUHID Buhid PANGO_SCRIPT_TAGBANWA Tagbanwa PANGO_SCRIPT_BRAILLE Braille PANGO_SCRIPT_CYPRIOT Cypriot PANGO_SCRIPT_LIMBU Limbu PANGO_SCRIPT_OSMANYA Osmanya PANGO_SCRIPT_SHAVIAN Shavian PANGO_SCRIPT_LINEAR_B Linear B PANGO_SCRIPT_TAI_LE Tai Le PANGO_SCRIPT_UGARITIC Ugaritic PANGO_SCRIPT_NEW_TAI_LUE New Tai Lue. Since 1.10 PANGO_SCRIPT_BUGINESE Buginese. Since 1.10 PANGO_SCRIPT_GLAGOLITIC Glagolitic. Since 1.10 PANGO_SCRIPT_TIFINAGH Tiﬁnagh. Since 1.10 PANGO_SCRIPT_SYLOTI_NAGRI Syloti Nagri. Since 1.10 PANGO_SCRIPT_OLD_PERSIAN Old Persian. Since 1.10 PANGO_SCRIPT_KHAROSHTHI Kharoshthi. Since 1.10 PANGO_SCRIPT_UNKNOWN an unassigned code point. Since 1.14 PANGO_SCRIPT_BALINESE Balinese. Since 1.14 PANGO_SCRIPT_CUNEIFORM Cuneiform. Since 1.14 PANGO_SCRIPT_PHOENICIAN Phoenician. Since 1.14 PANGO_SCRIPT_PHAGS_PA Phags-pa. Since 1.14

113 CHAPTER 1. BASIC PANGO INTERFACES 1.8. SCRIPTS AND LANGUAGES

PANGO_SCRIPT_NKO N’Ko. Since 1.14 PANGO_SCRIPT_KAYAH_LI Kayah Li. Since 1.20.1 PANGO_SCRIPT_LEPCHA Lepcha. Since 1.20.1 PANGO_SCRIPT_REJANG Rejang. Since 1.20.1 PANGO_SCRIPT_SUNDANESE Sundanese. Since 1.20.1 PANGO_SCRIPT_SAURASHTRA Saurashtra. Since 1.20.1 PANGO_SCRIPT_CHAM Cham. Since 1.20.1 PANGO_SCRIPT_OL_CHIKI Ol Chiki. Since 1.20.1 PANGO_SCRIPT_VAI Vai. Since 1.20.1 PANGO_SCRIPT_CARIAN Carian. Since 1.20.1 PANGO_SCRIPT_LYCIAN Lycian. Since 1.20.1 PANGO_SCRIPT_LYDIAN Lydian. Since 1.20.1

PANGO_TYPE_SCRIPT

#define PANGO_TYPE_SCRIPT(pango_script_get_type())

The GObject type for PangoScript

PangoScriptIter typedef struct _PangoScriptIter PangoScriptIter;

A PangoScriptIter is used to iterate through a string and identify ranges in different scripts. pango_script_for_unichar ()

PangoScript pango_script_for_unichar(gunichar ch);

Looks up the PangoScript for a particular character (as deﬁned 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 undeﬁned. As of Pango 1.18, this function simply returns the return value of g_unichar_get_script(). ch : a Unicode character Returns : the PangoScript for the character. Since 1.4 pango_script_get_sample_language ()

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

114 CHAPTER 1. BASIC PANGO INTERFACES 1.8. SCRIPTS AND LANGUAGES or other separators. This function will return the ﬁrst 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. script : a PangoScript

Returns : a PangoLanguage that is representative of the script, or NULL if no such language exists.

Since 1.4 pango_script_iter_new ()

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(). text : a UTF-8 string length : length of text, or -1 if text is nul-terminated.

Returns : the new script iterator, initialized to point at the ﬁrst 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 pango_script_iter_get_range () 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) iter : a PangoScriptIter start : location to store start position of the range, or NULL end : location to store end position of the range, or NULL script : location to store script for range, or NULL

Since 1.4 pango_script_iter_next () 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. iter : a PangoScriptIter

Returns : TRUE if iter was successfully advanced.

Since 1.4

115 CHAPTER 1. BASIC PANGO INTERFACES 1.8. SCRIPTS AND LANGUAGES pango_script_iter_free () void pango_script_iter_free(PangoScriptIter *iter); Frees a PangoScriptIter created with pango_script_iter_new(). iter : a PangoScriptIter Since 1.4

PangoLanguage typedef struct _PangoLanguage PangoLanguage;

The PangoLanguage structure is used to represent a language. PangoLanguage pointers can be efﬁciently copied and compared with each other.

PANGO_TYPE_LANGUAGE

#define PANGO_TYPE_LANGUAGE(pango_language_get_type ())

The GObject type for PangoLanguage. pango_language_from_string ()

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 efﬁciently copied (copy the pointer) and compared with other language tags (compare the pointer.) This function ﬁrst 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. language : 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. pango_language_to_string () const char * pango_language_to_string(PangoLanguage *language) ←- ;

Gets the RFC-3066 format string representing the given language tag. language : a language tag. Returns : a string representing the language tag. This is owned by Pango and should not be freed. pango_language_matches () 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 preﬁx of the tag, and the character after it in the tag is ’-’. language : a language tag (see pango_language_from_string()), NULL is allowed and matches nothing but ’*’ range_list : 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.

116 CHAPTER 1. BASIC PANGO INTERFACES 1.8. SCRIPTS AND LANGUAGES pango_language_includes_script () 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. language : a PangoLanguage, or NULL script : 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 pango_language_get_scripts () 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. language : a PangoLanguage, or NULL num_scripts : 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_scri- pts, 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 modiﬁed or freed. Since 1.22 pango_language_get_default ()

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,

117 CHAPTER 1. BASIC PANGO INTERFACES 1.9. BIDIRECTIONAL TEXT 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 pango_language_get_sample_string () 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")) language : a PangoLanguage, or NULL

Returns : the sample string. This value is owned by Pango and should not be freed.

1.9 Bidirectional Text

Name

Bidirectional Text – Types and functions to help with handling bidirectional text

Synopsis 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);

Description

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.

118 CHAPTER 1. BASIC PANGO INTERFACES 1.9. BIDIRECTIONAL TEXT

Details enum PangoDirection 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_ﬁnd_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. PANGO_DIRECTION_LTR A strong left-to-right direction PANGO_DIRECTION_RTL A strong right-to-left direction PANGO_DIRECTION_TTB_LTR Deprecated value; treated the same as PANGO_DIRECTION_RTL. PANGO_DIRECTION_TTB_RTL Deprecated value; treated the same as PANGO_DIRECTION_LTR PANGO_DIRECTION_WEAK_LTR A weak left-to-right direction PANGO_DIRECTION_WEAK_RTL A weak right-to-left direction PANGO_DIRECTION_NEUTRAL No direction speciﬁed pango_unichar_direction ()

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 every- thing else. If full Unicode bidirectional type of a character is needed, pango_bidi_type_for_gunichar() can be used instead. ch : a Unicode character Returns : the direction of the character. pango_ﬁnd_base_dir ()

PangoDirection pango_find_base_dir(const gchar *text, gint length);

Searches a string the ﬁrst character that has a strong direction, according to the Unicode bidirectional algorithm. text : the text to process length : length of text in bytes (may be -1 if text is nul-terminated) Returns : The direction corresponding to the ﬁrst strong character. If no such character is found, then PANGO_DIRECTION_NEUTRAL is returned. Since 1.4

119 CHAPTER 1. BASIC PANGO INTERFACES 1.9. BIDIRECTIONAL TEXT pango_get_mirror_char () gboolean pango_get_mirror_char(gunichar ch, gunichar *mirrored_ch);

WARNING

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 mirrore- d_ch. Use g_unichar_get_mirror_char() instead; the docs for that function provide full details. ch : a Unicode character mirrored_ch : location to store the mirrored character Returns : TRUE if ch has a mirrored character and mirrored_ch is ﬁlled in, FALSE otherwise enum PangoBidiType 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 speci- ﬁed by the Unicode bidirectional algorithm. PANGO_BIDI_TYPE_L Left-to-Right PANGO_BIDI_TYPE_LRE Left-to-Right Embedding PANGO_BIDI_TYPE_LRO Left-to-Right Override PANGO_BIDI_TYPE_R Right-to-Left

120 CHAPTER 1. BASIC PANGO INTERFACES 1.10. VERTICAL TEXT

PANGO_BIDI_TYPE_AL Right-to-Left Arabic PANGO_BIDI_TYPE_RLE Right-to-Left Embedding PANGO_BIDI_TYPE_RLO Right-to-Left Override PANGO_BIDI_TYPE_PDF Pop Directional Format PANGO_BIDI_TYPE_EN European Number PANGO_BIDI_TYPE_ES European Number Separator PANGO_BIDI_TYPE_ET European Number Terminator PANGO_BIDI_TYPE_AN Arabic Number PANGO_BIDI_TYPE_CS Common Number Separator PANGO_BIDI_TYPE_NSM Nonspacing Mark PANGO_BIDI_TYPE_BN Boundary Neutral PANGO_BIDI_TYPE_B Paragraph Separator PANGO_BIDI_TYPE_S Segment Separator PANGO_BIDI_TYPE_WS Whitespace PANGO_BIDI_TYPE_ON Other Neutrals Since 1.22 pango_bidi_type_for_unichar ()

PangoBidiType pango_bidi_type_for_unichar(gunichar ch);

Determines the normative bidirectional character type of a character, as speciﬁed in the Unicode Character Database. A simpliﬁed version of this function is available as pango_unichar_get_direction(). ch : a Unicode character Returns : the bidirectional character type, as used in the Unicode bidirectional algorithm. Since 1.22

See Also pango_context_get_base_dir(), pango_context_set_base_dir(), pango_itemize_with_base_dir()

1.10 Vertical Text

Name Vertical Text – Laying text out in vertical directions

Synopsis 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); double pango_gravity_to_rotation (PangoGravity gravity);

121 CHAPTER 1. BASIC PANGO INTERFACES 1.10. VERTICAL TEXT

Description

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().

Details enum PangoGravity 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 PangoMa- trix, 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

PANGO_GRAVITY_SOUTH Glyphs stand upright (default)

PANGO_GRAVITY_EAST Glyphs are rotated 90 degrees clockwise

PANGO_GRAVITY_NORTH Glyphs are upside-down

PANGO_GRAVITY_WEST Glyphs are rotated 90 degrees counter-clockwise

PANGO_GRAVITY_AUTO Gravity is resolved from the context matrix

Since 1.16

122 CHAPTER 1. BASIC PANGO INTERFACES 1.10. VERTICAL TEXT enum PangoGravityHint typedef enum{ PANGO_GRAVITY_HINT_NATURAL, PANGO_GRAVITY_HINT_STRONG, PANGO_GRAVITY_HINT_LINE } PangoGravityHint;

The PangoGravityHint deﬁnes how horizontal scripts should behave in a vertical context. That is, English excerpt in a vertical paragraph for example. See PangoGravity. PANGO_GRAVITY_HINT_NATURAL scripts will take their natural gravity based on the base gravity and the script. This is the default. PANGO_GRAVITY_HINT_STRONG always use the base gravity set, regardless of the script. PANGO_GRAVITY_HINT_LINE 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 ﬂow top-to-bottom for example. Since 1.16

PANGO_GRAVITY_IS_VERTICAL()

#define PANGO_GRAVITY_IS_VERTICAL(gravity)

Whether a PangoGravity represents vertical writing directions. gravity : the PangoGravity to check Since 1.16 pango_gravity_get_for_matrix ()

PangoGravity pango_gravity_get_for_matrix(const PangoMatrix * ←- matrix);

Finds the gravity that best matches the rotation component in a PangoMatrix. matrix : 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 pango_gravity_get_for_script ()

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 Pan- goItem. If base_gravity is PANGO_GRAVITY_AUTO, it is ﬁrst 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. script : PangoScript to query base_gravity : base gravity of the paragraph hint : orientation hint Returns : resolved gravity suitable to use for a run of text Since 1.16

123 CHAPTER 1. BASIC PANGO INTERFACES 1.10. VERTICAL TEXT pango_gravity_to_rotation () 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 : gravity to query

Returns : the rotation value corresponding to gravity. Since 1.16

See Also 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()

124 Chapter 2

Rendering with Pango

2.1 Win32 Fonts and Rendering

Name Win32 Fonts and Rendering – Functions for shape engines to manipulate Win32 fonts

Synopsis #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);

125 CHAPTER 2. RENDERING WITH PANGO 2.1. WIN32 FONTS AND RENDERING

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);

Description 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.

Details PANGO_RENDER_TYPE_WIN32

#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_ﬁnd_map(). pango_win32_get_context ()

PangoContext * pango_win32_get_context(void);

WARNING

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 pango_win32_render () void pango_win32_render(HDC hdc, PangoFont *font, PangoGlyphString *glyphs ←- , gintx, ginty);

Render a PangoGlyphString onto a Windows DC hdc : the device context font : the font in which to draw the string

126 CHAPTER 2. RENDERING WITH PANGO 2.1. WIN32 FONTS AND RENDERING glyphs : the glyph string to draw x : the x position of start of string (in pixels) y : the y position of baseline (in pixels) pango_win32_render_transformed () void pango_win32_render_transformed(HDC hdc, const PangoMatrix * ←- matrix, PangoFont *font, PangoGlyphString *glyphs ←- , intx, inty);

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. hdc : a windows device context matrix : a PangoMatrix, or NULL to use an identity transformation font : the font in which to draw the string glyphs : the glyph string to draw x : the x position of the start of the string (in Pango units in user space coordinates) y : the y position of the baseline (in Pango units in user space coordinates) pango_win32_render_layout_line () void pango_win32_render_layout_line(HDC hdc, PangoLayoutLine *line, intx, inty);

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. hdc : DC to use for uncolored drawing line : a PangoLayoutLine x : the x position of start of string (in pixels) y : the y position of baseline (in pixels) pango_win32_render_layout () void pango_win32_render_layout(HDC hdc, PangoLayout *layout, intx, inty);

Render a PangoLayoutLine onto an X drawable hdc : HDC to use for uncolored drawing layout : a PangoLayout x : the X position of the left of the layout (in pixels) y : the Y position of the top of the layout (in pixels)

127 CHAPTER 2. RENDERING WITH PANGO 2.1. WIN32 FONTS AND RENDERING pango_win32_get_unknown_glyph ()

PangoGlyph pango_win32_get_unknown_glyph(PangoFont *font, gunichar wc);

WARNING

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. font : a PangoFont wc : the Unicode character for which a glyph is needed.

Returns : a glyph index into font pango_win32_font_get_glyph_index () 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. font : a PangoFont. wc : a Unicode character.

Returns : the glyph index for wc. pango_win32_font_select_font () gboolean pango_win32_font_select_font(PangoFont *font, HDC hdc);

Selects the font into the speciﬁed 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. font : a PangoFont from the Win32 backend hdc : a windows device context

Returns : TRUE if the operation succeeded. pango_win32_font_done_font () void pango_win32_font_done_font(PangoFont *font);

Releases any resources allocated by pango_win32_font_done_font() font : a PangoFont from the win32 backend

128 CHAPTER 2. RENDERING WITH PANGO 2.1. WIN32 FONTS AND RENDERING pango_win32_font_get_metrics_factor () 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. font : a PangoFont from the win32 backend

Returns : factor to multiply logical units by to get Pango units. pango_win32_get_debug_ﬂag () gboolean pango_win32_get_debug_flag(void);

Returns whether debugging is turned on.

Returns : TRUE if debugging is turned on.

Since 1.2 pango_win32_get_dc ()

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.

PangoWin32FontCache typedef struct _PangoWin32FontCache PangoWin32FontCache;

A PangoWin32FontCache caches HFONTs by their LOGFONT descriptions. pango_win32_font_cache_new ()

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(). 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. cache : a PangoWin32FontCache

129 CHAPTER 2. RENDERING WITH PANGO 2.1. WIN32 FONTS AND RENDERING pango_win32_font_cache_load ()

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 cache : a PangoWin32FontCache logfont : 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(). pango_win32_font_cache_loadw ()

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 cache : a PangoWin32FontCache logfont : 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 pango_win32_font_cache_unload () void pango_win32_font_cache_unload(PangoWin32FontCache * ←- cache, HFONT hfont);

Frees a font structure previously loaded with pango_win32_font_cache_load(). cache : a PangoWin32FontCache hfont : the HFONT to unload pango_win32_font_map_for_display ()

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. pango_win32_shutdown_display () void pango_win32_shutdown_display(void);

Free cached resources.

130 CHAPTER 2. RENDERING WITH PANGO 2.1. WIN32 FONTS AND RENDERING pango_win32_font_map_get_font_cache ()

PangoWin32FontCache * pango_win32_font_map_get_font_cache (PangoFontMap *font_map);

Obtains the font cache associated with the given font map. font_map : a PangoWin32FontMap.

Returns : the PangoWin32FontCache of font_map. pango_win32_font_logfont ()

LOGFONTA * pango_win32_font_logfont(PangoFont *font);

Determine the LOGFONTA struct for the speciﬁed font. Note that Pango internally uses LOG- FONTW 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 Pango- Font, 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. font : a PangoFont which must be from the Win32 backend

Returns : A newly allocated LOGFONTA struct. It must be freed with g_free(). pango_win32_font_logfontw ()

LOGFONTW * pango_win32_font_logfontw(PangoFont *font);

Determine the LOGFONTW struct for the speciﬁed font. 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 pango_win32_font_description_from_logfont ()

PangoFontDescription * pango_win32_font_description_from_logfont (const LOGFONTA *lfp);

Creates a PangoFontDescription that matches the speciﬁed LOGFONTA. The face name, italicness and weight ﬁelds in the LOGFONTA are used to set up the resulting Pan- goFontDescription. 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. lfp : a LOGFONTA

Returns : the newly allocated PangoFontDescription, which should be freed using pango_font_description_free()

Since 1.12

131 CHAPTER 2. RENDERING WITH PANGO 2.2. FREETYPE FONTS AND RENDERING pango_win32_font_description_from_logfontw ()

PangoFontDescription * pango_win32_font_description_from_logfontw (const LOGFONTW *lfp);

Creates a PangoFontDescription that matches the speciﬁed LOGFONTW. The face name, italicness and weight ﬁelds 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. lfp : a LOGFONTW Returns : the newly allocated PangoFontDescription, which should be freed using pango_font_description_free() Since 1.16

2.2 FreeType Fonts and Rendering

Name FreeType Fonts and Rendering – Functions for shape engines to manipulate FreeType fonts

Synopsis 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

132 CHAPTER 2. RENDERING WITH PANGO 2.2. FREETYPE FONTS AND RENDERING

(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);

Object Hierarchy GObject +----PangoFontMap +----PangoFcFontMap +----PangoFT2FontMap

Description

The macros and functions in this section are used to access fonts and render text to bitmaps using the FreeType 2 library.

Details PangoFT2FontMap typedef struct _PangoFT2FontMap PangoFT2FontMap;

The PangoFT2FontMap is the PangoFontMap implementation for FreeType fonts.

PANGO_RENDER_TYPE_FT2

#define PANGO_RENDER_TYPE_FT2"PangoRenderFT2"

WARNING

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.

133 CHAPTER 2. RENDERING WITH PANGO 2.2. FREETYPE FONTS AND RENDERING pango_ft2_font_map_new ()

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 ﬁnished with it.

Since 1.2 pango_ft2_font_map_set_resolution () void pango_ft2_font_map_set_resolution(PangoFT2FontMap *fontmap ←- , double dpi_x, double dpi_y);

Sets the horizontal and vertical resolutions for the fontmap. fontmap : a PangoFT2Fontmap dpi_x : dots per inch in the X direction dpi_y : dots per inch in the Y direction

Since 1.2 pango_ft2_font_map_create_context ()

PangoContext * pango_ft2_font_map_create_context(PangoFT2FontMap *fontmap ←- );

WARNING

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. fontmap : a PangoFT2Fontmap

Returns : the newly created context; free with g_object_unref().

Since 1.2

PangoFT2SubstituteFunc () void( *PangoFT2SubstituteFunc)(FcPattern *pattern, gpointer data);

Function type for doing ﬁnal conﬁg tweaking on prepared FcPatterns. pattern : the FcPattern to tweak. data : user data.

134 CHAPTER 2. RENDERING WITH PANGO 2.2. FREETYPE FONTS AND RENDERING pango_ft2_font_map_set_default_substitute () 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. fontmap : a PangoFT2FontMap func : function to call to to do final config tweaking on FcPattern objects. data : data to pass to func notify : function to call when data is no longer used.

Since 1.2 pango_ft2_font_map_substitute_changed () 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. fontmap : a PangoFT2Fontmap

Since 1.2 pango_ft2_get_context ()

PangoContext * pango_ft2_get_context(double dpi_x, double dpi_y);

WARNING

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. dpi_x : the horizontal DPI of the target device dpi_y : the vertical DPI of the target device

Returns : the new PangoContext

135 CHAPTER 2. RENDERING WITH PANGO 2.2. FREETYPE FONTS AND RENDERING pango_ft2_render () void pango_ft2_render(FT_Bitmap *bitmap, PangoFont *font, PangoGlyphString *glyphs ←- , gintx, ginty);

Renders a PangoGlyphString onto a FreeType2 bitmap. bitmap : the FreeType2 bitmap onto which to draw the string font : the font in which to draw the string glyphs : the glyph string to draw x : the x position of the start of the string (in pixels) y : the y position of the baseline (in pixels) pango_ft2_render_transformed () void pango_ft2_render_transformed(FT_Bitmap *bitmap, const PangoMatrix * ←- matrix, PangoFont *font, PangoGlyphString *glyphs ←- , intx, inty);

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. bitmap : the FreeType2 bitmap onto which to draw the string matrix : a PangoMatrix, or NULL to use an identity transformation font : the font in which to draw the string glyphs : the glyph string to draw x : the x position of the start of the string (in Pango units in user space coordinates) y : the y position of the baseline (in Pango units in user space coordinates) Since 1.6 pango_ft2_render_layout_line () void pango_ft2_render_layout_line(FT_Bitmap *bitmap, PangoLayoutLine *line, intx, inty);

Render a PangoLayoutLine onto a FreeType2 bitmap bitmap : a FT_Bitmap to render the line onto line : a PangoLayoutLine x : the x position of start of string (in pixels) y : the y position of baseline (in pixels)

136 CHAPTER 2. RENDERING WITH PANGO 2.2. FREETYPE FONTS AND RENDERING pango_ft2_render_layout_line_subpixel () void pango_ft2_render_layout_line_subpixel (FT_Bitmap *bitmap, PangoLayoutLine *line, intx, inty);

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.) bitmap : a FT_Bitmap to render the line onto line : a PangoLayoutLine x : the x position of start of string (in Pango units) y : the y position of baseline (in Pango units)

Since 1.6 pango_ft2_render_layout () void pango_ft2_render_layout(FT_Bitmap *bitmap, PangoLayout *layout, intx, inty);

Render a PangoLayout onto a FreeType2 bitmap bitmap : a FT_Bitmap to render the layout onto layout : a PangoLayout x : the X position of the left of the layout (in pixels) y : the Y position of the top of the layout (in pixels) pango_ft2_render_layout_subpixel () void pango_ft2_render_layout_subpixel(FT_Bitmap *bitmap, PangoLayout *layout, intx, inty);

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.) bitmap : a FT_Bitmap to render the layout onto layout : a PangoLayout x : the X position of the left of the layout (in Pango units) y : the Y position of the top of the layout (in Pango units)

Since 1.6

137 CHAPTER 2. RENDERING WITH PANGO 2.2. FREETYPE FONTS AND RENDERING pango_ft2_get_unknown_glyph ()

PangoGlyph pango_ft2_get_unknown_glyph(PangoFont *font);

WARNING

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. font : a PangoFont Returns : a glyph index into font, or PANGO_GLYPH_EMPTY pango_ft2_font_get_kerning () int pango_ft2_font_get_kerning(PangoFont *font, PangoGlyph left, PangoGlyph right);

WARNING

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. font : a PangoFont left : the left PangoGlyph right : the right PangoGlyph Returns : The amount of kerning (in Pango units) to apply for the given combination of glyphs. pango_ft2_font_get_face ()

FT_Face pango_ft2_font_get_face(PangoFont *font);

WARNING

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.

138 CHAPTER 2. RENDERING WITH PANGO 2.2. FREETYPE FONTS AND RENDERING

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(). font : a PangoFont Returns : a pointer to a FT_Face structure, with the size set correctly, or NULL if font is NULL. pango_ft2_font_get_coverage ()

PangoCoverage * pango_ft2_font_get_coverage(PangoFont *font, PangoLanguage *language) ←- ;

WARNING

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. font : a PangoFT2Font. language : a language tag. Returns : a PangoCoverage. pango_ft2_font_map_for_display ()

PangoFontMap * pango_ft2_font_map_for_display(void);

WARNING

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. pango_ft2_shutdown_display () void pango_ft2_shutdown_display(void);

WARNING

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.

139 CHAPTER 2. RENDERING WITH PANGO 2.3. XFT FONTS AND RENDERING

2.3 Xft Fonts and Rendering

Name Xft Fonts and Rendering – Font handling and rendering with the Xft backend

Synopsis 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,

140 CHAPTER 2. RENDERING WITH PANGO 2.3. XFT FONTS AND RENDERING

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);

Object Hierarchy GObject +----PangoFont +----PangoFcFont +----PangoXftFont

GObject +----PangoFontMap +----PangoFcFontMap +----PangoXftFontMap

GObject +----PangoRenderer +----PangoXftRenderer

Properties "display" gpointer : Write / Construct Only "screen" gint : Write / Construct Only

Description 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 ’com- posite_trapezoids’.

Details PangoXftFont

141 CHAPTER 2. RENDERING WITH PANGO 2.3. XFT FONTS AND RENDERING

typedef struct _PangoXftFont PangoXftFont;

PangoXftFont is an implementation of PangoFcFont using the Xft library for rendering. It is used in conjunction with PangoXftFontMap.

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.

PANGO_RENDER_TYPE_XFT

#define PANGO_RENDER_TYPE_XFT"PangoRenderXft"

WARNING

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. pango_xft_get_context ()

PangoContext * pango_xft_get_context(Display *display, int screen);

WARNING

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. display : an X display. screen : an X screen. Returns : the new PangoContext. pango_xft_get_font_map ()

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. display : an X display

142 CHAPTER 2. RENDERING WITH PANGO 2.3. XFT FONTS AND RENDERING screen : the screen number of a screen within display Returns : a PangoFontMap object, owned by Pango. Since 1.2 pango_xft_set_default_substitute () 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. display : an X Display screen : the screen number of a screen within display func : function to call to to do final config tweaking on FcPattern objects. data : data to pass to func notify : function to call when data is no longer used. Since 1.2

PangoXftSubstituteFunc () void( *PangoXftSubstituteFunc)(FcPattern *pattern, gpointer data);

Function type for doing ﬁnal conﬁg tweaking on prepared FcPatterns. pattern : the FcPattern to tweak. data : user data. pango_xft_substitute_changed () 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. display : an X Display screen : the screen number of a screen within display Since 1.2 pango_xft_shutdown_display () 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. display : an X display screen : the screen number of a screen within display Since 1.2

143 CHAPTER 2. RENDERING WITH PANGO 2.3. XFT FONTS AND RENDERING pango_xft_font_get_font ()

XftFont * pango_xft_font_get_font(PangoFont *font); Returns the XftFont of a font. font : a PangoFont. Returns : the XftFont associated to font, or NULL if font is NULL. pango_xft_font_get_display ()

Display * pango_xft_font_get_display(PangoFont *font); Returns the X display of the XftFont of a font. font : a PangoFont. Returns : the X display of the XftFont associated to font. pango_xft_font_has_char () gboolean pango_xft_font_has_char(PangoFont *font, gunichar wc);

WARNING

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. font : a PangoFont for the Xft backend wc : Unicode codepoint to look up Returns : TRUE if font has the requested codepoint. Since 1.2 pango_xft_font_lock_face ()

FT_Face pango_xft_font_lock_face(PangoFont *font);

WARNING

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. font : a PangoFont. Returns : the FreeType FT_Face associated with font. Since 1.2

144 CHAPTER 2. RENDERING WITH PANGO 2.3. XFT FONTS AND RENDERING pango_xft_font_unlock_face () void pango_xft_font_unlock_face(PangoFont *font);

WARNING

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. font : a PangoFont.

Since 1.2 pango_xft_font_get_glyph () guint pango_xft_font_get_glyph(PangoFont *font, gunichar wc);

WARNING

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. font : a PangoFont for the Xft backend wc : Unicode codepoint to look up

Returns : the glyph index, or 0, if the Unicode character does not exist in the font.

Since 1.2 pango_xft_font_get_unknown_glyph ()

PangoGlyph pango_xft_font_get_unknown_glyph(PangoFont *font, gunichar wc);

WARNING

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.

145 CHAPTER 2. RENDERING WITH PANGO 2.3. XFT FONTS AND RENDERING font : a PangoFont. wc : the Unicode character for which a glyph is needed. Returns : a glyph index into font.

PangoXftRenderer 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

PangoXftRendererClass 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 composite_trapezoids () draw the speciﬁed trapezoids using the current color and other attributes for part composite_glyphs () draw the speciﬁed glyphs using the current foreground color and other foreground attributes Since 1.8 pango_xft_renderer_new ()

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. display : an X display screen : 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 pango_xft_renderer_set_draw () 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. xftrenderer : a PangoXftRenderer draw : a XftDraw Since 1.8

146 CHAPTER 2. RENDERING WITH PANGO 2.3. XFT FONTS AND RENDERING pango_xft_renderer_set_default_color () void pango_xft_renderer_set_default_color (PangoXftRenderer * ←- xftrenderer, PangoColor * ←- default_color);

Sets the default foreground color for a XftRenderer. xftrenderer : a XftRenderer default_color : the default foreground color Since 1.8 pango_xft_render () void pango_xft_render(XftDraw *draw, XftColor *color, PangoFont *font, PangoGlyphString *glyphs ←- , gintx, ginty);

Renders a PangoGlyphString onto an XftDraw object wrapping an X drawable. draw : the XftDraw object. color : the color in which to draw the string font : the font in which to draw the string glyphs : the glyph string to draw x : the x position of start of string (in pixels) y : the y position of baseline (in pixels) pango_xft_picture_render () void pango_xft_picture_render(Display *display, Picture src_picture, Picture dest_picture, PangoFont *font, PangoGlyphString *glyphs ←- , gintx, ginty);

Renders a PangoGlyphString onto an Xrender Picture object. display : an X display src_picture : the source picture to draw the string with dest_picture : the destination picture to draw the string onto font : the font in which to draw the string glyphs : the glyph string to draw x : the x position of start of string (in pixels) y : the y position of baseline (in pixels)

147 CHAPTER 2. RENDERING WITH PANGO 2.3. XFT FONTS AND RENDERING pango_xft_render_transformed () void pango_xft_render_transformed(XftDraw *draw, XftColor *color, PangoMatrix *matrix, PangoFont *font, PangoGlyphString *glyphs ←- , intx, inty);

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. draw : an XftDraw color : the color in which to draw the glyphs matrix : a PangoMatrix, or NULL to use an identity transformation font : the font in which to draw the string glyphs : the glyph string to draw x : the x position of the start of the string (in Pango units in user space coordinates) y : the y position of the baseline (in Pango units in user space coordinates)

Since 1.8 pango_xft_render_layout_line () void pango_xft_render_layout_line(XftDraw *draw, XftColor *color, PangoLayoutLine *line, intx, inty);

Render a PangoLayoutLine onto a XftDraw draw : an XftDraw color : the foreground color in which to draw the layout line (may be overridden by color attributes) line : a PangoLayoutLine x : the x position of start of string (in Pango units) y : the y position of baseline (in Pango units)

Since 1.8 pango_xft_render_layout () void pango_xft_render_layout(XftDraw *draw, XftColor *color, PangoLayout *layout, intx, inty);

Render a PangoLayout onto a XftDraw draw : an XftDraw

148 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING color : the foreground color in which to draw the layout (may be overridden by color attributes) layout : a PangoLayout x : the X position of the left of the layout (in Pango units) y : the Y position of the top of the layout (in Pango units) Since 1.8

Property Details The "display" property

"display" gpointer: Write/ Construct Only

The display being rendered to.

The "screen" property

"screen" gint: Write/ Construct Only

The screen being rendered to. Allowed values: >= 0 Default value: 0

2.4 Cairo Rendering

Name Cairo Rendering – Rendering with the Cairo backend

Synopsis 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

149 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING

(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);

Object Hierarchy GInterface +----PangoCairoFont

GInterface +----PangoCairoFontMap

Prerequisites PangoCairoFont requires PangoFont. PangoCairoFontMap requires PangoFontMap.

Description 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

150 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING allow rendering to images, to PDF ﬁles, 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 ﬂoating point units used in Cairo divide by PANGO_SCALE.

151 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING

Example 2.1 Using Pango with Cairo #include #include static void draw_text(cairo_t *cr) { #define RADIUS 150 #define N_WORDS 10 #define FONT"Sans Bold 27" PangoLayout *layout; PangoFontDescription *desc; inti; /* Center coordinates on the middle of the region we are drawing */ cairo_translate(cr, RADIUS, RADIUS); /* Createa 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 ina 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; 152 } return 0; } CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING

Figure 2.1 Output of Example 2.1

Details PangoCairoFont 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

PangoCairoFontMap 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 pango_cairo_font_map_get_default ()

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

153 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING pango_cairo_font_map_set_default () 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(). fontmap : The new default font map, or NULL

Since 1.22 pango_cairo_font_map_new ()

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 pango_cairo_font_map_new_for_font_type ()

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(). fonttype : 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 pango_cairo_font_map_get_font_type () cairo_font_type_t pango_cairo_font_map_get_font_type(PangoCairoFontMap * ←- fontmap);

Gets the type of Cairo font backend that fontmap uses. fontmap : a PangoCairoFontMap

Returns : the cairo_font_type_t cairo font backend type

Since 1.18

154 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING pango_cairo_font_map_set_resolution () void pango_cairo_font_map_set_resolution(PangoCairoFontMap * ←- fontmap, double dpi);

Sets the resolution for the fontmap. This is a scale factor between points speciﬁed in a PangoFontDe- scription and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3). fontmap : a PangoCairoFontMap dpi : the resolution in "dots per inch". (Physical inches aren’t actually involved; the terminology is conventional.)

Since 1.10 pango_cairo_font_map_get_resolution () double pango_cairo_font_map_get_resolution(PangoCairoFontMap * ←- fontmap);

Gets the resolution for the fontmap. See pango_cairo_font_map_set_resolution() fontmap : a PangoCairoFontMap

Returns : the resolution in "dots per inch"

Since 1.10 pango_cairo_font_map_create_context ()

PangoContext * pango_cairo_font_map_create_context(PangoCairoFontMap * ←- fontmap);

WARNING

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. fontmap : a PangoCairoFontMap

Returns : the newly created context; free with g_object_unref().

Since 1.10 pango_cairo_font_get_scaled_font () 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(). font : a PangoFont from a PangoCairoFontMap

Returns : the cairo_scaled_font_t used by font, or NULL if font is NULL.

Since 1.18

155 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING pango_cairo_context_set_resolution () void pango_cairo_context_set_resolution(PangoContext *context, double dpi);

Sets the resolution for the context. This is a scale factor between points speciﬁed in a PangoFontDe- scription and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3). context : a PangoContext, from a pangocairo font map dpi : 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 pango_cairo_context_get_resolution () double pango_cairo_context_get_resolution(PangoContext *context);

Gets the resolution for the context. See pango_cairo_context_set_resolution() context : 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 pango_cairo_context_set_font_options () 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. context : a PangoContext, from a pangocairo font map options : a cairo_font_options_t, or NULL to unset any previously set options. A copy is made.

Since 1.10 pango_cairo_context_get_font_options () 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() 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 modiﬁed or freed.

Since 1.10

156 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING

PangoCairoShapeRendererFunc () 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. cr : a Cairo context with current point set to where the shape should be rendered attr : the PANGO_ATTR_SHAPE to render do_path : whether only the shape path should be appended to current path of cr and no ﬁlling/stroking done. This will be set to TRUE when called from pango_cairo_layout_path() and pango_cairo_layout_line_path() rendering functions. data : user data passed to pango_cairo_context_set_shape_renderer() 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. context : a PangoContext, from a pangocairo font map func : Callback function for rendering attributes of type PANGO_ATTR_SHAPE, or NULL to disable shape rendering. data : User data that will be passed to func. dnotify : Callback that will be called when the context is freed to release data, or NULL.

Since 1.18 pango_cairo_context_get_shape_renderer ()

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. context : a PangoContext, from a pangocairo font map data : 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

157 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING pango_cairo_create_context ()

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. cr : a Cairo context

Returns : the newly created PangoContext. Free with g_object_unref().

Since 1.22 pango_cairo_update_context () 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. cr : a Cairo context context : a PangoContext, from a pangocairo font map

Since 1.10 pango_cairo_create_layout ()

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 inefﬁcient since it creates a separate PangoContext object for each layout. This might matter in an application that was laying out large amounts of text. cr : a Cairo context

Returns : the newly created PangoLayout. Free with g_object_unref().

Since 1.10 pango_cairo_update_layout () 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. cr : a Cairo context layout : a PangoLayout, from pango_cairo_create_layout()

Since 1.10

158 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING pango_cairo_show_glyph_string () void pango_cairo_show_glyph_string(cairo_t *cr, PangoFont *font, PangoGlyphString *glyphs ←- );

Draws the glyphs in glyphs in the speciﬁed cairo context. The origin of the glyphs (the left edge of the baseline) will be drawn at the current point of the cairo context. cr : a Cairo context font : a PangoFont from a PangoCairoFontMap glyphs : a PangoGlyphString Since 1.10 pango_cairo_show_glyph_item () 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. cr : a Cairo context text : the UTF-8 text that glyph_item refers to glyph_item : a PangoGlyphItem Since 1.22 pango_cairo_show_layout_line () 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. cr : a Cairo context line : a PangoLayoutLine Since 1.10 pango_cairo_show_layout () 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. cr : a Cairo context layout : a Pango layout Since 1.10

159 CHAPTER 2. RENDERING WITH PANGO 2.4. CAIRO RENDERING pango_cairo_show_error_underline () void pango_cairo_show_error_underline(cairo_t *cr, doublex, doubley, double width, double height);

Draw a squiggly line in the speciﬁed 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) cr : a Cairo context x : The X coordinate of one corner of the rectangle y : The Y coordinate of one corner of the rectangle width : Non-negative width of the rectangle height : Non-negative height of the rectangle Since 1.14 pango_cairo_glyph_string_path () 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. cr : a Cairo context font : a PangoFont from a PangoCairoFontMap glyphs : a PangoGlyphString Since 1.10 pango_cairo_layout_line_path () 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. cr : a Cairo context line : a PangoLayoutLine Since 1.10 pango_cairo_layout_path () 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. cr : a Cairo context layout : a Pango layout Since 1.10

160 CHAPTER 2. RENDERING WITH PANGO 2.5. ATSUI FONTS pango_cairo_error_underline_path () void pango_cairo_error_underline_path(cairo_t *cr, doublex, doubley, double width, double height);

Add a squiggly line to the current path in the speciﬁed 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) cr : a Cairo context x : The X coordinate of one corner of the rectangle y : The Y coordinate of one corner of the rectangle width : Non-negative width of the rectangle height : Non-negative height of the rectangle

Since 1.14

2.5 ATSUI Fonts

Name ATSUI Fonts – Font handling with ATSUI fonts

Synopsis #define PANGO_RENDER_TYPE_ATSUI ATSUFontID pango_atsui_font_get_atsu_font_id (PangoATSUIFont *font);

Description The macros and functions in this section are used to access fonts natively on MacOS systems using the ATSUI text rendering subsystem.

Details PANGO_RENDER_TYPE_ATSUI

#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_ﬁnd_map(). pango_atsui_font_get_atsu_font_id ()

ATSUFontID pango_atsui_font_get_atsu_font_id(PangoATSUIFont *font);

Returns the ATSUFontID of a font. font : A PangoATSUIFont

Returns : the ATSUFontID associated to font.

Since 1.18

161 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND

2.6 Deprecated X font backend

Name Deprecated X font backend – Font handling and rendering with the deprecated X font backend

Synopsis #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,

162 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND

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);

Description 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 unpre- dictable results. Use the Xft or Cairo backend instead.

Details PANGO_RENDER_TYPE_X

#define PANGO_RENDER_TYPE_X"PangoRenderX"

WARNING

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_ﬁnd_map(). pango_x_get_context ()

PangoContext * pango_x_get_context(Display *display);

WARNING

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. display : an X display (As returned by XOpenDisplay().)

163 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND

Returns : the new PangoContext. pango_x_context_set_funcs () void pango_x_context_set_funcs(PangoContext *context, PangoGetGCFunc ←- get_gc_func, PangoFreeGCFunc ←- free_gc_func);

WARNING

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. context : a PangoContext. get_gc_func : function called to create a new GC for a given color. free_gc_func : function called to free a GC created with get_gc_func.

PangoGetGCFunc ()

GC( *PangoGetGCFunc)(PangoContext *context, PangoColor *color, GC base_gc);

WARNING

PangoGetGCFunc is deprecated and should not be used in newly-written code.

Speciﬁes the type of the function used to create a new GC for a given color. context : a PangoContext. color : the color to create a new GC for. base_gc : the GC to base the new GC on.

Returns : the new GC.

PangoFreeGCFunc () void( *PangoFreeGCFunc)(PangoContext *context, GC gc);

164 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND

WARNING

PangoFreeGCFunc is deprecated and should not be used in newly-written code.

Speciﬁes the type of the function used to free a GC created with the corresponding PangoGetGCFunc function. context : a PangoContext. gc : the GC to free. pango_x_render () void pango_x_render(Display *display, Drawabled, GC gc, PangoFont *font, PangoGlyphString *glyphs ←- , gintx, ginty);

WARNING

pango_x_render is deprecated and should not be used in newly-written code.

Renders a PangoGlyphString onto an X drawable. display : the X display. d : the drawable on which to draw string. gc : the graphics context. font : the font in which to draw the string. glyphs : the glyph string to draw. x : the x position of start of string (in pixels). y : the y position of baseline (in pixels). pango_x_render_layout_line () void pango_x_render_layout_line(Display *display, Drawable drawable, GC gc, PangoLayoutLine *line, intx, inty);

165 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND

WARNING

pango_x_render_layout_line is deprecated and should not be used in newly- written code.

Renders a PangoLayoutLine onto an X drawable. display : the X display. drawable : the drawable on which to draw. gc : GC to use for uncolored drawing. line : a PangoLayoutLine. x : the x position of start of string (in pixels). y : the y position of baseline (in pixels). pango_x_render_layout () void pango_x_render_layout(Display *display, Drawable drawable, GC gc, PangoLayout *layout, intx, inty);

WARNING

pango_x_render_layout is deprecated and should not be used in newly-written code.

Renders a PangoLayout onto an X drawable. display : the X display. drawable : the drawable on which to draw. gc : GC to use for uncolored drawing. layout : a PangoLayout. x : the x position of the left of the layout (in pixels). y : the y position of the top of the layout (in pixels).

PangoXSubfont typedef guint16 PangoXSubfont;

166 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND

WARNING

PangoXSubfont is deprecated and should not be used in newly-written code.

The PangoXSubFont type is an integer ID that identiﬁes one particular X font within the fonts referenced in a PangoFont.

PANGO_X_MAKE_GLYPH()

#define PANGO_X_MAKE_GLYPH(subfont,index_) ((subfont)<<16 | (index_))

WARNING

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. subfont : a PangoXSubfont index index_ : the index of a character within an X font.

PANGO_X_GLYPH_SUBFONT()

#define PANGO_X_GLYPH_SUBFONT(glyph) ((glyph)>>16)

WARNING

PANGO_X_GLYPH_SUBFONT is deprecated and should not be used in newly-written code.

Extract the subfont index from a glyph index. glyph : a PangoGlyphIndex

PANGO_X_GLYPH_INDEX()

#define PANGO_X_GLYPH_INDEX(glyph) ((glyph) & 0xffff)

WARNING

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.

167 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND glyph : a PangoGlyphIndex pango_x_load_font ()

PangoFont * pango_x_load_font(Display *display, const gchar *spec);

WARNING

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 speciﬁcation. 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. display : the X display. spec : a comma-separated list of XLFD’s. Returns : a new PangoFont. pango_x_get_unknown_glyph ()

PangoGlyph pango_x_get_unknown_glyph(PangoFont *font);

WARNING

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.) font : a PangoFont. Returns : a glyph index into font. pango_x_has_glyph () gboolean pango_x_has_glyph(PangoFont *font, PangoGlyph glyph);

WARNING

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.

168 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND font : a PangoFont which must be from the X backend. glyph : the index of a glyph in the font. (Formed using the PANGO_X_MAKE_GLYPH macro)

Returns : TRUE if the glyph is present. pango_x_list_subfonts () int pango_x_list_subfonts(PangoFont *font, char **charsets, int n_charsets, PangoXSubfont ** ←- subfont_ids, int **subfont_charsets);

WARNING

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 ﬁrst by charset, and then within each charset, by the order of fonts in the font speciﬁcation. font : a PangoFont. charsets : the charsets to list subfonts for. n_charsets : the number of charsets in charsets. subfont_ids : location to store a pointer to an array of subfont IDs for each found subfont; the result must be freed using g_free(). subfont_charsets : 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. pango_x_font_map_for_display ()

PangoFontMap * pango_x_font_map_for_display(Display *display);

WARNING

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(). display : an X Display.

Returns : a PangoXFontMap for display.

169 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND pango_x_shutdown_display () void pango_x_shutdown_display(Display *display);

WARNING

pango_x_shutdown_display is deprecated and should not be used in newly- written code.

Free cached resources for the given X display structure. display : an X Display pango_x_font_map_get_font_cache ()

PangoXFontCache * pango_x_font_map_get_font_cache(PangoFontMap *font_map);

WARNING

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. font_map : a PangoXFontMap.

Returns : the PangoXFontCache of font_map. pango_x_font_subfont_xlfd () char * pango_x_font_subfont_xlfd(PangoFont *font, PangoXSubfont subfont_id ←- );

WARNING

pango_x_font_subfont_xlfd is deprecated and should not be used in newly- written code.

Determines the X Logical Font Description for the speciﬁed subfont. font : a PangoFont which must be from the X backend. subfont_id : the id of a subfont within the font.

Returns : A newly-allocated string containing the XLFD for the subfont. This string must be freed with g_free().

170 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND pango_x_ﬁnd_ﬁrst_subfont () gboolean pango_x_find_first_subfont(PangoFont *font, char **charsets, int n_charsets, PangoXSubfont *rfont);

WARNING

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 ﬁrst one in *rfont. font : A PangoFont. charsets : An array of charsets. n_charsets : The number of charsets in charsets. rfont : A pointer to a PangoXSubfont.

Returns : TRUE if *rfont now contains a font. pango_x_font_get_unknown_glyph ()

PangoGlyph pango_x_font_get_unknown_glyph(PangoFont *font, gunichar wc);

WARNING

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. font : a PangoFont. wc : the Unicode character for which a glyph is needed.

Returns : a glyph index into font. pango_x_apply_ligatures () gboolean pango_x_apply_ligatures(PangoFont *font, PangoXSubfont subfont, gunichar **glyphs, int *n_glyphs, int **clusters);

171 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND

WARNING

pango_x_apply_ligatures is deprecated and should not be used in newly-written code.

Previously did subfont-speciﬁc ligation. Now a no-op. font : unused subfont : unused glyphs : unused n_glyphs : unused clusters : unused Returns : FALSE, always. pango_x_fallback_shape () void pango_x_fallback_shape(PangoFont *font, PangoGlyphString *glyphs ←- , const char *text, int n_chars);

WARNING

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. font : A PangoFont. glyphs : A pointer to a PangoGlyphString. text : UTF-8 string. n_chars : Number of UTF-8 seqs in text.

PangoXFontCache typedef struct _PangoXFontCache PangoXFontCache;

WARNING

PangoXFontCache is deprecated and should not be used in newly-written code.

A PangoXFontCache caches XFontStructs for a single display by their XLFD name.

172 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND pango_x_font_cache_new ()

PangoXFontCache * pango_x_font_cache_new(Display *display);

WARNING

pango_x_font_cache_new is deprecated and should not be used in newly-written code.

Creates a font cache for the speciﬁed display. display : an X display.

Returns : The newly allocated PangoXFontCache, which should be freed with pango_x_font_cache_free(). pango_x_font_cache_free () void pango_x_font_cache_free(PangoXFontCache *cache);

WARNING

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. cache : a PangoXFontCache pango_x_font_cache_load ()

XFontStruct * pango_x_font_cache_load(PangoXFontCache *cache, const char *xlfd);

WARNING

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. cache : a PangoXFontCache xlfd : 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().

173 CHAPTER 2. RENDERING WITH PANGO 2.6. DEPRECATED X FONT BACKEND pango_x_font_cache_unload () void pango_x_font_cache_unload(PangoXFontCache *cache, XFontStruct *fs);

WARNING

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(). cache : a PangoXFontCache fs : the font structure to unload

174 Chapter 3

Low Level Functionality

3.1 PangoRenderer

Name PangoRenderer – Rendering driver base class

Synopsis 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_,

175 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.1. PANGORENDERER

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);

Object Hierarchy GObject +----PangoRenderer +----PangoXftRenderer

Description PangoRenderer is a base class that contains the necessary logic for rendering a PangoLayout or Pan- goLayoutLine. By subclassing PangoRenderer and overriding operations such as draw_glyphs and draw_rectangle, renderers for particular font backends and destinations can be created.

Details PangoRenderer typedef struct{ PangoMatrix *matrix;/* May be NULL */ } PangoRenderer;

PangoRenderer is a base class for objects that are used to render Pango objects such as PangoGlyph- String and PangoLayout.

PangoMatrix* matrix; the current transformation matrix for the Renderer; may be NULL, which should be treated the same as the identity matrix.

Since 1.8 enum PangoRenderPart typedef enum { PANGO_RENDER_PART_FOREGROUND, PANGO_RENDER_PART_BACKGROUND, PANGO_RENDER_PART_UNDERLINE,

176 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.1. PANGORENDERER

PANGO_RENDER_PART_STRIKETHROUGH } PangoRenderPart;

PangoRenderPart deﬁnes different items to render for such purposes as setting colors. PANGO_RENDER_PART_FOREGROUND the text itself PANGO_RENDER_PART_BACKGROUND the area behind the text PANGO_RENDER_PART_UNDERLINE underlines PANGO_RENDER_PART_STRIKETHROUGH strikethrough lines Since 1.8

PANGO_TYPE_RENDER_PART

#define PANGO_TYPE_RENDER_PART(pango_render_part_get_type())

The GObject type for PangoRenderPart.

PangoRendererClass 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, intx, inty); void( *draw_rectangle)(PangoRenderer *renderer, PangoRenderPart part, intx, inty, int width, int height); void( *draw_error_underline)(PangoRenderer *renderer, intx, inty, int width, int height);

/* Nothing is drawn for shaped glyphs unless this is implemented */ void( *draw_shape)(PangoRenderer *renderer, PangoAttrShape *attr, intx, inty);

/* 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,

177 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.1. PANGORENDERER

doublex, doubley);

/* 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, intx, inty); } PangoRendererClass;

Class structure for PangoRenderer. draw_glyphs () draws a PangoGlyphString draw_rectangle () draws a rectangle draw_error_underline () draws a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. draw_shape () draw content for a glyph shaped with PangoAttrShape. x, y are the coordinates of the left edge of the baseline, in user coordinates. draw_trapezoid () draws a trapezoidal filled area draw_glyph () draws a single glyph part_changed () do renderer specific processing when rendering attributes change begin () Do renderer-specific initialization before drawing end () Do renderer-specific cleanup after drawing prepare_run () updates the renderer for a new run draw_glyph_item () draws a PangoGlyphItem Since 1.8 pango_renderer_draw_layout () void pango_renderer_draw_layout(PangoRenderer *renderer, PangoLayout *layout, intx, inty);

Draws layout with the speciﬁed PangoRenderer. renderer : a PangoRenderer

178 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.1. PANGORENDERER layout : a PangoLayout x : X position of left edge of baseline, in user space coordinates in Pango units. y : Y position of left edge of baseline, in user space coordinates in Pango units. Since 1.8 pango_renderer_draw_layout_line () void pango_renderer_draw_layout_line(PangoRenderer *renderer, PangoLayoutLine *line, intx, inty);

Draws line with the speciﬁed PangoRenderer. renderer : a PangoRenderer line : a PangoLayoutLine x : X position of left edge of baseline, in user space coordinates in Pango units. y : Y position of left edge of baseline, in user space coordinates in Pango units. Since 1.8 pango_renderer_draw_glyphs () void pango_renderer_draw_glyphs(PangoRenderer *renderer, PangoFont *font, PangoGlyphString *glyphs ←- , intx, inty);

Draws the glyphs in glyphs with the speciﬁed PangoRenderer. renderer : a PangoRenderer font : a PangoFont glyphs : a PangoGlyphString x : X position of left edge of baseline, in user space coordinates in Pango units. y : Y position of left edge of baseline, in user space coordinates in Pango units. Since 1.8 pango_renderer_draw_glyph_item () void pango_renderer_draw_glyph_item(PangoRenderer *renderer, const char *text, PangoGlyphItem * ←- glyph_item, intx, inty);

Draws the glyphs in glyph_item with the speciﬁed 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().

179 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.1. PANGORENDERER renderer : a PangoRenderer text : the UTF-8 text that glyph_item refers to, or NULL glyph_item : a PangoGlyphItem x : X position of left edge of baseline, in user space coordinates in Pango units. y : Y position of left edge of baseline, in user space coordinates in Pango units.

Since 1.22 pango_renderer_draw_rectangle () void pango_renderer_draw_rectangle(PangoRenderer *renderer, PangoRenderPart part, intx, inty, int width, int height);

Draws an axis-aligned rectangle in user space coordinates with the speciﬁed PangoRenderer. This should be called while renderer is already active. Use pango_renderer_activate() to activate a renderer. renderer : a PangoRenderer part : type of object this rectangle is part of x : X position at which to draw rectangle, in user space coordinates in Pango units y : Y position at which to draw rectangle, in user space coordinates in Pango units width : width of rectangle in Pango units in user space coordinates height : height of rectangle in Pango units in user space coordinates

Since 1.8 pango_renderer_draw_error_underline () void pango_renderer_draw_error_underline(PangoRenderer *renderer, intx, inty, 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. renderer : a PangoRenderer x : X coordinate of underline, in Pango units in user coordinate system y : Y coordinate of underline, in Pango units in user coordinate system width : width of underline, in Pango units in user coordinate system height : height of underline, in Pango units in user coordinate system

Since 1.8

180 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.1. PANGORENDERER pango_renderer_draw_trapezoid () 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. renderer : a PangoRenderer part : type of object this trapezoid is part of y1_ : Y coordinate of top of trapezoid x11 : X coordinate of left end of top of trapezoid x21 : X coordinate of right end of top of trapezoid y2 : Y coordinate of bottom of trapezoid x12 : X coordinate of left end of bottom of trapezoid x22 : X coordinate of right end of bottom of trapezoid Since 1.8 pango_renderer_draw_glyph () void pango_renderer_draw_glyph(PangoRenderer *renderer, PangoFont *font, PangoGlyph glyph, doublex, doubley);

Draws a single glyph with coordinates in device space. renderer : a PangoRenderer font : a PangoFont glyph : the glyph index of a single glyph x : X coordinate of left edge of baseline of glyph y : Y coordinate of left edge of baseline of glyph Since 1.8 pango_renderer_activate () 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. renderer : a PangoRenderer Since 1.8

181 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.1. PANGORENDERER pango_renderer_deactivate () void pango_renderer_deactivate(PangoRenderer *renderer) ←- ;

Cleans up after rendering operations on renderer. See docs for pango_renderer_activate(). renderer : a PangoRenderer

Since 1.8 pango_renderer_part_changed () 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 Pan- goRenderer 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()) renderer : a PangoRenderer part : the part for which rendering has changed.

Since 1.8 pango_renderer_set_color () void pango_renderer_set_color(PangoRenderer *renderer, PangoRenderPart part, const PangoColor *color) ←- ;

Sets the color for part of the rendering. renderer : a PangoRenderer part : the part to change the color of color : the new color or NULL to unset the current color

Since 1.8 pango_renderer_get_color ()

PangoColor * pango_renderer_get_color(PangoRenderer *renderer, PangoRenderPart part);

Gets the current rendering color for the speciﬁed part. renderer : a PangoRenderer part : the part to get the color for

Returns : the color for the speciﬁed part, or NULL if it hasn’t been set and should be inherited from the environment.

Since 1.8

182 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.2. PANGOFCFONTMAP pango_renderer_set_matrix () void pango_renderer_set_matrix(PangoRenderer *renderer, const PangoMatrix * ←- matrix);

Sets the transformation matrix that will be applied when rendering. renderer : a PangoRenderer matrix : a PangoMatrix, or NULL to unset any existing matrix. (No matrix set is the same as setting the identity matrix.) Since 1.8 pango_renderer_get_matrix () const PangoMatrix * pango_renderer_get_matrix(PangoRenderer *renderer) ←- ;

Gets the transformation matrix that will be applied when rendering. See pango_renderer_set_matrix(). renderer : 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 modiﬁed or freed. Since 1.8 pango_renderer_get_layout ()

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 modiﬁed while still being rendered. renderer : a PangoRenderer Returns : the layout, or NULL if no layout is being rendered using renderer at this time. Since 1.20 pango_renderer_get_layout_line ()

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 modiﬁed while still being rendered. renderer : a PangoRenderer Returns : the layout line, or NULL if no layout line is being rendered using renderer at this time. Since 1.20

3.2 PangoFcFontMap

Name PangoFcFontMap – Base fontmap class for Fontconﬁg-based backends

183 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.2. PANGOFCFONTMAP

Synopsis 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);

Object Hierarchy GObject +----PangoFontMap +----PangoFcFontMap +----PangoFT2FontMap +----PangoXftFontMap

Description PangoFcFontMap is a base class for font map implementations using the Fontconﬁg 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.

Details PangoFcFontMap typedef struct _PangoFcFontMap PangoFcFontMap;

184 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.2. PANGOFCFONTMAP

PangoFcFontMap is a base class for font map implementations using the Fontconﬁg and FreeType libraries. To create a new backend using Fontconﬁg and FreeType, you derive from this class and implement a new_font() virtual function that creates an instance deriving from PangoFcFont.

PangoFcFontMapClass 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. default_substitute () 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(). new_font () 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(). get_resolution () 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. context_key_get () 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. context_key_copy () Copies a context key. Pango uses this to make a persistant copy of the value returned from context_key_get. context_key_free () Frees a context key copied with context_key_copy. context_key_hash () Gets a hash value for a context key context_key_equal () Compares two context keys for equality. fontset_key_substitute () 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)

185 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.2. PANGOFCFONTMAP create_font () Creates a new PangoFcFont for the speciﬁed 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) pango_fc_font_map_create_context ()

PangoContext * pango_fc_font_map_create_context(PangoFcFontMap * ←- fcfontmap);

WARNING

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. fcfontmap : a PangoFcFontMap

Returns : a new PangoContext

Since 1.4

PangoFcDecoderFindFunc ()

PangoFcDecoder * (*PangoFcDecoderFindFunc)(FcPattern *pattern, gpointer user_data);

Callback function passed to pango_fc_font_map_add_decoder_ﬁnd_func(). pattern : a fully resolved FcPattern specifying the font on the system user_data : user data passed to pango_fc_font_map_add_decoder_ﬁnd_func()

Returns : a new reference to a custom decoder for this pattern, or NULL if the default decoder handling should be used. pango_fc_font_map_add_decoder_ﬁnd_func () 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-speciﬁc encodings for various fonts. fcfontmap : The PangoFcFontMap to add this method to. findfunc : The PangoFcDecoderFindFunc callback function

186 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.2. PANGOFCFONTMAP user_data : User data. dnotify : A GDestroyNotify callback that will be called when the fontmap is ﬁnalized and the decoder is released. Since 1.6. pango_fc_font_map_ﬁnd_decoder ()

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_ﬁnd_func(). fcfontmap : The PangoFcFontMap to use. pattern : The FcPattern to ﬁnd the decoder for. Returns : a newly created PangoFcDecoder object or NULL if no decoder is set for pattern. Since 1.26. pango_fc_font_map_cache_clear () 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 fontconﬁg has been reinitialized to new conﬁguration. fcfontmap : a PangoFcFontmap Since 1.4 pango_fc_font_map_shutdown () 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. fcfontmap : a PangoFcFontmap Since 1.4 pango_fc_font_description_from_pattern ()

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. pattern : a FcPattern include_size : 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

187 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.2. PANGOFCFONTMAP

PANGO_FC_GRAVITY

#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

PANGO_FC_VERSION

#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

PANGO_FC_PRGNAME

#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

PangoFcFontsetKey typedef struct _PangoFcFontsetKey PangoFcFontsetKey;

An opaque structure containing all the information needed for loading a fontset with the PangoFc fontmap. Since 1.24 pango_fc_fontset_key_get_context_key () gpointer pango_fc_fontset_key_get_context_key (const PangoFcFontsetKey ←- *key);

Gets the context key member of key. key : the font key Returns : the context key, which is owned by key and should not be modiﬁed. Since 1.24 pango_fc_fontset_key_get_description () const PangoFontDescription * pango_fc_fontset_key_get_description (const PangoFcFontsetKey ←- *key);

Gets the font description of key.

188 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.2. PANGOFCFONTMAP key : the fontset key Returns : the font description, which is owned by key and should not be modiﬁed. Since 1.24 pango_fc_fontset_key_get_language ()

PangoLanguage * pango_fc_fontset_key_get_language(const PangoFcFontsetKey ←- *key);

Gets the language member of key. key : the fontset key Returns : the language Since 1.24 pango_fc_fontset_key_get_matrix () const PangoMatrix * pango_fc_fontset_key_get_matrix(const PangoFcFontsetKey ←- *key);

Gets the matrix member of key. key : the fontset key Returns : the matrix, which is owned by key and should not be modiﬁed. Since 1.24 pango_fc_fontset_key_get_absolute_size () 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. key : the fontset key Returns : the pixel size of key. Since 1.24 pango_fc_fontset_key_get_resolution () double pango_fc_fontset_key_get_resolution(const PangoFcFontsetKey ←- *key);

Gets the resolution of key key : the fontset key Returns : the resolution of key Since 1.24

PangoFcFontKey typedef struct _PangoFcFontKey PangoFcFontKey;

An opaque structure containing all the information needed for loading a font with the PangoFc fontmap. Since 1.24

189 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.3. PANGOFCFONT pango_fc_font_key_get_context_key () gpointer pango_fc_font_key_get_context_key(const PangoFcFontKey * ←- key);

Gets the context key member of key. key : the font key Returns : the context key, which is owned by key and should not be modiﬁed. Since 1.24 pango_fc_font_key_get_matrix () const PangoMatrix * pango_fc_font_key_get_matrix(const PangoFcFontKey * ←- key);

Gets the matrix member of key. key : the font key Returns : the matrix, which is owned by key and should not be modiﬁed. Since 1.24 pango_fc_font_key_get_pattern () const FcPattern * pango_fc_font_key_get_pattern(const PangoFcFontKey * ←- key);

Gets the fontconﬁg pattern member of key. key : the font key Returns : the pattern, which is owned by key and should not be modiﬁed. Since 1.24

See Also

PangoFcFontMap The base class for font maps; creating a new Fontconﬁg-based backend involves deriving from both PangoFcFontMap and PangoFcFont..

193 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.4. PANGOFCDECODER

3.4 PangoFcDecoder

Name PangoFcDecoder – Custom font encoding handling

Synopsis PangoFcDecoder; PangoFcDecoderClass; FcCharSet * pango_fc_decoder_get_charset (PangoFcDecoder *decoder, PangoFcFont *fcfont); PangoGlyph pango_fc_decoder_get_glyph (PangoFcDecoder *decoder, PangoFcFont *fcfont, guint32 wc);

Object Hierarchy GObject +----PangoFcDecoder

Description PangoFcDecoder represents a decoder that an application provides for handling a font that is encoded in a custom way.

Details PangoFcDecoder typedef struct _PangoFcDecoder PangoFcDecoder;

PangoFcDecoder is a virtual base class that implementations will inherit from. It’s the interface that is used to deﬁne 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_ﬁnd_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

PangoFcDecoderClass typedef struct{ FcCharSet *(*get_charset)(PangoFcDecoder *decoder, PangoFcFont *fcfont); PangoGlyph( *get_glyph)(PangoFcDecoder *decoder, PangoFcFont *fcfont, guint32 wc); } PangoFcDecoderClass;

Class structure for PangoFcDecoder. get_charset () 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. get_glyph () This returns a single PangoGlyph for a given Unicode code point.

Since 1.6

194 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING pango_fc_decoder_get_charset ()

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 modiﬁed or freed. decoder : a PangoFcDecoder fcfont : the PangoFcFont to query. Returns : the FcCharset for fcfont; must not be modiﬁed or freed. Since 1.6 pango_fc_decoder_get_glyph ()

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.) decoder : a PangoFcDecoder fcfont : a PangoFcFont to query. wc : 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

3.5 OpenType Font Handling

Name OpenType Font Handling – Obtaining information from OpenType tables

Stability Level Unstable, unless otherwise indicated

Synopsis 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

195 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING

#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,

196 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING

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);

Object Hierarchy GObject +----PangoOTInfo

GObject +----PangoOTRuleset

Description Functions and macros in this section are used to implement the OpenType Layout features and algorithms. These are mostly useful when writing Fontconﬁg-based shaping engines

Details PangoOTTag 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 Pan- goOTTags manually.

PangoOTInfo typedef struct _PangoOTInfo PangoOTInfo;

The PangoOTInfo struct contains the various tables associated with an OpenType font. It contains only private ﬁelds and should only be accessed via the pango_ot_info_* functions which are documented below. To obtain a PangoOTInfo, use pango_ot_info_new().

197 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING

PangoOTBuffer 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 ﬁelds and should only be accessed via the pango_ot_buffer_* functions which are documented below. To obtain a PangoOTBuffer, use pango_ot_buffer_new().

PangoOTGlyph typedef struct{ guint glyph; guint properties; guint cluster; gushort component; gushort ligID; gushort property_cache;/* Internal */ } PangoOTGlyph;

The PangoOTGlyph structure represents a single glyph together with information used for Open- Type layout processing of the glyph. It contains the following ﬁelds. guint glyph; the glyph itself. guint properties; the properties value, identifying which features should be applied on this glyph. See pango_ruleset_add_feature(). guint cluster; the cluster that this glyph belongs to. gushort component; a component value, set by the OpenType layout engine. gushort ligID; a ligature index value, set by the OpenType layout engine. gushort property_cache; for internal use.

PangoOTRuleset 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().

PangoOTRulesetDescription 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 PangoOTRule- set 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().

198 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING

PangoScript script; a PangoScript. PangoLanguage* language; a PangoLanguage. const PangoOTFeatureMap* static_gsub_features; static map of GSUB features, or NULL. guint n_static_gsub_features; length of static_gsub_features, or 0. const PangoOTFeatureMap* static_gpos_features; static map of GPOS features, or NULL. guint n_static_gpos_features; length of static_gpos_features, or 0. const PangoOTFeatureMap* other_features; 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 n_other_features; length of other_features, or 0. Since 1.18 enum PangoOTTableType 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. PANGO_OT_TABLE_GSUB The GSUB table. PANGO_OT_TABLE_GPOS The GPOS table.

PangoOTFeatureMap 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_name[5]; feature tag in represented as four-letter ASCII string. gulong property_bit; the property bit to use for this feature. See pango_ot_ruleset_add_feature() for details. Since 1.18

PANGO_OT_TAG_MAKE()

#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_TA- G() macro from FreeType. c1 : First character. c2 : Second character. c3 : Third character. c4 : Fourth character.

199 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING

PANGO_OT_TAG_MAKE_FROM_STRING()

#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 expres- sion, as it dereferences pointers. s : The string representation of the tag.

PANGO_OT_ALL_GLYPHS

#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

PANGO_OT_NO_FEATURE

#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_ﬁnd_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

PANGO_OT_NO_SCRIPT

#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_ﬁnd_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

PANGO_OT_DEFAULT_LANGUAGE

#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

PANGO_OT_TAG_DEFAULT_LANGUAGE

#define PANGO_OT_TAG_DEFAULT_LANGUAGE PANGO_OT_TAG_MAKE(’d’, ’f’, ’l’, ’t’)

This is a PangoOTTag representing a special language tag ’dﬂt’. 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_ﬁnd_language() as that function falls back to returning default language-system if the requested language tag is not found. Since 1.18

200 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING

PANGO_OT_TAG_DEFAULT_SCRIPT

#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 pango_ot_info_get ()

PangoOTInfo * pango_ot_info_get(FT_Face face);

Returns the PangoOTInfo structure for the given FreeType font face. face : a FT_Face. Returns : the PangoOTInfo for face. This object will have the same lifetime as face. Since 1.2 pango_ot_info_ﬁnd_script () 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. info : a PangoOTInfo. table_type : the table type to obtain information about. script_tag : the tag of the script to find. script_index : location to store the index of the script, or NULL. Returns : TRUE if the script was found. pango_ot_info_find_language () 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 lang- uage_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 ’dﬂt’ 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.

201 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING info : a PangoOTInfo. table_type : the table type to obtain information about. script_index : the index of the script whose languages are searched. language_tag : the tag of the language to ﬁnd. language_index : location to store the index of the language, or NULL. required_feature_index : location to store the required feature index of the language, or NULL.

Returns : TRUE if the language was found. pango_ot_info_ﬁnd_feature () 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. info : a PangoOTInfo. table_type : the table type to obtain information about. feature_tag : the tag of the feature to ﬁnd. script_index : the index of the script. language_index : the index of the language whose features are searched, or PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script. feature_index : location to store the index of the feature, or NULL.

Returns : TRUE if the feature was found. pango_ot_info_list_scripts ()

PangoOTTag * pango_ot_info_list_scripts(PangoOTInfo *info, PangoOTTableType ←- table_type);

Obtains the list of available scripts. info : a PangoOTInfo. table_type : 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().

202 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING pango_ot_info_list_languages ()

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. info : a PangoOTInfo. table_type : the table type to obtain information about. script_index : the index of the script to list languages for. language_tag : unused parameter. Returns : a newly-allocated zero-terminated array containing the tags of the available languages. Should be freed using g_free(). pango_ot_info_list_features ()

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. info : a PangoOTInfo. table_type : the table type to obtain information about. tag : unused parameter. script_index : the index of the script to obtain information about. language_index : 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(). pango_ot_buffer_new ()

PangoOTBuffer * pango_ot_buffer_new(PangoFcFont *font);

Creates a new PangoOTBuffer for the given OpenType font. font : a PangoFcFont Returns : the newly allocated PangoOTBuffer, which should be freed with pango_ot_buffer_destroy(). Since 1.4 pango_ot_buffer_destroy () void pango_ot_buffer_destroy(PangoOTBuffer *buffer);

Destroys a PangoOTBuffer and free all associated memory. buffer : a PangoOTBuffer Since 1.4

203 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING pango_ot_buffer_clear () void pango_ot_buffer_clear(PangoOTBuffer *buffer);

Empties a PangoOTBuffer, make it ready to add glyphs to. buffer : a PangoOTBuffer

Since 1.4 pango_ot_buffer_add_glyph () 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(). buffer : a PangoOTBuffer glyph : the glyph index to add, like a PangoGlyph properties : the glyph properties cluster : the cluster that this glyph belongs to

Since 1.4 pango_ot_buffer_set_rtl () 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. buffer : a PangoOTBuffer rtl : TRUE for right-to-left text

Since 1.4 pango_ot_buffer_set_zero_width_marks () 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. buffer : a PangoOTBuffer zero_width_marks : TRUE if characters with a mark class should be forced to zero width.

Since 1.6

204 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING pango_ot_buffer_get_glyphs () 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 modiﬁed. buffer : a PangoOTBuffer glyphs : location to store the array of glyphs, or NULL n_glyphs : location to store the number of glyphs, or NULL Since 1.4 pango_ot_buffer_output () 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. buffer : a PangoOTBuffer glyphs : a PangoGlyphString Since 1.4 pango_ot_ruleset_get_for_description () 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 modiﬁed or destroyed. The static feature map members of desc should be alive as long as info is. info : a PangoOTInfo. desc : a PangoOTRulesetDescription. Returns : the PangoOTRuleset for desc. This object will have the same lifetime as info. Since 1.18 pango_ot_ruleset_new ()

PangoOTRuleset * pango_ot_ruleset_new(PangoOTInfo *info);

Creates a new PangoOTRuleset for the given OpenType info. info : a PangoOTInfo. Returns : the newly allocated PangoOTRuleset, which should be freed with g_object_unref().

205 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING pango_ot_ruleset_new_for ()

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:

• Find the PangoOTTag script and language tags associated with script and language using pango_ot_tag_from_script() and pango_ot_tag_from_language(),

• For each of table types 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(),

• For found language-systems, if they have required feature index, add that feature to the ruleset using pango_ot_ruleset_add_feature(),

• Remember found script and language indices for both table types, and use them in future 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. info : a PangoOTInfo. script : a PangoScript. language : a PangoLanguage.

Returns : the newly allocated PangoOTRuleset, which should be freed with g_object_unref().

Since 1.18 pango_ot_ruleset_new_from_description ()

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/G- POS 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. info : a PangoOTInfo. desc : a PangoOTRulesetDescription.

Returns : the newly allocated PangoOTRuleset, which should be freed with g_object_unref().

Since 1.18

206 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING pango_ot_ruleset_add_feature () void pango_ot_ruleset_add_feature(PangoOTRuleset *ruleset, PangoOTTableType ←- table_type, guint feature_index, gulong property_bit);

Adds a feature to the ruleset. ruleset : a PangoOTRuleset. table_type : the table type to add a feature to. feature_index : the index of the feature to add. property_bit : 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. pango_ot_ruleset_maybe_add_feature () 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. ruleset : a PangoOTRuleset. table_type : the table type to add a feature to. feature_tag : the tag of the feature to add. property_bit : 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 pango_ot_ruleset_maybe_add_features () 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. ruleset : a PangoOTRuleset. table_type : the table type to add features to. features : array of feature name and property bits to add. n_features : number of feature records in features array. Returns : The number of features in features that were found and added to ruleset. Since 1.18

207 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING pango_ot_ruleset_get_feature_count () 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. ruleset : a PangoOTRuleset. n_gsub_features : location to store number of GSUB features, or NULL. n_gpos_features : location to store number of GPOS features, or NULL.

Returns : Total number of features in the ruleset.

Since 1.18 pango_ot_ruleset_substitute () void pango_ot_ruleset_substitute(const PangoOTRuleset * ←- ruleset, PangoOTBuffer *buffer);

Performs the OpenType GSUB substitution on buffer using the features in ruleset ruleset : a PangoOTRuleset. buffer : a PangoOTBuffer.

Since 1.4 pango_ot_ruleset_position () void pango_ot_ruleset_position(const PangoOTRuleset * ←- ruleset, PangoOTBuffer *buffer);

Performs the OpenType GPOS positioning on buffer using the features in ruleset ruleset : a PangoOTRuleset. buffer : a PangoOTBuffer.

Since 1.4 pango_ot_ruleset_description_copy ()

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. desc : ruleset description to copy

Returns : the newly allocated PangoOTRulesetDescription, which should be freed with pango_ot_ruleset_description_free().

Since 1.18

208 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.5. OPENTYPE FONT HANDLING pango_ot_ruleset_description_equal () 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.) desc1 : a ruleset description desc2 : a ruleset description

Returns : TRUE if two ruleset descriptions are identical, FALSE otherwise.

Since 1.18 pango_ot_ruleset_description_free () void pango_ot_ruleset_description_free( ←- PangoOTRulesetDescription *desc);

Frees a ruleset description allocated by pango_ot_ruleset_description_copy(). desc : an allocated PangoOTRulesetDescription

Since 1.18 pango_ot_ruleset_description_hash () 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(). desc : a ruleset description

Returns : the hash value.

Since 1.18 pango_ot_tag_from_language ()

PangoOTTag pango_ot_tag_from_language(PangoLanguage *language) ←- ;

Finds the OpenType language-system tag best describing language. 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

209 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.6. COVERAGE MAPS pango_ot_tag_from_script ()

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 deﬁned 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’. script : A PangoScript Returns : PangoOTTag corresponding to script or PANGO_OT_TAG_DEFAULT_SCRIPT if none found. Since 1.18 pango_ot_tag_to_language ()

PangoLanguage * pango_ot_tag_to_language(PangoOTTag language_tag) ←- ;

Finds a PangoLanguage corresponding to language_tag. 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 pango_ot_tag_to_script ()

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’. script_tag : A PangoOTTag OpenType script tag Returns : PangoScript corresponding to script_tag or PANGO_SCRIPT_UNKNOWN if none found. Since 1.18

3.6 Coverage Maps

Name Coverage Maps – Unicode character range coverage storage

Synopsis 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);

210 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.6. COVERAGE MAPS

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);

Description

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.

Details enum PangoCoverageLevel 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.

PANGO_COVERAGE_NONE The character is not representable with the font.

PANGO_COVERAGE_FALLBACK 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.

PANGO_COVERAGE_APPROXIMATE The character is represented as basically the correct graphical form, but with a stylistic variant inappropriate for the current script.

PANGO_COVERAGE_EXACT The character is represented as the correct graphical form.

PANGO_TYPE_COVERAGE_LEVEL

#define PANGO_TYPE_COVERAGE_LEVEL(pango_coverage_level_get_type())

The GObject type for PangoCoverageLevel.

PangoCoverage typedef struct _PangoCoverage PangoCoverage;

The PangoCoverage structure represents a map from Unicode characters to PangoCoverageLevel. It is an opaque structure with no public ﬁelds.

211 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.6. COVERAGE MAPS pango_coverage_new ()

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(). pango_coverage_ref ()

PangoCoverage * pango_coverage_ref(PangoCoverage *coverage) ←- ;

Increase the reference count on the PangoCoverage by one coverage : a PangoCoverage Returns : coverage pango_coverage_unref () 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. coverage : a PangoCoverage pango_coverage_copy ()

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.) coverage : a PangoCoverage Returns : the newly allocated PangoCoverage, with a reference count of one, which should be freed with pango_coverage_unref(). pango_coverage_get ()

PangoCoverageLevel pango_coverage_get(PangoCoverage *coverage, int index_);

Determine whether a particular index is covered by coverage coverage : a PangoCoverage index_ : the index to check Returns : the coverage level of coverage for character index_. pango_coverage_max () 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. coverage : a PangoCoverage other : another PangoCoverage

212 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.7. ENGINES pango_coverage_set () void pango_coverage_set(PangoCoverage *coverage, int index_, PangoCoverageLevel level ←- );

Modify a particular index within coverage coverage : a PangoCoverage index_ : the index to modify level : the new level for index_ pango_coverage_to_bytes () void pango_coverage_to_bytes(PangoCoverage *coverage, guchar **bytes, int *n_bytes);

Convert a PangoCoverage structure into a ﬂat binary format coverage : a PangoCoverage bytes : location to store result (must be freed with g_free()) n_bytes : location to store size of result pango_coverage_from_bytes ()

PangoCoverage * pango_coverage_from_bytes(guchar *bytes, int n_bytes);

Convert data generated from pango_converage_to_bytes() back to a PangoCoverage bytes : binary data representing a PangoCoverage n_bytes : the size of bytes in bytes

Returns : a newly allocated PangoCoverage, or NULL if the data was invalid.

3.7 Engines

Name Engines – Language-speciﬁc and rendering-system-speciﬁc processing

Synopsis 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);

213 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.7. ENGINES

Object Hierarchy GObject +----PangoEngine +----PangoEngineLang +----PangoEngineShape

Description 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.

Details PangoEngineInfo 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 ﬁelds: const gchar* id; a unique string ID for the engine. const gchar* engine_type; a string identifying the engine type. const gchar* render_type; a string identifying the render type.

PangoEngineScriptInfo* scripts; array of scripts this engine supports. gint n_scripts; number of items in scripts.

PangoEngineScriptInfo typedef struct{ PangoScript script; const gchar *langs; } PangoEngineScriptInfo;

The PangoEngineScriptInfo structure contains information about how the shaper covers a particular script.

PangoScript script; a PangoScript. The value PANGO_SCRIPT_COMMON has the special meaning here of "all scripts" const gchar* langs; 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 speciﬁc for the language for a given code point. An entry in this list of "*" indicates that this engine is speciﬁc to all languages for this range.

214 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.7. ENGINES

PangoEngine typedef struct _PangoEngine PangoEngine;

PangoEngine is the base class for all types of language and script speciﬁc engines. It has no functionality by itself.

PangoEngineClass typedef struct{ } PangoEngineClass;

Class structure for PangoEngine

PANGO_RENDER_TYPE_NONE

#define PANGO_RENDER_TYPE_NONE"PangoRenderNone"

A string constant deﬁning the render type for engines that are not rendering-system speciﬁc. script_engine_list () 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. engines : location to store a pointer to an array of engines. n_engines : location to store the number of elements in engines. script_engine_init () void script_engine_init(GTypeModule *module);

Function to be provided by a module to register any GObject types in the module. module : a GTypeModule structure used to associate any GObject types created in this module with the module. script_engine_exit () void script_engine_exit(void);

Function to be provided by the module that is called when the module is unloading. Frequently does nothing. script_engine_create ()

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. id : the ID of an engine as reported by script_engine_list. Returns : a newly created PangoEngine of the speciﬁed 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 misconﬁguration or bugs in the driver routine are encountered.)

215 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.8. PANGOENGINELANG

3.8 PangoEngineLang

Name

PangoEngineLang – Rendering-system independent script engines

Stability Level

Unstable, unless otherwise indicated

Synopsis PangoEngineLang; PangoEngineLangClass; #define PANGO_ENGINE_TYPE_LANG #define PANGO_ENGINE_LANG_DEFINE_TYPE (name, prefix, class_init, instance_init)

Object Hierarchy GObject +----PangoEngine +----PangoEngineLang

Description

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().

Details PangoEngineLang 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 Pango- EngineLang could be provided for Thai to implement the dictionary-based word boundary lookups needed for that language.

PangoEngineLangClass typedef struct{ void( *script_break)(PangoEngineLang *engine, const char *text, int len, PangoAnalysis *analysis, PangoLogAttr *attrs, int attrs_len); } PangoEngineLangClass;

Class structure for PangoEngineLang script_break () 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.

216 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.9. PANGOENGINESHAPE

PANGO_ENGINE_TYPE_LANG

#define PANGO_ENGINE_TYPE_LANG"PangoEngineLang"

A string constant deﬁning the engine type for language engines. These engines derive from Pango- EngineLang.

PANGO_ENGINE_LANG_DEFINE_TYPE()

#define PANGO_ENGINE_LANG_DEFINE_TYPE(name, prefix, class_init, ←- instance_init)

Outputs the necessary code for GObject type registration for a PangoEngineLang class deﬁned in a module. Two static symbols are deﬁned. static GType prefix_type; static void prefix_register_type(GTypeModule module);

PangoEngine *engine= g_object_new(prefix_type, NULL); name : Name of the the type to register (for example:, ArabicEngineFc prefix : Preﬁx for symbols that will be deﬁned (for example:, arabic_engine_fc class_init : Class initialization function for the new type, or NULL instance_init : Instance initialization function for the new type, or NULL

3.9 PangoEngineShape

Name PangoEngineShape – Rendering-system dependent script engines

Stability Level Unstable, unless otherwise indicated

Synopsis PangoEngineShape; PangoEngineShapeClass; #define PANGO_ENGINE_TYPE_SHAPE #define PANGO_ENGINE_SHAPE_DEFINE_TYPE (name, prefix, class_init, instance_init)

Object Hierarchy GObject +----PangoEngine +----PangoEngineShape

Description The shape engines are rendering-system dependent engines that convert character strings into glyph strings. These engines are used in pango_shape().

217 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.9. PANGOENGINESHAPE

Details PangoEngineShape 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 speciﬁc 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 Fontconﬁg-based backends.

PangoEngineShapeClass 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 script_shape () Given a font, a piece of text, and a PangoAnalysis structure, converts characters to glyphs and positions the resulting glyphs. The results are stored in the PangoGlyphString that is passed in. (The implementation should resize it appropriately using pango_glyph_string_set_size()). All fields of the log_clusters and glyphs array must be filled in, with the exception that Pango will automatically generate 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 PangoGlyphID 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. covers () 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.

PANGO_ENGINE_TYPE_SHAPE

#define PANGO_ENGINE_TYPE_SHAPE"PangoEngineShape"

A string constant deﬁning the engine type for shaping engines. These engines derive from Pango- EngineShape.

PANGO_ENGINE_SHAPE_DEFINE_TYPE()

#define PANGO_ENGINE_SHAPE_DEFINE_TYPE(name, prefix, class_init, ←- instance_init)

Outputs the necessary code for GObject type registration for a PangoEngineShape class deﬁned in a module. Two static symbols are deﬁned. static GType prefix_type; static void prefix_register_type(GTypeModule module);

218 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.10. MODULES

The prefix, (_register_type()) function should be called in your script_engine_init() function for each type that your module implements, and then your script_engine_create() function can create in- stances of the object as follows: PangoEngine *engine= g_object_new(prefix_type, NULL); name : Name of the the type to register (for example:, ArabicEngineFc prefix : Preﬁx for symbols that will be deﬁned (for example:, arabic_engine_fc class_init : Class initialization function for the new type, or NULL instance_init : Instance initialization function for the new type, or NULL

3.10 Modules

Name Modules – Support for loadable modules

Synopsis 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);

Description Functions and macros in this section are used to support loading dynamic modules that add engines to Pango at run time.

Details PangoIncludedModule 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. list () a function that lists the engines deﬁned in this module. init () a function to initialize the module. exit () a function to ﬁnalize the module. create () a function to create an engine, given the engine name.

219 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.10. MODULES

PangoMap typedef struct _PangoMap PangoMap;

A PangoMap structure can be used to determine the engine to use for each character.

PangoMapEntry 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. pango_ﬁnd_map ()

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. language : the language tag for which to find the map engine_type_id : the engine type for the map to find render_type_id : the render type for the map to find Returns : the suitable PangoMap. pango_map_get_engine ()

PangoEngine * pango_map_get_engine(PangoMap *map, PangoScript script);

Returns the best engine listed in the map for a given script map : a PangoMap script : 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. pango_map_get_engines () 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. map : a PangoMap script : a PangoScript exact_engines : location to store list of engines that exactly handle this script. fallback_engines : location to store list of engines that approximately handle this script. Since 1.4

220 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.11. MISCELLANEOUS UTILITIES pango_module_register () 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. module : a PangoIncludedModule

3.11 Miscellaneous Utilities

Name Miscellaneous Utilities – Various convenience and utility functions

Synopsis 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);

221 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.11. MISCELLANEOUS UTILITIES

Description The functions and utilities in this section are mostly used from Pango backends and modules, but may be useful for other purposes too.

Details pango_split_file_list () char ** pango_split_file_list(const char *str); Splits a G_SEARCHPATH_SEPARATOR-separated list of files, stripping white space and substitut- ing ~/ with $HOME/. str : a G_SEARCHPATH_SEPARATOR separated list of filenames Returns : a list of strings to be freed with g_strfreev() pango_trim_string () char * pango_trim_string(const char *str); Trims leading and trailing whitespace from a string. str : a string Returns : A newly-allocated string that must be freed with g_free() pango_read_line () 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. stream : a stdio stream str : 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 ’\’) pango_skip_space () gboolean pango_skip_space(const char **pos); Skips 0 or more characters of white space. pos : in/out string position Returns : FALSE if skipping the white space leaves the position at a ’\0’ character. pango_scan_word () 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. pos : in/out string position out : a GString into which to write the result Returns : FALSE if a parse error occurred.

222 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.11. MISCELLANEOUS UTILITIES pango_scan_string () 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. pos : in/out string position out : a GString into which to write the result

Returns : FALSE if a parse error occurred. pango_scan_int () gboolean pango_scan_int(const char **pos, int *out);

Scans an integer. Leading white space is skipped. pos : in/out string position out : an int into which to write the result

Returns : FALSE if a parse error occurred. pango_conﬁg_key_get () char * pango_config_key_get(const char *key);

Looks up a key in the Pango conﬁg database (pseudo-win.ini style, read from $sysconfdir/pango/- pangorc, ~/.pangorc, and getenv (PANGO_RC_FILE).) key : Key to look up, in the form "SECTION/KEY".

Returns : the value, if found, otherwise NULL. The value is a newly-allocated string and must be freed with g_free(). pango_lookup_aliases () void pango_lookup_aliases(const char *fontname, char ***families, int *n_families);

Look up all user deﬁned aliases for the alias fontname. The resulting font family names will be stored in families, and the number of families in n_families. fontname : an ascii string families : will be set to an array of font family names. this array is owned by pango and should not be freed. n_families : will be set to the length of the families array.

223 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.11. MISCELLANEOUS UTILITIES pango_parse_enum () 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(). type : enum type to parse, eg. PANGO_TYPE_ELLIPSIZE_MODE. str : string to parse. May be NULL. value : integer to store the result in, or NULL. warn : if TRUE, issue a g_warning() on bad input. possible_values : place to store list of possible values on failure, or NULL.

Returns : TRUE if str was successfully parsed.

Since 1.16 pango_parse_style () 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. str : a string to parse. style : a PangoStyle to store the result in. warn : if TRUE, issue a g_warning() on bad input.

Returns : TRUE if str was successfully parsed. pango_parse_variant () 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. str : a string to parse. variant : a PangoVariant to store the result in. warn : if TRUE, issue a g_warning() on bad input.

Returns : TRUE if str was successfully parsed.

224 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.11. MISCELLANEOUS UTILITIES pango_parse_weight () gboolean pango_parse_weight(const char *str, PangoWeight *weight, gboolean warn);

Parses a font weight. The allowed values are "heavy", "ultrabold", "bold", "normal", "light", "ultra- leight" and integers. Case variations are ignored. str : a string to parse. weight : a PangoWeight to store the result in. warn : if TRUE, issue a g_warning() on bad input.

Returns : TRUE if str was successfully parsed. pango_parse_stretch () 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. str : a string to parse. stretch : a PangoStretch to store the result in. warn : if TRUE, issue a g_warning() on bad input.

Returns : TRUE if str was successfully parsed. pango_get_sysconf_subdirectory () 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. pango_get_lib_subdirectory () 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.

225 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.12. VERSION CHECKING pango_log2vis_get_embedding_levels () 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 deﬁned 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 ﬁnal resolved direction. text : the text to itemize. length : the number of bytes (not characters) to process, or -1 if text is nul-terminated and the length should be calculated. pbase_dir : 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 pango_is_zero_width () 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. ch : a Unicode character

Returns : TRUE if ch is a zero-width character, FALSE otherwise

Since 1.10 pango_quantize_line_geometry () 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. thickness : pointer to the thickness of a line, in Pango units position : corresponding position

Since 1.12

3.12 Version Checking

Name Version Checking – Tools for checking Pango version at compile- and run-time.

226 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.12. VERSION CHECKING

Synopsis #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);

Description The capital-letter macros deﬁned 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.

Details PANGO_VERSION_ENCODE()

#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. major : the major component of the version number minor : the minor component of the version number micro : the micro component of the version number

PANGO_VERSION

#define PANGO_VERSION

The version of Pango available at compile-time, encoded using PANGO_VERSION_ENCODE().

PANGO_VERSION_MAJOR

#define PANGO_VERSION_MAJOR1

The major component of the version of Pango available at compile-time.

PANGO_VERSION_MINOR

#define PANGO_VERSION_MINOR 24

The minor component of the version of Pango available at compile-time.

PANGO_VERSION_MICRO

#define PANGO_VERSION_MICRO2

The micro component of the version of Pango available at compile-time.

227 CHAPTER 3. LOW LEVEL FUNCTIONALITY 3.12. VERSION CHECKING

PANGO_VERSION_STRING

#define PANGO_VERSION_STRING "1.24.2"

A string literal containing the version of Pango available at compile-time.

PANGO_VERSION_CHECK()

#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. major : the major component of the version number minor : the minor component of the version number micro : the micro component of the version number pango_version () 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 pango_version_string () 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 modiﬁed or freed. Since 1.16 pango_version_check () 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(). required_major : the required major version. required_minor : the required minor version. required_micro : 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

228 Chapter 4

Pango Tools

4.1 pango-querymodules

Name pango-querymodules – Module registration utility

Synopsis pango-querymodules [module...]

Description 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 speciﬁed modules. The arguments may be absolute or relative paths.

Environment The Pango module path is specified by the key Pango/ModulesPath in the Pango config database, which is read from sysconfdir/pango/pangorc, ~/.pangorc and the file specified in the environment variable PANGO_RC_FILE.

Bugs None known yet.

229

Chapter 5

Object Hierarchy

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

231

Index

P pango_cairo_context_get_font_options, 156 PANGO_ANALYSIS_FLAG_CENTERED_BASELINE,pango_cairo_context_get_resolution, 156 4 pango_cairo_context_get_shape_renderer, 157 PANGO_ASCENT, 17 pango_cairo_context_set_font_options, 156 pango_atsui_font_get_atsu_font_id, 161 pango_cairo_context_set_resolution, 156 pango_attr_background_new, 69 pango_cairo_context_set_shape_renderer, 157 pango_attr_fallback_new, 73 pango_cairo_create_context, 158 pango_attr_family_new, 68 pango_cairo_create_layout, 158 pango_attr_font_desc_new, 69 pango_cairo_error_underline_path, 161 pango_attr_foreground_new, 69 pango_cairo_font_get_scaled_font, 155 pango_attr_gravity_hint_new, 73 pango_cairo_font_map_create_context, 155 pango_attr_gravity_new, 73 pango_cairo_font_map_get_default, 153 PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING,pango_cairo_font_map_get_font_type, 154 63 pango_cairo_font_map_get_resolution, 155 PANGO_ATTR_INDEX_TO_TEXT_END, 63 pango_cairo_font_map_new, 154 pango_attr_iterator_copy, 78 pango_cairo_font_map_new_for_font_type, 154 pango_attr_iterator_destroy, 79 pango_cairo_font_map_set_default, 154 pango_attr_iterator_get, 78 pango_cairo_font_map_set_resolution, 155 pango_attr_iterator_get_attrs, 79 pango_cairo_glyph_string_path, 160 pango_attr_iterator_get_font, 79 pango_cairo_layout_line_path, 160 pango_attr_iterator_next, 78 pango_cairo_layout_path, 160 pango_attr_iterator_range, 78 pango_cairo_show_error_underline, 160 pango_attr_language_new, 67 pango_cairo_show_glyph_item, 159 pango_attr_letter_spacing_new, 73 pango_cairo_show_glyph_string, 159 pango_attr_list_change, 76 pango_cairo_show_layout, 159 pango_attr_list_copy, 76 pango_cairo_show_layout_line, 159 pango_attr_list_ﬁlter, 77 pango_cairo_update_context, 158 pango_attr_list_get_iterator, 77 pango_cairo_update_layout, 158 pango_attr_list_insert, 76 pango_color_copy, 74 pango_attr_list_insert_before, 76 pango_color_free, 74 pango_attr_list_new, 75 pango_color_parse, 74 pango_attr_list_ref, 75 pango_color_to_string, 75 pango_attr_list_splice, 76 pango_conﬁg_key_get, 223 pango_attr_list_unref, 75 pango_context_get_base_dir,7 pango_attr_rise_new, 73 pango_context_get_base_gravity,8 pango_attr_scale_new, 72 pango_context_get_font_description,6 pango_attr_shape_new, 71 pango_context_get_font_map,6 pango_attr_shape_new_with_data, 71 pango_context_get_gravity,8 pango_attr_size_new, 68 pango_context_get_gravity_hint,8 pango_attr_size_new_absolute, 69 pango_context_get_language,7 pango_attr_stretch_new, 68 pango_context_get_matrix,9 pango_attr_strikethrough_color_new, 70 pango_context_get_metrics, 10 pango_attr_strikethrough_new, 69 pango_context_list_families, 10 pango_attr_style_new, 68 pango_context_load_font,9 pango_attr_type_get_name, 66 pango_context_load_fontset,9 pango_attr_type_register, 66 pango_context_new,6 pango_attr_underline_color_new, 70 pango_context_set_base_dir,7 pango_attr_underline_new, 70 pango_context_set_base_gravity,8 pango_attr_variant_new, 68 pango_context_set_font_description,7 pango_attr_weight_new, 68 pango_context_set_font_map,6 pango_attribute_copy, 67 pango_context_set_gravity_hint,8 pango_attribute_destroy, 67 pango_context_set_language,7 pango_attribute_equal, 67 pango_context_set_matrix,9 pango_attribute_init, 67 pango_coverage_copy, 212 pango_bidi_type_for_unichar, 121 pango_coverage_from_bytes, 213 pango_break, 10 pango_coverage_get, 212

233 INDEX INDEX pango_coverage_max, 212 pango_font_description_get_weight, 41 pango_coverage_new, 212 pango_font_description_hash, 39 pango_coverage_ref, 212 pango_font_description_merge, 44 pango_coverage_set, 213 pango_font_description_merge_static, 44 pango_coverage_to_bytes, 213 pango_font_description_new, 38 pango_coverage_unref, 212 pango_font_description_set_absolute_size, 43 pango_default_break, 11 pango_font_description_set_family, 40 PANGO_DESCENT, 17 pango_font_description_set_family_static, 40 PANGO_ENGINE_LANG_DEFINE_TYPE, 217 pango_font_description_set_gravity, 43 PANGO_ENGINE_SHAPE_DEFINE_TYPE, 218 pango_font_description_set_size, 42 PANGO_ENGINE_TYPE_LANG, 217 pango_font_description_set_stretch, 42 PANGO_ENGINE_TYPE_SHAPE, 218 pango_font_description_set_style, 40 pango_extents_to_pixels, 18 pango_font_description_set_variant, 41 pango_fc_decoder_get_charset, 195 pango_font_description_set_weight, 41 pango_fc_decoder_get_glyph, 195 pango_font_description_to_filename, 46 pango_fc_font_description_from_pattern, 187 pango_font_description_to_string, 45 pango_fc_font_get_glyph, 192 pango_font_description_unset_fields, 44 pango_fc_font_get_unknown_glyph, 193 pango_font_descriptions_free, 39 pango_fc_font_has_char, 192 PANGO_FONT_FACE, 53 pango_fc_font_kern_glyphs, 193 pango_font_face_describe, 53 pango_fc_font_key_get_context_key, 190 pango_font_face_get_face_name, 53 pango_fc_font_key_get_matrix, 190 pango_font_face_is_synthesized, 54 pango_fc_font_key_get_pattern, 190 pango_font_face_list_sizes, 53 pango_fc_font_lock_face, 192 PANGO_FONT_FAMILY, 51 pango_fc_font_map_add_decoder_find_func, 186 pango_font_family_get_name, 52 pango_fc_font_map_cache_clear, 187 pango_font_family_is_monospace, 52 pango_fc_font_map_create_context, 186 pango_font_family_list_faces, 52 pango_fc_font_map_find_decoder, 187 pango_font_find_shaper, 49 pango_fc_font_map_shutdown, 187 pango_font_get_coverage, 50 pango_fc_font_unlock_face, 192 pango_font_get_font_map, 51 pango_fc_fontset_key_get_absolute_size, 189 pango_font_get_glyph_extents, 50 pango_fc_fontset_key_get_context_key, 188 pango_font_get_metrics, 51 pango_fc_fontset_key_get_description, 188 PANGO_FONT_MAP, 54 pango_fc_fontset_key_get_language, 189 PANGO_FONT_MAP_CLASS, 55 pango_fc_fontset_key_get_matrix, 189 pango_font_map_create_context, 55 pango_fc_fontset_key_get_resolution, 189 PANGO_FONT_MAP_GET_CLASS, 55 PANGO_FC_GRAVITY, 188 pango_font_map_get_shape_engine_type, 56 PANGO_FC_PRGNAME, 188 pango_font_map_list_families, 56 PANGO_FC_VERSION, 188 pango_font_map_load_font, 56 pango_find_base_dir, 119 pango_font_map_load_fontset, 56 pango_find_map, 220 pango_font_metrics_get_approximate_char_width, pango_find_paragraph_boundary, 11 47 PANGO_FONT, 49 pango_font_metrics_get_approximate_digit_width, pango_font_describe, 50 48 pango_font_describe_with_absolute_size, 50 pango_font_metrics_get_ascent, 47 pango_font_description_better_match, 45 pango_font_metrics_get_descent, 47 pango_font_description_copy, 38 pango_font_metrics_get_strikethrough_position, 49 pango_font_description_copy_static, 38 pango_font_metrics_get_strikethrough_thickness, 48 pango_font_description_equal, 39 pango_font_metrics_get_underline_position, 48 pango_font_description_free, 39 pango_font_metrics_get_underline_thickness, 48 pango_font_description_from_string, 45 pango_font_metrics_ref, 47 pango_font_description_get_family, 40 pango_font_metrics_unref, 47 pango_font_description_get_gravity, 43 pango_fontset_foreach, 58 pango_font_description_get_set_fields, 44 pango_fontset_get_font, 57 pango_font_description_get_size, 42 pango_fontset_get_metrics, 58 pango_font_description_get_size_is_absolute, 43 pango_fontset_simple_append, 59 pango_font_description_get_stretch, 42 pango_fontset_simple_new, 59 pango_font_description_get_style, 41 pango_fontset_simple_size, 59 pango_font_description_get_variant, 41 pango_ft2_font_get_coverage, 139

234 INDEX INDEX pango_ft2_font_get_face, 138 pango_item_split,5 pango_ft2_font_get_kerning, 138 pango_itemize,4 pango_ft2_font_map_create_context, 134 pango_itemize_with_base_dir,4 pango_ft2_font_map_for_display, 139 pango_language_from_string, 116 pango_ft2_font_map_new, 134 pango_language_get_default, 117 pango_ft2_font_map_set_default_substitute, 135 pango_language_get_sample_string, 118 pango_ft2_font_map_set_resolution, 134 pango_language_get_scripts, 117 pango_ft2_font_map_substitute_changed, 135 pango_language_includes_script, 117 pango_ft2_get_context, 135 pango_language_matches, 116 pango_ft2_get_unknown_glyph, 138 pango_language_to_string, 116 pango_ft2_render, 136 pango_layout_context_changed, 89 pango_ft2_render_layout, 137 pango_layout_copy, 89 pango_ft2_render_layout_line, 136 pango_layout_get_alignment, 96 pango_ft2_render_layout_line_subpixel, 137 pango_layout_get_attributes, 91 pango_ft2_render_layout_subpixel, 137 pango_layout_get_auto_dir, 96 pango_ft2_render_transformed, 136 pango_layout_get_baseline, 101 pango_ft2_shutdown_display, 139 pango_layout_get_context, 89 pango_get_lib_subdirectory, 225 pango_layout_get_cursor_pos, 99 pango_get_log_attrs, 11 pango_layout_get_ellipsize, 93 pango_get_mirror_char, 120 pango_layout_get_extents, 100 pango_get_sysconf_subdirectory, 225 pango_layout_get_font_description, 91 PANGO_GET_UNKNOWN_GLYPH, 22 pango_layout_get_height, 92 PANGO_GLYPH_EMPTY, 22 pango_layout_get_indent, 94 PANGO_GLYPH_INVALID_INPUT, 22 pango_layout_get_iter, 103 pango_glyph_item_apply_attrs, 29 pango_layout_get_justify, 95 pango_glyph_item_copy, 28 pango_layout_get_line, 102 pango_glyph_item_free, 29 pango_layout_get_line_count, 101 pango_glyph_item_iter_copy, 30 pango_layout_get_line_readonly, 102 pango_glyph_item_iter_free, 30 pango_layout_get_lines, 102 pango_glyph_item_iter_init_end, 31 pango_layout_get_lines_readonly, 102 pango_glyph_item_iter_init_start, 31 pango_layout_get_log_attrs, 98 pango_glyph_item_iter_next_cluster, 31 pango_layout_get_pixel_extents, 100 pango_glyph_item_iter_prev_cluster, 31 pango_layout_get_pixel_size, 101 pango_glyph_item_letter_space, 30 pango_layout_get_single_paragraph_mode, 97 pango_glyph_item_split, 29 pango_layout_get_size, 101 pango_glyph_string_copy, 25 pango_layout_get_spacing, 95 pango_glyph_string_extents, 26 pango_layout_get_tabs, 96 pango_glyph_string_extents_range, 26 pango_layout_get_text, 90 pango_glyph_string_free, 26 pango_layout_get_unknown_glyphs_count, 97 pango_glyph_string_get_logical_widths, 28 pango_layout_get_width, 91 pango_glyph_string_get_width, 27 pango_layout_get_wrap, 92 pango_glyph_string_index_to_x, 27 pango_layout_index_to_line_x, 98 pango_glyph_string_new, 25 pango_layout_index_to_pos, 98 pango_glyph_string_set_size, 26 pango_layout_is_ellipsized, 94 pango_glyph_string_x_to_index, 27 pango_layout_is_wrapped, 93 PANGO_GLYPH_UNKNOWN_FLAG, 22 pango_layout_iter_at_last_line, 104 pango_gravity_get_for_matrix, 123 pango_layout_iter_copy, 103 pango_gravity_get_for_script, 123 pango_layout_iter_free, 103 PANGO_GRAVITY_IS_VERTICAL, 123 pango_layout_iter_get_baseline, 104 pango_gravity_to_rotation, 124 pango_layout_iter_get_char_extents, 105 PANGO_IS_FONT, 49 pango_layout_iter_get_cluster_extents, 106 PANGO_IS_FONT_FACE, 53 pango_layout_iter_get_index, 104 PANGO_IS_FONT_FAMILY, 52 pango_layout_iter_get_layout, 105 PANGO_IS_FONT_MAP, 54 pango_layout_iter_get_layout_extents, 107 PANGO_IS_FONT_MAP_CLASS, 55 pango_layout_iter_get_line, 105 pango_is_zero_width, 226 pango_layout_iter_get_line_extents, 106 pango_item_copy,5 pango_layout_iter_get_line_readonly, 105 pango_item_free,5 pango_layout_iter_get_line_yrange, 106 pango_item_new,5 pango_layout_iter_get_run, 104

235 INDEX INDEX pango_layout_iter_get_run_extents, 106 PANGO_OT_DEFAULT_LANGUAGE, 200 pango_layout_iter_get_run_readonly, 105 pango_ot_info_find_feature, 202 pango_layout_iter_next_char, 103 pango_ot_info_find_language, 201 pango_layout_iter_next_cluster, 103 pango_ot_info_find_script, 201 pango_layout_iter_next_line, 104 pango_ot_info_get, 201 pango_layout_iter_next_run, 103 pango_ot_info_list_features, 203 pango_layout_line_get_extents, 108 pango_ot_info_list_languages, 203 pango_layout_line_get_pixel_extents, 108 pango_ot_info_list_scripts, 202 pango_layout_line_get_x_ranges, 109 PANGO_OT_NO_FEATURE, 200 pango_layout_line_index_to_x, 108 PANGO_OT_NO_SCRIPT, 200 pango_layout_line_ref, 107 pango_ot_ruleset_add_feature, 207 pango_layout_line_unref, 108 pango_ot_ruleset_description_copy, 208 pango_layout_line_x_to_index, 109 pango_ot_ruleset_description_equal, 209 pango_layout_move_cursor_visually, 99 pango_ot_ruleset_description_free, 209 pango_layout_new, 89 pango_ot_ruleset_description_hash, 209 pango_layout_set_alignment, 96 pango_ot_ruleset_get_feature_count, 208 pango_layout_set_attributes, 90 pango_ot_ruleset_get_for_description, 205 pango_layout_set_auto_dir, 95 pango_ot_ruleset_maybe_add_feature, 207 pango_layout_set_ellipsize, 93 pango_ot_ruleset_maybe_add_features, 207 pango_layout_set_font_description, 91 pango_ot_ruleset_new, 205 pango_layout_set_height, 92 pango_ot_ruleset_new_for, 206 pango_layout_set_indent, 94 pango_ot_ruleset_new_from_description, 206 pango_layout_set_justify, 95 pango_ot_ruleset_position, 208 pango_layout_set_markup, 90 pango_ot_ruleset_substitute, 208 pango_layout_set_markup_with_accel, 90 PANGO_OT_TAG_DEFAULT_LANGUAGE, 200 pango_layout_set_single_paragraph_mode, 97 PANGO_OT_TAG_DEFAULT_SCRIPT, 201 pango_layout_set_spacing, 95 pango_ot_tag_from_language, 209 pango_layout_set_tabs, 96 pango_ot_tag_from_script, 210 pango_layout_set_text, 89 PANGO_OT_TAG_MAKE, 199 pango_layout_set_width, 91 PANGO_OT_TAG_MAKE_FROM_STRING, 200 pango_layout_set_wrap, 92 pango_ot_tag_to_language, 210 pango_layout_xy_to_index, 99 pango_ot_tag_to_script, 210 PANGO_LBEARING, 18 pango_parse_enum, 224 pango_log2vis_get_embedding_levels, 226 pango_parse_markup, 66 pango_lookup_aliases, 223 pango_parse_stretch, 225 pango_map_get_engine, 220 pango_parse_style, 224 pango_map_get_engines, 220 pango_parse_variant, 224 pango_matrix_concat, 20 pango_parse_weight, 225 pango_matrix_copy, 19 PANGO_PIXELS, 16 pango_matrix_free, 19 PANGO_PIXELS_CEIL, 16 pango_matrix_get_font_scale_factor, 22 PANGO_PIXELS_FLOOR, 16 PANGO_MATRIX_INIT, 19 pango_quantize_line_geometry, 226 pango_matrix_rotate, 20 PANGO_RBEARING, 18 pango_matrix_scale, 20 pango_read_line, 222 pango_matrix_transform_distance, 21 PANGO_RENDER_TYPE_ATSUI, 161 pango_matrix_transform_pixel_rectangle, 21 PANGO_RENDER_TYPE_FC, 192 pango_matrix_transform_point, 20 PANGO_RENDER_TYPE_FT2, 133 pango_matrix_transform_rectangle, 21 PANGO_RENDER_TYPE_NONE, 215 pango_matrix_translate, 19 PANGO_RENDER_TYPE_WIN32, 126 pango_module_register, 221 PANGO_RENDER_TYPE_X, 163 PANGO_OT_ALL_GLYPHS, 200 PANGO_RENDER_TYPE_XFT, 142 pango_ot_buffer_add_glyph, 204 pango_renderer_activate, 181 pango_ot_buffer_clear, 204 pango_renderer_deactivate, 182 pango_ot_buffer_destroy, 203 pango_renderer_draw_error_underline, 180 pango_ot_buffer_get_glyphs, 205 pango_renderer_draw_glyph, 181 pango_ot_buffer_new, 203 pango_renderer_draw_glyph_item, 179 pango_ot_buffer_output, 205 pango_renderer_draw_glyphs, 179 pango_ot_buffer_set_rtl, 204 pango_renderer_draw_layout, 178 pango_ot_buffer_set_zero_width_marks, 204 pango_renderer_draw_layout_line, 179

236 INDEX INDEX pango_renderer_draw_rectangle, 180 PANGO_TYPE_GLYPH_STRING, 25 pango_renderer_draw_trapezoid, 181 PANGO_TYPE_LANGUAGE, 116 pango_renderer_get_color, 182 PANGO_TYPE_MATRIX, 19 pango_renderer_get_layout, 183 PANGO_TYPE_RENDER_PART, 177 pango_renderer_get_layout_line, 183 PANGO_TYPE_SCRIPT, 114 pango_renderer_get_matrix, 183 PANGO_TYPE_STRETCH, 37 pango_renderer_part_changed, 182 PANGO_TYPE_STYLE, 36 pango_renderer_set_color, 182 PANGO_TYPE_TAB_ALIGN, 81 pango_renderer_set_matrix, 183 PANGO_TYPE_TAB_ARRAY, 80 pango_reorder_items,6 PANGO_TYPE_UNDERLINE, 71 PANGO_SCALE, 16 PANGO_TYPE_VARIANT, 37 PANGO_SCALE_LARGE, 72 PANGO_TYPE_WEIGHT, 36 PANGO_SCALE_MEDIUM, 72 PANGO_TYPE_WRAP_MODE, 93 PANGO_SCALE_SMALL, 72 pango_unichar_direction, 119 PANGO_SCALE_X_LARGE, 72 pango_units_from_double, 17 PANGO_SCALE_X_SMALL, 72 PANGO_UNITS_ROUND, 16 PANGO_SCALE_XX_LARGE, 73 pango_units_to_double, 17 PANGO_SCALE_XX_SMALL, 72 PANGO_VERSION, 227 pango_scan_int, 223 pango_version, 228 pango_scan_string, 223 PANGO_VERSION_CHECK, 228 pango_scan_word, 222 pango_version_check, 228 pango_script_for_unichar, 114 PANGO_VERSION_ENCODE, 227 pango_script_get_sample_language, 114 PANGO_VERSION_MAJOR, 227 pango_script_iter_free, 116 PANGO_VERSION_MICRO, 227 pango_script_iter_get_range, 115 PANGO_VERSION_MINOR, 227 pango_script_iter_new, 115 PANGO_VERSION_STRING, 228 pango_script_iter_next, 115 pango_version_string, 228 pango_shape, 13 pango_win32_font_cache_free, 129 pango_skip_space, 222 pango_win32_font_cache_load, 130 pango_split_file_list, 222 pango_win32_font_cache_loadw, 130 pango_tab_array_copy, 81 pango_win32_font_cache_new, 129 pango_tab_array_free, 81 pango_win32_font_cache_unload, 130 pango_tab_array_get_positions_in_pixels, 83 pango_win32_font_description_from_logfont, 131 pango_tab_array_get_size, 82 pango_win32_font_description_from_logfontw, 132 pango_tab_array_get_tab, 82 pango_win32_font_done_font, 128 pango_tab_array_get_tabs, 83 pango_win32_font_get_glyph_index, 128 pango_tab_array_new, 81 pango_win32_font_get_metrics_factor, 129 pango_tab_array_new_with_positions, 81 pango_win32_font_logfont, 131 pango_tab_array_resize, 82 pango_win32_font_logfontw, 131 pango_tab_array_set_tab, 82 pango_win32_font_map_for_display, 130 pango_trim_string, 222 pango_win32_font_map_get_font_cache, 131 PANGO_TYPE_ALIGNMENT, 97 pango_win32_font_select_font, 128 PANGO_TYPE_ATTR_LIST, 75 pango_win32_get_context, 126 PANGO_TYPE_ATTR_TYPE, 63 pango_win32_get_dc, 129 PANGO_TYPE_COLOR, 74 pango_win32_get_debug_flag, 129 PANGO_TYPE_COVERAGE_LEVEL, 211 pango_win32_get_unknown_glyph, 128 PANGO_TYPE_DIRECTION,4 pango_win32_render, 126 PANGO_TYPE_ELLIPSIZE_MODE, 94 pango_win32_render_layout, 127 PANGO_TYPE_FONT, 49 pango_win32_render_layout_line, 127 PANGO_TYPE_FONT_DESCRIPTION, 35 pango_win32_render_transformed, 127 PANGO_TYPE_FONT_FACE, 53 pango_win32_shutdown_display, 130 PANGO_TYPE_FONT_FAMILY, 51 pango_x_apply_ligatures, 171 PANGO_TYPE_FONT_MAP, 54 pango_x_context_set_funcs, 164 PANGO_TYPE_FONT_MASK, 38 pango_x_fallback_shape, 172 PANGO_TYPE_FONT_METRICS, 46 pango_x_find_first_subfont, 171 PANGO_TYPE_FONTSET, 57 pango_x_font_cache_free, 173 PANGO_TYPE_FONTSET_SIMPLE, 58 pango_x_font_cache_load, 173 PANGO_TYPE_GLYPH_ITEM, 28 pango_x_font_cache_new, 173 PANGO_TYPE_GLYPH_ITEM_ITER, 30 pango_x_font_cache_unload, 174

237 INDEX INDEX pango_x_font_get_unknown_glyph, 171 PangoCoverage, 211 pango_x_font_map_for_display, 169 PangoCoverageLevel, 211 pango_x_font_map_get_font_cache, 170 PangoDirection, 119 pango_x_font_subfont_xlfd, 170 PangoEllipsizeMode, 94 pango_x_get_context, 163 PangoEngine, 215 pango_x_get_unknown_glyph, 168 PangoEngineClass, 215 PANGO_X_GLYPH_INDEX, 167 PangoEngineInfo, 214 PANGO_X_GLYPH_SUBFONT, 167 PangoEngineLang, 216 pango_x_has_glyph, 168 PangoEngineLangClass, 216 pango_x_list_subfonts, 169 PangoEngineScriptInfo, 214 pango_x_load_font, 168 PangoEngineShape, 218 PANGO_X_MAKE_GLYPH, 167 PangoEngineShapeClass, 218 pango_x_render, 165 PangoFcDecoder, 194 pango_x_render_layout, 166 PangoFcDecoderClass, 194 pango_x_render_layout_line, 165 PangoFcDecoderFindFunc, 186 pango_x_shutdown_display, 170 PangoFcFont, 191 pango_xft_font_get_display, 144 PangoFcFont:fontmap, 193 pango_xft_font_get_font, 144 PangoFcFont:pattern, 193 pango_xft_font_get_glyph, 145 PangoFcFontClass, 191 pango_xft_font_get_unknown_glyph, 145 PangoFcFontKey, 189 pango_xft_font_has_char, 144 PangoFcFontMap, 184 pango_xft_font_lock_face, 144 PangoFcFontMapClass, 185 pango_xft_font_unlock_face, 145 PangoFcFontsetKey, 188 pango_xft_get_context, 142 PangoFont, 49 pango_xft_get_font_map, 142 PangoFontDescription, 35 pango_xft_picture_render, 147 PangoFontFace, 52 pango_xft_render, 147 PangoFontFamily, 51 pango_xft_render_layout, 148 PangoFontMap, 54 pango_xft_render_layout_line, 148 PangoFontMapClass, 54 pango_xft_render_transformed, 148 PangoFontMask, 38 pango_xft_renderer_new, 146 PangoFontMetrics, 46 pango_xft_renderer_set_default_color, 147 PangoFontset, 57 pango_xft_renderer_set_draw, 146 PangoFontsetClass, 57 pango_xft_set_default_substitute, 143 PangoFontsetForeachFunc, 58 pango_xft_shutdown_display, 143 PangoFontsetSimple, 58 pango_xft_substitute_changed, 143 PangoFreeGCFunc, 164 PangoAlignment, 97 PangoFT2FontMap, 133 PangoAnalysis,3 PangoFT2SubstituteFunc, 134 PangoAttrClass, 63 PangoGetGCFunc, 164 PangoAttrColor, 64 PangoGlyph, 22 PangoAttrDataCopyFunc, 72 PangoGlyphGeometry, 23 PangoAttrFilterFunc, 77 PangoGlyphInfo, 23 PangoAttrFloat, 64 PangoGlyphItem, 24 PangoAttrFontDesc, 65 PangoGlyphItemIter, 24 PangoAttribute, 63 PangoGlyphString, 24 PangoAttrInt, 64 PangoGlyphUnit, 23 PangoAttrIterator, 77 PangoGlyphVisAttr, 23 PangoAttrLanguage, 64 PangoGravity, 122 PangoAttrList, 75 PangoGravityHint, 123 PangoAttrShape, 65 PangoIncludedModule, 219 PangoAttrSize, 65 PangoItem,3 PangoAttrString, 64 PangoLanguage, 116 PangoAttrType, 61 PangoLayout, 88 PangoBidiType, 120 PangoLayoutIter, 88 PangoCairoFont, 153 PangoLayoutLine, 107 PangoCairoFontMap, 153 PangoLayoutRun, 107 PangoCairoShapeRendererFunc, 157 PangoLogAttr, 12 PangoColor, 74 PangoMap, 220 PangoContext,3 PangoMapEntry, 220

238 INDEX INDEX

PangoMatrix, 18 PangoOTBuffer, 198 PangoOTFeatureMap, 199 PangoOTGlyph, 198 PangoOTInfo, 197 PangoOTRuleset, 198 PangoOTRulesetDescription, 198 PangoOTTableType, 199 PangoOTTag, 197 PangoRectangle, 17 PangoRenderer, 176 PangoRendererClass, 177 PangoRenderPart, 176 PangoScript, 110 PangoScriptIter, 114 PangoStretch, 37 PangoStyle, 35 PangoTabAlign, 80 PangoTabArray, 80 PangoUnderline, 70 PangoVariant, 37 PangoWeight, 36 PangoWin32FontCache, 129 PangoWrapMode, 93 PangoXFontCache, 172 PangoXftFont, 141 PangoXftFontMap, 142 PangoXftRenderer, 146 PangoXftRenderer:display, 149 PangoXftRenderer:screen, 149 PangoXftRendererClass, 146 PangoXftSubstituteFunc, 143 PangoXSubfont, 166

S script_engine_create, 215 script_engine_exit, 215 script_engine_init, 215 script_engine_list, 215

239