Diagrams.Backend.Cairo.Text

This module provides convenience functions for querying information from cairo. In particular, this provides utilities for information about fonts, and creating text primitives with bounds based on the font being used. To render text with automatically determined envelopes, use textLineBounded, textLineBoundedIO, textVisualBounded, or textVisualBoundedIO.

Many of these functions take a Style R2 parameter, determining the style to apply to the text before rendering / querying information about the text. These Style R2 parameters can be created a variety of ways, but the most direct will likely be by applying style-transforming functions such as font, fontSize, fontSlant, and fontWeight to mempty. This works because there are instances of HasStyle and Monoid for Style v.

Primitives

These create diagrams instantiated with extent-based envelopes.

textLineBoundedIO :: Style R2 -> String -> IO (Diagram Cairo R2)

Creates text diagrams with their envelopes set such that using vcat . map (textLineBounded style) stacks them in the way that the font designer intended.

textVisualBoundedIO :: Style R2 -> String -> IO (Diagram Cairo R2)

Creates a text diagram with its envelope set to enclose the glyphs of the text, including leading (though not trailing) whitespace.

Unsafe

These are convenient unsafe variants of the above operations using unsafePerformIO. In practice, they should be fairly safe as the results depend only on the parameters and the font information (which ought to stay the same during a given execution).

kerningCorrection :: Style R2 -> Char -> Char -> Double

Queries the amount of horizontal offset that needs to be applied in order to position the second character properly, in the event that it is hcat-ed baselineText. See kerningCorrectionIO; this variant uses unsafePerformIO but should be fairly safe in practice.

textLineBounded :: Style R2 -> String -> Diagram Cairo R2

Creates text diagrams with their envelopes set such that using vcat . map (textLineBounded style) stacks them in the way that the font designer intended. See textLineBoundedIO; this variant uses unsafePerformIO but should be fairly safe in practice.

textVisualBounded :: Style R2 -> String -> Diagram Cairo R2

Creates a text diagram with its envelope set to enclose the glyphs of the text, including leading (though not trailing) whitespace. See textVisualBoundedIO; this variant uses unsafePerformIO but should be fairly safe in practice.

Extents

Data Structures

data TextExtents

A more convenient data structure for the results of a text-extents query.

Constructors

TextExtents R2 R2 R2

bearing :: Lens' TextExtents R2

textSize :: Lens' TextExtents R2

advance :: Lens' TextExtents R2

data FontExtents

A more convenient data structure for the results of a font-extents query.

Constructors

FontExtents Double Double Double R2

ascent :: Lens' FontExtents Double

descent :: Lens' FontExtents Double

height :: Lens' FontExtents Double

maxAdvance :: Lens' FontExtents R2

Queries

getTextExtents :: Style R2 -> String -> Render TextExtents

Get the extents of a string of text, given a style to render it with.

getFontExtents :: Style R2 -> Render FontExtents

Gets the intrinsic extents of a font.

getExtents :: Style R2 -> String -> Render (FontExtents, TextExtents)

Gets both the FontExtents and TextExtents of the string with the a particular style applied. This is more efficient than calling both getFontExtents and getTextExtents.

kerningCorrectionIO :: Style R2 -> Char -> Char -> IO Double

Queries the amount of horizontal offset that needs to be applied in order to position the second character properly, in the event that it is hcat-ed baselineText.

Utilities

queryCairo :: Render a -> IO a

Executes a cairo action on a dummy, zero-size image surface, in order to query things like font information.

unsafeCairo :: Render a -> a

Unsafely invokes queryCairo using unsafePerformIO.

cairoWithStyle :: Render a -> Style R2 -> Render a

Executes the given cairo action, with styling applied.