Copyright | (c) 2011 Diagrams-cairo team (see LICENSE) |
---|---|
License | BSD-style (see LICENSE) |
Maintainer | diagrams-discuss@googlegroups.com |
Safe Haskell | None |
Language | Haskell2010 |
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 forCairo
. In particular,renderDia
has the generic type
renderDia :: b -> Options b v -> QDiagram b v m -> Result b v
(omitting a few type class constraints). b
represents the
backend type, v
the vector space, 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
and v ~ R2
, we have
data family Options Cairo R2 = CairoOptions { _cairoFileName :: String -- ^ The name of the file you want generated , _cairoSizeSpec :: SizeSpec2D -- ^ 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 R2 = (IO (), Render
())
So the type of renderDia
resolves to
renderDia :: Cairo -> Options Cairo R2 -> QDiagram Cairo R2 m -> (IO (), Render
())
which you could call like so:
renderDia Cairo (CairoOptions "foo.png" (Width 250) PNG False) (myDiagram :: Diagram Cairo R2)
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 v = QDiagram b v Any
to fix m = Any
.
- renderCairo :: FilePath -> SizeSpec2D -> Diagram Cairo R2 -> IO ()
- data OutputType
- = PNG
- | PS
- | SVG
- | RenderOnly
- data Cairo = Cairo
- type B = Cairo
Rendering
renderCairo :: FilePath -> SizeSpec2D -> Diagram Cairo R2 -> 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.
PNG | Portable Network Graphics output. |
PS | PostScript output |
Portable Document Format output. | |
SVG | Scalable Vector Graphics output. |
RenderOnly | Don't output any file; the returned |
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 R2 = CairoOptions { _cairoFileName :: String -- ^ The name of the file you want generated , _cairoSizeSpec :: SizeSpec2D -- ^ The requested size of the output , _cairoOutputType :: OutputType -- ^ the output format and associated options }
See the documentation at the top of Diagrams.Backend.Cairo for information on how to make use of this.
Important note: a bug in GHC 7.0.x and 7.4.1 prevents re-exporting this data family. (Strangely, this bug seems to be present in 7.0 and 7.4 but not 7.2.) To bring CairoOptions into scope when using GHC 7.0.x or 7.4 you must import Diagrams.Backend.Cairo.Internal.
Backend token
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.
Eq Cairo | |
Ord Cairo | |
Read Cairo | |
Show Cairo | |
Typeable * Cairo | |
Backend Cairo R2 | |
Renderable Text Cairo | |
Mainable [(String, Diagram Cairo R2)] | |
Mainable [(Diagram Cairo R2, GifDelay)] | |
Renderable (DImage External) Cairo | |
Renderable (Path R2) Cairo | |
Renderable (Trail R2) Cairo | |
Show (Options Cairo R2) | |
Monoid (Render Cairo R2) | |
Mainable (Diagram Cairo R2) | |
Mainable (Animation Cairo R2) | |
Hashable (Options Cairo R2) | |
Renderable (Segment Closed R2) Cairo | |
data Options Cairo R2 = CairoOptions {} | |
type Result Cairo R2 = (IO (), Render ()) | |
data Render Cairo R2 = C (RenderM ()) | |
type MainOpts [(String, Diagram Cairo R2)] = (MainOpts (Diagram Cairo R2), DiagramMultiOpts) | |
type MainOpts [(Diagram Cairo R2, GifDelay)] = (DiagramOpts, GifOpts) | |
type MainOpts (Diagram Cairo R2) = (DiagramOpts, DiagramLoopOpts) | |
type MainOpts (Animation Cairo R2) = (MainOpts (Diagram Cairo R2), DiagramAnimOpts) |