nextapp.echo2.app
Class Extent

java.lang.Object
  nextapp.echo2.app.Extent

All Implemented Interfaces:

java.lang.Comparable, java.io.Serializable

public class Extent

extends java.lang.Object

implements java.lang.Comparable, java.io.Serializable

A representation of a linear distance with units. Extent objects are immutable once constructed.

WARNING: Many Components will have Extent-based properties that allow only certain types of units. Make certain to verify the API specification of any Component to ensure that you are using Extents correctly with it. The Extent-based getXXX() and setXXX() property methods of a Component will explain what types of Extents are allowed.

See Also:

Serialized Form

Field Summary

static int	CM Centimeter units.
static int	EM Em units (height of font).
static int	EX Ex units (height of character 'x' in font).
static int	IN Inch units.
static int	MM Millimeter units.
static int	PC Picas (1pc = 12pt)
static int	PERCENT Percentage units.
static int	PT Points (1pt = 1/72in).
static int	PX Pixel units.

Constructor Summary

Extent(int value)
Creates a new Extent with pixel units.

Extent(int value, int units)
Creates a new Extent.

Method Summary

static Extent	add(Extent a, Extent b) Adds one Extent to another, returning the sum as a new Extent.
int	compareTo(java.lang.Object o)
boolean	equals(java.lang.Object o)
int	getUnits() Returns the units of the Extent.
int	getValue() Returns the value of the Extent.
boolean	isComparableTo(Extent that) Determines whether this Extent can be compared to another Extent to determine which is a greater length.
boolean	isEnglish() Determines if the Extent has English units, i.e., the units are of type IN (inches), PC (picas), or PT (points).
boolean	isPercentage() Determines if the Extent has percentage-based units.
boolean	isPrint() Determines if this Extent has 'print' based units, i.e., the units are in real dimensions, such as SI or English values, rather than screen-based units such as pixels or percentages.
boolean	isSI() Determines if the Extent has SI (Metric) units, i.e., the units are of type MM (millimeters) or CM (centimeters).
int	toMm() Returns the value of the extent in millimeters.
int	toPoint() Returns the value of the extent in points.
java.lang.String	toString() Returns a string describing the state of the Extent.
static void	validate(Extent value, int validUnits) Validates that the specified Extent is acceptable for use in a particular environment, by ensuring that its units are of a supported type.

Methods inherited from class java.lang.Object

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

Field Detail

PX

public static final int PX

Pixel units.

See Also:

Constant Field Values

PERCENT

public static final int PERCENT

Percentage units.

See Also:

Constant Field Values

PT

public static final int PT

Points (1pt = 1/72in).

See Also:

Constant Field Values

CM

public static final int CM

Centimeter units.

See Also:

Constant Field Values

MM

public static final int MM

Millimeter units.

See Also:

Constant Field Values

IN

public static final int IN

Inch units.

See Also:

Constant Field Values

EM

public static final int EM

Em units (height of font).

See Also:

Constant Field Values

EX

public static final int EX

Ex units (height of character 'x' in font).

See Also:

Constant Field Values

PC

public static final int PC

Picas (1pc = 12pt)

See Also:

Constant Field Values

Constructor Detail

Extent

public Extent(int value)

Creates a new Extent with pixel units.

Parameters:

value - the value of the extent in pixels

Extent

public Extent(int value,
              int units)

Creates a new Extent.

Parameters:

value - the value of the extent

units - the units of the value, one of the following constants:

• PC: Pixels
• PERCENT: Percent (of size of containing component)
• PT: Points
• CM: Centimeters
• MM: Millimeters
• IN: Inches
• EM: Ems (height of 'M' character)
• EX: Exs (height of 'x' character)
• PC: Picas

Method Detail

add

public static Extent add(Extent a,
                         Extent b)

Adds one Extent to another, returning the sum as a new Extent. Null is returned if the Extents have incompatible units. If either provided Extent is null, the other is returned.

Parameters:

a - the first Extent

b - the second Extent

Returns:

the sum of the Extents, if calculable

validate

public static void validate(Extent value,
                            int validUnits)

Validates that the specified Extent is acceptable for use in a particular environment, by ensuring that its units are of a supported type.

Parameters:

value - the Extent to validate

validUnits - a bitmask containing one or more of the unit constants (multiple unit constants may be ORed together)

Throws:

java.lang.IllegalArgumentException - if the Extent is invalid

compareTo

public int compareTo(java.lang.Object o)

Specified by:

compareTo in interface java.lang.Comparable

See Also:

Comparable.compareTo(java.lang.Object)

equals

public boolean equals(java.lang.Object o)

See Also:

Object.equals(java.lang.Object)

getValue

public int getValue()

Returns the value of the Extent.

Returns:

The value of the Extent

getUnits

public int getUnits()

Returns the units of the Extent.

Returns:

The units of the Extent, one of the following constants:

• PC: Pixels
• PERCENT: Percent (of size of containing component)
• PT: Points
• CM: Centimeters
• MM: Millimeters
• IN: Inches
• EM: Ems (height of 'M' character)
• EX: Exs (height of 'x' character)
• PC: Picas

isComparableTo

public boolean isComparableTo(Extent that)

Determines whether this Extent can be compared to another Extent to determine which is a greater length.

Parameters:

that - the Extent to test comparability to

Returns:

true if the Extents can be compared

isEnglish

public boolean isEnglish()

Determines if the Extent has English units, i.e., the units are of type IN (inches), PC (picas), or PT (points).

Returns:

true if this Extent has English units

isSI

public boolean isSI()

Determines if the Extent has SI (Metric) units, i.e., the units are of type MM (millimeters) or CM (centimeters).

Returns:

true if this Extent has SI units

isPercentage

public boolean isPercentage()

Determines if the Extent has percentage-based units.

Returns:

true if the Extent has percentage-based units

isPrint

public boolean isPrint()

Determines if this Extent has 'print' based units, i.e., the units are in real dimensions, such as SI or English values, rather than screen-based units such as pixels or percentages.

Returns:

true if this Extent has 'print' based units

toMm

public int toMm()

Returns the value of the extent in millimeters.

Returns:

the value of the extent in millimeters

Throws:

java.lang.IllegalStateException - if the value cannot be returned in millimeters. Verify that isPrint() returns true to avoid potentially receiving this exception.

toPoint

public int toPoint()

Returns the value of the extent in points.

Returns:

the value of the extent in points

Throws:

java.lang.IllegalStateException - if the value cannot be returned in points (verify that isPrint() returns true to avoid potentially receiving this exception).

toString

public java.lang.String toString()

Returns a string describing the state of the Extent. For debugging purposes only, do not rely on formatting.

See Also:

Object.toString()