pango.c.types

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

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.

A PangoLayoutRun represents a single run within a [pango.layout_line.LayoutLine].

It is simply an alternate name for [pango.glyph_item.GlyphItem]. See the [pango.glyph_item.GlyphItem] docs for details on the fields.

[pango.types.Alignment] describes how to align the lines of a [pango.layout.Layout] within the available space.

If the [pango.layout.Layout] is set to justify using [pango.layout.Layout.setJustify], this only affects partial lines.

See [pango.layout.Layout.setAutoDir] for how text direction affects the interpretation of [pango.types.Alignment] values.

The [pango.types.AttrType] distinguishes between different types of attributes.

Along with the predefined values, it is possible to allocate additional values for custom attributes using func@AttrType.register. The predefined values are given below. The type of structure used to store the attribute is listed in parentheses after the description.

An enumeration that affects baseline shifts between runs.

[pango.types.BidiType] represents the bidirectional character type of a Unicode character.

The values in this enumeration are specified by the

[pango.types.CoverageLevel] is used to indicate how well a font can represent a particular Unicode character for a particular script.

Since 1.44, only [pango.types.CoverageLevel.None] and [pango.types.CoverageLevel.Exact] will be returned.

[pango.types.Direction] represents a direction in the Unicode bidirectional algorithm.

Not every value in this enumeration makes sense for every usage of [pango.types.Direction]; for example, the return value of func@unichar_direction and func@find_base_dir cannot be [pango.types.Direction.WeakLtr] or [pango.types.Direction.WeakRtl], since every character is either neutral or has a strong direction; on the other hand [pango.types.Direction.Neutral] doesn't make sense to pass to func@itemize_with_base_dir.

The [pango.types.Direction.TtbLtr], [pango.types.Direction.TtbRtl] values come from an earlier interpretation of this enumeration as the writing direction of a block of text and are no longer used. See [pango.types.Gravity] for how vertical text is handled in Pango.

If you are interested in text direction, you should really use fribidi directly. [pango.types.Direction] is only retained because it is used in some public apis.

[pango.types.EllipsizeMode] describes what sort of ellipsization should be applied to text.

In the ellipsization process characters are removed from the text in order to make it fit to a given width and replaced with an ellipsis.

The bits in a [pango.types.FontMask] correspond to the set fields in a [pango.font_description.FontDescription].

An enumeration that affects font sizes for superscript and subscript positioning and for (emulated) Small Caps.

[pango.types.Gravity] 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 [pango.matrix.Matrix], and then glyph orientation is controlled using [pango.types.Gravity].

Not every value in this enumeration makes sense for every usage of [pango.types.Gravity]; for example, [pango.types.Gravity.Auto] only can be passed to [pango.context.Context.setBaseGravity] and can only be returned by [pango.context.Context.getBaseGravity].

See also: [pango.types.GravityHint]

[pango.types.GravityHint] defines how horizontal scripts should behave in a vertical context.

That is, English excerpts in a vertical paragraph for example.

See also [pango.types.Gravity]

Errors that can be returned by [pango.layout.Layout.deserialize].

Flags that influence the behavior of [pango.layout.Layout.deserialize].

New members may be added to this enumeration over time.

Flags that influence the behavior of [pango.layout.Layout.serialize].

New members may be added to this enumeration over time.

The [pango.types.Overline] enumeration is used to specify whether text should be overlined, and if so, the type of line.

[pango.types.RenderPart] defines different items to render for such purposes as setting colors.

The [pango.types.Script] enumeration identifies different writing systems.

The values correspond to the names as defined in the Unicode standard. See

Note that this enumeration is deprecated and will not be updated to include values in newer versions of the Unicode standard. Applications should use the [glib.types.UnicodeScript] enumeration instead, whose values are interchangeable with [pango.types.Script].

Flags influencing the shaping process.

[pango.types.ShapeFlags] can be passed to func@Pango.shape_with_flags.

These flags affect how Pango treats characters that are normally not visible in the output.

An enumeration specifying the width of the font relative to other designs within a family.

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

[pango.types.TabAlign] specifies where the text appears relative to the tab stop position.

An enumeration that affects how Pango treats characters during shaping.

The [pango.types.Underline] enumeration is used to specify whether text should be underlined, and if so, the type of underlining.

An enumeration specifying capitalization variant of the font.

An enumeration specifying the weight (boldness) of a font.

Weight is specified as a numeric value ranging from 100 to 1000. This enumeration simply provides some common, predefined values.

[pango.types.WrapMode] describes how to wrap the lines of a [pango.layout.Layout] to the desired width.

For @PANGO_WRAP_WORD, Pango uses break opportunities that are determined by the Unicode line breaking algorithm. For @PANGO_WRAP_CHAR, Pango allows breaking at grapheme boundaries that are determined by the Unicode text segmentation algorithm.

The [pango.analysis.Analysis] structure stores information about the properties of a segment of text.

