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.

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

type StyleParam = forall a. HasStyle a => a -> a

Existential type for mutations on objects that "have style". This is used as a parameter to getTextExtents and getFontExtents in order to set font-size and font-face.

cairoWithStyle :: Render a -> StyleParam -> Render a

Executes the given cairo action, with styling applied. This does not do all styling - just attributes that are processed by "cairoMiscStyle", which does clip, fill color, fill rule, and, importantly for this module, font face, style, and weight.

Extents

Data Structures

data TextExtents

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

Constructors

TextExtents

Fields

bearing :: R2

textSize :: R2

advance :: R2

data FontExtents

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

Constructors

FontExtents

Fields

ascent :: Double

descent :: Double

height :: Double

maxAdvance :: R2

Queries

getTextExtents :: StyleParam -> String -> Render TextExtents

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

getFontExtents :: StyleParam -> Render FontExtents

Gets the intrinsic extents of a font.

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

Primitives

These create diagrams instantiated with extents-based envelopes

textLineBoundedIO :: StyleParam -> 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 :: StyleParam -> 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 postfixed with "IO". They should be pretty well-behaved as the results just depend on the parameters and the font information (which ought to stay the same during a given execution).

kerningCorrection :: StyleParam -> Char -> Char -> Double

textLineBounded, textVisualBounded :: StyleParam -> String -> Diagram Cairo R2