com.miginfocom.calendar.layout
Class Distributor

java.lang.Object
  extended by com.miginfocom.calendar.layout.Distributor

public class Distributor
extends java.lang.Object

A class that evenly distributes a number of one-dimensional lines (start, length) over some bounds given a gap and the number of lines. Uses float precision.
Also contains a number of static layout methods that will help laying out arbitrary sizes in one dimension.


Field Summary
static int MAX
           
static int MIN
           
static int PREFERRED
           
 
Constructor Summary
Distributor(float start, float size, AtRefNumber linePrefSize, AtRefNumber lineMinSize, AtRefNumber lineMaxSize, AtRefNumber internalGap, AtRefNumber externalGap, int lineCount, boolean roundToCords)
          Constructor
 
Method Summary
static AtRefNumber[][] cloneSizes(AtRefNumber[][] arr)
          Shallow clones the array
static float[] distribute(AtRefNumber[][] sizes, float bounds, boolean toBounds)
          Distributes some sizes that have optionally min, preferred and max size constraints within bounds.
static int[][] distribute(float[] lengths, float gap, boolean retCoords, boolean forDraw)
          Distributes a number of lines with different lengths and rounds the start and stop/lengths to ints.
static int[] distribute(int size, int count)
          Distribute (chops) a size count number of times and round the resulting sizes to ints.
 double getBoundsLength()
          Returns the bounds length.
 java.util.ListIterator getDoubleGapIterator(int index)
          Returns an Iterator that iterates over boundss returning Doubles that are the start of every dstributed line AND the length.
 java.util.ListIterator getDoubleIterator(int index)
          Returns an Iterator that iterates over boundss returning Doubles that are the start of every dstributed line AND the length.
 java.util.ListIterator getFloatGapIterator(int index)
          Returns an Iterator that iterates over boundss returning Floats that are the start of every dstributed line AND the length.
 java.util.ListIterator getFloatIterator(int index)
          Returns an Iterator that iterates over boundss returning Floats that are the start of every dstributed line AND the length.
 java.util.ListIterator getIntegerGapIterator(int index)
          Returns an Iterator that iterates over boundss returning Integerss that are the start of every distributed line AND the length.
 java.util.ListIterator getIntegerIterator(int index)
          Returns an Iterator that iterates over boundss returning Integerss that are the start of every distributed line AND the length.
 double getLineLength()
          Returns the length of the lines (i.e.
static int[] roundSizes(float[] sizes)
          Round a number of float sizes into int sizes so that the total length match up
static int[] roundSizes(float size, int count)
          Round a float size into int sizes so that the total length match up
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MIN

public static final int MIN
See Also:
Constant Field Values

PREFERRED

public static final int PREFERRED
See Also:
Constant Field Values

MAX

public static final int MAX
See Also:
Constant Field Values
Constructor Detail

Distributor

public Distributor(float start,
                   float size,
                   AtRefNumber linePrefSize,
                   AtRefNumber lineMinSize,
                   AtRefNumber lineMaxSize,
                   AtRefNumber internalGap,
                   AtRefNumber externalGap,
                   int lineCount,
                   boolean roundToCords)
Constructor

Parameters:
start - The start of the bounds
size - The length of the bounds
linePrefSize - If != null it it the length of returned line. null means that the length should be so that, counting the gap, it exactly fills the bounds given the number of lines.
lineMinSize - If != null it it the minimum length of returned line. null means no minimum.
lineMaxSize - If != null it it the maximum length of returned line. null means no maximum.
internalGap - The gap between the different lines. Negative values makes lines overlap. null means that the The gap is calculated so that the lines exactly fills the bounds (minus external gap).
externalGap - The gap before the first and after the last line. null means no gap (not same a 0!! see {link #getFloatGapIterator}).
lineCount - The number of lines to distribute over bounds
roundToCords - If true the returned lines is rounded so that the start and end coordinates is as close to the real positions as possible.
If it is false the length of the lines is more accurate than the end position.
true is best for layout that are painted on a pixel based screen.
Method Detail

getDoubleGapIterator

public java.util.ListIterator getDoubleGapIterator(int index)
Returns an Iterator that iterates over boundss returning Doubles that are the start of every dstributed line AND the length. The length is always the same for every line and can be fetched with getLineLength() but is included for consistency resons with getIntegerIterator(int)

Parameters:
index - The index to start from.
Returns:
An Iterator that iterates over boundss. The list is the one used internally in this calss, so it must NOT be changed via the Iterator!

getFloatGapIterator

public java.util.ListIterator getFloatGapIterator(int index)
Returns an Iterator that iterates over boundss returning Floats that are the start of every dstributed line AND the length. The length is always the same for every line and can be fetched with getLineLength() but is included for consistency resons with getIntegerIterator(int)

Parameters:
index - The index to start from.
Returns:
An Iterator that iterates over boundss. The list is the one used internally in this class, so it must NOT be changed via the Iterator!

getIntegerGapIterator

public java.util.ListIterator getIntegerGapIterator(int index)
Returns an Iterator that iterates over boundss returning Integerss that are the start of every distributed line AND the length. If roundToCords was set to true in the constructor, the length rounded to an Integer might not be the same all the time, since it is more important that the line ends in a certain place rather than have a specific length. Tis is why this Iterator returns Integers of both the start and length of every line.
So, in short, the returned iterator iterates over twise as many objects as getDoubleIterator(int) does!. If roundToCords was set to false, the length is always the same, but included anyway for consistency.

Parameters:
index - The index to start from.
Returns:
An Iterator that iterates over boundss. The list is the one used internally in this class, so it must NOT be changed via the Iterator!

getDoubleIterator

public java.util.ListIterator getDoubleIterator(int index)
Returns an Iterator that iterates over boundss returning Doubles that are the start of every dstributed line AND the length. The length is always the same for every line and can be fetched with getLineLength() but is included for consistency resons with getIntegerIterator(int)

Parameters:
index - The index to start from.
Returns:
An Iterator that iterates over boundss. The list is the one used internally in this calss, so it must NOT be changed via the Iterator!

getFloatIterator

public java.util.ListIterator getFloatIterator(int index)
Returns an Iterator that iterates over boundss returning Floats that are the start of every dstributed line AND the length. The length is always the same for every line and can be fetched with getLineLength() but is included for consistency resons with getIntegerIterator(int)

Parameters:
index - The index to start from.
Returns:
An Iterator that iterates over boundss. The list is the one used internally in this class, so it must NOT be changed via the Iterator!

getIntegerIterator

public java.util.ListIterator getIntegerIterator(int index)
Returns an Iterator that iterates over boundss returning Integerss that are the start of every distributed line AND the length. If roundToCords was set to true in the constructor, the length rounded to an Integer might not be the same all the time, since it is more important that the line ends in a certain place rather than have a specific length. Tis is why this Iterator returns Integers of both the start and length of every line.
So, in short, the returned iterator iterates over twise as many objects as getDoubleIterator(int) does!. If roundToCords was set to false, the length is always the same, but included anyway for consistency.

Parameters:
index - The index to start from.
Returns:
An Iterator that iterates over boundss. The list is the one used internally in this class, so it must NOT be changed via the Iterator!

getLineLength

public double getLineLength()
Returns the length of the lines (i.e. A line) that are distributed.

Returns:
The length of the lines that are distributed

getBoundsLength

public double getBoundsLength()
Returns the bounds length. If the preferred line length was adjusted due to min or max lengths, the new total bounds length is returned here (including all gaps). If the preferred size was ok, the length in the constructor is the same as returned here.

Returns:
Returns the bounds length

distribute

public static float[] distribute(AtRefNumber[][] sizes,
                                 float bounds,
                                 boolean toBounds)
Distributes some sizes that have optionally min, preferred and max size constraints within bounds.

Parameters:
sizes - The sizes to distribute. Every size has a MIN, PREFERRED and MAX constraints. However the constraints may be null and if so does not apply, except for PREFERRED witch is set to 1.0 if null. E.g. size[0][PREFERRED] is the first size's preferred size. The sizes themselves can be absolute or relative depending on the type of the AtRefNumber. This means that the size constraints can be very flexible.

Sizes will never be allowed to be negative.

bounds - The bounds that the sizes are laied out towards. An effort will be made lay out the sizes so they add up to bounds but the MAX/MIN boundaries won't be broken to do it.
toBounds - If true:
  1. All relative values (I.e. no a AtNumber) will be normalised so they add upp to 1.0. Otherwise if there are for instance just two preferred sizes, both with value 0.7f, the sum of the returned sizes will be 40% more than bounds. This might, or might not, be desirable depending on what's being layed out.
  2. Preferred relative values are relative to the remaining size when the absolute sizes have been taken away, so all match up to a total length of bounds. MAX/MIN, though, are not. They are, if they are relative (I.e. no a AtNumber) relative to the whole of bounds.
  3. The layout algorithm will try to give every size its preferred size but will scale them within MIN/MAX to fit the bounds.
Returns:
The sizes. Never null.

cloneSizes

public static AtRefNumber[][] cloneSizes(AtRefNumber[][] arr)
Shallow clones the array

Parameters:
arr - The array to clone. Size = [rowCount][3]
Returns:
A clone array.

distribute

public static int[] distribute(int size,
                               int count)
Distribute (chops) a size count number of times and round the resulting sizes to ints.

Parameters:
size - The size copy up.
count - The number of times to distribute/chop size.
Returns:
An array of count length with the sizes. Element's sizes will differ by 1 if (size % count != 0)

roundSizes

public static int[] roundSizes(float[] sizes)
Round a number of float sizes into int sizes so that the total length match up

Parameters:
sizes - The sizes to round
Returns:
An array of equal length as sizes.

roundSizes

public static int[] roundSizes(float size,
                               int count)
Round a float size into int sizes so that the total length match up

Parameters:
size - The sizes to round
Returns:
An array of equal length as sizes.

distribute

public static int[][] distribute(float[] lengths,
                                 float gap,
                                 boolean retCoords,
                                 boolean forDraw)
Distributes a number of lines with different lengths and rounds the start and stop/lengths to ints. Can for instance be used to lay out (i.e. map to ints) a number of rows in a table that all are of different heights.
NOTE! The values returned should not ge greater than an int can hold. Since this method should be used to lay out stuff on a screen this should never be a problem though.
NOTE 2! The returned lines lengths don't have to be the same for all lines if retCoords is false. This is because the length is also used as a regulator to lay out the lines correctly and there might be rounding errors. The lengths should never differ from the length sent in by more than 1 though.

Parameters:
lengths - The absolute lengths of the "lines" that are to be distributed.
gap - The gap between the lines.
retCoords - If true the second element is an absolute coordinate.
If false the second elements is the length of the line.
forDraw - If the returned coordinates if to be used in a "draw" command (as opposed to a "fill" command) set this to true. If will reduce the end coord with 1. This has no effect if retCoords is false since the length is always correct anyway.
Returns:
The rounded ints ([n][0] == start, [n][1] == (end or length) )


Copyright © 2009 MiG InfoCom AB. All Rights Reserved.