jimmc.treepar
Class Layout

java.lang.Object
  |
  +--jimmc.treepar.Layout

public class Layout
extends java.lang.Object

Layout is the root object containing all of the data used to do a place and route with the treepar package.

There are three phases of use for Layout, which must be done in order:

Layout uses a channel-based algorithm. The layout is optimized for looks (as opposed to density, as is typical in a CAD application), and is intended for simple tree-structured data, as is commonly found in a family tree. It will handle arbitrary network-stuctured data, but may not make a very nice looking plot. It will insert feedthroughs when necessary, but is not particularly intelligent about where in a row a feedthrough should go.

The algorithm uses the following additional object types:

Layout can work with either horizontal rows or vertical rows. In many places, the algorithm is simplified by being able to ignore this selection. In order to reduce confusion, terms such as width, height, x, and y are avoided. Instead, a different set of terms are used.

For the dimensions of a row, thickness and length are used instead of width and height. The long dimension of the row (in the typical case) is called the length, and the short dimension is called the thickness. Thus if the rows are oriented horizontally, the thickness of a row is its height, and the length of the row is its width; whereas if the rows are oriented vertically, then the thickness is the width, and the length is the height. By using thickness and length rather than width and height the algorithm can in most places ignore the actual orientation of the rows.

For point coordinates, r and s are used instead of x any y. The r coordinate is the position of the point along the length of the rows, whereas the s coordinate is the position of the point along the thickness of the rows. Thus if the rows are oriented horizontally, then r=x and s=y; whereas if the rows are oriented vertically, then r=y and s=x.

For directions, the terms Rmore, Rless, Smore, and Sless are used, referring to the directions of greater or lesser values of the r and s coordinates. If the rows are oriented horizontally, then Rmore=east, Rless=west, Smore=north, and Sless=south; whereas if the rows are oriented vertically, then Rmore=north, Rless=south, Smore=east, and Sless=west.

Each row is assigned a row number. The channels between rows also have row numbers. All rows have even row numbers, whereas all channels have odd row numbers.

The (x,y) coordinate system has it's origin in the lower left, as with standard mathematical coordinates.


Field Summary
protected  BoundsRectangle bounds
          Our bounds, in which all drawable items lie.
protected  Box[] boxes
          The set of Box objects used during the layout process.
protected  java.util.Vector boxVector
          The set of Box objects added during the setup phase.
protected  int characterWidth
          The width of one character.
protected  Connector[] connectors
          The set of Connector objects used during the layout process.
static int EAST
          Constant for connector edges.
protected  int interBoxSpace
          The default spacing between boxes (R dimension)
protected  int interRowSpace
          The spacing between rows (S dimension).
static int LEFT
          Constant for routing angle.
protected  int lineHeight
          The height of a character (actually, spacing between baselines).
protected  int maxRowLength
          The maximum length of a row.
protected  Net[] nets
          The set of Net objects used during the layout process.
protected  java.util.Dictionary netsDict
          The set of Net objects, while collecting nets.
protected  int NorE
          NORTH if horizontal rows; EAST if vertical rows (Smore).
static int NORTH
          Constant for connector edges.
static int RIGHT
          Constant for routing angle.
protected  Box rootBox
          The root box to use for the place algorithm.
protected  Row[] rows
          The set of Row objects in the layout.
protected  int SorW
          SOUTH if horizontal rows; WEST if vertical rows (Sless).
static int SOUTH
          Constant for connector edges.
static int STEP_ALL
          Constant referring to all steps.
static int STEP_BOUNDS
          Constant referring to the step where bounding rectangle is calculated.
static int STEP_FEEDTHROUGHS
          Constant referring to the step where feedthroughs are created.
static int STEP_ROUTE
          Constant referring to the step where routing is done.
static int STEP_ROW_NUMBERS
          Constant referring to the step where row numbers are assigned.
static int STEP_ROW_ORDER
          Constant referring to the step where boxes within rows are ordered.
static int STEP_ROW_POSITION
          Constant referring to the step where row positions are calculated.
static int STEP_ROW_SPACE
          Constant referring to the step where row thicknesses are calculated.
static int STEP_ROWS
          Constant referring to the step where rows are allocated.
static int STEP_SETUP_DONE
          Constant referring to the first step in the place-and-route process: collecting the application-specified data into a form which is easier to process.
protected  int trackSpace
          The amount of space between tracks in a routing channel.
protected  boolean useGreedyRoute
          True to use a greedy routing algorithm for track assignment.
protected  boolean verticalRows
          True if rows are vertical; false if horizontal.
static int WEST
          Constant for connector edges.
 
Constructor Summary
Layout(boolean verticalRows)
          Create an empty Layout.
 
