com.adobe.xfa.ut
Class UnitSpan

java.lang.Object
  com.adobe.xfa.ut.UnitSpan

All Implemented Interfaces:

java.lang.Comparable<UnitSpan>

public final class UnitSpan
extends java.lang.Object
implements java.lang.Comparable<UnitSpan>

A class to describe a unit span. It consists of a value with a units specification. Unit spans of unknown units are valid.

Instances of this class are immutable. All change operations return a new instance of this UnitSpan class.

Field Summary

static int	CM_250K Unit code for 250,000 units per cm.
static int	INCHES_1M Unit code for 1,000,000 units per inch.
static int	INCHES_72K Unit code for 72,000 units per inch.
static int	MILLIPOINT Unit code for 1,000 units per point (72,000 units per inch).
static int	MM_25K Unit code for 25,000 units per mm.
static int	PICA_PT_10K Deprecated. Unit deprecated. The unit is not accurate and does not actually handle picas.
static int	PICA_PT_1K Deprecated. Unit deprecated in favour of UnitSpan.POINTS_1K.
static int	PICAS_12K Unit code for 12,000 units per pica (72,000 units per inch).
static int	POINTS_1K Unit code for 1,000 units per point (72,000 units per inch).
static int	UNIT_UNKNOWN Unit code for units unknown.

Constructor Summary

UnitSpan()
Instantiates a UnitSpan with the value 0 and default units INCHES_72K.

UnitSpan(double dValue, int eUnits)
Instantiates a UnitSpan with the given double value and units.

UnitSpan(int nValue)
Instantiates a UnitSpan with the given int value and unknown units.

UnitSpan(int eNewUnits, int eOldUnits, int nOldValue)
Instantiates a UnitSpan with the given units and a value equal to the given value after it has been converted from it's old units to the new units.

UnitSpan(java.lang.String sText)
Instantiates a UnitSpan with a value and unit code parsed from the given text.

UnitSpan(UnitSpan source)
Deprecated. UnitSpan is immutable, so there is no need to copy an instance.

Method Summary

UnitSpan	abs() Returns a UnitSpan representing the absolute value of this UnitSpan.
UnitSpan	add(UnitSpan add) Returns a UnitSpan representing the addition of this object and the given UnitSpan.
int	compareTo(UnitSpan compare) Compares this object to the given UnitSpan.
static int	defaultUnits() Gets the default unit code for all UnitSpans.
UnitSpan	divide(int nDivisor) Returns a UnitSpan representing the division of this object's value by the given int value.
double	divide(UnitSpan divisor) Returns a UnitSpan representing the division of this object's value by the given UnitSpan.
boolean	equals(java.lang.Object object) Determines if this object is equal to the given Object.
UnitSpan	grid(UnitSpan grid) Returns a UnitSpan representing this UnitSpan's value snaped to the nearest grid coordinate of the given UnitSpan.
boolean	gt(UnitSpan compare) Determines if this object is greater than the given UnitSpan.
boolean	gte(UnitSpan compare) Determines if this object is greater than or equal to the given.
boolean	lt(UnitSpan compare) Determines if this object is less than the given UnitSpan.
boolean	lte(UnitSpan compare) Determines if this object is less than or equal to the given UnitSpan.
static boolean	match(UnitSpan u1, UnitSpan u2) Compares two UnitSpan(s) for equality, allowing for null arguments.
UnitSpan	multiply(double dScale) Returns a UnitSpan representing the multiplication of this object's value by the given double value.
UnitSpan	multiply(int nScale) Returns a UnitSpan representing the multiplication of this object's value by the given int value.
static int	stringToUnit(java.lang.String sUnit, int eDefaultUnits) Converts the given unit string to a unit code.
java.lang.String	toString() Returns a String containing this object's value followed by its units.
int	units() Gets this object's units.
int	unitsPerInch() Gets the units per inch for this object's unit code.
static int	unitsPerInch(int eUnit) Gets the units per inch for the given unit code.
static java.lang.String	unitToString(int eUnit) Converts the given unit code to a string.
int	value() Gets this object's value.
int	valueAsUnit(int eUnits) Gets this object's value converted to the given unit code.
static UnitSpan	zero() The zero unit span.

Methods inherited from class java.lang.Object

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

Field Detail

INCHES_1M

public static final int INCHES_1M

Unit code for 1,000,000 units per inch.

See Also:

Constant Field Values

CM_250K

