org.writersforge.catalan.layout
Interface LayoutEngine

All Known Implementing Classes:

AbstractLayoutEngine

public interface LayoutEngine

Base interface for all layout engines. The primary task of the LayoutEngine is to fit LayoutArea objects into a rectangular region. The areas are managed by a LayoutContext object, which the engine will modify as it proceeds with its layout.

Author:

jsheets

Method Summary

void	acceptArea(LayoutArea area) Adds the area to the layout queue.
LayoutArea[]	clearQueue() Empties out the layout queue.
boolean	fitsInRegion(LayoutArea area) Checks to see if the given area will fit anywhere in the current layout region.
boolean	fitsInRegion(LayoutArea area, java.awt.Rectangle region, java.util.List areasInRegion) Checks to see if the area will fit in the given region.
java.awt.Shape	getFreeSpace() Returns the free space in the current layout region.
int	getQueueSize() Returns the number of areas currently in the layout queue.
java.awt.Dimension	guessSize(LayoutArea area) Estimates the size that the area "wants" to be.
java.util.List	layoutAreas(java.util.List areas) Attempts to lay out all the areas in the supplied List.
void	layoutRegion(LayoutContext context, java.awt.Rectangle region) Attempts to lay out as many of the pending areas in the context as it can, into the provided region's bounding box.
void	setCurrentRegion(java.awt.Shape region) Assigns a clipping region for the current rendering context.

Method Detail

setCurrentRegion

public void setCurrentRegion(java.awt.Shape region)

Assigns a clipping region for the current rendering context. All layout operations will limit themselves to the current region, either clipping or rejecting areas as necessary to make them fit. As areas are accepted to a region, they accumulate in the layout queue, and must be flushed out with clearQueue() before setting a new current region.

Parameters:

region - the new clipping region

Throws:

java.lang.IllegalStateException - if called with areas in the queue

getQueueSize

public int getQueueSize()

Returns the number of areas currently in the layout queue.

Returns:

the number of areas currently in the layout queue

clearQueue

public LayoutArea[] clearQueue()

Empties out the layout queue. This must be called before assigning a new clipping region with setCurrentRegion().

Returns:

an array of areas that were in the layout queue

layoutAreas

public java.util.List layoutAreas(java.util.List areas)

Attempts to lay out all the areas in the supplied List. Areas that fit are added to the layout queue. Areas that don't fit are returned. When this method returns, it typically means the current region is full, and the queue needs to be cleared for the next layout pass.

Parameters:

areas - the list of areas to add to the current region

Returns:

the areas that did not fit in the current region

Throws:

java.lang.IllegalStateException - if called without a valid current region

acceptArea

public void acceptArea(LayoutArea area)

Adds the area to the layout queue. This method should initialize the area's extents to match its new position in the layout, and because it's in the queue, the area should reduce the free space in the current layout.

Parameters:

area - the area to add to the layout queue

Throws:

java.lang.IllegalStateException - if called without a valid current region

getFreeSpace

public java.awt.Shape getFreeSpace()

Returns the free space in the current layout region. Areas accepted into the layout queue reduce the free space. The returned Shape can be any closed shape, but is typically a Rectangle.

Returns:

the space in the current region unclaimed by the layout queue

Throws:

java.lang.IllegalStateException - if called without a valid current region

guessSize

public java.awt.Dimension guessSize(LayoutArea area)

Estimates the size that the area "wants" to be. The default implementation simply returns the value of 'preferred'. If the preferred width or height is DefaultStyle.NOT_FOUND, that extent is autosized. In the case of a LayoutText area, the size the text needs will determine the autosized extent. A LayoutGroup extent will become the sum of its children in that direction.

Parameters:

area - the area to examine

Returns:

the size the area should be

fitsInRegion

public boolean fitsInRegion(LayoutArea area)

Checks to see if the given area will fit anywhere in the current layout region.

Parameters:

area - the area to check

Returns:

true if the area fits in the current region, or false if it does not fit

Throws:

java.lang.IllegalStateException - if called without a valid current region

fitsInRegion

public boolean fitsInRegion(LayoutArea area,
                            java.awt.Rectangle region,
                            java.util.List areasInRegion)

Checks to see if the area will fit in the given region. The areasInRegion parameter may contain an optional array of LayoutArea objects that the engine has already fitted into the region. This method should take these pre-existing areas into account. If no areas are currently in the region, areasInRegion can be null or an empty array.

Parameters:

area - the LayoutArea object to try to fit

region - the bounding area of the region

areasInRegion - optional list of areas already in the region

Returns:

true if the area fits in the region, or false if not

layoutRegion

public void layoutRegion(LayoutContext context,
                         java.awt.Rectangle region)

Attempts to lay out as many of the pending areas in the context as it can, into the provided region's bounding box. The LayoutEngine should put all the areas that fit into the LayoutContext's "accepted area" pile, and put areas that fail to fit into the context's "rejected area" pile. The engine may stop after the first reject, or keep going as long as it wants. NOTE: this method should not call LayoutContext.flush(), since that will delete all accepted areas. flush() should only be called by the driving RenderTemplate class.

Parameters:

context - the running context for this rendering pass

region - the bounding area to render areas into