Portability | GHC |
---|---|

Stability | unstable |

Maintainer | stephen.tetley@gmail.com |

A Picture-with-implicit-context object.

This is the corresponding type to Picture in the Wumpus-Core.

Note - many of the composition functions are in
*destructor form*. As Wumpus cannot make a Picture from an
empty list of Pictures, *destructor form* decomposes the
list into the `head`

and `rest`

as arguments in the function
signature, rather than take a possibly empty list and have to
throw an error.

TODO - PosImage no longer supports composition operators, so better names are up for grabs...

- data CtxPicture u
- type DCtxPicture = CtxPicture Double
- runCtxPicture :: DrawingContext -> CtxPicture u -> Maybe (Picture u)
- runCtxPictureU :: DrawingContext -> CtxPicture u -> Picture u
- drawTracing :: (Real u, Floating u, FromPtSize u) => TraceDrawing u a -> CtxPicture u
- clipCtxPicture :: (Num u, Ord u) => PrimPath u -> CtxPicture u -> CtxPicture u
- mapCtxPicture :: (Picture u -> Picture u) -> CtxPicture u -> CtxPicture u
- cxpBeneath :: (Num u, Ord u) => CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpUniteCenter :: (Fractional u, Ord u) => CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpRight :: (Num u, Ord u) => CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpDown :: (Num u, Ord u) => CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpCenteredAt :: (Fractional u, Ord u) => CtxPicture u -> Point2 u -> CtxPicture u
- cxpRow :: (Real u, Floating u, FromPtSize u) => CtxPicture u -> [CtxPicture u] -> CtxPicture u
- cxpColumn :: (Real u, Floating u, FromPtSize u) => CtxPicture u -> [CtxPicture u] -> CtxPicture u
- cxpRightSep :: (Num u, Ord u) => u -> CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpDownSep :: (Num u, Ord u) => u -> CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpRowSep :: (Real u, Floating u, FromPtSize u) => u -> CtxPicture u -> [CtxPicture u] -> CtxPicture u
- cxpColumnSep :: (Real u, Floating u, FromPtSize u) => u -> CtxPicture u -> [CtxPicture u] -> CtxPicture u
- cxpAlignH :: (Fractional u, Ord u) => HAlign -> CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpAlignV :: (Fractional u, Ord u) => VAlign -> CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpAlignSepH :: (Fractional u, Ord u) => HAlign -> u -> CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpAlignSepV :: (Fractional u, Ord u) => VAlign -> u -> CtxPicture u -> CtxPicture u -> CtxPicture u
- cxpAlignRow :: (Real u, Floating u, FromPtSize u) => HAlign -> CtxPicture u -> [CtxPicture u] -> CtxPicture u
- cxpAlignColumn :: (Real u, Floating u, FromPtSize u) => VAlign -> CtxPicture u -> [CtxPicture u] -> CtxPicture u
- cxpAlignRowSep :: (Real u, Floating u, FromPtSize u) => HAlign -> u -> CtxPicture u -> [CtxPicture u] -> CtxPicture u
- cxpAlignColumnSep :: (Real u, Floating u, FromPtSize u) => VAlign -> u -> CtxPicture u -> [CtxPicture u] -> CtxPicture u

# Documentation

data CtxPicture u Source

A *Contextual Picture*.

This type corresponds to the `Picture`

type in Wumpus-Core, but
it is embedded with a `DrawingContext`

(for font properties,
fill colour etc.). So it is a function
*from DrawingContext to Picture*.

Internally the result is actually a (Maybe Picture) and not a Picture, this is a trick to promote the extraction from possibly empty drawings (created by TraceDrawing) to the top-level of the type hierarchy where client code can deal with empty drawings explicitly (empty Pictures cannot be rendered by Wumpus-Core).

a `oplus` b

The `OPlus`

(semigroup) instance for `CtxPicture`

draws picture
a in front of picture b in the z-order, neither picture is
moved. (Usually the picture composition operators in this
module move the second picture aligning it somehow with the
first).

(Real u, Floating u) => Rotate (CtxPicture u) | |

(Real u, Floating u) => RotateAbout (CtxPicture u) | |

(Num u, Ord u) => Scale (CtxPicture u) | |

(Num u, Ord u) => Translate (CtxPicture u) | |

(Num u, Ord u) => OPlus (CtxPicture u) | a `oplus` b Place 'drawing' a over b. The idea of |

type DCtxPicture = CtxPicture DoubleSource

Version of CtxPicture specialized to Double for the unit type.

runCtxPicture :: DrawingContext -> CtxPicture u -> Maybe (Picture u)Source

`runCtxPicture`

: ` drawing_ctx * ctx_picture -> Maybe Picture `

Run a `CtxPicture`

with the supplied `DrawingContext`

producing a `Picture`

.

The resulting Picture may be empty. Wumpus-Core cannot generate empty pictures as they have no bounding box, so the result is wrapped within a Maybe. This delegates reponsibility for handling empty pictures to client code.

runCtxPictureU :: DrawingContext -> CtxPicture u -> Picture uSource

`runCtxPictureU`

: ` drawing_ctx * ctx_picture -> Picture `

*Unsafe* version of `runCtxPicture`

.

This function throws a runtime error when supplied with an empty CtxPicture.

drawTracing :: (Real u, Floating u, FromPtSize u) => TraceDrawing u a -> CtxPicture uSource

`drawTracing`

: ` trace_drawing -> CtxPicture `

Transform a `TraceDrawing`

into a `CtxPicture`

.

clipCtxPicture :: (Num u, Ord u) => PrimPath u -> CtxPicture u -> CtxPicture uSource

`clipCtxPicture`

: ` path * ctx_picture -> CtxPicture `

Clip a picture with a path.