public static final int CM_250K

Unit code for 250,000 units per cm.

See Also:

Constant Field Values

INCHES_72K

public static final int INCHES_72K

Unit code for 72,000 units per inch.

See Also:

Constant Field Values

MM_25K

public static final int MM_25K

Unit code for 25,000 units per mm.

See Also:

Constant Field Values

POINTS_1K

public static final int POINTS_1K

Unit code for 1,000 units per point (72,000 units per inch).

See Also:

Constant Field Values

PICA_PT_1K

public static final int PICA_PT_1K

Deprecated. Unit deprecated in favour of UnitSpan.POINTS_1K.

Unit code for 1,000 units per point (72,000 units per inch).

See Also:

Constant Field Values

MILLIPOINT

public static final int MILLIPOINT

Unit code for 1,000 units per point (72,000 units per inch).

See Also:

Constant Field Values

PICA_PT_10K

public static final int PICA_PT_10K

Deprecated. Unit deprecated. The unit is not accurate and does not actually handle picas.

Unit code for 10,000 units per point.

See Also:

Constant Field Values

PICAS_12K

public static final int PICAS_12K

Unit code for 12,000 units per pica (72,000 units per inch).

See Also:

Constant Field Values

UNIT_UNKNOWN

public static final int UNIT_UNKNOWN

Unit code for units unknown.

See Also:

Constant Field Values

Constructor Detail

UnitSpan

public UnitSpan()

Instantiates a UnitSpan with the value 0 and default units INCHES_72K.

See Also:

UnitSpan.zero()

UnitSpan

public UnitSpan(double dValue,
                int eUnits)

Instantiates a UnitSpan with the given double value and units.

Parameters:

dValue - the value of the unit span.

eUnits - the unit code of the unit span.

UnitSpan

public UnitSpan(int nValue)

Instantiates a UnitSpan with the given int value and unknown units. The unit code will be UNIT_UNKNOWN.

Parameters:

nValue - the value of the unit span.

UnitSpan

public UnitSpan(int eNewUnits,
                int eOldUnits,
                int nOldValue)

Instantiates a UnitSpan with the given units and a value equal to the given value after it has been converted from it's old units to the new units.

Parameters:

eNewUnits - the unit code of the unit span to which the value will be converted.

eOldUnits - the unit code from which the value will be converted.

nOldValue - the value to be converted and set as this object's value.

UnitSpan

public UnitSpan(java.lang.String sText)

Instantiates a UnitSpan with a value and unit code parsed from the given text.

Parameters:

sText - text containing a numeric value possibly followed by a unit string of "in", "inches", "cm", "centimeters", "pt", "points", "picas", "mm", "millimeters", "mp", or "millipoints". If no unit is specified, this object's unit will default to UNIT_UNKNOWN.

UnitSpan

public UnitSpan(UnitSpan source)

Deprecated. UnitSpan is immutable, so there is no need to copy an instance.

Instantiates a UnitSpan from the given UnitSpan.

Parameters:

source - the UnitSpan to copy to this object.

Method Detail

defaultUnits

public static int defaultUnits()

Gets the default unit code for all UnitSpans.

Returns:

the default unit code, which is INCHES_72K.

stringToUnit

public static int stringToUnit(java.lang.String sUnit,
                               int eDefaultUnits)

Converts the given unit string to a unit code. If the string is not recognized as a unit string, a default may be specified.

Parameters:

sUnit - the string to be converted.

eDefaultUnits - the default unit code.

Returns:

the converted unit code.

unitsPerInch

public static int unitsPerInch(int eUnit)

Gets the units per inch for the given unit code.

Returns:

the units per inch for the unit code.

unitToString

public static java.lang.String unitToString(int eUnit)

Converts the given unit code to a string.

Parameters:

eUnit - the unit code to be converted.

Returns:

the string version of the unit code.

zero

public static UnitSpan zero()

The zero unit span.

Returns:

the unit span equal to zero.

abs

public UnitSpan abs()

Returns a UnitSpan representing the absolute value of this UnitSpan.

Returns:

a unit span of the absolute value.

add

public UnitSpan add(UnitSpan add)

Returns a UnitSpan representing the addition of this object and the given UnitSpan. The given UnitSpan's value is converted to this object's units for the operation.

Parameters:

add - the UnitSpan to add.

Returns:

a unit span of the addition.

divide

public UnitSpan divide(int nDivisor)

