Graphics.Rendering.Pango.Font

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

Description

Fonts. The selection of an appropriate font to render text becomes a substantial task in the presence of Unicode where a single font does not cover the whole range of possible characters. Pango provides several concepts to find appropriate fonts and to query information about them:

- `FontDescription`: Font descriptions provide a way to query and state requirements on fonts. This data structure has several fields describing different characteristics of a font. Each of these fields can be set of left unspecified.
- `FontMap` : A font map represents the set of fonts available for a particular rendering system. In particular this map defines the relation between font size and pixel size in terms of the output medium.
- `FontFamily` : A font family represents a set of fonts that have related faces, that is, their faces share a common design, but differ in slant, weight, width and other aspects.
- `FontFace`: A face is a specific font where all characteristics are fixed except for the size.
- `Font`: A font in the underlying rendering system.
- `FontMetrics`: Information about the font that will be used to render a specific `Context` or `PangoItem`.

Synopsis

- data FontDescription
- fontDescriptionNew :: IO FontDescription
- fontDescriptionCopy :: FontDescription -> IO FontDescription
- fontDescriptionSetFamily :: FontDescription -> String -> IO ()
- fontDescriptionGetFamily :: FontDescription -> IO (Maybe String)
- fontDescriptionSetStyle :: FontDescription -> FontStyle -> IO ()
- fontDescriptionGetStyle :: FontDescription -> IO (Maybe FontStyle)
- fontDescriptionSetVariant :: FontDescription -> Variant -> IO ()
- fontDescriptionGetVariant :: FontDescription -> IO (Maybe Variant)
- fontDescriptionSetWeight :: FontDescription -> Weight -> IO ()
- fontDescriptionGetWeight :: FontDescription -> IO (Maybe Weight)
- fontDescriptionSetStretch :: FontDescription -> Stretch -> IO ()
- fontDescriptionGetStretch :: FontDescription -> IO (Maybe Stretch)
- fontDescriptionSetSize :: FontDescription -> Double -> IO ()
- fontDescriptionGetSize :: FontDescription -> IO (Maybe Double)
- data FontMask
  - = PangoFontMaskFamily
  - | PangoFontMaskStyle
  - | PangoFontMaskVariant
  - | PangoFontMaskWeight
  - | PangoFontMaskStretch
  - | PangoFontMaskSize
  - | PangoFontMaskGravity
- fontDescriptionUnsetFields :: FontDescription -> [FontMask] -> IO ()
- fontDescriptionMerge :: FontDescription -> FontDescription -> Bool -> IO ()
- fontDescriptionBetterMatch :: FontDescription -> FontDescription -> FontDescription -> Bool
- fontDescriptionFromString :: String -> IO FontDescription
- fontDescriptionToString :: FontDescription -> IO String
- data FontMap
- class GObjectClass o => FontMapClass o
- pangoFontMapListFamilies :: FontMap -> IO [FontFamily]
- data FontFamily
- class GObjectClass o => FontFamilyClass o
- pangoFontFamilyIsMonospace :: FontFamily -> Bool
- pangoFontFamilyListFaces :: FontFamily -> IO [FontFace]
- data FontFace
- class GObjectClass o => FontFaceClass o
- pangoFontFaceListSizes :: FontFace -> IO (Maybe [Double])
- pangoFontFaceDescribe :: FontFace -> IO FontDescription
- data Font
- class GObjectClass o => FontClass o

# Documentation

data FontDescription

A possibly partial description of font(s).

Instances

Show FontDescription |

fontDescriptionNew :: IO FontDescription

Create a new font description.

- All field are unset.

fontDescriptionCopy :: FontDescription -> IO FontDescription

Make a deep copy of a font description.

fontDescriptionSetFamily :: FontDescription -> String -> IO ()

Set the font famliy.

- A font family is a name designating the design of the font (e.g. Sans or Times) without the variant.
- In some contexts a comma separated list of font families can be used.

fontDescriptionGetFamily :: FontDescription -> IO (Maybe String)

Get the font family.

- `Nothing` is returned if the font family is not set.

fontDescriptionSetStyle :: FontDescription -> FontStyle -> IO ()

fontDescriptionGetStyle :: FontDescription -> IO (Maybe FontStyle)

Get the style field.

fontDescriptionSetVariant :: FontDescription -> Variant -> IO ()

Set the variant field.

fontDescriptionGetVariant :: FontDescription -> IO (Maybe Variant)

Get the variant field.

fontDescriptionSetWeight :: FontDescription -> Weight -> IO ()

Set the weight field.