The [pango.types.AttrClass] 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 [pango.attribute.Attribute].

The [pango.attr_color.AttrColor] structure is used to represent attributes that are colors.

The [pango.attr_float.AttrFloat] structure is used to represent attributes with a float or double value.

The [pango.attr_font_desc.AttrFontDesc] structure is used to store an attribute that sets all aspects of the font description at once.

The [pango.attr_font_features.AttrFontFeatures] structure is used to represent OpenType font features as an attribute.

The [pango.attr_int.AttrInt] structure is used to represent attributes with an integer or enumeration value.

A [pango.attr_iterator.AttrIterator] is used to iterate through a [pango.attr_list.AttrList].

A new iterator is created with [pango.attr_list.AttrList.getIterator]. Once the iterator is created, it can be advanced through the style changes in the text using [pango.attr_iterator.AttrIterator.next]. At each style change, the range of the current style segment and the attributes currently in effect can be queried.

The [pango.attr_language.AttrLanguage] structure is used to represent attributes that are languages.

A [pango.attr_list.AttrList] represents a list of attributes that apply to a section of text.

The attributes in a [pango.attr_list.AttrList] are, in general, allowed to overlap in an arbitrary fashion. However, if the attributes are manipulated only through [pango.attr_list.AttrList.change], the overlap between properties will meet stricter criteria.

Since the [pango.attr_list.AttrList] 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 [pango.attr_list.AttrList] for more than one paragraph of text.

The [pango.attr_shape.AttrShape] structure is used to represent attributes which impose shape restrictions.

The [pango.attr_size.AttrSize] structure is used to represent attributes which set font size.

The [pango.attr_string.AttrString] structure is used to represent attributes with a string value.

The [pango.attribute.Attribute] structure represents the common portions of all attributes.

Particular types of attributes include this structure as their initial portion. The common portion of the attribute holds the range to which the value in the type-specific part of the attribute applies and should be initialized using [pango.attribute.Attribute.init_]. By default, an attribute will have an all-inclusive range of [0,G_MAXUINT].

The [pango.color.Color] structure is used to represent a color in an uncalibrated RGB color-space.

A [pango.context.Context] stores global information used to control the itemization process.

The information stored by [pango.context.Context] includes the fontmap used to look up fonts, and default values such as the default language, default gravity, or default font.

To obtain a [pango.context.Context], use [pango.font_map.FontMap.createContext].

A [pango.coverage.Coverage] structure is a map from Unicode characters to [pango.types.CoverageLevel] values.

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 [pango.coverage.Coverage] is a data structure that is used to represent that information. It is an opaque structure with no public fields.

A [pango.font.Font] is used to represent a font in a rendering-system-independent manner.

A [pango.font_description.FontDescription] describes a font in an implementation-independent manner.

[pango.font_description.FontDescription] structures are used both to list what fonts are available on the system and also for specifying the characteristics of a font to load.

A [pango.font_face.FontFace] is used to represent a group of fonts with the same family, slant, weight, and width, but varying sizes.

A [pango.font_family.FontFamily] is used to represent a family of related font faces.

The font faces in a family share a common design, but differ in slant, weight, width or other aspects.

A [pango.font_map.FontMap] represents the set of fonts available for a particular rendering system.

This is a virtual object with implementations being specific to particular rendering systems.

The [pango.font_map_class.FontMapClass] structure holds the virtual functions for a particular [pango.font_map.FontMap] implementation.

A [pango.font_metrics.FontMetrics] structure holds the overall metric information for a font.

The information in a [pango.font_metrics.FontMetrics] structure may be restricted to a script. The fields of this structure are private to implementations of a font backend. See the documentation of the corresponding getters for documentation of their meaning.

For an overview of the most important metrics, see:

A [pango.fontset.Fontset] represents a set of [pango.font.Font] to use when rendering text.

A [pango.fontset.Fontset] is the result of resolving a [pango.font_description.FontDescription] against a particular [pango.context.Context]. It has operations for finding the component font for a particular Unicode character, and for finding a composite set of metrics for the entire fontset.

The [pango.fontset_class.FontsetClass] structure holds the virtual functions for a particular [pango.fontset.Fontset] implementation.

[pango.fontset_simple.FontsetSimple] is a implementation of the abstract [pango.fontset.Fontset] base class as an array of fonts.

When creating a [pango.fontset_simple.FontsetSimple], you have to provide the array of fonts that make up the fontset.

The [pango.types.GlyphGeometry] structure contains width and positioning information for a single glyph.

Note that @width is not guaranteed to be the same as the glyph extents. Kerning and other positioning applied during shaping will affect both the @width and the @x_offset for the glyphs in the glyph string that results from shaping.

The information in this struct is intended for rendering the glyphs, as follows:

1. Assume the current point is (x, y)
2. Render the current glyph at (x + x_offset, y + y_offset),
3. Advance the current point to (x + width, y)
4. Render the next glyph

