Package pango

Functions to run the rendering pipeline.

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.

Structures representing abstract fonts.

Pango supports a flexible architecture where a particular rendering architecture can supply an implementation of fonts. The pango-font class represents an abstract rendering-system-independent font. Pango provides routines to list available fonts, and to load a font of a given description.

Structures for storing information about glyphs.

the function 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.

Font and other attributes for annotating text.

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 Pango layout. The data types and functions in this section are used to represent and manipulate sets of attributes applied to a portion of text.

Simple markup language for text with attributes.

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 pango-attr-list instance 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 pango-attr-list instance using either of the functions pango-parse-markup or pango-markup-parser-new.

A simple example of a marked-up string might be:

<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!      

Pango uses GMarkup to parse this language, which means that XML features such as numeric character entities such as © for © can be used too.

The root tag of a marked-up document is <markup>, but the function 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 <span>, then there are some convenience tags.

Span attributes

<span> has the following attributes:

font_desc

A font description string, such as "Sans Italic 12". See the function 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

A font family name.

font_size, 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_style

One of normal, oblique, italic.

font_weight

One of ultralight, light, normal, bold, ultrabold, heavy, or a numeric weight.

font_variant

One of normal or smallcaps.

font_stretch, stretch

One of ultracondensed, extracondensed, condensed, semicondensed, normal, semiexpanded, expanded, extraexpanded, ultraexpanded.

font_features

A comma-separated list of OpenType font feature settings, in the same syntax as accepted by CSS. E.g: font_features='dlig=1, -kern, afrc on'.

foreground, fgcolor

An RGB color specification such as #00FF00 or a color name such as red. Since 1.38, an RGBA color specification such as #00FF007F will be interpreted as specifying both a foreground color and foreground alpha.

background, bgcolor

An RGB color specification such as #00FF00 or a color name such as red. Since 1.38, an RGBA color specification such as #00FF007F will be interpreted as specifying both a background color and background alpha.

alpha, fgalpha

An alpha value for the foreground color, either a plain integer between 1 and 65536 or a percentage value like 50%.

background_alpha, bgalpha

An alpha value for the background color, either a plain integer between 1 and 65536 or a percentage value like 50%.

underline

One of none, single, double, low, error, single-line, double-line or error-line.

underline_color

The color of underlines; an RGB color specification such as #00FF00 or a color name such as red.

overline

One of none or single.

overline_color

The color of overlines; an RGB color specification such as #00FF00 or a color name such as red.

rise

Vertical displacement, in Pango units. 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.

allow_breaks

true or false whether to allow line breaks or not. If not allowed, the range will be kept in a single run as far as possible. Breaks are allowed by default.

insert_hyphens

true or false` whether to insert hyphens when breaking lines in the middle of a word. Hyphens are inserted by default.

show

A value determining how invisible characters are treated. Possible values are spaces, line-breaks, ignorables or combinations, such as spaces|line-breaks.

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.

Convenience tags

The following convenience tags are provided:

<b>

Bold.

<big>

Makes font relatively larger, equivalent to <span size="larger">.

<i>

{Italic.

<s>

Strikethrough.

<sub>

Subscript.

<sup>

Superscript.

<small>

Makes font relatively smaller, equivalent to <span size="smaller">.

<tt>

Monospace.

<u>

Underline.

High-level layout driver objects.

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. This includes paragraph-level functionality such as line-breaking, justification, alignment and ellipsization.

Identifying writing systems and languages.

Types and functions to help with handling bidirectional text.

Pango supports bidirectional text (like Arabic and Hebrew) automatically. Some applications however, need some help to correctly handle bidirectional text.

The pango-direction enumeration can be used with the function pango-context-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.

Laying text out in vertical directions.

Font handling and rendering with Cairo.

not implemented

not implemented

not implemented

not implemented

Global context object.

Structures for storing tab stops.

Unicode character range coverage storage.

Rendering driver base class.

not implemented

not implemented

not implemented

not implemented

Tools for checking Pango version at compile- and run-time.

not implemented

not implemented

not implemented

not implemented

not implemented