Chart-1.5.4: A library for generating 2D Charts and Plots

Copyright | (c) Tim Docker 2014
License | BSD-style (see chart/COPYRIGHT)
Safe Haskell | None
Language | Haskell98

Graphics.Rendering.Chart.Backend

Contents

- The backend Monad
- Backend Operations
- Backend Helpers
- Text Metrics
- Line Types
- Fill Types
- Font and Text Types

Description

This module provides the API for drawing operations abstracted to arbitrary `ChartBackend`s.

Synopsis

- type ChartBackend a = Program ChartBackendInstr a
- fillPath :: Path -> ChartBackend ()
- strokePath :: Path -> ChartBackend ()
- drawText :: Point -> String -> ChartBackend ()
- textSize :: String -> ChartBackend TextSize
- withTransform :: Matrix -> ChartBackend a -> ChartBackend a
- withClipRegion :: Rect -> ChartBackend a -> ChartBackend a
- withFontStyle :: FontStyle -> ChartBackend a -> ChartBackend a
- withFillStyle :: FillStyle -> ChartBackend a -> ChartBackend a
- withLineStyle :: LineStyle -> ChartBackend a -> ChartBackend a
- getPointAlignFn :: ChartBackend (Point -> Point)
- getCoordAlignFn :: ChartBackend (Point -> Point)
- data TextSize = TextSize {
  - textSizeWidth :: Double
  - textSizeAscent :: Double
  - textSizeDescent :: Double
  - textSizeYBearing :: Double
  - textSizeHeight :: Double
  }
- data LineCap
  - = LineCapButt
  - | LineCapRound
  - | LineCapSquare
- data LineJoin
  - = LineJoinMiter
  - | LineJoinRound
  - | LineJoinBevel
- data LineStyle = LineStyle {
  - _line_width :: Double
  - _line_color :: AlphaColour Double
  - _line_dashes :: [Double]
  - _line_cap :: LineCap
  - _line_join :: LineJoin
  }
- line_width :: Lens' LineStyle Double
- line_color :: Lens' LineStyle (AlphaColour Double)
- line_dashes :: Lens' LineStyle [Double]
- line_cap :: Lens' LineStyle LineCap
- line_join :: Lens' LineStyle LineJoin
- newtype FillStyle = FillStyleSolid {
  - _fill_color :: AlphaColour Double
  }
- data FontWeight
  - = FontWeightNormal
  - | FontWeightBold
- data FontSlant
  - = FontSlantNormal
  - | FontSlantItalic
  - | FontSlantOblique
- data FontStyle = FontStyle {
  - _font_name :: String
  - _font_size :: Double
  - _font_slant :: FontSlant
  - _font_weight :: FontWeight
  - _font_color :: AlphaColour Double
  }
- data HTextAnchor
  - = HTA_Left
  - | HTA_Centre
  - | HTA_Right
- data VTextAnchor
  - = VTA_Top
  - | VTA_Centre
  - | VTA_Bottom
  - | VTA_BaseLine
- font_name :: Lens' FontStyle String
- font_size :: Lens' FontStyle Double
- font_slant :: Lens' FontStyle FontSlant
- font_weight :: Lens' FontStyle FontWeight
- font_color :: Lens' FontStyle (AlphaColour Double)
- type AlignmentFn = Point -> Point
- data AlignmentFns
- vectorAlignmentFns :: AlignmentFns
- bitmapAlignmentFns :: AlignmentFns

# The backend Monad

type ChartBackend a = Program ChartBackendInstr a Source

A `ChartBackend` provides the capability to render a chart somewhere.

The coordinate system of the backend has its initial origin (0,0) in the top left corner of the drawing plane. The x-axis points towards the top right corner and the y-axis points towards the bottom left corner. The unit used by coordinates, the font size, and lengths is the always the same, but depends on the backend. All angles are measured in radians.

The line, fill and font style are set to their default values initially.

Information about the semantics of the instructions can be found in the documentation of `ChartBackendInstr`.

# Backend Operations

fillPath :: Path -> ChartBackend () Source

Fill the given path using the current `FillStyle`. The given path will be closed prior to filling. This function does not perform alignment operations on the path. See `Path` for the exact semantic of paths.

strokePath :: Path -> ChartBackend () Source

Stroke the outline of the given path using the current `LineStyle`. This function does not perform alignment operations on the path. See `Path` for the exact semantic of paths.

drawText :: Point -> String -> ChartBackend () Source

Draw a single-line textual label anchored by the baseline (vertical) left (horizontal) point. Uses the current `FontStyle` for drawing.

textSize :: String -> ChartBackend TextSize Source

Calculate a `TextSize` object with rendering information about the given string without actually rendering it.

withTransform :: Matrix -> ChartBackend a -> ChartBackend a Source

Apply the given transformation in this local environment when drawing. The given transformation is applied after the current transformation. This means both are combined.

withClipRegion :: Rect -> ChartBackend a -> ChartBackend a Source

Use the given clipping rectangle when drawing in this local environment. The new clipping region is intersected with the given clip region. You cannot escape the clip!

withFontStyle :: FontStyle -> ChartBackend a -> ChartBackend a Source

Use the given font style in this local environment when drawing text.

