Diagrams.Backend.Cairo

A full-featured rendering backend for diagrams using the cairo rendering engine.

To invoke the cairo backend, you have three options.

• You can use the Diagrams.Backend.Cairo.CmdLine module to create standalone executables which output images when invoked.
• You can use the renderCairo function provided by this module, which gives you more flexible programmatic control over when and how images are output (making it easy to, for example, write a single program that outputs multiple images, or one that outputs images dynamically based on user input, and so on).
• Finally, for the most flexibility, you can directly use methods from the Backend instance for Cairo. In particular, renderDia has the generic type

renderDia :: b -> Options b v n -> QDiagram b v n m -> Result b v n

(omitting a few type class constraints). b represents the backend type, v the vector space, n the numeric field, and m the type of monoidal query annotations on the diagram. Options and Result are associated data and type families, respectively, which yield the type of option records and rendering results specific to any particular backend. For b ~ Cairo, v ~ V2, and n ~ Double, we have

data family Options Cairo V2 Double = CairoOptions
         { _cairoFileName     :: String             -- ^ The name of the file you want generated
         , _cairoSizeSpec     :: SizeSpec V2 Double -- ^ The requested size of the output
         , _cairoOutputType   :: OutputType         -- ^ the output format and associated options
         , _cairoBypassAdjust :: Bool               -- ^ Should the 'adjustDia' step be bypassed during rendering?
         }

type family Result Cairo V2 Double = (IO (), Render ())

So the type of renderDia resolves to

renderDia :: Cairo -> Options Cairo V2 Double -> QQDiagram Cairo V2 Double Any m -> (IO (), Render ())

which you could call like so:

renderDia Cairo (CairoOptions "foo.png" (Width 250) PNG False) (myDiagram :: QDiagram Cairo V2 Double Any)

This would return a pair; the first element is an IO () action which will write out foo.png to disk, and the second is a cairo rendering action which can be used, for example, to directly draw to a Gtk window. Note the type annotation on myDiagram which may be necessary to fix the type variable m; this example uses the type synonym Diagram b = QDiagram b (V b) (N b) Any to fix m = Any and fix v and n to backend specific types.

Rendering

renderCairo :: FilePath -> SizeSpec V2 Double -> QDiagram Cairo V2 Double Any -> IO ()

Render a diagram using the cairo backend, writing to the given output file and using the requested size. The output type (PNG, PS, PDF, or SVG) is determined automatically from the output file extension.

This function is provided as a convenience; if you need more flexibility than it provides, you can call renderDia directly, as described above.

Cairo-supported output formats

data OutputType

Output types supported by cairo, including four different file types (PNG, PS, PDF, SVG). If you want to output directly to GTK windows, see the diagrams-gtk package.

Constructors

PNG

Portable Network Graphics output.

PS

PostScript output

PDF

Portable Document Format output.

SVG

Scalable Vector Graphics output.

RenderOnly

Don't output any file; the returned IO () action will do nothing, but the Render () action can be used (e.g. to draw to a Gtk window; see the diagrams-gtk package).

Instances

Bounded OutputType

Methods

minBound :: OutputType

maxBound :: OutputType

Enum OutputType

Methods

succ :: OutputType -> OutputType

pred :: OutputType -> OutputType

toEnum :: Int -> OutputType

fromEnum :: OutputType -> Int

enumFrom :: OutputType -> [OutputType]

enumFromThen :: OutputType -> OutputType -> [OutputType]

enumFromTo :: OutputType -> OutputType -> [OutputType]

enumFromThenTo :: OutputType -> OutputType -> OutputType -> [OutputType]

Eq OutputType

Methods

(==) :: OutputType -> OutputType -> Bool

(/=) :: OutputType -> OutputType -> Bool

Ord OutputType

Methods

compare :: OutputType -> OutputType -> Ordering

(<) :: OutputType -> OutputType -> Bool

(<=) :: OutputType -> OutputType -> Bool

(>) :: OutputType -> OutputType -> Bool

(>=) :: OutputType -> OutputType -> Bool

max :: OutputType -> OutputType -> OutputType

min :: OutputType -> OutputType -> OutputType

Read OutputType

Methods

readsPrec :: Int -> ReadS OutputType

readList :: ReadS [OutputType]

readPrec :: ReadPrec OutputType

readListPrec :: ReadPrec [OutputType]

Show OutputType

Methods

showsPrec :: Int -> OutputType -> ShowS

show :: OutputType -> String

showList :: [OutputType] -> ShowS

Generic OutputType

Associated Types

type Rep OutputType :: * -> *

Methods

from :: OutputType -> Rep OutputType x

to :: Rep OutputType x -> OutputType

Hashable OutputType

Methods

hashWithSalt :: Int -> OutputType -> Int

hash :: OutputType -> Int

type Rep OutputType

type Rep OutputType = D1 (MetaData "OutputType" "Diagrams.Backend.Cairo.Internal" "diagrams-cairo-1.4-HuatH6VZc9pNOHRiKlO0U" False) ((:+:) ((:+:) (C1 (MetaCons "PNG" PrefixI False) U1) (C1 (MetaCons "PS" PrefixI False) U1)) ((:+:) (C1 (MetaCons "PDF" PrefixI False) U1) ((:+:) (C1 (MetaCons "SVG" PrefixI False) U1) (C1 (MetaCons "RenderOnly" PrefixI False) U1))))

Cairo-specific options

