diagrams-cairo-1.5: Cairo backend for diagrams drawing EDSL

Copyright | (c) 2011 Diagrams-cairo team (see LICENSE)
License | BSD-style (see LICENSE)
Maintainer | diagrams-discuss@googlegroups.com
Safe Haskell | None
Language | Haskell2010

Diagrams.Backend.Cairo

Contents

- Rendering
- Cairo-supported output formats
- Cairo-specific options
- Backend token

Description

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.

Synopsis

- renderCairo :: FilePath -> SizeSpec V2 Double -> QDiagram Cairo V2 Double Any -> IO ()
- data OutputType
  - = PNG
  - | PS
  - | PDF
  - | SVG
  - | RenderOnly
- data Cairo = Cairo
- type B = Cairo

# Rendering

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

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 Source #

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

Instances details

Bounded OutputType Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods minBound :: OutputType Source # maxBound :: OutputType Source #
Enum OutputType Source # |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

Methods

succ :: OutputType -> OutputType Source #

pred :: OutputType -> OutputType Source #

toEnum :: Int -> OutputType Source #

fromEnum :: OutputType -> Int Source #

enumFrom :: OutputType -> [OutputType] Source #

enumFromThen :: OutputType -> OutputType -> [OutputType] Source #

enumFromTo :: OutputType -> OutputType -> [OutputType] Source #

enumFromThenTo :: OutputType -> OutputType -> OutputType -> [OutputType] Source #

Generic OutputType Source # |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

Associated Types

type Rep OutputType |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

