net.sf.jguiraffe.gui.layout

Class NumberWithUnit

java.lang.Object

net.sf.jguiraffe.gui.layout.NumberWithUnit

All Implemented Interfaces:

Serializable

public class NumberWithUnit
extends Object
implements Serializable

A class that combines a value with a unit.

This class can be used to work with values that have an associated unit. For instance spaces in a layout can be defined in arbitrary units like pixels, dialog units, inches or centimeters. To support this, an instance of this class stores a value (as a floating point number) and a reference to a Unit object. This Unit object is also used to perform conversions of the stored value to the default unit pixels.

Instances of this class are immutable. Once created, they cannot be changed any more. Thus they can be shared between multiple threads.

Version:

$Id: NumberWithUnit.java 205 2012-01-29 18:29:57Z oheger $

Author:

Oliver Heger

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static NumberWithUnit	ZERO Constant for the special value zero.

Constructor Summary

Constructors

Constructor and Description
NumberWithUnit(double val, Unit unit) Creates a new instance of NumberWithUnit and initializes it.
NumberWithUnit(int val) Creates a new instance of NumberWithUnit with the given value and the unit pixels.
NumberWithUnit(String s) Creates a new instance of NumberWithUnit and initializes it from the given string representation.

Method Summary

Modifier and Type	Method and Description
void	buildUnitString(StringBuilder buf) Appends a string representation of this number and its unit to the given string buffer.
boolean	equals(Object obj) Compares two objects.
Unit	getUnit() Returns the unit of this number.
double	getValue() Returns the numeric value.
int	hashCode() Returns a hash code for this object.
static NumberWithUnit	nonNull(NumberWithUnit n) A convenience method for performing checks for null values.
int	toPixel(UnitSizeHandler handler, Object comp, boolean y) Converts this number into a pixel value.
String	toString() Returns a string representation of this object.
String	toUnitString() Returns a string representation for the stored value and the unit.

Methods inherited from class java.lang.Object

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

Field Detail

ZERO

public static final NumberWithUnit ZERO

Constant for the special value zero.

Constructor Detail

NumberWithUnit

public NumberWithUnit(int val)

Creates a new instance of NumberWithUnit with the given value and the unit pixels.

Parameters:

val - the value

NumberWithUnit

public NumberWithUnit(double val,
                      Unit unit)

Creates a new instance of NumberWithUnit and initializes it.

Parameters:

val - the numeric value

unit - the unit (must not be null )

NumberWithUnit

public NumberWithUnit(String s)

Creates a new instance of NumberWithUnit and initializes it from the given string representation. The string passed to this method must start with a valid double number. Then after optional whitespace the name of the unit must follow. If no unit is provided, pixel is assumed. Valid strings are for instance "10", "10cm", "10.5 cm".

Parameters:

s - the string to be parsed (must not be null)

Throws:

IllegalArgumentException - if the passed in string is not a valid unit string

See Also:

toUnitString()

Method Detail

getValue

public final double getValue()

Returns the numeric value.

Returns:

the value

getUnit

public final Unit getUnit()

Returns the unit of this number.

Returns:

the unit

toPixel

public int toPixel(UnitSizeHandler handler,
                   Object comp,
                   boolean y)

Converts this number into a pixel value. This method calls the corresponding conversion method on the actual Unit object.

Parameters:

handler - the size handler

comp - the component

y - flag for X or Y direction

Returns:

the pixel value

See Also:

Unit.toPixel(double, UnitSizeHandler, Object, boolean)

buildUnitString

public void buildUnitString(StringBuilder buf)

Appends a string representation of this number and its unit to the given string buffer. First the number is written and then the name of the unit. This is the same as toUnitString(), but the string is directly appended to the given buffer.

Parameters:

buf - the string buffer (must not be null)

Throws:

IllegalArgumentException - if the buffer is null

toUnitString

public String toUnitString()

Returns a string representation for the stored value and the unit. This string contains the value immediately followed by the short unit name, e.g. 10px, 100dlu, 2.5in. Strings in this format can be passed to the constructor that takes a string argument.

Returns:

a string for the value and the unit

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class Object

Returns:

a string for this object

hashCode

public int hashCode()

Returns a hash code for this object.

Overrides:

hashCode in class Object

Returns:

a hash code

equals

public boolean equals(Object obj)

Compares two objects. Two instances of this class are equal if they have the same unit and the same value.

Overrides:

equals in class Object

Parameters:

obj - the object to compare to

Returns:

a flag if the objects are equal

nonNull

public static NumberWithUnit nonNull(NumberWithUnit n)

A convenience method for performing checks for null values. This method converts a null argument into an instance with the value 0. Other arguments are directly returned. This is useful if null references are to be avoided.

Parameters:

n - the source number

Returns:

the guaranteed non null result number