Wumpus.Basic.Kernel.Objects.CtxPicture

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...

Documentation

data CtxPicture

A Contextual Picture.

 CtxPicture = DrawingContext -> Maybe Picture

This type corresponds to the Picture type in Wumpus-Core, but it is embedded with a DrawingContext (for font properties, fill colour etc.). The DrawingContext is embedded so that font metrics - loaded in IO can be passed into the pure world of TraceDrawing.

Internally a context picture is a function from DrawingContext to (Maybe Picture). The Maybe represents that it is possible to construct empty Pictures, even though Wumpus-Core cannot render them. Just as the DrawingContext pushes font-metrics from the IO to the pure world, the Maybe lifts the problem of unrenderable Pictures into the API where client code must deal with it explicitly.

(In practice, it is very unlikely a program will create empty pictures and runCtxPictureU can be used without worry).

Note - pictures are fixed to the unit Double (representing PostScript points). Pictures are intentionally unsophisticated, any fine grained control of units should be delegated to the elements that build the picture (Graphics, LocGraphics, etc.).

Instances

Monoid CtxPicture

Avoid initial mempty for mconcat.

Rotate CtxPicture

RotateAbout CtxPicture

Scale CtxPicture

Translate CtxPicture

OPlus CtxPicture

 a `oplus` b

Place 'drawing' a over b. The idea of over here is in terms z-ordering, nither picture a or b are actually moved.

AlignSpace CtxPicture

Align CtxPicture

CatSpace CtxPicture

Concat CtxPicture

ZConcat CtxPicture

runCtxPicture :: DrawingContext -> CtxPicture -> Maybe Picture

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 -> Picture

runCtxPictureU : drawing_ctx * ctx_picture -> Picture

Unsafe version of runCtxPicture.

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

drawTracing :: TraceDrawing u a -> CtxPicture

drawTracing : trace_drawing -> CtxPicture

Transform a TraceDrawing into a CtxPicture.

udrawTracing :: u -> TraceDrawing u a -> CtxPicture

udrawTracing : scalar_unit_value * trace_drawing -> CtxPicture

Variant of drawTracing with a phantom first argument - the phantom identifies the unit type of the TraceDrawing. It is not scurtinized at the value level.

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

mapCtxPicture : trafo * ctx_picture -> CtxPicture

Apply a picture transformation function to the Picture warpped in a CtxPicture.

Composition

uniteCenter :: CtxPicture -> CtxPicture -> CtxPicture

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 

centeredAt :: CtxPicture -> DPoint2 -> CtxPicture

Center the picture at the supplied point.