nextapp.echo.app.Extent Maven / Gradle / Ivy
/*
* This file is part of the Echo Web Application Framework (hereinafter "Echo").
* Copyright (C) 2002-2009 NextApp, Inc.
*
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*/
package nextapp.echo.app;
import java.io.Serializable;
/**
* A representation of an integer linear distance with units. Extent
* objects are immutable once constructed.
*
* WARNING: Some 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.
*/
public class Extent
implements Comparable, Serializable {
/** Serial Version UID. */
private static final long serialVersionUID = 20070101L;
/**
* 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.
*
* @param a the first Extent
* @param b the second Extent
* @return the sum of the Extents, if calculable
*/
public static Extent add(Extent a, Extent b) {
if (a == null) {
return b;
}
if (b == null) {
return a;
}
if (a.getUnits() == b.getUnits()) {
return new Extent(a.getValue() + b.getValue(), a.getUnits());
}
if (a.isPrint() && b.isPrint()) {
if (a.isEnglish() && b.isEnglish()) {
return new Extent(a.toPoint() + b.toPoint(), PT);
}
return new Extent(a.toMm() + b.toMm(), MM);
}
return null;
}
/**
* Validates that the specified Extent is acceptable for use
* in a particular environment, by ensuring that its units are of a
* supported type.
*
* @param value the Extent to validate
* @param validUnits a bitmask containing one or more of the unit constants
* (multiple unit constants may be ORed together)
* @throws IllegalArgumentException if the Extent is invalid
*/
public static void validate(Extent value, int validUnits) {
if (value != null && (value.getUnits() & validUnits) == 0) {
throw new IllegalArgumentException("Specified units are unsupported in this context.");
}
}
/**
* Returns a string representation of a units type.
*
* @param units the units
* @return the unit string
*/
static String getUnitsString(int units) {
switch (units) {
case Extent.CM: return "cm";
case Extent.EM: return "em";
case Extent.EX: return "ex";
case Extent.IN: return "in";
case Extent.MM: return "mm";
case Extent.PC: return "pc";
case Extent.PERCENT: return "%";
case Extent.PT: return "pt";
default: return "px";
}
}
/**
* Pixel units.
*/
public static final int PX = 1;
/**
* Percentage units.
*/
public static final int PERCENT = 2;
/**
* Points (1pt = 1/72in).
*/
public static final int PT = 4;
/**
* Centimeter units.
*/
public static final int CM = 8;
/**
* Millimeter units.
*/
public static final int MM = 16;
/**
* Inch units.
*/
public static final int IN = 32;
/**
* Em units (height of font).
*/
public static final int EM = 64;
/**
* Ex units (height of character 'x' in font).
*/
public static final int EX = 128;
/**
* Picas (1pc = 12pt)
*/
public static final int PC = 256;
private final int value;
private final int units;
/**
* Creates a new Extent with pixel units.
*
* @param value the value of the extent in pixels
*/
public Extent(int value) {
this.value = value;
this.units = Extent.PX;
}
/**
* Creates a new Extent.
*
* @param value the value of the extent
* @param units the units of the value, one of the following constants:
*
* PC: PixelsPERCENT: Percent (of size of containing
* component)PT: PointsCM: CentimetersMM: MillimetersIN: InchesEM: Ems (height of 'M' character)EX: Exs (height of 'x' character)PC: Picas
*/
public Extent(int value, int units) {
this.value = value;
this.units = units;
}
/**
* @see java.lang.Comparable#compareTo(java.lang.Object)
*/
public int compareTo(Object o) {
Extent that = (Extent) o;
if (this.units == that.units) {
return this.value - that.value;
}
if (this.isPrint() && that.isPrint()) {
return this.toPoint() - that.toPoint();
}
return this.units - that.units;
}
/**
* @see java.lang.Object#equals(java.lang.Object)
*/
public boolean equals(Object o) {
if (this == o) {
return true;
} else if (o == null) {
return false;
} else if (o instanceof Extent) {
Extent that = (Extent) o;
return this.value == that.value && this.units == that.units;
} else {
return false;
}
}
/**
* Returns the value of the Extent.
*
* @return The value of the Extent
*/
public int getValue() {
return value;
}
/**
* Returns the units of the Extent.
*
* @return The units of the Extent, one of the following
* constants:
*
* PC: PixelsPERCENT: Percent (of size of containing
* component)PT: PointsCM: CentimetersMM: MillimetersIN: InchesEM: Ems (height of 'M' character)EX: Exs (height of 'x' character)PC: Picas
*/
public int getUnits() {
return units;
}
/**
* Determines whether this Extent can be compared to another
* Extent to determine which is a greater length.
*
* @param that the Extent to test comparability to
* @return true if the Extents can be compared
*/
public boolean isComparableTo(Extent that) {
return this.units == that.units || (this.isPrint() && that.isPrint());
}
/**
* Determines if the Extent has English units, i.e., the
* units are of type IN (inches), PC (picas), or
* PT (points).
*
* @return true if this Extent has English units
*/
public boolean isEnglish() {
return units == IN || units == PC || units == PT;
}
/**
* Determines if the Extent has SI (Metric) units, i.e., the
* units are of type MM (millimeters) or CM
* (centimeters).
*
* @return true if this Extent has SI units
*/
public boolean isSI() {
return units == MM || units == CM;
}
/**
* Determines if the Extent has percentage-based units.
*
* @return true if the Extent has percentage-based units
*/
public boolean isPercentage() {
return units == PERCENT;
}
/**
* 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.
*
* @return true if this Extent has 'print' based units
*/
public boolean isPrint() {
return units == IN || units == PC || units == PT || units == MM || units == CM;
}
/**
* Returns the value of the extent in millimeters.
*
* @return the value of the extent in millimeters
* @throws IllegalStateException if the value cannot be returned in
* millimeters.
* Verify that isPrint() returns true to avoid
* potentially receiving this exception.
*/
public int toMm() {
switch (units) {
case MM:
return value;
case CM:
return value * 10;
case IN:
return (int) (value * 25.4);
case PT:
return (int) ((value / 72) * 25.4);
case PC:
return (int) ((value / 6) * 25.4);
}
throw new IllegalStateException("Cannot convert to mm.");
}
/**
* Returns the value of the extent in points.
*
* @return the value of the extent in points
* @throws IllegalStateException if the value cannot be returned in points
* (verify that isPrint() returns true to avoid
* potentially receiving this exception).
*/
public int toPoint() {
switch (units) {
case PT:
return value;
case PC:
return value * 12;
case IN:
return value * 72;
case MM:
return (int) ((value / 25.4) * 72);
case CM:
return (int) ((value / 2.54) * 72);
}
throw new IllegalStateException("Cannot convert to pt.");
}
/**
* Returns a string describing the state of the Extent.
* For debugging purposes only, do not rely on formatting.
*
* @see java.lang.Object#toString()
*/
public String toString() {
return value + getUnitsString(units);
}
}