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 Unicode bidirectional algorithm.

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 Unicode Standard Annex 24: Script names

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 G_MAXUINT">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.