Gtk2HsContentsIndex
Graphics.UI.Gtk.Pango.Rendering
Portabilityportable (depends on GHC)
Stabilityprovisional
Maintainergtk2hs-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 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.
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
}
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 PangoItems.

  • A given attribute is applied from its start position paStart up, but not including the end position, paEnd.
Constructors
AttrLanguageA hint as to what language this piece of text is written in.
paStart :: Int
paEnd :: Int
paLang :: Language
AttrFamilyThe font family, e.g. sans serif.
paStart :: Int
paEnd :: Int
paFamily :: String
AttrStyleThe slant of the current font.
paStart :: Int
paEnd :: Int
paStyle :: FontStyle
AttrWeightWeight of font, e.g. WeightBold.
paStart :: Int
paEnd :: Int
paWeight :: Weight
AttrVariantVariantSmallCaps will display lower case letters as small upper case letters (if the font supports this).
paStart :: Int
paEnd :: Int
paVariant :: Variant
AttrStretchStretch or condense the width of the letters.
paStart :: Int
paEnd :: Int
paStretch :: Stretch
AttrSizeSpecify 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
AttrFontDescriptionSpecify several attributes of a font at once.
paStart :: Int
paEnd :: Int
paFontDescription :: FontDescription
AttrForegroundSpecify the foreground color.
paStart :: Int
paEnd :: Int
paColor :: Color
AttrBackgroundSpecify the background color.
paStart :: Int
paEnd :: Int
paColor :: Color
AttrUnderlineSpecify 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
AttrStrikethroughSpecify 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
AttrRiseDisplace 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
AttrScaleScale the font up (values greater than one) or shrink the font.
paStart :: Int
paEnd :: Int
paScale :: Double
AttrFallbackDetermine 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
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 :: 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. 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 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
:: GlyphItemthe rendered string
-> Intthe index into the string
-> Boolreturn 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 0.8