org.writersforge.catalan.layout
Class Relation

java.lang.Object
  |
  +--org.writersforge.catalan.layout.Relation

Direct Known Subclasses:

Relation.Above, Relation.Below, Relation.Indent

public class Relation

extends java.lang.Object

A constraints-based relationship between two LayoutArea objects. The Relation consists of an attractor, the anchor point for the relationship, and a satellite, the "floating" area that the relationship applies to. A Relation does not affect the position of the attractor, only the satellite.

A Relation object is essentially a fancy vector, with direction, magnitude, and an optional distance. The direction is a collection of relationship states, like edge attraction, horizontal/vertical orientation, etc. The magnitude determines the strength of the relationship; stronger magnitudes will win out over weaker magnitudes if more than one Relation contends for a scarce position in the layout. A third optional parameter is the desired distance between two parallel edges of the areas. A Relation can suggest that an area should be, for example, within 50 units of the target area, or at least 25 units away from it, or indented 10 units to the left of it. The LayoutEngine uses Relations to make these layout decisions when rendering a Page.

The relation is valid if the following equation is true:

  satellite-edge + distance OP attractor-edge

where satellite-edge is the appropriate leading/trailing edge on the area being laid out, attractor-edge is the leading/trailing edge on the target (already laid out) area, and OP is the comparison operator, one of: =, !=, <, <=, >, >=. The placement of the satellite-edge is typically the variable parameter during the layout process. In a given Relation, the attractor-edge and distance can both be assumed to be constants.

Author:

jsheets

Nested Class Summary

static class	Relation.Above Convenience class to constrain an area that must remain vertically above the previous area in the layout.
static class	Relation.Below Convenience class to constrain an area that must remain vertically below the previous area in the layout.
static class	Relation.Indent Convenience class to constrain an area that must remain indented to the right of the previous area in the layout (leftward indentation can be achieved with a negative distance).

Field Summary

static int	ABOVE_AT_MASK Vertically above the attractor, at exactly distance
static int	ABOVE_MASK Vertically above the attractor, with no comparison operator specified
static int	ABOVE_MAX_MASK Vertically above the attractor, no further than distance
static int	ABOVE_MIN_MASK Vertically above the attractor, no closer than distance
static int	BELOW_AT_MASK Vertically below the attractor, at exactly distance
static int	BELOW_MASK Vertically below the attractor, at exactly distance
static int	BELOW_MAX_MASK Vertically below the attractor, no further than distance
static int	BELOW_MIN_MASK Vertically below the attractor, no closer than distance
static int	EQUAL_MASK Require equal to distance
static int	GREATER_THAN_EQUAL_MASK Require greater than or equal to distance
static int	GREATER_THAN_MASK Require greater than distance
static int	HEAVY_WEIGHT Very important Relation, only override if critical
static int	HORIZONTAL_MASK Apply relation along horizontal axis
static int	INDENT_MASK Horizontally indented to the left of the attractor (can be negative for indentation to the right)
static int	LEADING_ATTRACTOR_EDGE_MASK Relate to leading edge in attractor
static int	LEADING_SATELLITE_EDGE_MASK Relate to leading edge in satellite
static int	LESS_THAN_EQUAL_MASK Require less than or equal to distance
static int	LESS_THAN_MASK Require less than distance
static int	LIGHT_WEIGHT Optional Relation, use as a fallback, if nothing else needs the position
static int	MANDATORY_WEIGHT The highest valid Relation, cannot be ignored
static int	MEDIUM_WEIGHT Moderately important Relation, should think twice before overriding
static int	MINIMAL_WEIGHT The lowest valid Relation weight, overridden by anything
static int	NOT_EQUAL_MASK Require not equal to distance
static int	TRAILING_ATTRACTOR_EDGE_MASK Relate to trailing edge in attractor
static int	TRAILING_SATELLITE_EDGE_MASK Relate to trailing edge in satellite
static int	VERTICAL_MASK Apply relation along vertical axis

