pango — PPM

pango clib 1.0.0

High-level internationalized text layout engine. Paragraph layout, line breaking, BiDi, RTL, complex scripts, font selection, markup, and ellipsis — the text engine behind GTK, GNOME, LibreOffice, Inkscape, and GIMP.

What is Pango?

Pango is the industry-standard text layout engine used across the Linux desktop ecosystem. It sits above FreeType and HarfBuzz in the rendering stack and adds everything needed to lay out a full paragraph: line breaking, tab stops, text alignment, ellipsis, font selection by description string, and attribute lists that apply bold, italic, color, or size to arbitrary text spans.

Pango handles the full complexity of internationalized typography: bidirectional (BiDi) paragraphs that mix left-to-right and right-to-left text, Arabic and Hebrew contextual letter forms, Devanagari conjunct clusters, CJK ideographic spacing, automatic font fallback (if a glyph is missing from the primary font Pango transparently selects another installed font that covers that codepoint), and its own markup language for rich-text strings.

Pango is used by GTK 2, GTK 3, GTK 4, GNOME, LibreOffice, Inkscape, GIMP, Evince, and many other Linux applications. Its Cairo backend is the most common rendering path, producing vector output to PNG, PDF, or SVG with full anti-aliasing.

What Pango Adds Beyond FreeType / HarfBuzz

Layer	Library	Responsibility
Rasterization	FreeType	Renders individual glyphs into bitmaps at a requested pixel size. Does not know about words, lines, or paragraphs.
Shaping	HarfBuzz	Maps Unicode codepoints to the correct glyph IDs with ligatures, kerning, Arabic/Hebrew contextual forms, and OpenType GSUB/GPOS. Does not know about wrapping or alignment.
Layout	Pango	Full paragraph layout: line breaking, word/char wrap, font selection from a description string, font fallback across families, attribute lists (bold/italic/color/size on spans), alignment (left/center/right), ellipsis, tab stops, and BiDi paragraph resolution.

Pango Markup

Pango markup is an XML-like rich-text format accepted by SetMarkup. It lets you mix styles inline without managing attribute lists manually.