An implementing backend is expected to guarentee to support the following font families: `serif`, `sans-serif` and `monospace`;

If the backend is not able to find or load a given font it is required to fall back to a custom fail-safe font and use it instead.

withFillStyle :: FillStyle -> ChartBackend a -> ChartBackend a Source

Use the given fill style in this local environment when filling paths.

withLineStyle :: LineStyle -> ChartBackend a -> ChartBackend a Source

Use the given line style in this local environment when stroking paths.

# Backend Helpers

getPointAlignFn :: ChartBackend (Point -> Point) Source

Get the point alignment function

getCoordAlignFn :: ChartBackend (Point -> Point) Source

Get the coordinate alignment function

# Text Metrics

data TextSize Source

Text metrics returned by `textSize`.

Constructors

TextSize |

Fields

textSizeWidth :: Double

  The total width of the text.

textSizeAscent :: Double

  The ascent or space above the baseline.

textSizeDescent :: Double

  The decent or space below the baseline.

textSizeYBearing :: Double

  The Y bearing.

textSizeHeight :: Double

  The total height of the text.

Instances

Eq TextSize Source |
Show TextSize Source |

# Line Types

data LineCap Source

The different supported line ends.

Constructors

LineCapButt | Just cut the line straight.
LineCapRound | Make a rounded line end.
LineCapSquare | Make a square that ends the line.

Instances

Eq LineCap Source |
Ord LineCap Source |
Show LineCap Source |

data LineJoin Source

The different supported ways to join line ends.

Constructors

LineJoinMiter | Extends the outline until they meet each other.
LineJoinRound | Draw a circle fragment to connet line end.
LineJoinBevel | Like miter, but cuts it off if a certain threshold is exceeded.

Instances

Eq LineJoin Source |
Ord LineJoin Source |
Show LineJoin Source |

data LineStyle Source

Data type for the style of a line.

Constructors

LineStyle |

Fields

_line_width :: Double

  The thickness of a line in device units.

_line_color :: AlphaColour Double

  The color of a line.

_line_dashes :: [Double]

  The dash pattern. Every value at a even index gives a dash width and every value at a odd index gives a gap width in device units.

_line_cap :: LineCap

  How to end a line.

_line_join :: LineJoin

  How to connect two lines.

Instances

Eq LineStyle Source |
Show LineStyle Source |
Default LineStyle Source | The default line style.

line_width :: Lens' LineStyle Double Source

line_color :: Lens' LineStyle (AlphaColour Double) Source

line_dashes :: Lens' LineStyle [Double] Source

line_cap :: Lens' LineStyle LineCap Source

line_join :: Lens' LineStyle LineJoin Source

# Fill Types

newtype FillStyle Source

Abstract data type for a fill style.

The contained action sets the required fill style in the rendering state.

Constructors

FillStyleSolid |

Fields

_fill_color :: AlphaColour Double

Instances

Eq FillStyle Source |
Show FillStyle Source |
Default FillStyle Source | The default fill style.

# Font and Text Types

data FontWeight Source

The possible weights of a font.

Constructors

FontWeightNormal | Normal font style without weight.
FontWeightBold | Bold font.

Instances

Eq FontWeight Source |
Ord FontWeight Source |
Show FontWeight Source |
Default FontWeight Source | The default font weight.

data FontSlant Source

The possible slants of a font.

Constructors

FontSlantNormal | Normal font style without slant.
FontSlantItalic | With a slight slant.
FontSlantOblique | With a greater slant.

Instances

Eq FontSlant Source |
Ord FontSlant Source |
Show FontSlant Source |
Default FontSlant Source | The default font slant.

data FontStyle Source

Data type for a font.

Constructors

FontStyle |

Fields

_font_name :: String

  The font family or font face to use.

_font_size :: Double

  The height of the rendered font in device coordinates.

_font_slant :: FontSlant

  The slant to render with.

_font_weight :: FontWeight

  The weight to render with.

_font_color :: AlphaColour Double

  The color to render text with.

Instances

Eq FontStyle Source |
Show FontStyle Source |
Default FontStyle Source | The default font style.

data HTextAnchor Source

Possible horizontal anchor points for text.

Constructors

HTA_Left |
HTA_Centre |
HTA_Right |

Instances

Eq HTextAnchor Source |
Ord HTextAnchor Source |
Show HTextAnchor Source |

data VTextAnchor Source

Possible vertical anchor points for text.

Constructors

VTA_Top |
VTA_Centre |
VTA_Bottom |
VTA_BaseLine |

Instances

Eq VTextAnchor Source |
Ord VTextAnchor Source |
Show VTextAnchor Source |

font_name :: Lens' FontStyle String Source

font_size :: Lens' FontStyle Double Source

font_slant :: Lens' FontStyle FontSlant Source

font_weight :: Lens' FontStyle FontWeight Source

font_color :: Lens' FontStyle (AlphaColour Double) Source

type AlignmentFn = Point -> Point Source

A function to align points for a certain rendering device.

data AlignmentFns Source

Holds the point and coordinate alignment function.

vectorAlignmentFns :: AlignmentFns Source

Alignment to render on vector based graphics.

bitmapAlignmentFns :: AlignmentFns Source

Alignment to render on raster based graphics.