-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Helper functions for dealing with SVG files -- -- A library for performing simple manipulations with SVG files, -- primarily tiling several SVG files together into a single file (ready -- for printing). -- -- As well as the exposed library modules, the package comes with an -- executable called SVGtile that can perform this SVG tiling from the -- command-line. SVGtile takes a list of SVG files as command-line -- arguments, then generates lots of files of the form TiledFront-1.svg. -- Paper-size (default A4) and other settings can be set using -- command-line options: see SVGtile --help. @package svgutils @version 0.1 -- | A module containing all the basic types for dealing with SVG files. module Data.SVG.SVG -- | A wrapper around Double for measurements in millimetres. -- -- The Show instance appends "mm" to the value. newtype MM MM :: Double -> MM -- | A size (width and height) measured in millimetres. data Size Size :: MM -> MM -> Size mmWidth :: Size -> MM mmHeight :: Size -> MM -- | A dots-per-inch measurement for dealing with graphics. -- -- (To get dots per millimetre, divide by 25.4) newtype DPI DPI :: Double -> DPI -- | A container for SVG documents. See the makeSVG function for -- creating them, and the getSVGElement function for accessing -- them. -- -- The Show instance prints this as a complete XML document. data SVG -- | Gets the top-level "svg" element. getSVGElement :: SVG -> Element -- | Creates an SVG item from an XML element. -- -- If the element is named "svg", this function will return a Just -- result. If the element is named anything else, this function will -- return Nothing. makeSVG :: Element -> Maybe SVG -- | Makes a blank SVG file of the given size. makeBlankSVG :: Size -> SVG -- | Parses a String containing a complete XML document into an SVG. -- -- This function can fail in two ways: it will fail either if the -- String is not a complete valid XML document, or if the -- top-level element is not an "svg" element. parseSVG :: String -> Maybe SVG -- | Gets the size of the SVG document. -- -- In an ideal world, this size would be some measurement in centimetres, -- etc. that would be trivial to convert to millimetres. -- -- Unfortunately, some programs (most notably Inkscape) record the -- document size in pixels, which is very unhelpful when trying to get -- the size of the document for printing, etc. Therefore you must supply -- a DPI parameter for converting this pixel size into -- millimetres. On my system, Inkscape uses a DPI of 90 but I am not sure -- if this is system-specific or a constant that is used on all machines. -- -- The method will fail if either the width or height attributes are -- missing at the top-level, or they cannot be parsed using -- parseCoord. getSVGSize :: DPI -> SVG -> Maybe Size -- | Gets all the namespaces from the header of the SVG file. namespaces :: SVG -> [(QName, String)] -- | Parses a coordinate/length value from an SVG file. -- -- All valid units are supported, except "em" and "ex" which depend on -- the size of the current font. -- -- The DPI parameter is needed in order to convert user coordinate -- units (pixels) to millimetres. -- -- This method assumes that no transformation is currently in place on -- the size. It is primarily intended for parsing the size of the -- document, where there can be no transformations present. parseCoord :: DPI -> String -> Maybe MM -- | Places the given XML content (which is assumed to be a valid SVG -- fragment) at the given (x, y) coordinates by wrapping them in an -- appropriate SVG transformation (<g> element with transform -- attribute). -- -- Note that if you place the resulting element inside a transformation, -- that transformation will of course apply to this element as is -- standard in SVG. So if you place something at (20, 20) then wrap that -- in a scale transformation with factor 0.1, it will end up placed at -- (2, 2). placeAt :: DPI -> (MM, MM) -> [Content] -> Element instance Num DPI instance Ord DPI instance Eq DPI instance Fractional DPI instance Show Size instance Eq Size instance Num MM instance Ord MM instance Eq MM instance Fractional MM instance Show SVG instance Show DPI instance Show MM -- | A module with a helper function for tiling several SVG files (which -- can vary in size) into a group of SVG files of a specific size. module Data.SVG.Tile -- | An item to be tiled, with an SVG image for the front, and an optional -- SVG for the back. If the two images are different sizes, the smallest -- size that can accommodate both is used for tiling. This means that if -- you have a larger back image, the front will have enough space left to -- match up with the back (and vice versa). -- -- The label is currently only used for error reporting. data TileItem TileItem :: String -> SVG -> Maybe SVG -> TileItem tileLabel :: TileItem -> String tileFront :: TileItem -> SVG tileBack :: TileItem -> Maybe SVG -- | Tiles the given items. -- -- This function takes a list of front (and optional back) SVG images, -- then arranges them using the given paper size, margin and gaps between -- items. The return is a list of front images (with back images where -- needed). -- -- This method is intended to be used to put multiple small SVG items -- onto a single page for printing. -- -- The layout algorithm is very simple. It places the first item in the -- top-left, then attempts to fill the rest of the row with the next -- items in the list. Once a row is full, it moves down to make more -- rows, until the page is full. Thus, list items will always appear in -- the order they are given, and you can potentially get some wasted -- space, especially if the items vary wildly in size, and are not sorted -- by size first. -- -- This method can fail because it cannot get the sizes of the items to -- tile using getSVGSize, because there are conflicts between the -- namespaces of the files, or because there are one or more items in the -- list that cannot fit on a single page by themselves. tileSVGs :: DPI -> TileSettings -> [TileItem] -> Either String [(SVG, Maybe SVG)] -- | The settings for tiling: the paper size, margin (same on all sides) -- and gap (between tiled items) data TileSettings TileSettings :: Size -> MM -> MM -> Bool -> TileSettings tilePaperSize :: TileSettings -> Size tileMargin :: TileSettings -> MM tileGap :: TileSettings -> MM ignoreNamespaceConflicts :: TileSettings -> Bool instance Show TileSettings instance Eq TileSettings -- | A module with a helper function for dealing with paper sizes. module Data.SVG.Paper -- | Parses a paper size which can either be a known name or a detailed -- size. -- -- Paper sizes such as "a4" are not part of the SVG specification; this -- helper is provided here in case you want help getting a paper size -- from a command-line argument. -- -- This recognises two styles of paper size. One is a literal name from -- the list below, and the other is "width*height" (no spaces around the -- asterisk) where width and height are valid SVG sizes that can be -- parsed by parseCoord (using a DPI of 90). The list of literal -- sizes, recognised case-insensitive (most of which are from the ISO 216 -- standard), is: -- -- parsePaperSize :: String -> Maybe Size