Constructor Summary

Relation(LayoutArea target, int mask, int weight)
Creates a new instance of Relation.

Relation(LayoutArea target, int mask, int weight, int distance)
Creates a new instance of Relation

Method Summary

int	getDistance() Getter for property distance, a scalar measure to use with comparisons.
LayoutArea	getTarget() Getter for property target, the LayoutArea (attractor) to bind to.
int	getWeight() Getter for property weight, how important this relationship is.
boolean	isEqual() Does the Relation allow distances exactly equal to the distance property?
boolean	isGreaterThan() Does the Relation allow distances greater than the distance property?
boolean	isLeadingAttractorEdge() Does the Relation refer to the leading edge of the attractor area?
boolean	isLeadingSatelliteEdge() Does the Relation refer to the leading edge of the satellite area?
boolean	isLessThan() Does the Relation allow distances less than the distance property?
boolean	isVertical() Is the Relation oriented along the horizontal axis?
void	setDistance(int distance) Setter for property distance, a scalar measure to use with comparisons.
java.lang.String	toString() Returns this object as a String

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

VERTICAL_MASK

public static final int VERTICAL_MASK

Apply relation along vertical axis

See Also:

Constant Field Values

HORIZONTAL_MASK

public static final int HORIZONTAL_MASK

Apply relation along horizontal axis

See Also:

Constant Field Values

LEADING_ATTRACTOR_EDGE_MASK

public static final int LEADING_ATTRACTOR_EDGE_MASK

Relate to leading edge in attractor

See Also:

Constant Field Values

TRAILING_ATTRACTOR_EDGE_MASK

public static final int TRAILING_ATTRACTOR_EDGE_MASK

Relate to trailing edge in attractor

See Also:

Constant Field Values

LEADING_SATELLITE_EDGE_MASK

public static final int LEADING_SATELLITE_EDGE_MASK

Relate to leading edge in satellite

See Also:

Constant Field Values

TRAILING_SATELLITE_EDGE_MASK

public static final int TRAILING_SATELLITE_EDGE_MASK

Relate to trailing edge in satellite

See Also:

Constant Field Values

LESS_THAN_MASK

public static final int LESS_THAN_MASK

Require less than distance

See Also:

Constant Field Values

EQUAL_MASK

public static final int EQUAL_MASK

Require equal to distance

See Also:

Constant Field Values

GREATER_THAN_MASK

public static final int GREATER_THAN_MASK

Require greater than distance

See Also:

Constant Field Values

LESS_THAN_EQUAL_MASK

public static final int LESS_THAN_EQUAL_MASK

Require less than or equal to distance

See Also:

Constant Field Values

GREATER_THAN_EQUAL_MASK

public static final int GREATER_THAN_EQUAL_MASK

Require greater than or equal to distance

See Also:

Constant Field Values

NOT_EQUAL_MASK

public static final int NOT_EQUAL_MASK

Require not equal to distance

See Also:

Constant Field Values

INDENT_MASK

public static final int INDENT_MASK

Horizontally indented to the left of the attractor (can be negative for indentation to the right)

See Also:

Constant Field Values

ABOVE_MASK

public static final int ABOVE_MASK

Vertically above the attractor, with no comparison operator specified

See Also:

Constant Field Values

ABOVE_AT_MASK

public static final int ABOVE_AT_MASK

Vertically above the attractor, at exactly distance

See Also:

Constant Field Values

ABOVE_MAX_MASK

public static final int ABOVE_MAX_MASK

Vertically above the attractor, no further than distance

See Also:

Constant Field Values

ABOVE_MIN_MASK

public static final int ABOVE_MIN_MASK

Vertically above the attractor, no closer than distance

See Also:

Constant Field Values

BELOW_MASK

public static final int BELOW_MASK

Vertically below the attractor, at exactly distance

See Also:

Constant Field Values

BELOW_AT_MASK

public static final int BELOW_AT_MASK

Vertically below the attractor, at exactly distance

