API / geotoolkit / util / UnitFactory / UnitFactory
util.UnitFactory.UnitFactory
Factory that creates Unit This class acts as a factory and a registry class that can convert string representation of units into plain unit object. Unit objects themselves can perform conversion of values.
This class embeds a default catalog of commonly used units. Units Tutorial in Geotoolkit/CarnacJS/Utils demonstrates how one could extend or replace units by creating and registering new units.
It lists the base units and shows how to convert and add new units to the factory as shown in the example below.
This class also holds the information used by the toolkit to convert device (screen) dimensions to rendering dimensions.
For example if we are rendering a track with width 1" on display or device size, this 1" can be measured through a ruler. But Javascript cannot set size in device coordinates, so we need Pixel per Inch (PPI, each device has different value) and Pixel per css Pixel (PPCP is what can be used in Javascript and is not same as Pixel).
UnitFactory Class has a static dictionary and can recognize all existing Apple devices and we have APIs to let predefined devices set correct values. The toolkit embeds a recognition algorithm that will try to retrieve those values from a dictionary by analysing the user-agent and other global properties of the browser. However, this algorithm will only recognize some of the predefined devices.
One could either extend this list or customize the algorithm or explicitly set those ppi & ppcp values.
The later is recommended for production application where the displayed scales are critical and the supported platforms list is open. The suggested approach is to provide the user with a calibration tool that will let him set the actual ratios manually.
Example
const unit = factory.getUnit('foot');
// unit is named unit.getName(), and display a unit.getQuantityType() in unit.getSymbol()
// convert to another length unit:
unit.convert(1500.00, 'm'); // 1500.00 ft = 457.20 m
// Add new unit for your own use
factory.addUnit({
// information about the new Unit
'name': 'pint',
'quantityType': 'volume', //or create your own
'symbol': 'pt',
'description': 'drink responsibly',
'baseUnitSymbol': 'm3',
// Computation Detail : newunit = (a+b*base)/(c+d*base)
'a': 0, 'b': 0.000473176, 'c': 1, 'd': 0
});↳
UnitFactory
Constructors
Methods
Methods
▸ addDevicePPIList(list): UnitFactory
Adds device PPI list
| Name | Type | Description |
|---|---|---|
list | PPI[] | Accept function returns true if device matched. |
this
▸ addUnit(name, quantityType, symbol, baseUnitSymbol, a, b, c, d, description?): UnitFactory
Adds a unit to factory. please reference the constructor in Unit for more details.
| Name | Type | Description |
|---|---|---|
name | string | AbstractUnit | unit name or unit inherited from AbstractUnit |
quantityType | string | string[] | expected quantity type |
symbol | string | unit symbol |
baseUnitSymbol | string | base unit symbol |
a | number | factor |
b | number | factor |
c | number | factor |
d | number | factor |
Optional description | string | description of the unit |
this
▸ addUnitAlias(baseUnitSymbol, isCaseSensitive, alias?): UnitFactory
Adds a unit alias to unit factory
| Name | Type | Description |
|---|---|---|
baseUnitSymbol | string | base unit symbol |
isCaseSensitive | boolean | isCaseSensitive case sensitivity flag |
Optional alias | string | string[] | alias unit symbols |
this
▸ addUnitClass(unitInfo): UnitFactory
| Name | Type |
|---|---|
unitInfo | UnitInfo |
▸ addUnitClass(name, baseUnitSymbol?, unitSymbols?): UnitFactory
Adds a unit class to unit factory
| Name | Type | Description |
|---|---|---|
name | string | unit name or object |
Optional baseUnitSymbol | string | base unit symbol |
Optional unitSymbols | string | string[] | array of unit symbols |
this
▸ clearDevicePPIList(): UnitFactory
Clears device PPI list
this
▸ clearUnitAlias(): UnitFactory
Clears all unit alias from unit factory
this
▸ clearUnitClasses(): UnitFactory
Clears all unit classes from unit factory
this
▸ clearUnits(): UnitFactory
Clears all units from unit factory except CSS units (pixel, point and pica)
this
▸ getCSSPixelPerInch(): number
Returns the number of CSS pixels (browser) per physical inch (device) CSS pixels per physical inch is different from pixels per inch of the device. It considers operating system and browser scaling and the ratio between browser inch and physical device inch
number
▸ getClassName(): string
string
AbstractUnitFactory.getClassName
▸ getConvertableUnitSymbols(unit): string[]
Returns all convertible unit symbols
| Name | Type | Description |
|---|---|---|
unit | string | AbstractUnit | unit to convert from/to |
string[]
▸ getPPI(): number
Returns physical pixels per inch of the device
number
▸ getTimeStamp(): number
Returns the time stamp (version) of unit factory. This value will be updated whenever modification made.
number
AbstractUnitFactory.getTimeStamp
▸ getUnit(value, quantityType?, nullIfNotExist?): AbstractUnit
Returns an instance of unit based on specified information
| Name | Type | Description |
|---|---|---|
value | string | AbstractUnit | represent the {string} name, {string} symbol or {AbstractUnit} unit to be created |
Optional quantityType | string[] | expected quantity types |
Optional nullIfNotExist | boolean | return null if unit does not exist instead of returning a user-defined unit |
▸ getUnitSymbolsByClass(name): string[]
Return array of unit symbols by class name
| Name | Type | Description |
|---|---|---|
name | string | class name |
string[]
▸ removeUnit(unit): UnitFactory
Removes a unit from factory.
| Name | Type | Description |
|---|---|---|
unit | string | AbstractUnit | unit name or unit inherited from AbstractUnit |
this
▸ removeUnitAlias(baseUnitSymbol, isCaseSensitive, alias): UnitFactory
Removes a unit alias from unit factory
| Name | Type | Description |
|---|---|---|
baseUnitSymbol | string | base unit symbol |
isCaseSensitive | boolean | case sensitivity flag |
alias | string | string[] | alias unit symbols |
this
▸ removeUnitClass(name, unitSymbols?): UnitFactory
Removes a unit class from unit factory
| Name | Type | Description |
|---|---|---|
name | string | Omit<UnitInfo, "baseunitsymbol"> | unit name or object |
Optional unitSymbols | string | string[] | array of unit symbols |
this
▸ setPPI(ppi, ppcp): UnitFactory
Sets physical pixels per inch of the device
| Name | Type | Description |
|---|---|---|
ppi | number | pixel per inch |
ppcp | number | pixel per css pixel (sometimes different from window.devicePixelRatio) |
this
▸ updateDevicePPI(): UnitFactory
Updates CSS pixels per physical inch
this
▸ Static getClassName(): string
string
AbstractUnitFactory.getClassName
▸ Static getDefaultFactory(): UnitFactory
Returns instance of unit factory
factory
AbstractUnitFactory.getDefaultFactory
▸ Static getInstance(): UnitFactory
Returns instance of unit factory
factory
▸ Static registerDefaults(): UnitFactory
Returns instance of unit factory
factory
▸ Static setType(type): void
Returns instance of unit factory
| Name | Type | Description |
|---|---|---|
type | typeof UnitFactory | factory ctor |
void