Unfortunately, Haddock does not yet support documentation for associated data families, so we must just provide it manually. This module defines

data family Options Cairo V2 Double = CairoOptions
  { _cairoFileName   :: String     -- ^ The name of the file you want generated
  , _cairoSizeSpec   :: SizeSpec V2 Double -- ^ The requested size of the output
  , _cairoOutputType :: OutputType -- ^ the output format and associated options
  , _cairoBypassAdjust  :: Bool    -- ^ Should the 'adjustDia' step be bypassed during rendering?
  }

See the documentation at the top of Diagrams.Backend.Cairo for information on how to make use of this.

Backend token

data Cairo

This data declaration is simply used as a token to distinguish the cairo backend: (1) when calling functions where the type inference engine would otherwise have no way to know which backend you wanted to use, and (2) as an argument to the Backend and Renderable type classes.

Constructors

Cairo

Instances

Eq Cairo

Methods

(==) :: Cairo -> Cairo -> Bool

(/=) :: Cairo -> Cairo -> Bool

Ord Cairo

Methods

compare :: Cairo -> Cairo -> Ordering

(<) :: Cairo -> Cairo -> Bool

(<=) :: Cairo -> Cairo -> Bool

(>) :: Cairo -> Cairo -> Bool

(>=) :: Cairo -> Cairo -> Bool

max :: Cairo -> Cairo -> Cairo

min :: Cairo -> Cairo -> Cairo

Read Cairo

Methods

readsPrec :: Int -> ReadS Cairo

readList :: ReadS [Cairo]

readPrec :: ReadPrec Cairo

readListPrec :: ReadPrec [Cairo]

Show Cairo

Methods

showsPrec :: Int -> Cairo -> ShowS

show :: Cairo -> String

showList :: [Cairo] -> ShowS

Backend Cairo V2 Double

Associated Types

data Render Cairo (V2 :: * -> *) Double :: *

type Result Cairo (V2 :: * -> *) Double :: *

data Options Cairo (V2 :: * -> *) Double :: *

Methods

adjustDia :: (Additive V2, Monoid' m, Num Double) => Cairo -> Options Cairo V2 Double -> QDiagram Cairo V2 Double m -> (Options Cairo V2 Double, Transformation V2 Double, QDiagram Cairo V2 Double m)

renderRTree :: Cairo -> Options Cairo V2 Double -> RTree Cairo V2 Double Annotation -> Result Cairo V2 Double

Renderable (Text Double) Cairo

Methods

render :: Cairo -> Text Double -> Render Cairo (V (Text Double)) (N (Text Double))

Renderable (DImage Double Embedded) Cairo

Methods

render :: Cairo -> DImage Double Embedded -> Render Cairo (V (DImage Double Embedded)) (N (DImage Double Embedded))

Renderable (DImage Double External) Cairo

Methods

render :: Cairo -> DImage Double External -> Render Cairo (V (DImage Double External)) (N (DImage Double External))

Renderable (Path V2 Double) Cairo

Methods

render :: Cairo -> Path V2 Double -> Render Cairo (V (Path V2 Double)) (N (Path V2 Double))

Renderable (Trail V2 Double) Cairo

Methods

render :: Cairo -> Trail V2 Double -> Render Cairo (V (Trail V2 Double)) (N (Trail V2 Double))

Show (Options Cairo V2 Double)

Methods

showsPrec :: Int -> Options Cairo V2 Double -> ShowS

show :: Options Cairo V2 Double -> String

showList :: [Options Cairo V2 Double] -> ShowS

Monoid (Render Cairo V2 Double)

Methods

mempty :: Render Cairo V2 Double

mappend :: Render Cairo V2 Double -> Render Cairo V2 Double -> Render Cairo V2 Double

mconcat :: [Render Cairo V2 Double] -> Render Cairo V2 Double

Hashable (Options Cairo V2 Double)

Methods

hashWithSalt :: Int -> Options Cairo V2 Double -> Int

hash :: Options Cairo V2 Double -> Int

Renderable (Segment Closed V2 Double) Cairo

Methods

render :: Cairo -> Segment Closed V2 Double -> Render Cairo (V (Segment Closed V2 Double)) (N (Segment Closed V2 Double))

type V Cairo

type V Cairo = V2

type N Cairo

type N Cairo = Double

data Options Cairo V2 Double

data Options Cairo V2 Double = CairoOptions {

• _cairoFileName :: String
• _cairoSizeSpec :: SizeSpec V2 Double
• _cairoOutputType :: OutputType
• _cairoBypassAdjust :: Bool

}

type Result Cairo V2 Double

type Result Cairo V2 Double = (IO (), Render ())

data Render Cairo V2 Double

data Render Cairo V2 Double = C (RenderM ())

type MainOpts [(String, QDiagram Cairo V2 Double Any)]

type MainOpts [(String, QDiagram Cairo V2 Double Any)] = (MainOpts (QDiagram Cairo V2 Double Any), DiagramMultiOpts)

type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)]

type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] = (DiagramOpts, GifOpts)

type MainOpts (Animation Cairo V2 Double)

type MainOpts (Animation Cairo V2 Double) = ((DiagramOpts, DiagramAnimOpts), DiagramLoopOpts)

type MainOpts (QDiagram Cairo V2 Double Any)

type MainOpts (QDiagram Cairo V2 Double Any) = (DiagramOpts, DiagramLoopOpts)

type B = Cairo