| Gtk2Hs | Contents | Index

Graphics.UI.Gtk.Pango.Rendering

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

Contents

`PangoAttribute`: Apply emphasis to parts of an output string.
`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 Graphics.UI.Gtk.Cairo.cairoShowGlyphString.

Synopsis

data PangoAttribute

= AttrLanguage {

paStart :: Int
paEnd :: Int
paLang :: Language

}

| AttrFamily {

paStart :: Int
paEnd :: Int
paFamily :: String

}

| AttrStyle {

paStart :: Int
paEnd :: Int
paStyle :: FontStyle

}

| AttrWeight {

paStart :: Int
paEnd :: Int
paWeight :: Weight

}

| AttrVariant {

paStart :: Int
paEnd :: Int
paVariant :: Variant

}

| AttrStretch {

paStart :: Int
paEnd :: Int
paStretch :: Stretch

}

| AttrSize {

paStart :: Int
paEnd :: Int
paSize :: Double

}

| AttrAbsSize {

paStart :: Int
paEnd :: Int
paSize :: Double

}

| AttrFontDescription {

paStart :: Int
paEnd :: Int
paFontDescription :: FontDescription

}

| AttrForeground {

paStart :: Int
paEnd :: Int
paColor :: Color

}

| AttrBackground {

paStart :: Int
paEnd :: Int
paColor :: Color

}

| AttrUnderline {

paStart :: Int
paEnd :: Int
paUnderline :: Underline

}

| AttrUnderlineColor {

paStart :: Int
paEnd :: Int
paColor :: Color

}

| AttrStrikethrough {

paStart :: Int
paEnd :: Int
paStrikethrough :: Bool

}

| AttrStrikethroughColor {

paStart :: Int
paEnd :: Int
paColor :: Color

}

| AttrRise {

paStart :: Int
paEnd :: Int
paRise :: Double

}

| AttrShape {

paStart :: Int
paEnd :: Int
paInk :: PangoRectangle
paLogical :: PangoRectangle

}

| AttrScale {

paStart :: Int
paEnd :: Int
paScale :: Double

}

| AttrFallback {

paStart :: Int
paEnd :: Int
paFallback :: Bool

}

| AttrLetterSpacing {

paStart :: Int
paEnd :: Int
paLetterSpacing :: Double

}

| AttrGravity {

paStart :: Int
paEnd :: Int
paGravity :: PangoGravity

}

| AttrGravityHint {

paStart :: Int
paEnd :: Int
paGravityHint :: PangoGravityHint

}

data PangoItem
pangoItemize :: PangoContext -> String -> [PangoAttribute] -> IO [PangoItem]
pangoItemGetFontMetrics :: PangoItem -> IO FontMetrics
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)

`PangoAttribute`: Apply emphasis to parts of an output string.
data PangoAttribute

Attributes for `PangoItem`s.

- A given attribute is applied from its start position `paStart` up, but not including the end position, `paEnd`.

Constructors

AttrLanguage | A hint as to what language this piece of text is written in.

paStart :: Int |
paEnd :: Int |
paLang :: Language |

AttrFamily | The font family, e.g. sans serif.

paStart :: Int |
paEnd :: Int |
paFamily :: String |

AttrStyle | The slant of the current font.

paStart :: Int |
paEnd :: Int |
paStyle :: FontStyle |

AttrWeight | Weight of font, e.g. `WeightBold`.

paStart :: Int |
paEnd :: Int |
paWeight :: Weight |

AttrVariant | `VariantSmallCaps` will display lower case letters as small upper case letters (if the font supports this).

paStart :: Int |
paEnd :: Int |
paVariant :: Variant |

AttrStretch | Stretch or condense the width of the letters.

paStart :: Int |
paEnd :: Int |
paStretch :: Stretch |

AttrSize | Specify the size of the font in points.

paStart :: Int |
paEnd :: Int |
paSize :: Double |

AttrAbsSize

Specify the size of the font in device units (pixels).

- Available in Pango 1.8.0 and higher.

paStart :: Int |
paEnd :: Int |
paSize :: Double |

AttrFontDescription | Specify several attributes of a font at once. Note that no deep copy of the description is made when this attributes is passed to or received from functions.

paStart :: Int |
paEnd :: Int |
paFontDescription :: FontDescription |

AttrForeground | Specify the foreground color.

paStart :: Int |
paEnd :: Int |
paColor :: Color |

AttrBackground | Specify the background color.

paStart :: Int |
paEnd :: Int |
paColor :: Color |

AttrUnderline | Specify the kind of underline, e.g. `UnderlineSingle`.

paStart :: Int |
paEnd :: Int |
paUnderline :: Underline |

AttrUnderlineColor

Specify the color of an underline.

- Available in Pango 1.8.0 and higher.

paStart :: Int |
paEnd :: Int |
paColor :: Color |

AttrStrikethrough | Specify if this piece of text should have a line through it.

paStart :: Int |
paEnd :: Int |
paStrikethrough :: Bool |

AttrStrikethroughColor

Specify the color of the strike through line.

- Available in Pango 1.8.0 and higher.

paStart :: Int |
paEnd :: Int |
paColor :: Color |

AttrRise | Displace the text vertically. Positive values move the text upwards.

paStart :: Int |
paEnd :: Int |
paRise :: Double |

AttrShape

Restrict the amount of what is drawn of the marked shapes.

- Available in Pango 1.8.0 and higher.

paStart :: Int |
paEnd :: Int |
paInk :: PangoRectangle |
paLogical :: PangoRectangle |

AttrScale | Scale the font up (values greater than one) or shrink the font.

paStart :: Int |
paEnd :: Int |
paScale :: Double |

AttrFallback | Determine if a fall back font should be substituted if no matching font is available.

paStart :: Int |
paEnd :: Int |
paFallback :: Bool |

AttrLetterSpacing

Add extra space between graphemes of the text.

- Available in Pango 1.6.0 and higher.

paStart :: Int |
paEnd :: Int |
paLetterSpacing :: Double |

AttrGravity

Sets the gravity field of a font description. The gravity field specifies how the glyphs should be rotated. If gravity is GravityAuto, this actually unsets the gravity mask on the font description.

- This function is seldom useful to the user. Gravity should normally be set on a PangoContext.
- Available in Pango 1.16.0 and higher.

paStart :: Int |
paEnd :: Int |
paGravity :: PangoGravity |

AttrGravityHint

Set the way horizontal scripts behave in a vertical context.

- Available in Pango 1.16.0 and higher.

paStart :: Int |
paEnd :: Int |
paGravityHint :: PangoGravityHint |

Instances

Show PangoAttribute

`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`.
`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

:: 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.

Produced by Haddock version 2.4.2