type Rep OutputType = D1 ('MetaData "OutputType" "Diagrams.Backend.Cairo.Internal" "diagrams-cairo-1.5-7whDVksPswEEJgZnrNwV6i" 'False) ((C1 ('MetaCons "PNG" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "PS" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "PDF" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "SVG" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "RenderOnly" 'PrefixI 'False) (U1 :: Type -> Type))))

Methods

from :: OutputType -> Rep OutputType x Source #

to :: Rep OutputType x -> OutputType Source #

Read OutputType Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods readsPrec :: Int -> ReadS OutputType Source # readList :: ReadS [OutputType] Source # readPrec :: ReadPrec OutputType Source # readListPrec :: ReadPrec [OutputType] Source #
Show OutputType Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods showsPrec :: Int -> OutputType -> ShowS Source # show :: OutputType -> String Source # showList :: [OutputType] -> ShowS Source #
Eq OutputType Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods (==) :: OutputType -> OutputType -> Bool Source # (/=) :: OutputType -> OutputType -> Bool Source #
Ord OutputType Source # |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

Methods

compare :: OutputType -> OutputType -> Ordering Source #

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

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

(>) :: OutputType -> OutputType -> Bool Source #

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

max :: OutputType -> OutputType -> OutputType Source #

min :: OutputType -> OutputType -> OutputType Source #

Hashable OutputType Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods hashWithSalt :: Int -> OutputType -> Int Source # hash :: OutputType -> Int Source #
type Rep OutputType Source # |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

type Rep OutputType = D1 ('MetaData "OutputType" "Diagrams.Backend.Cairo.Internal" "diagrams-cairo-1.5-7whDVksPswEEJgZnrNwV6i" 'False) ((C1 ('MetaCons "PNG" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "PS" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "PDF" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "SVG" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "RenderOnly" 'PrefixI 'False) (U1 :: Type -> Type))))

# 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 Source #

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

Instances details

Read Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods readsPrec :: Int -> ReadS Cairo Source # readList :: ReadS [Cairo] Source # readPrec :: ReadPrec Cairo Source # readListPrec :: ReadPrec [Cairo] Source #
Show Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods showsPrec :: Int -> Cairo -> ShowS Source # show :: Cairo -> String Source # showList :: [Cairo] -> ShowS Source #
Eq Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods (==) :: Cairo -> Cairo -> Bool Source # (/=) :: Cairo -> Cairo -> Bool Source #
Ord Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods compare :: Cairo -> Cairo -> Ordering Source # (<) :: Cairo -> Cairo -> Bool Source # (<=) :: Cairo -> Cairo -> Bool Source # (>) :: Cairo -> Cairo -> Bool Source # (>=) :: Cairo -> Cairo -> Bool Source # max :: Cairo -> Cairo -> Cairo Source # min :: Cairo -> Cairo -> Cairo Source #
Backend Cairo V2 Double Source # |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

Associated Types

data Render Cairo V2 Double |
Instance details Defined in Diagrams.Backend.Cairo.Internal data Render Cairo V2 Double = C (RenderM ())
type Result Cairo V2 Double |
Instance details Defined in Diagrams.Backend.Cairo.Internal type Result Cairo V2 Double = (IO (), Render ())
data Options Cairo V2 Double |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

data Options Cairo V2 Double = CairoOptions {

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

}

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) Source #

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

Mainable [(QDiagram Cairo V2 Double Any, GifDelay)] Source # |

Instance details

Defined in Diagrams.Backend.Cairo.CmdLine

Associated Types

type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] = (DiagramOpts, GifOpts)

Methods

mainArgs :: Parseable (MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)]) => proxy [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO (MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)]) Source #

mainRender :: MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] -> [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO () Source #

mainWith :: [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO () Source #

Mainable [(String, QDiagram Cairo V2 Double Any)] Source # |

Instance details

Defined in Diagrams.Backend.Cairo.CmdLine

Associated Types

type MainOpts [(String, QDiagram Cairo V2 Double Any)] |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(String, QDiagram Cairo V2 Double Any)] = (MainOpts (QDiagram Cairo V2 Double Any), DiagramMultiOpts)

Methods

mainArgs :: Parseable (MainOpts [(String, QDiagram Cairo V2 Double Any)]) => proxy [(String, QDiagram Cairo V2 Double Any)] -> IO (MainOpts [(String, QDiagram Cairo V2 Double Any)]) Source #

mainRender :: MainOpts [(String, QDiagram Cairo V2 Double Any)] -> [(String, QDiagram Cairo V2 Double Any)] -> IO () Source #

mainWith :: [(String, QDiagram Cairo V2 Double Any)] -> IO () Source #

Renderable (Text Double) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> Text Double -> Render Cairo (V (Text Double)) (N (Text Double)) Source #
Renderable (Path V2 Double) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> Path V2 Double -> Render Cairo (V (Path V2 Double)) (N (Path V2 Double)) Source #
Renderable (Trail V2 Double) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> Trail V2 Double -> Render Cairo (V (Trail V2 Double)) (N (Trail V2 Double)) Source #
Renderable (DImage Double Embedded) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> DImage Double Embedded -> Render Cairo (V (DImage Double Embedded)) (N (DImage Double Embedded)) Source #
Renderable (DImage Double External) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> DImage Double External -> Render Cairo (V (DImage Double External)) (N (DImage Double External)) Source #
Mainable (Animation Cairo V2 Double) Source # |

Instance details

Defined in Diagrams.Backend.Cairo.CmdLine

Associated Types

type MainOpts (Animation Cairo V2 Double) |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (Animation Cairo V2 Double) = (DiagramOpts, DiagramAnimOpts)

Methods

mainArgs :: Parseable (MainOpts (Animation Cairo V2 Double)) => proxy (Animation Cairo V2 Double) -> IO (MainOpts (Animation Cairo V2 Double)) Source #

mainRender :: MainOpts (Animation Cairo V2 Double) -> Animation Cairo V2 Double -> IO () Source #

mainWith :: Animation Cairo V2 Double -> IO () Source #

Monoid (Render Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods mempty :: Render Cairo V2 Double Source # mappend :: Render Cairo V2 Double -> Render Cairo V2 Double -> Render Cairo V2 Double Source # mconcat :: [Render Cairo V2 Double] -> Render Cairo V2 Double Source #
Semigroup (Render Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods (<>) :: Render Cairo V2 Double -> Render Cairo V2 Double -> Render Cairo V2 Double Source # sconcat :: NonEmpty (Render Cairo V2 Double) -> Render Cairo V2 Double Source # stimes :: Integral b => b -> Render Cairo V2 Double -> Render Cairo V2 Double Source #
Show (Options Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods showsPrec :: Int -> Options Cairo V2 Double -> ShowS Source # show :: Options Cairo V2 Double -> String Source # showList :: [Options Cairo V2 Double] -> ShowS Source #
Eq (Options Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods (==) :: Options Cairo V2 Double -> Options Cairo V2 Double -> Bool Source # (/=) :: Options Cairo V2 Double -> Options Cairo V2 Double -> Bool Source #
Hashable (Options Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods hashWithSalt :: Int -> Options Cairo V2 Double -> Int Source # hash :: Options Cairo V2 Double -> Int Source #
Renderable (Segment Closed V2 Double) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> Segment Closed V2 Double -> Render Cairo (V (Segment Closed V2 Double)) (N (Segment Closed V2 Double)) Source #
Mainable (QDiagram Cairo V2 Double Any) Source # |

Instance details

Defined in Diagrams.Backend.Cairo.CmdLine

Associated Types

type MainOpts (QDiagram Cairo V2 Double Any) |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (QDiagram Cairo V2 Double Any) = DiagramOpts

Methods

mainArgs :: Parseable (MainOpts (QDiagram Cairo V2 Double Any)) => proxy (QDiagram Cairo V2 Double Any) -> IO (MainOpts (QDiagram Cairo V2 Double Any)) Source #

mainRender :: MainOpts (QDiagram Cairo V2 Double Any) -> QDiagram Cairo V2 Double Any -> IO () Source #

mainWith :: QDiagram Cairo V2 Double Any -> IO () Source #

type N Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal type N Cairo = Double
type V Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal type V Cairo = V2
data Options Cairo V2 Double Source # |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

data Options Cairo V2 Double = CairoOptions {

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

}

data Render Cairo V2 Double Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal data Render Cairo V2 Double = C (RenderM ())
type Result Cairo V2 Double Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal type Result Cairo V2 Double = (IO (), Render ())
type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] Source # |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] = (DiagramOpts, GifOpts)
type MainOpts [(String, QDiagram Cairo V2 Double Any)] Source # |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(String, QDiagram Cairo V2 Double Any)] = (MainOpts (QDiagram Cairo V2 Double Any), DiagramMultiOpts)
type MainOpts (Animation Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (Animation Cairo V2 Double) = (DiagramOpts, DiagramAnimOpts)
type MainOpts (QDiagram Cairo V2 Double Any) Source # |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (QDiagram Cairo V2 Double Any) = DiagramOpts

type B = Cairo Source #