Method Summary
protected  void addBox(Box box)
          Add a box to the list of boxes in the layout.
 void createRows()
          Figure out how many rows we need, create them, and add the boxes and nets to their rows.
 void dump(java.io.PrintWriter f)
          For debugging, dump the layout.
protected  void dumpBoxes(java.io.PrintWriter f)
          Dump the boxes.
protected  void dumpConnectors(java.io.PrintWriter f)
          Dump the connectors.
protected  void dumpNets(java.io.PrintWriter f)
          Dump the nets.
protected  void dumpRows(java.io.PrintWriter f)
          Dump the rows.
 void feed()
          Create feedthroughs.
protected  Box findBox(java.lang.String boxName)
          Find a box by name.
protected  Net findNet(java.lang.String name)
          Find a net by name.
protected  Net findOrCreateNet(java.lang.String name)
          Find a net by name.
 BoundsRectangle getBounds()
          Get the bounds of the layout.
 int getCharacterWidth()
          Get the character width.
 LayoutHitText getHitText(int x, int y)
          Get the text line around the specified point.
 int getLineHeight()
          Get the lineHeight.
 void paint(LayoutGraphics g)
          Draw the layout.
 void placeAndRoute()
          Do the complete place and route.
 void placeAndRoute(int step)
          Do a partial place-and-route, finishing the step specified.
 void reFeed()
          Redo feedthrougs.
 void route()
          Do the channel route.
 void rowOrder(Box box)
          Calculate the ordering of the boxes within the rows.
 void rowPosition()
          Calculate the R position of each row.
 void rowSpace()
          Calculate the thickness and S coordinate of each row.
protected  void setBounds()
          Calculate the bounding rectangle for all paintable items in the layout.
 void setCharacterWidth(int characterWidth)
          Set the character width.
 void setLineHeight(int lineHeight)
          Set the lineHeight.
 void setRowNumbers(Box box)
          Go through all of the boxes and determine which row each box goes into.
 void setRowOrientation(boolean vertical)
          Set the orientation of the rows.
 void setupDone()
          After all calls to addBox, call this method to indicate that the setup phase is complete.
 void unFeed()
          Undo feedthroughs.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NORTH

public static final int NORTH
Constant for connector edges.

SOUTH

public static final int SOUTH
Constant for connector edges.

EAST

public static final int EAST
Constant for connector edges.

WEST

public static final int WEST
Constant for connector edges.

LEFT

public static final int LEFT
Constant for routing angle.

RIGHT

public static final int RIGHT
Constant for routing angle.

STEP_SETUP_DONE

public static final int STEP_SETUP_DONE
Constant referring to the first step in the place-and-route process: collecting the application-specified data into a form which is easier to process.

The order of the steps is:


STEP_ROW_NUMBERS

public static final int STEP_ROW_NUMBERS
Constant referring to the step where row numbers are assigned.

STEP_FEEDTHROUGHS

public static final int STEP_FEEDTHROUGHS
Constant referring to the step where feedthroughs are created.

STEP_ROWS

public static final int STEP_ROWS
Constant referring to the step where rows are allocated.

STEP_ROW_SPACE

public static final int STEP_ROW_SPACE
Constant referring to the step where row thicknesses are calculated.

STEP_ROW_ORDER

public static final int STEP_ROW_ORDER
Constant referring to the step where boxes within rows are ordered.

STEP_ROW_POSITION

public static final int STEP_ROW_POSITION
Constant referring to the step where row positions are calculated.

STEP_ROUTE

public static final int STEP_ROUTE
Constant referring to the step where routing is done.

STEP_BOUNDS

public static final int STEP_BOUNDS
Constant referring to the step where bounding rectangle is calculated.

STEP_ALL

public static final int STEP_ALL
Constant referring to all steps.

boxVector

protected java.util.Vector boxVector
The set of Box objects added during the setup phase. Boxes are automatically added to this list when created with the Box(Layout) constructor.

verticalRows

protected boolean verticalRows
True if rows are vertical; false if horizontal. Use setVertical to set this value.

rootBox

protected Box rootBox
The root box to use for the place algorithm. May be null. This only matters if the network is not a simple tree.

useGreedyRoute

protected boolean useGreedyRoute
True to use a greedy routing algorithm for track assignment.

lineHeight

protected int lineHeight
The height of a character (actually, spacing between baselines).

characterWidth

protected int characterWidth
The width of one character.

interRowSpace

protected int interRowSpace
The spacing between rows (S dimension).

interBoxSpace

protected int interBoxSpace
The default spacing between boxes (R dimension)

trackSpace

protected int trackSpace
The amount of space between tracks in a routing channel.

NorE

