Graphics.Rendering.Pango.Rendering

Functions to run the rendering pipeline.

• This module provides elementary rendering functions. For a simpler interface, consider using PangoLayouts.
• The Pango rendering pipeline takes a string of Unicode characters, divides them into sequences of letters that have the same characteristics such as font, size, color, etc. Such a sequence is called PangoItem. Each PangoItem is then converted into one GlyphItem, that is an actual sequence of glyphs, where several characters might be turned into legatures or clusters, e.g. an "e" and an accent modifier are turned into a single glyph. These GlyphItems can then be rendered onto the output device with functions such as cairoShowGlyphString.

PangoItem: Partition text into units with similar attributes.

data PangoItem

A sequence of characters that are rendered with the same settings.

• A preprocessing stage done by itemize splits the input text into several chunks such that each chunk can be rendered with the same font, direction, slant, etc. Some attributes such as the color, underline or strikethrough do not affect a break into several PangoItems. See also GlyphItem.

pangoItemize :: GlibString string => PangoContext -> string -> [PangoAttribute] -> IO [PangoItem]

Turn a string into a sequence of glyphs.

• Partitions the input string into segments with the same text direction and shaping engine. The generated list of items will be in logical order (the start offsets of the items are ascending).

pangoItemGetFontMetrics :: PangoItem -> IO FontMetrics

Retrieve the metrics of the font that was chosen to break the given PangoItem.

pangoItemGetFont :: PangoItem -> IO Font

Extract the font used for this PangoItem.

pangoItemGetLanguage :: PangoItem -> IO Language

Extract the Language used for this PangoItem.

GlyphItem: Turn text segments into glyph sequences.

data GlyphItem

A sequence of glyphs for a chunk of a string.

• A glyph item contains the graphical representation of a PangoItem. Clusters (like e and an accent modifier) as well as legatures (such as ffi turning into a single letter that omits the dot over the i) are usually represented as a single glyph.

pangoShape :: PangoItem -> IO GlyphItem

Turn a PangoItem into a GlyphItem.

• Turns a PangoItem, that is, sequence of characters with the same attributes such as font, size and color, into a GlyphItem which contains the graphical representation of these characters. GlyphItems can be rendered directly (and several times) onto screens.

glyphItemExtents :: GlyphItem -> IO (PangoRectangle, PangoRectangle)

Ask for bounding rectangles of this glyph sequence.

• Compute the ink and logical extents of a glyph string. The logical size is used for positioning, the ink size is the smallest bounding box that includes all character pixels. The ink size can be smaller or larger than the logical size.

glyphItemExtentsRange :: GlyphItem -> Int -> Int -> IO (PangoRectangle, PangoRectangle)

Ask for bounding rectangles for a sub-range of a glyph sequence.

• The returned rectangles are relative to the given sub-range, that is, the result of this function is the same as if glyphItemExtents were called on the sub-string.

glyphItemIndexToX

Arguments

:: GlyphItem

the rendered string

-> Int

the index into the string

-> Bool

return the beginning (False) or the end of the character

-> IO Double

Get the horizontal position of a character.

• Clusters (e.g. "e" with an accent modifier) are divided up into equal portions.

glyphItemXToIndex :: GlyphItem -> Double -> IO (Int, Bool)

Get the character at the given horizontal position.

• The position is clipped to the width of this line.
• The function returns the position in the string that corresponds to the given horizontal location. Furthermore, if the position lies on the first half of the character, False is returned.

glyphItemGetLogicalWidths :: GlyphItem -> Maybe Bool -> IO [Double]

Retrieve the width of every character in a string.

• The boolean parameter determines if the returned array starts with the leftmost glyph (False) or with the rightmost glyph (True). If Nothing is passed in, the direction is taken from the GlyphItem, i.e., the array starts with the leftmost glyph for left-to-rigth text and with the rightmost glyph for right-to-left text. When multiple characters compose a single glyph, the width of this glyph is divided among the characters that compose this cluster.

glyphItemSplit :: GlyphItem -> Int -> IO (GlyphItem, GlyphItem)

Split a GlyphItem at the given index.

• The given GlyphItem is split at the given index. The index must be at least one and not greater or equal to length, i.e. the item must be split into two non-empty segments. The function throws an ArrayException if the index is out of bounds.