bold — bold weight
italic — italic style
underline — underline decoration
<s>strikethrough</s> — strikethrough decoration
red — foreground color (name or #rrggbb)
big — relative sizes: xx-small x-small small medium large x-large xx-large
code — switch font family inline
heading — combined attributes

Typical Pipeline

1. PangoFontDescription — describe the font: family, style, weight, size.
2. PangoContext — holds the font map and rendering settings (DPI, language).
3. PangoLayout — the text layout object. Attach font, width, alignment, wrap, ellipsize.
4. SetText / SetMarkup — supply the text content to the layout.
5. ShowLayout (via Cairo) — render the laid-out text to a Cairo surface at the current point.

For Cairo integration, use CreateCairoLayout(CR) instead of steps 1–3 to create a layout directly from an existing Cairo context.

Types

Type	Description
TPangoContext	Pango context — holds a font map, rendering settings (DPI, language, base direction). Created once per surface or Cairo context.
TPangoLayout	Core text layout object. Holds text content, font, width constraint, alignment, wrap mode, ellipsize mode, and computed line breaks. Reuse and update between frames.
TPangoFontDesc	Font description — encodes family, style, weight, and size. Created via `ParseFontDesc` or `NewFontDesc`. Serializes back to a human-readable string.
TPangoFontMap	Collection of all fonts available to Pango. The Cairo font map (`NewCairoFontMap`) is the standard choice on Linux desktops.
TPangoAttrList	List of styled spans to apply to a layout. Each attribute covers a byte range in the UTF-8 text. Use `AttrSetColor`/`AttrSetSize` to populate, then `SetAttributes` to attach.
TCairoContext	Opaque handle to a Cairo drawing context, as returned by the `cairo` package. Passed to `CreateCairoContext`, `CreateCairoLayout`, and the rendering functions.
TPangoAlignment	Enum: `paLeft=0` (default), `paCenter=1`, `paRight=2`. Controls horizontal alignment within the layout width.
TPangoWrapMode	Enum: `pwWord=0` (wrap at word boundaries), `pwChar=1` (wrap at any character), `pwWordChar=2` (word-wrap with char fallback for long tokens).
TPangoEllipsize	Enum: `peNone=0`, `peStart=1` (`"...text"`), `peMiddle=2` (`"te...xt"`), `peEnd=3` (`"text..."`). Requires a width constraint to take effect.
TPangoWeight	Enum: `pwThin=100`, `pwUltraLight=200`, `pwLight=300`, `pwNormal=400`, `pwMedium=500`, `pwSemiBold=600`, `pwBold=700`, `pwUltraBold=800`, `pwHeavy=900`.
TPangoLayoutLine	Record: `StartIndex: Integer` (byte offset into text), `Length: Integer` (byte count), `IsParagraphStart: Boolean`, `Width: Integer` (in Pango units = 1/1024 pixel).
TPangoRectangle	Record: `X, Y, W, H: Integer` in Pango units. Divide by `PANGO_SCALE` (1024) to obtain pixels.

API Reference

Font Map & Context

function NewCairoFontMap: TPangoFontMap

Create a Cairo-backed Pango font map. This is the standard font map for Cairo rendering and gives access to all fonts installed on the system.

function NewContext(FontMap: TPangoFontMap): TPangoContext

Create a Pango context from a font map. The context stores rendering settings such as DPI and base text direction. Required before creating a layout the manual way.

function CreateCairoContext(CR: TCairoContext): TPangoContext

Create a Pango context wired to an existing Cairo context. Inherits the Cairo surface DPI automatically. Prefer this over NewContext when you already have a Cairo context.

procedure FreeContext(Ctx: TPangoContext)

Release a Pango context and its associated resources.

Font Description

function ParseFontDesc(const Desc: string): TPangoFontDesc

Parse a font description string such as 'Sans Bold 12', 'Noto Serif Italic 14', or 'Monospace 10'. Returns a font description handle for use with SetFont.

function NewFontDesc(const Family: string; Weight: TPangoWeight; Italic: Boolean; SizePoints: Double): TPangoFontDesc

Create a font description from individual components. Equivalent to constructing the description string manually but type-safe.

function FontDescToString(Desc: TPangoFontDesc): string

Serialize a font description back to a human-readable string such as 'Sans Bold 12'. Useful for logging or persisting font choices.

procedure FreeFontDesc(Desc: TPangoFontDesc)

Release a font description created by ParseFontDesc or NewFontDesc.

Layout

function NewLayout(Ctx: TPangoContext): TPangoLayout

Create a text layout attached to a Pango context. Use when you have an explicit context from NewContext or CreateCairoContext.

function CreateCairoLayout(CR: TCairoContext): TPangoLayout

Create a layout directly from a Cairo context. This is the most convenient entry point when using the Cairo backend: it creates the Pango context internally and ties the layout to the Cairo surface.

procedure FreeLayout(Layout: TPangoLayout)

Release the layout and all its computed line data.

procedure SetText(Layout: TPangoLayout; const Text: string)

Set the plain UTF-8 text content of the layout. Pango re-runs line breaking and shaping on the next measuring or rendering call. Replaces any previously set text or markup.

procedure SetMarkup(Layout: TPangoLayout; const Markup: string)

Set the text as Pango markup. Inline tags such as , , and  are parsed and converted to an internal attribute list. Replaces any previously set text or markup.

procedure SetFont(Layout: TPangoLayout; Desc: TPangoFontDesc)

Set the default font for the layout from a pre-created font description handle.

procedure SetFontStr(Layout: TPangoLayout; const Desc: string)

Set the default font from a description string such as 'Noto Sans 14' or 'Monospace Bold 12'. Combines ParseFontDesc and SetFont in one call.

procedure SetWidth(Layout: TPangoLayout; Pixels: Integer)

Set the maximum layout width in pixels. Lines longer than this are wrapped according to the wrap mode. Pass -1 to disable wrapping entirely.

procedure SetAlignment(Layout: TPangoLayout; Align: TPangoAlignment)

Set horizontal text alignment within the layout width. Has no effect if no width constraint is set.

procedure SetWrap(Layout: TPangoLayout; Wrap: TPangoWrapMode)

Set the line-wrap strategy. pwWord (default) wraps at word boundaries; pwChar wraps at any character; pwWordChar tries word-wrap first and falls back to character-wrap for tokens that exceed the width.

procedure SetEllipsize(Layout: TPangoLayout; Mode: TPangoEllipsize)

Enable automatic truncation with an ellipsis character when the text does not fit. Requires a width constraint (SetWidth) and optionally a line limit (SetLines).

procedure SetLines(Layout: TPangoLayout; Lines: Integer)

Limit the layout to at most Lines lines. Any overflow is subject to the ellipsize mode. Combine with SetEllipsize(Layout, peEnd) for the classic "show N lines with trailing ellipsis" effect.

procedure SetLineSpacing(Layout: TPangoLayout; Factor: Double)

Set line spacing as a multiplier of the font's natural line height. 1.0 is the default; 1.5 gives 150% spacing, 2.0 gives double-spaced text.

Measuring

procedure GetSize(Layout: TPangoLayout; out W, H: Integer)

Return the layout's pixel dimensions after line breaking. W is the widest line; H is the total height including all lines and inter-line spacing. Use this to position or clip the layout before rendering.

function GetInkExtents(Layout: TPangoLayout): TPangoRectangle

Return the ink rectangle — the tightest bounding box around the actual drawn pixels, in Pango units. Divide fields by 1024 to convert to pixels. Excludes whitespace and inter-line gaps that GetSize includes.

function GetLineCount(Layout: TPangoLayout): Integer

Return the number of lines the layout was broken into after applying the width constraint and line limit. Call after setting text and before or after rendering.

Rendering with Cairo

procedure ShowLayout(CR: TCairoContext; Layout: TPangoLayout)

Render the layout to the Cairo context at the current Cairo point. The text is drawn using the current Cairo source color. Move the Cairo current point with cairo.MoveTo before calling.

procedure ShowLayoutAt(CR: TCairoContext; Layout: TPangoLayout; X, Y: Double)

Render the layout at the explicit position (X, Y) in Cairo user-space coordinates. Equivalent to calling cairo.MoveTo(CR, X, Y) followed by ShowLayout.

Attributes

function NewAttrList: TPangoAttrList

Allocate an empty attribute list. Add styled spans with AttrSetColor and AttrSetSize, then attach to a layout with SetAttributes. For most use-cases, Pango markup via SetMarkup is simpler.

procedure FreeAttrList(Attrs: TPangoAttrList)

Release an attribute list. The layout retains its own reference, so free the list after calling SetAttributes.

procedure AttrSetColor(Attrs: TPangoAttrList; R, G, B: Integer; StartByte, EndByte: Integer)

Add a foreground color attribute to the text byte range [StartByte, EndByte). R, G, B are in the range 0–65535 (Pango's 16-bit color space; multiply an 8-bit value by 256).

procedure AttrSetSize(Attrs: TPangoAttrList; SizePoints: Double; StartByte, EndByte: Integer)

Add a font size attribute to the text byte range. SizePoints is the size in typographic points. The attribute overrides the layout's default font size for the covered span.

procedure SetAttributes(Layout: TPangoLayout; Attrs: TPangoAttrList)

Attach an attribute list to the layout. Replaces any previously set attribute list. The layout takes its own reference; you may free Attrs afterwards.

Font Listing

function ListFontFamilies(FontMap: TPangoFontMap): array of string

Return the names of all font families available through the font map, e.g. 'Noto Sans', 'DejaVu Serif', 'Monospace'. Useful for building font-picker UIs or verifying that a required font is installed.

Info

function PangoVersion: string

Return the runtime Pango library version string, e.g. '1.52.1'.

Code Example with Cairo

The typical workflow is to create a Cairo surface and context first (using the cairo package), then create a Pango layout from the Cairo context with CreateCairoLayout, configure it, and render with ShowLayoutAt.

uses pango;

var
  Layout : TPangoLayout;
  CR     : TCairoContext;  { from cairo package }
  W, H   : Integer;
begin
  { CR = cairo_create(surface) — created via the cairo package }
  Layout := CreateCairoLayout(CR);

  SetFontStr(Layout, 'Noto Sans 14');
  SetWidth(Layout, 400);         { wrap at 400 px }
  SetAlignment(Layout, paCenter);
  SetEllipsize(Layout, peEnd);
  SetLines(Layout, 3);           { max 3 lines }

  { Plain text }
  SetText(Layout, 'Hello, World!');
  GetSize(Layout, W, H);
  WriteLn('Layout: ', W, 'x', H, ' px');
  ShowLayoutAt(CR, Layout, 10, 20);

  { Markup text }
  SetMarkup(Layout, '<b>Bold</b> and <span color="#ff6b6b">red</span> text');
  ShowLayoutAt(CR, Layout, 10, 60);

  FreeLayout(Layout);
end.

Font Description Syntax

Format: 'Family [Style] [Size]'

Pango selects the best matching font installed on the system. Style and size are optional.

'Sans Bold 12' — sans-serif, bold, 12 pt
'Noto Serif Italic 14' — Noto Serif, italic, 14 pt
'Monospace 10' — system monospace, 10 pt
'Noto Color Emoji 20' — color emoji font, 20 pt
'Noto Sans CJK SC 13' — Chinese (Simplified) text, 13 pt
'DejaVu Sans Mono Bold Oblique 11' — bold oblique monospace, 11 pt

If the exact family is not installed, Pango falls back to the closest available alternative. Use ListFontFamilies to enumerate installed families at runtime.