protected int NorE
NORTH if horizontal rows; EAST if vertical rows (Smore). Set by setVertical.

SorW

protected int SorW
SOUTH if horizontal rows; WEST if vertical rows (Sless). Set by setVertical.

boxes

protected Box[] boxes
The set of Box objects used during the layout process.

netsDict

protected java.util.Dictionary netsDict
The set of Net objects, while collecting nets.

nets

protected Net[] nets
The set of Net objects used during the layout process.

connectors

protected Connector[] connectors
The set of Connector objects used during the layout process.

rows

protected Row[] rows
The set of Row objects in the layout.

maxRowLength

protected int maxRowLength
The maximum length of a row.

bounds

protected BoundsRectangle bounds
Our bounds, in which all drawable items lie.
Constructor Detail

Layout

public Layout(boolean verticalRows)
Create an empty Layout.
Method Detail

setRowOrientation

public void setRowOrientation(boolean vertical)
Set the orientation of the rows. This method may be called at any time during the setup phase.
Parameters:
vertical - true if the typically long dimension of the rows are vertical; false if horizontal.

setLineHeight

public void setLineHeight(int lineHeight)
Set the lineHeight.

getLineHeight

public int getLineHeight()
Get the lineHeight.

setCharacterWidth

public void setCharacterWidth(int characterWidth)
Set the character width.

getCharacterWidth

public int getCharacterWidth()
Get the character width.

addBox

protected void addBox(Box box)
Add a box to the list of boxes in the layout. This is called from the Box constructor.

setupDone

public void setupDone()
After all calls to addBox, call this method to indicate that the setup phase is complete. This method creates the internal array of boxes used during calculations.

findOrCreateNet

protected Net findOrCreateNet(java.lang.String name)
Find a net by name. If not found, creates a new net and adds it to the layout.
Returns:
the net.

findNet

protected Net findNet(java.lang.String name)
Find a net by name.
Returns:
the net, or null if not found.

placeAndRoute

public void placeAndRoute()
Do the complete place and route.
Parameters:
box - the box to be used as the root of the layout process. May be null.

placeAndRoute

public void placeAndRoute(int step)
Do a partial place-and-route, finishing the step specified.
Parameters:
box - The root box for the route; may be null.
step - The last step to execute. Useful for debugging.

findBox

protected Box findBox(java.lang.String boxName)
Find a box by name.
Parameters:
boxName - the name of the box.
Returns:
the box, or null if not found.

setRowNumbers

public void setRowNumbers(Box box)
Go through all of the boxes and determine which row each box goes into.
Parameters:
box - the root of the row select process. This only matters if the network is not a simple tree.

reFeed

public void reFeed()
Redo feedthrougs.

unFeed

public void unFeed()
Undo feedthroughs.

feed

public void feed()
Create feedthroughs.

createRows

public void createRows()
Figure out how many rows we need, create them, and add the boxes and nets to their rows.

rowSpace

public void rowSpace()
Calculate the thickness and S coordinate of each row. Set the S coordinat of each box in the row, then recalculate the positions of the connectors.

rowOrder

public void rowOrder(Box box)
Calculate the ordering of the boxes within the rows. A depth-first network traversal is done, and a box is assigned an ordinal position with the its row the first time it is encountered. When the network traversal leaves a box on a connector that is higher than the connector on which it entered, the boxes it enters are assigned a number on the positive end of their row ordering; when the network traversal leaves a box on a connector that is lower than the connector on which it entered, the boxes it enters are assigned a number on the negative end of their row ordering. For a simple tree-structured network, this algorithm gives a unique relative ordering of boxes within each row. When the network is not a simple tree, the ordering can be strongly affected by the choice of the initial box.
Parameters:
box - the initial box for the calculation. This only matters if the network is not a simple tree.

rowPosition

public void rowPosition()
Calculate the R position of each row.

route

public void route()
Do the channel route.

setBounds

protected void setBounds()
Calculate the bounding rectangle for all paintable items in the layout.

getBounds

public BoundsRectangle getBounds()
Get the bounds of the layout.

getHitText

public LayoutHitText getHitText(int x,
                                int y)
Get the text line around the specified point.

paint

public void paint(LayoutGraphics g)
Draw the layout.

dump

public void dump(java.io.PrintWriter f)
For debugging, dump the layout.

dumpBoxes

protected void dumpBoxes(java.io.PrintWriter f)
Dump the boxes.

dumpConnectors

protected void dumpConnectors(java.io.PrintWriter f)
Dump the connectors.

dumpNets

protected void dumpNets(java.io.PrintWriter f)
Dump the nets.

dumpRows

protected void dumpRows(java.io.PrintWriter f)
Dump the rows.