mapCtxPicture :: (Picture u -> Picture u) -> CtxPicture u -> CtxPicture uSource

`mapCtxPicture`

: ` trafo * ctx_picture -> CtxPicture `

Apply a picture transformation function to the `Picture`

warpped in a `CtxPicture`

.

# Composition

cxpBeneath :: (Num u, Ord u) => CtxPicture u -> CtxPicture u -> CtxPicture uSource

`cxpBeneath`

: ` ctx_picture1 * ctx_picture2 -> CtxPicture `

a `cxpBeneath` b

Similarly `beneath`

draws the first picture behind the second
picture in the z-order, neither picture is moved.

cxpUniteCenter :: (Fractional u, Ord u) => CtxPicture u -> CtxPicture u -> CtxPicture uSource

Draw `a`

, move `b`

so its center is at the same center as
`a`

, `b`

is drawn over underneath in the zorder.

a `cxpUniteCenter` b

cxpRight :: (Num u, Ord u) => CtxPicture u -> CtxPicture u -> CtxPicture uSource

a `cxpRight` b

Horizontal composition - position picture `b`

to the right of
picture `a`

.

cxpDown :: (Num u, Ord u) => CtxPicture u -> CtxPicture u -> CtxPicture uSource

a `cxpDown` b

Vertical composition - position picture `b`

*down* from picture
`a`

.

cxpCenteredAt :: (Fractional u, Ord u) => CtxPicture u -> Point2 u -> CtxPicture uSource

Center the picture at the supplied point.

cxpRow :: (Real u, Floating u, FromPtSize u) => CtxPicture u -> [CtxPicture u] -> CtxPicture uSource

`cxpRow`

: ` ctx_picture1 * [ctx_picture] -> CtxPicture `

Make a row of pictures concatenating them horizontally.

Note - this function is in *destructor form*. As Wumpus cannot
make a Picture from an empty list of Pictures,
*destructor form* decomposes the list into the `head`

and the
`rest`

in the function signature, rather than take a possibly
empty list and have to throw an error.

cxpColumn :: (Real u, Floating u, FromPtSize u) => CtxPicture u -> [CtxPicture u] -> CtxPicture uSource

`cxpColumn`

: ` ctx_picture1 * [ctx_picture] -> CtxPicture `

Make a column of pictures concatenating them vertically.

Note - this function is in *destructor form*.

cxpRightSep :: (Num u, Ord u) => u -> CtxPicture u -> CtxPicture u -> CtxPicture uSource

cxpRightSep n a b

Horizontal composition - move `b`

, placing it to the right
of `a`

with a horizontal gap of `n`

separating the pictures.

cxpDownSep :: (Num u, Ord u) => u -> CtxPicture u -> CtxPicture u -> CtxPicture uSource

cxpDownSep n a b

Vertical composition - move `b`

, placing it below `a`

with a
vertical gap of `n`

separating the pictures.

cxpRowSep :: (Real u, Floating u, FromPtSize u) => u -> CtxPicture u -> [CtxPicture u] -> CtxPicture uSource

picRowSep n x xs

Concatenate the list of pictures `xs`

horizontally with
`hspace`

starting at `x`

. The pictures are interspersed with
spaces of `n`

units.

cxpColumnSep :: (Real u, Floating u, FromPtSize u) => u -> CtxPicture u -> [CtxPicture u] -> CtxPicture uSource

vsepPic n xs

Concatenate the list of pictures `xs`

vertically with
`vspace`

starting at `x`

. The pictures are interspersed with
spaces of `n`

units.

# Compose with alignment

cxpAlignH :: (Fractional u, Ord u) => HAlign -> CtxPicture u -> CtxPicture u -> CtxPicture uSource

cxpAlignH align a b

Horizontal composition - move `b`

, placing it to the right
of `a`

and align it with the top, center or bottom of `a`

.

cxpAlignV :: (Fractional u, Ord u) => VAlign -> CtxPicture u -> CtxPicture u -> CtxPicture uSource

cxpAlignV align a b

Vertical composition - move `b`

, placing it below `a`

and align it with the left, center or right of `a`

.

cxpAlignSepH :: (Fractional u, Ord u) => HAlign -> u -> CtxPicture u -> CtxPicture u -> CtxPicture uSource

cxpAlignSepH align sep a b

Spacing version of `cxpAlignH`

- move `b`

to the right of `a`

separated by `sep`

units, align `b`

according to `align`

.

cxpAlignSepV :: (Fractional u, Ord u) => VAlign -> u -> CtxPicture u -> CtxPicture u -> CtxPicture uSource

cxpAlignSepV align sep a b

Spacing version of alignV - move `b`

below `a`

separated by `sep`

units, align `b`

according to `align`

.

cxpAlignRow :: (Real u, Floating u, FromPtSize u) => HAlign -> CtxPicture u -> [CtxPicture u] -> CtxPicture uSource

Variant of `cxpRow`

that aligns the pictures as well as
concatenating them.

cxpAlignColumn :: (Real u, Floating u, FromPtSize u) => VAlign -> CtxPicture u -> [CtxPicture u] -> CtxPicture uSource

Variant of `cxpColumn`

that aligns the pictures as well as
concatenating them.

cxpAlignRowSep :: (Real u, Floating u, FromPtSize u) => HAlign -> u -> CtxPicture u -> [CtxPicture u] -> CtxPicture uSource

Variant of `cxpRow`

that aligns the pictures as well as
concatenating and spacing them.

cxpAlignColumnSep :: (Real u, Floating u, FromPtSize u) => VAlign -> u -> CtxPicture u -> [CtxPicture u] -> CtxPicture uSource

Variant of `cxpColumn`

that aligns the pictures as well as
concatenating and spacing them.