The type of reified expressions over Vars, with numeric values taken from the type n. The important point to note is that Expr is an instance of Num, Fractional, and Floating, so Expr values can be combined and manipulated as if they were numeric expressions, even when they occur inside other types. For example, 2D vector values of type V2 (Expr s n) and point values of type P2 (Expr s n) can be combined using operators such as .+^, .-., and so on, in order to express constraints on vectors and points.

To create literal Expr values, you can use mkExpr. Otherwise, they are introduced by creation functions such as newPoint, newScalar, or diagram accessor functions like centerOf or xOf.

Convert a literal numeric value into an Expr. To convert structured types such as vectors or points, you can use e.g. fmap mkExpr :: V2 n -> V2 (Expr s n).

A monad for constrained systems. It suffices to think of it as an abstract monadic type; the constructor for the internal state is intentionally not exported. Constrained values can be created using the combinators below; combined using the Monad interface; and discharged by the layout function.

Note that s is a phantom parameter, used in a similar fashion to the ST monad, to ensure that generated diagram IDs cannot be mixed between different layout blocks.

The state maintained by the Constrained monad. Note that s is a phantom parameter, used in a similar fashion to the ST monad, to ensure that generated diagram IDs do not leak.

An abstract type representing unique IDs for diagrams. The constructor is not exported, so the only way to obtain a DiaID is by calling newDia or newDias. The phantom type parameter s ensures that such DiaIDs can only be used with the constrained system in which they were introduced.

Solve a constrained system, combining the resulting diagrams with mconcat. This is the top-level function for introducing a constrained system, and is the only way to generate an actual diagram.

Redundant constraints are ignored. If there are any unconstrained diagram variables remaining, they are given default values one at a time, beginning with defaulting remaining scaling factors to 1, then defaulting x- and y-coordinates to zero.

An overconstrained system will cause layout to simply crash. This is obviously not ideal. A future version may do something more reasonable.

Introduce a new diagram into the constrained system. Returns a unique ID for use in referring to the diagram later.

The position of the diagram's origin may be constrained. If unconstrained, the origin will default to (0,0). For a diagram whose scaling factor may also be constrained, see newScalableDia.

Introduce a list of diagrams into the constrained system. Returns a corresponding list of unique IDs for use in referring to the diagrams later.

Introduce a new diagram into the constrained system. Returns a unique ID for use in referring to the diagram later.

Both the position of the diagram's origin and its scaling factor may be constrained. If unconstrained, the origin will default to (0,0), and the scaling factor to 1, respectively.

Introduce a new constrainable point, unattached to any particular diagram. If either of the coordinates are still unconstrained at the end, they will default to zero.

Create a new (constrainable) point attached to the given diagram, using a function that picks a point given a diagram.

For example, to get the point on the right edge of a diagram's envelope, one may write

rt <- newPointOn d (envelopeP unitX)

To get the point (1,1),

one_one <- newPointOn d (const (1 ^& 1))

This latter example is far from useless: note that one_one now corresponds not to the absolute coordinates (1,1), but to the point which lies at (1,1) /relative to the unscaled diagram's origin/. If the diagram is positioned or scaled to satisfy some other constraints, one_one will move right along with it.

For example, the following code establishes a small circle which is located at a specific point relative to a big circle. The small circle is carried along with the big circle as it is laid out in between some squares.

import Diagrams.TwoD.Layout.Constrained

circleWithCircle = frame 0.3 $ layout $ do
  c2 <- newScalableDia (circle 2)
  p <- newPointOn c2 (const $ (1 ^& 0) # rotateBy (1/8))

  c1 <- newDia (circle 1)
  centerOf c1 =.= p

  [a,b] <- newDias (replicate 2 (square 2))
  constrainWith hcat [a,c2,b]

Introduce a new scalar value which can be constrained. If still unconstrained at the end, it will default to 1.

The point at the center (i.e. local origin) of the given diagram. For example, to constrain the origin of diagram b to be offset from the origin of diagram a by one unit to the right and one unit up, one may write

centerOf b =.= centerOf a .+^ (1 ^& 1)

The x-coordinate of the center for the given diagram, which can be used in constraints to determine the x-position of this diagram relative to others.

For example,

xOf d1 + 2 === xOf d2

constrains diagram d2 to lie 2 units to the right of d1 in the horizontal direction, though it does not constrain their relative positioning in the vertical direction.

The y-coordinate of the center for the given diagram, which can be used in constraints to determine the y-position of this diagram relative to others.

For example,

allSame (map yOf ds)

constrains the diagrams ds to all lie on the same horizontal line.

The scaling factor applied to this diagram.

For example,

scaleOf d1 === 2 * scaleOf d2

constrains d1 to be scaled twice as much as d2. (It does not, however, guarantee anything about their actual relative sizes; that depends on their relative size when unscaled.)

Constrain two scalar expressions to be equal. Note that you need not worry about introducing redundant constraints; they are ignored.

Constrain two points to be equal.

Constrain two vectors to be equal.

Constrain the origins of two diagrams to have the same x-coordinate.

Constrain the origins of two diagrams to have the same y-coordinate.

Constrain a list of scalar expressions to be all equal.

Constrain a collection of diagrams to be positioned relative to one another according to a function such as hcat, vcat, hsep, and so on.

A typical use would be

cirs <- newDias (map circle [1..5])
constrainWith (hsep 1) cirs

which creates five circles and constrains them to be positioned in a row, with one unit of space in between adjacent pairs.

The funny type signature is something of a hack. The sorts of functions which should be passed as the first argument to constrainWith tend to be highly polymorphic; constrainWith uses a concrete type which it can use to extract relevant information about the function by observing its behavior. In short, you do not need to know anything about Located Envelopes in order to call this function.

constrainDir d p q constrains the direction from p to q to be d. That is, the direction of the vector q .-. p must be d.

along d ps constrains the points ps to all lie along a ray parallel to the direction d.