Graphics.Rendering.Pango.Rendering

pango-0.12.3: Binding to the Pango text rendering engine.

Portability | portable (depends on GHC)
Stability | provisional
Maintainer | gtk2hs-users@lists.sourceforge.net
Safe Haskell | None

Graphics.Rendering.Pango.Rendering

Contents

- `PangoItem`: Partition text into units with similar attributes.
- `GlyphItem`: Turn text segments into glyph sequences.

Description

Functions to run the rendering pipeline.

- This module provides elementary rendering functions. For a simpler interface, consider using `PangoLayout`s.
- 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 `GlyphItem`s can then be rendered onto the output device with functions such as `cairoShowGlyphString`.

Synopsis

- data PangoItem
- pangoItemize :: PangoContext -> String -> [PangoAttribute] -> IO [PangoItem]
- pangoItemGetFontMetrics :: PangoItem -> IO FontMetrics
- pangoItemGetFont :: PangoItem -> IO Font
- pangoItemGetLanguage :: PangoItem -> IO Language
- data GlyphItem
- pangoShape :: PangoItem -> IO GlyphItem
- glyphItemExtents :: GlyphItem -> IO (PangoRectangle, PangoRectangle)
- glyphItemExtentsRange :: GlyphItem -> Int -> Int -> IO (PangoRectangle, PangoRectangle)
- glyphItemIndexToX :: GlyphItem -> Int -> Bool -> IO Double
- glyphItemXToIndex :: GlyphItem -> Double -> IO (Int, Bool)
- glyphItemGetLogicalWidths :: GlyphItem -> Maybe Bool -> IO [Double]
- glyphItemSplit :: GlyphItem -> Int -> IO (GlyphItem, GlyphItem)

# `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 `PangoItem`s. See also `GlyphItem`.

pangoItemize :: 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. `GlyphItem`s can be rendered directly (and several times) onto screens.

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

Ask for bounding rectangles of this glyph sequence.

- Compute the logical and ink extents of a glyph string. The logical extend 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 that the logical layout.

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.