See Also:

Constant Field Values

BELOW_MAX_MASK

public static final int BELOW_MAX_MASK

Vertically below the attractor, no further than distance

See Also:

Constant Field Values

BELOW_MIN_MASK

public static final int BELOW_MIN_MASK

Vertically below the attractor, no closer than distance

See Also:

Constant Field Values

MINIMAL_WEIGHT

public static final int MINIMAL_WEIGHT

The lowest valid Relation weight, overridden by anything

See Also:

Constant Field Values

LIGHT_WEIGHT

public static final int LIGHT_WEIGHT

Optional Relation, use as a fallback, if nothing else needs the position

See Also:

Constant Field Values

MEDIUM_WEIGHT

public static final int MEDIUM_WEIGHT

Moderately important Relation, should think twice before overriding

See Also:

Constant Field Values

HEAVY_WEIGHT

public static final int HEAVY_WEIGHT

Very important Relation, only override if critical

See Also:

Constant Field Values

MANDATORY_WEIGHT

public static final int MANDATORY_WEIGHT

The highest valid Relation, cannot be ignored

See Also:

Constant Field Values

Constructor Detail

Relation

public Relation(LayoutArea target,
                int mask,
                int weight)

Creates a new instance of Relation.

Parameters:

target - the attractor area this Relation refers to

mask - a bitmask of initializers for this Relation

weight - the magnitude of importance for this Relation

Relation

public Relation(LayoutArea target,
                int mask,
                int weight,
                int distance)

Creates a new instance of Relation

Parameters:

target - the attractor area this Relation refers to

mask - a bitmask of initializers for this Relation

weight - the magnitude of importance for this Relation

distance - a scalar measure to use with comparisons

Method Detail

getWeight

public int getWeight()

Getter for property weight, how important this relationship is.

Returns:

Value of property weight.

getDistance

public int getDistance()

Getter for property distance, a scalar measure to use with comparisons. The relation is valid if the following equation is true:

  satellite-edge + distance OP attractor-edge

where satellite-edge is the appropriate leading/trailing edge on the area being laid out, attractor-edge is the leading/trailing edge on the target (already laid out) area, and OP is the comparison operator, one of: =, !=, <, <=, >, >=.

Returns:

Value of property distance.

setDistance

public void setDistance(int distance)

Setter for property distance, a scalar measure to use with comparisons. The relation is valid if the following equation is true:

  satellite-edge + distance OP attractor-edge

where satellite-edge is the appropriate leading/trailing edge on the area being laid out, attractor-edge is the leading/trailing edge on the target (already laid out) area, and OP is the comparison operator, one of: =, !=, <, <=, >, >=.

Parameters:

distance - New value of property distance.

getTarget

public LayoutArea getTarget()

Getter for property target, the LayoutArea (attractor) to bind to.

Returns:

Value of property target.

isVertical

public boolean isVertical()

Is the Relation oriented along the horizontal axis?

Returns:

true if vertical orientation, or false if horizontal orientation

isLeadingSatelliteEdge

public boolean isLeadingSatelliteEdge()

Does the Relation refer to the leading edge of the satellite area?

Returns:

true if leading satellite edge, or false if trailing edge

isLeadingAttractorEdge

public boolean isLeadingAttractorEdge()

Does the Relation refer to the leading edge of the attractor area?

Returns:

true if leading attractor edge, or false if trailing edge

isEqual

public boolean isEqual()

Does the Relation allow distances exactly equal to the distance property?

Returns:

true if equal distance is allowed

isLessThan

public boolean isLessThan()

Does the Relation allow distances less than the distance property?

Returns:

true if lesser distance is allowed

isGreaterThan

public boolean isGreaterThan()

Does the Relation allow distances greater than the distance property?

Returns:

true if greater distance is allowed

toString

public java.lang.String toString()

Returns this object as a String

Overrides:

toString in class java.lang.Object

Returns:

a String representation of this object

See Also:

Object.toString()