A [pango.glyph_info.GlyphInfo] structure represents a single glyph with positioning information and visual attributes.

A [pango.glyph_item.GlyphItem] is a pair of a [pango.item.Item] and the glyphs resulting from shaping the items text.

As an example of the usage of [pango.glyph_item.GlyphItem], the results of shaping text with [pango.layout.Layout] is a list of [pango.layout_line.LayoutLine], each of which contains a list of [pango.glyph_item.GlyphItem].

A [pango.glyph_item_iter.GlyphItemIter] is an iterator over the clusters in a [pango.glyph_item.GlyphItem].

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_glyph decreases as the iterator moves forward. Moreover, in right-to-left cases, @start_glyph is greater than @end_glyph.

An iterator should be initialized using either [pango.glyph_item_iter.GlyphItemIter.initStart] or [pango.glyph_item_iter.GlyphItemIter.initEnd], for forward and backward iteration respectively, and walked over using any desired mixture of [pango.glyph_item_iter.GlyphItemIter.nextCluster] and [pango.glyph_item_iter.GlyphItemIter.prevCluster].

A common idiom for doing a forward iteration over the clusters is:

PangoGlyphItemIter cluster_iter;
gboolean have_cluster;

for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
                                                     glyph_item, text);
    have_cluster;
    have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
{
 ...
}

Note that @text is the start of the text for layout, which is then indexed by glyph_item->item->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 [pango.glyph_item_iter.GlyphItemIter] should be modified manually.

A [pango.glyph_string.GlyphString] is used to store strings of glyphs with geometry and visual attribute information.

The storage for the glyph information is owned by the structure which simplifies memory management.

A [pango.types.GlyphVisAttr] structure communicates information between the shaping and rendering phases.

Currently, it contains cluster start and color information. More attributes may be added in the future.

Clusters are stored in visual order, within the cluster, glyphs are always ordered in logical order, since visual order is meaningless; that is, in Arabic text, accent glyphs follow the glyphs for the base character.

The [pango.item.Item] structure stores information about a segment of text.

You typically obtain PangoItems by itemizing a piece of text with func@itemize.

The [pango.language.Language] structure is used to represent a language.

[pango.language.Language] pointers can be efficiently copied and compared with each other.

A [pango.layout.Layout] structure represents an entire paragraph of text.

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. [pango.layout.Layout] provides a high-level driver for formatting entire paragraphs of text at once. This includes paragraph-level functionality such as line breaking, justification, alignment and ellipsization.

A [pango.layout.Layout] is initialized with a [pango.context.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 a number of parameters to adjust the formatting of a [pango.layout.Layout]. The following image shows adjustable parameters (on the left) and font metrics (on the right):

The following images demonstrate the effect of alignment and justification on the layout of text:

It is possible, as well, to ignore the 2-D setup, and simply treat the results of a [pango.layout.Layout] as a list of lines.

A [pango.layout_iter.LayoutIter] can be used to iterate over the visual extents of a [pango.layout.Layout].

To obtain a [pango.layout_iter.LayoutIter], use [pango.layout.Layout.getIter].

The [pango.layout_iter.LayoutIter] structure is opaque, and has no user-visible fields.

A [pango.layout_line.LayoutLine] represents one of the lines resulting from laying out a paragraph via [pango.layout.Layout].

[pango.layout_line.LayoutLine] structures are obtained by calling [pango.layout.Layout.getLine] and are only valid until the text, attributes, or settings of the parent [pango.layout.Layout] are modified.

The [pango.types.LogAttr] structure stores information about the attributes of a single character.

A [pango.matrix.Matrix] specifies a transformation between user-space 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;

The [pango.types.Rectangle] structure represents a rectangle.

[pango.types.Rectangle] is frequently used to represent the logical or ink extents of a single glyph or section of text. (See, for instance, [pango.font.Font.getGlyphExtents].)

[pango.renderer.Renderer] is a base class for objects that can render text provided as [pango.glyph_string.GlyphString] or [pango.layout.Layout].

By subclassing [pango.renderer.Renderer] and overriding operations such as @draw_glyphs and @draw_rectangle, renderers for particular font backends and destinations can be created.

Class structure for [pango.renderer.Renderer].

The following vfuncs take user space coordinates in Pango units and have default implementations:

• draw_glyphs
• draw_rectangle
• draw_error_underline
• draw_shape
• draw_glyph_item

The default draw_shape implementation draws nothing.

The following vfuncs take device space coordinates as doubles and must be implemented:

• draw_trapezoid
• draw_glyph

A [pango.script_iter.ScriptIter] is used to iterate through a string and identify ranges in different scripts.

A [pango.tab_array.TabArray] contains an array of tab stops.

[pango.tab_array.TabArray] can be used to set tab stops in a [pango.layout.Layout]. Each tab stop has an alignment, a position, and optionally a character to use as decimal point.