fontDescriptionGetWeight :: FontDescription -> IO (Maybe Weight)

Get the weight field.

fontDescriptionSetStretch :: FontDescription -> Stretch -> IO ()

Set the stretch field.

fontDescriptionGetStretch :: FontDescription -> IO (Maybe Stretch)

Get the stretch field.

fontDescriptionSetSize :: FontDescription -> Double -> IO ()

Set the size field.

- The given size is in points (pts). One point is 1/72 inch.

fontDescriptionGetSize :: FontDescription -> IO (Maybe Double)

Get the size field.

data FontMask

Flags denoting which fields in a font description are set.

Constructors

PangoFontMaskFamily |
PangoFontMaskStyle |
PangoFontMaskVariant |
PangoFontMaskWeight |
PangoFontMaskStretch |
PangoFontMaskSize |
PangoFontMaskGravity |

Instances

Bounded FontMask |
Enum FontMask | Set the style field. Most fonts will have either a `StyleItalic` or `StyleOblique` but rarely both.
Flags FontMask |

fontDescriptionUnsetFields :: FontDescription -> [FontMask] -> IO ()

Reset fields in a font description.

fontDescriptionMerge :: FontDescription -> FontDescription -> Bool -> IO ()

Merge two font descriptions.

- Copy fields from the second description to the first. If the boolean parameter is set, existing fields in the first description will be replaced.

fontDescriptionBetterMatch :: FontDescription -> FontDescription -> FontDescription -> Bool

Determine which of two descriptions matches a given description better.

- Returns `True` if the last description is a better match to the first arguement than the middle one.
- Approximate matching is done on weight and style. If the other attributes do not match, the function returns `False`.

fontDescriptionFromString :: String -> IO FontDescription

Create a font description from a string.

- The given argument must have the form `[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]` where `FAMILY_LIST` is a comma separated list of font families optionally terminated by a comma, `STYLE_OPTIONS` is a whitespace separated list of words where each word describes one of style, variant, weight or stretch. `SIZE` is a decimal number giving the size of the font in points. If any of these fields is absent, the resulting `FontDescription` will have the corresponing fields unset.

fontDescriptionToString :: FontDescription -> IO String

Convert a font description to a string.

- Creates a string representation of a font description. See `fontDescriptionFromString` for the format of the string.

data FontMap

Instances

Eq FontMap |
Ord FontMap |
GObjectClass FontMap |
FontMapClass FontMap |

class GObjectClass o => FontMapClass o

Instances

FontMapClass FontMap |

pangoFontMapListFamilies :: FontMap -> IO [FontFamily]

Ask for the different font families that a particular back-end supports.

- The `FontMap` can be acquired by calling `cairoFontMapGetDefault`.

data FontFamily

Instances

Eq FontFamily |
Ord FontFamily |
Show FontFamily |
GObjectClass FontFamily |
FontFamilyClass FontFamily |

class GObjectClass o => FontFamilyClass o

Instances

FontFamilyClass FontFamily |

pangoFontFamilyIsMonospace :: FontFamily -> Bool

Ask if the given family contains monospace fonts.

- A monospace font is a font designed for text display where the characters form a regular grid. For Western languages this would mean that the advance width of all characters are the same, but this categorization also includes Asian fonts which include double-width characters: characters that occupy two grid cells.
- The best way to find out the grid-cell size is to query the members of the according `FontMetrics` structure.

pangoFontFamilyListFaces :: FontFamily -> IO [FontFace]

Ask for the faces contained in a particular family.

- Asks for all font faces in the given family. The faces in a family share a common design, but differ in slant, weight, width and other aspects. For example, the font family Sans contains several fonts such as Helvetica and Arial.

data FontFace

Instances

Eq FontFace |
Ord FontFace |
Show FontFace |
GObjectClass FontFace |
FontFaceClass FontFace |

class GObjectClass o => FontFaceClass o

Instances

FontFaceClass FontFace |

pangoFontFaceListSizes :: FontFace -> IO (Maybe [Double])

Ask for available sizes of this font face.

- List the available sizes for a font. This is only applicable to bitmap fonts since all other fonts can be scaled arbitrarily. For scalable fonts, this function returns `Nothing`. The sizes returned are in ascending order, their unit is points (1/72 inch).

pangoFontFaceDescribe :: FontFace -> IO FontDescription

Ask for a description of this face.

- Returns the family, style, variant, weight and stretch of a `FontFace`. The size field of the resulting font description will be unset.

data Font

Instances

Eq Font |
Ord Font |
GObjectClass Font |
FontClass Font |

class GObjectClass o => FontClass o

Instances

FontClass Font |