| Gtk2Hs | Contents | Index

Graphics.UI.Gtk.Pango.Font

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

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.
- `FontMetrics`: Information about the font that will be used to render a specific Graphics.UI.Gtk.Pango.Context.Context or Graphics.UI.Gtk.Pango.Rendering.PangoItem.

Synopsis

type PangoUnit = Double
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
pangoFontMapListFamilies :: FontMap -> IO [FontFamily]
data FontFamily
pangoFontFamilyIsMonospace :: FontFamily -> Bool
pangoFontFamilyListFaces :: FontFamily -> IO [FontFace]
data FontFace
pangoFontFaceListSizes :: FontFace -> IO (Maybe [Double])
pangoFontFaceDescribe :: FontFace -> IO FontDescription

data FontMetrics = FontMetrics {

ascent :: Double
descent :: Double
approximateCharWidth :: Double
approximateDigitWidth :: Double
underlineThickness :: Double
underlinePosition :: Double
strikethroughThickenss :: Double
strikethroughPosition :: Double

}

Documentation
type PangoUnit = Double
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
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

GObjectClass FontMap
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 Graphics.UI.Gtk.Cairo.cairoFontMapGetDefault.

data FontFamily

Instances

Show FontFamily
GObjectClass FontFamily
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

Show FontFace
GObjectClass FontFace
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 FontMetrics

The characteristic measurements of a font.

- All values are measured in pixels.
- In Pango versions before 1.6 only `ascent`, `descent`, `approximateCharWidth` and `approximateDigitWidth` are available.

Constructors

FontMetrics |

ascent :: Double | The ascent is the distance from the baseline to the logical top of a line of text. (The logical top may be above or below the top of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.)
descent :: Double | The descent is the distance from the baseline to the logical bottom of a line of text. (The logical bottom may be above or below the bottom of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.)
approximateCharWidth :: Double | The approximate character width. This is merely a representative value useful, for example, for determining the initial size for a window. Actual characters in text will be wider and narrower than this.
approximateDigitWidth :: Double | The approximate digit width. This is merely a representative value useful, for example, for determining the initial size for a window. Actual digits in text can be wider and narrower than this, though this value is generally somewhat more accurate than `approximateCharWidth`.
underlineThickness :: Double | The suggested thickness to draw an underline.
underlinePosition :: Double | The suggested position to draw the underline. The value returned is the distance above the baseline of the top of the underline. Since most fonts have underline positions beneath the baseline, this value is typically negative.
strikethroughThickenss :: Double | The suggested thickness to draw for the strikethrough.
strikethroughPosition :: Double | The suggested position to draw the strikethrough. The value returned is the distance above the baseline of the top of the strikethrough.

Instances

Show FontMetrics

Produced by Haddock version 2.4.2