Package org.eclipse.birt.report.model.api.util

# Class DimensionUtil

java.lang.Object
org.eclipse.birt.report.model.api.util.DimensionUtil

public class DimensionUtil extends Object
Utility class to do conversions between units.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final double`
`CM_PER_INCH`
Conversion factor from inches to cm.
`static final int`
`DEFAULT_DPI`
The default DPI value.
`static final double`
`PIXEL_PER_PICA`
Conversion factor from picas to pixel.
`static final double`
`POINTS_PER_CM`
Conversion factor from cm to points.
`static final double`
`POINTS_PER_INCH`
Conversion factor from inches to points.
`static final double`
`POINTS_PER_PICA`
Conversion factor from picas to points.

## Constructor Summary

Constructors
Constructor
Description
`DimensionUtil()`

## Method Summary

Modifier and Type
Method
Description
`static DimensionValue`
`convertTo(double measure, String fromUnits, String targetUnits)`
Convert a measure from one units to another.
`static DimensionValue`
`convertTo(double measure, String fromUnits, String targetUnits, int dpi)`
Convert a measure from one units to another.
`static double`
`convertTo(Object value, String appUnits, String targetUnits, double baseSize, int dpi)`
Convert a measure from one units to another.
`static double`
`convertTo(Object value, String appUnits, String targetUnits, double baseSize, String baseSizeUnits, int dpi)`
Convert a measure from one units to another.
`static DimensionValue`
`convertTo(String dimension, String appUnit, String targetUnits)`
Convert a dimension from one units to another, the dimension like "12pt, 12cm" is composed of two parts: "measure" and "units".
`static DimensionValue`
`convertTo(DimensionValue dimension, String appUnit, String targetUnits)`
Convert a `DimensionValue` from one units to another, The conversion is between absolute the units should be one of the absolute units(CM, IN, MM, PT, PC, PX).
`static boolean`
`isAbsoluteFontSize(String value)`
Returns whether the dimension string value is absolute font size constant.
`static final boolean`
`isAbsoluteUnit(String unit)`
Return if the given unit is an absolute unit or not.
`static boolean`
`isRelativeFontSize(String value)`
Returns whether the dimension string value is relative font size constant.
`static final boolean`
`isRelativeUnit(String unit)`
Return if the given unit is a relative unit or not.
`static DimensionValue`
`mergeDimension(DimensionValue dimension1, DimensionValue dimension2)`
Merges two dimension values with default dpi.
`static DimensionValue`
`mergeDimension(DimensionValue dimension1, DimensionValue dimension2, int dpi)`
Merges two dimension values with the given dpi value.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### CM_PER_INCH

public static final double CM_PER_INCH
Conversion factor from inches to cm.

See Also:
  - Constant Field Values

### POINTS_PER_INCH

public static final double POINTS_PER_INCH
Conversion factor from inches to points.

See Also:
  - Constant Field Values

### POINTS_PER_CM

public static final double POINTS_PER_CM
Conversion factor from cm to points.

See Also:
  - Constant Field Values

### POINTS_PER_PICA

public static final double POINTS_PER_PICA
Conversion factor from picas to points.

See Also:
  - Constant Field Values

### PIXEL_PER_PICA

public static final double PIXEL_PER_PICA
Conversion factor from picas to pixel.

See Also:
  - Constant Field Values

### DEFAULT_DPI

public static final int DEFAULT_DPI
The default DPI value.

See Also:
  - Constant Field Values

## Constructor Details

### DimensionUtil

public DimensionUtil()

## Method Details

### convertTo

public static DimensionValue convertTo(double measure, String fromUnits, String targetUnits)
Convert a measure from one units to another. The conversion is between absolute the units should be one of the absolute units(CM, IN, MM, PT, PC, PX).

Parameters:
  `measure` - the numeric measure of the dimension.
  `fromUnits` - unit of the measure, it must be one of the absolute unit.
  `targetUnits` - the desired units, it must be one of the absolute unit.
Returns:
  `DimensionValue` in the target unit.

### convertTo

public static DimensionValue convertTo(double measure, String fromUnits, String targetUnits, int dpi)
Convert a measure from one units to another. The conversion is between absolute the units should be one of the absolute units(CM, IN, MM, PT, PC, PX).

Parameters:
  `measure` - the numeric measure of the dimension.
  `fromUnits` - unit of the measure, it must be one of the absolute unit.
  `targetUnits` - the desired units, it must be one of the absolute unit.
  `dpi` - resolution to calculate px with alternative dpi
Returns:
  `DimensionValue` in the target unit.

### convertTo

public static DimensionValue convertTo(DimensionValue dimension, String appUnit, String targetUnits)
Convert a `DimensionValue` from one units to another, The conversion is between absolute the units should be one of the absolute units(CM, IN, MM, PT, PC, PX).

Parameters:
  `dimension` - the numeric measure of the dimension.
  `appUnit` - the application unit of the dimension, if the dimension has not specified a unit, the the application unit will be applied to it. It must be one of the absolute unit.
  `targetUnits` - the desired unit.
Returns:
  `DimensionValue` in the target unit.

### convertTo

public static DimensionValue convertTo(String dimension, String appUnit, String targetUnits) throws PropertyValueException
Convert a dimension from one units to another, the dimension like "12pt, 12cm" is composed of two parts: "measure" and "units". The conversion is between absolute the units should be one of the absolute units(CM, IN, MM, PT, PC, PX).

Parameters:
  `dimension` - a string representing a absolute dimension value like "12pt, 12pc...".
  `appUnit` - the application unit of the dimension, if the dimension has not specified a unit, the the application unit will be applied to it. It must be one of the absolute unit.
  `targetUnits` - the desired unit.
Returns:
  `DimensionValue` in the target unit.
Throws:
  `PropertyValueException` - if the dimension is not valid.

### isAbsoluteUnit

public static final boolean isAbsoluteUnit(String unit)
Return if the given unit is an absolute unit or not. The following units defined in `DesignChoiceConstants` are considered as absolute:

- UNITS_IN
- UNITS_CM
- UNITS_MM
- UNITS_PT
- UNITS_PC

Parameters:
  `unit` - a given unit.
Returns:
  `true` if the unit is an absolute unit like cm, in, mm, pt and pc. Return `false` if the unit is not an absolute unit.( it can be an relative unit like "%", or even an unrecognized unit. )

### isRelativeUnit

public static final boolean isRelativeUnit(String unit)
Return if the given unit is a relative unit or not. The following units defined in `DesignChoiceConstants` are considered as relative:

- UNITS_EM
- UNITS_EX
- UNITS_PERCENTAGE
- UNITS_PX

Parameters:
  `unit` - a given unit.
Returns:
  `true` if the unit is a relative unit like em, ex, % and px. Return `false` if the unit is not a relative unit.( it can be an absolute relative unit like "mm", or even an unrecognized unit. )

### isAbsoluteFontSize

public static boolean isAbsoluteFontSize(String value)
Returns whether the dimension string value is absolute font size constant. The absolute font size constants are defined in `DesignChoiceConstants` as followed.

- `FONT_SIZE_XX_SMALL`
- `FONT_SIZE_X_SMALL`
- `FONT_SIZE_SMALL`
- `FONT_SIZE_MEDIUM`
- `FONT_SIZE_LARGE`
- `FONT_SIZE_X_LARGE`
- `FONT_SIZE_XX_LARGE`

Parameters:
  `value` - dimension string value
Returns:
  true if the given value is absolute font size constant.

### isRelativeFontSize

public static boolean isRelativeFontSize(String value)
Returns whether the dimension string value is relative font size constant. The relative font size constants are defined in `DesignChoiceConstants` as followed.

- `FONT_SIZE_SMALLER`
- `FONT_SIZE_LARGER`

Parameters:
  `value` - dimension string value
Returns:
  true if the given value is relative font size constant.

### convertTo

public static double convertTo(Object value, String appUnits, String targetUnits, double baseSize, int dpi)
Convert a measure from one units to another. The target units must be one of the absolute units(CM, IN, MM, PT, PC). The input dimension value must be one of the following types:

- `String`. It must be a legal dimension value, such as '10 em', '+3.5pt', '10%'.
- `DimensionValue`
- `DimensionHandle`

Parameters:
  `value` - the input dimension value to be converted
  `appUnits` - the application units, used as default to convert from when units part of the input value is empty or null
  `targetUnits` - the desired units, it must be one of the absolute unit.
  `baseSize` - the base size to convert value with relative units, such as em, ex and %, this value must be computed in units of `DesignChoiceConstants.UNITS_PT`.
  `dpi` - int value that represents the pixel per inch
Returns:
  double value in the target unit.

### convertTo

public static double convertTo(Object value, String appUnits, String targetUnits, double baseSize, String baseSizeUnits, int dpi)
Convert a measure from one units to another. The application units, target units and base size units must be one of the absolute units(CM, IN, MM, PT, PC). The input dimension value must be one of the following types:

- `String`. It must be a legal dimension value, measure part and units part such as '10 em', '+3.5pt', '10%' or only measure part, such as 10.12, 45, +4.
- `DimensionValue`
- `DimensionHandle`

Parameters:
  `value` - the input dimension value to be converted
  `appUnits` - the application units, used as the original units to convert from when units part of the input value is empty or null.It must be one of the absolute unit(CM, IN, MM, PT, PC).
  `targetUnits` - the desired units, it must be one of the absolute unit(CM, IN, MM, PT, PC).
  `baseSize` - the base size to convert value with relative units, such as em, ex and %
  `baseSizeUnits` - the units for the base size. It must be one of the absolute units(CM, IN, MM, PT, PC). By default it is `DesignChoiceConstants.UNITS_PT`
  `dpi` - int value that represents the pixel per inch
Returns:
  double value in the target unit.

### mergeDimension

public static DimensionValue mergeDimension(DimensionValue dimension1, DimensionValue dimension2)
Merges two dimension values with default dpi. If these two dimension values are not in the same unit, only dimension values in absolute units and pixels can be merged. The unit of the merged result will be according to the first dimension value except its unit is is pixel. If one of them is null, the other value will be returned.

Parameters:
  `dimension1` - the first dimension value to merge
  `dimension2` - the second dimension value to merge
Returns:
  the merged dimension value, or null if these two dimension value cannot be merged or both of them are null.

### mergeDimension

public static DimensionValue mergeDimension(DimensionValue dimension1, DimensionValue dimension2, int dpi)
Merges two dimension values with the given dpi value. If these two dimension values are not in the same unit, only dimension values in absolute units and pixels can be merged. The unit of the merged result will be according to the first dimension value except its unit is pixel.If one of them is null, the other value will be returned.

Parameters:
  `dimension1` - the first dimension value to merge
  `dimension2` - the second dimension value to merge
  `dpi` - the dpi value
Returns:
  the merged dimension value, or null if these two dimension value cannot be merged or both of them are null.