Returns a UnitSpan representing the division of this object's value by the given int value. The resulting value is rounded to 0 decimal places.

Parameters:

nDivisor - the divisor.

Returns:

a unit span of the division.

divide

public double divide(UnitSpan divisor)

Returns a UnitSpan representing the division of this object's value by the given UnitSpan. The given UnitSpan's value is converted to this object's units for the operation.

Parameters:

divisor - the divisor.

Returns:

a unit span of the division.

equals

public boolean equals(java.lang.Object object)

Determines if this object is equal to the given Object. Comparisons with instances of non-UnitSpan objects are never equal.

Overrides:

equals in class java.lang.Object

Parameters:

object - the Object to compare.

Returns:

true if equal, false otherwise.

grid

public UnitSpan grid(UnitSpan grid)

Returns a UnitSpan representing this UnitSpan's value snaped to the nearest grid coordinate of the given UnitSpan. The given UnitSpan's value is converted to this object's units for the calculation.

Positive grid values will "move" this object's value to the left (or down), and negative grid values will "move" this object's value to the right (or up).

The algorithm used to "snap" this object's value is (<y/x> ∗ x) where y is this value, x is the grid size, and <> is the floor function; this is best explained with examples:

 grid = 5, pt = 7 and (<7/5> * 5) = 1 * 5 = 5 (moved to left)
 grid = 5, pt = -7 and (<-7/5> * * 5) = -2 * 5 = -10 (moved to left)
 
 grid = -5, pt = 7 and (<7/-5> * -5) = -2 * -5 = 10 (moved to right)
 grid = -5, pt = * -7 and (<-7/-5> * -5) = 1 * -5 = -5 (moved to right)
 

Parameters:

grid - the grid coordinate

Returns:

a unit span aligned to the grid.

gt

public boolean gt(UnitSpan compare)

Determines if this object is greater than the given UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.

Parameters:

compare - the UnitSpan to compare.

Returns:

true if greater than, false otherwise.

gte

public boolean gte(UnitSpan compare)

Determines if this object is greater than or equal to the given. UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.

Parameters:

compare - the UnitSpan to compare.

Returns:

true if greater than or equal to, false otherwise.

lt

public boolean lt(UnitSpan compare)

Determines if this object is less than the given UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.

Parameters:

compare - the UnitSpan to compare.

Returns:

true if less than, false otherwise.

lte

public boolean lte(UnitSpan compare)

Determines if this object is less than or equal to the given UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.

Parameters:

compare - the UnitSpan to compare.

Returns:

true if less than or equal to, false otherwise.

multiply

public UnitSpan multiply(double dScale)

Returns a UnitSpan representing the multiplication of this object's value by the given double value. The resulting value is rounded to 0 decimal places.

Parameters:

dScale - the multiplier.

Returns:

a unit span of the multiplication.

multiply

public UnitSpan multiply(int nScale)

Returns a UnitSpan representing the multiplication of this object's value by the given int value.

Parameters:

nScale - the multiplier.

Returns:

a unit span of the multiplication.

toString

public java.lang.String toString()

Returns a String containing this object's value followed by its units.

Overrides:

toString in class java.lang.Object

Returns:

a string of this UnitSpan's value followed by its (abbreviated) unit.

units

public int units()

Gets this object's units.

Returns:

the unit as an int.

unitsPerInch

public int unitsPerInch()

Gets the units per inch for this object's unit code.

Returns:

the units per inch for this unit.

value

public int value()

Gets this object's value.

Returns:

the value.

valueAsUnit

public int valueAsUnit(int eUnits)

Gets this object's value converted to the given unit code.

Parameters:

eUnits - the unit code.

Returns:

the converted value.

match

public static boolean match(UnitSpan u1,
                            UnitSpan u2)

Compares two UnitSpan(s) for equality, allowing for null arguments.

Parameters:

u1 - the first UnitSpan to compare.

u2 - the second UnitSpan to compare.

Returns:

true if equal, false othewise. Note that two null arguments will be considered equal, but comparing a null argument to a non-null one will not be considered equal.

compareTo

public int compareTo(UnitSpan compare)

Compares this object to the given UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.

Specified by:

compareTo in interface java.lang.Comparable<UnitSpan>

Parameters:

compare - the UnitSpan to compare.

Returns:

the value 0 if equal; a value less than zero if this object is less that the given argument; and a value greater than zero if this object is greater that the given argument.