QuantityFormatter Class
Beta
Class that supports formatting quantity values into strings and parsing strings into quantity values. This class also maintains the "active" unit system and caches FormatterSpecs and ParserSpecs for the "active" unit system to allow synchronous access to parsing and formatting values. The support unit systems are defined by UnitSystemKey and is kept in synch with the unit systems provided by the Presentation Manager on the backend. The QuantityFormatter contains a registry of quantity type definitions. These definitions implement the QuantityTypeDefinition interface, which among other things, provide default [FormatProps]$(imodeljs-quantity), and provide methods to generate both a [FormatterSpec]$(imodeljs-quantity) and a [ParserSpec]$(imodeljs-quantity). There are built-in quantity types that are identified by the QuantityType enum. CustomQuantityTypeDefinition can be registered to extend the available quantity types available by frontend tools. The QuantityFormatter also allows the default formats to be overriden.
Implements
Methods
| Name | Description | |
|---|---|---|
| constructor(showMetricOrUnitSystem?: boolean | UnitSystemKey): QuantityFormatter | constructor | |
| clearAllOverrideFormats(): Promise<void> | ||
| clearOverrideFormats(type: QuantityTypeArg): Promise<void> | ||
| findFormatterSpecByQuantityType(type: QuantityTypeArg, _unused?: boolean): undefined | FormatterSpec | Synchronous call to get a FormatterSpec of a QuantityType. | |
| findParserSpecByQuantityType(type: QuantityTypeArg): undefined | ParserSpec | Synchronous call to get a ParserSpec for a QuantityType. | |
| findUnit(unitLabel: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps> | ||
| findUnitByName(unitName: string): Promise<UnitProps> | ||
| formatQuantity(magnitude: number, formatSpec: undefined | FormatterSpec): string | Generates a formatted string for a quantity given its format spec. | |
| generateFormatterSpecByType(type: QuantityTypeArg, formatProps: FormatProps): Promise<FormatterSpec> | ||
| getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversion> | ||
| getFormatPropsByQuantityType(quantityType: QuantityTypeArg, requestedSystem?: UnitSystemKey, ignoreOverrides?: boolean): undefined | FormatProps | ||
| getFormatterSpecByQuantityType(type: QuantityTypeArg, isImperial?: boolean): Promise<undefined | FormatterSpec> | Asynchronous Call to get a FormatterSpec for a QuantityType. | |
| getFormatterSpecByQuantityTypeAndSystem(type: QuantityTypeArg, system?: UnitSystemKey): Promise<undefined | FormatterSpec> | Asynchronous Call to get a FormatterSpec of a QuantityType. | |
| getParserSpecByQuantityType(type: QuantityTypeArg, isImperial?: boolean): Promise<undefined | ParserSpec> | Asynchronous Call to get a ParserSpec for a QuantityType. | |
| getParserSpecByQuantityTypeAndSystem(type: QuantityTypeArg, system?: UnitSystemKey): Promise<undefined | ParserSpec> | ||
| getQuantityDefinition(type: QuantityTypeArg): undefined | QuantityTypeDefinition | ||
| getQuantityTypeKey(type: QuantityTypeArg): string | Converts a QuantityTypeArg into a QuantityTypeKey/string value. | |
| getUnitSystemFromString(inputSystem: string, fallback?: UnitSystemKey): UnitSystemKey | Get a UnitSystemKey from a string that may have been entered via a key-in. | |
| getUnitsByFamily(phenomenon: string): Promise<UnitProps[]> | ||
| hasActiveOverride(type: QuantityTypeArg, checkOnlyActiveUnitSystem?: boolean): boolean | ||
| initializeQuantityTypesRegistry(): Promise<void> Protected | ||
| parseToQuantityValue(inString: string, parserSpec: undefined | ParserSpec): QuantityParseResult | Parse input string into quantity given the ParserSpec | |
| registerQuantityType(entry: CustomQuantityTypeDefinition, replace?: boolean): Promise<boolean> | ||
| reinitializeFormatAndParsingsMaps(overrideFormatPropsByUnitSystem: Map<UnitSystemKey, Map<string, FormatProps>>, unitSystemKey?: UnitSystemKey, fireUnitSystemChanged?: boolean, startDefaultTool?: boolean): Promise<void> | Reinitialize caches. | Beta |
| setActiveUnitSystem(isImperialOrUnitSystem: boolean | UnitSystemKey, restartActiveTool?: boolean): Promise<void> | Set the Active unit system to one of the supported types. | |
| setOverrideFormat(type: QuantityTypeArg, overrideFormat: FormatProps): Promise<void> | ||
| setOverrideFormats(type: QuantityTypeArg, overrideEntry: OverrideFormatEntry): Promise<void> | ||
| setUnitFormattingSettingsProvider(provider: UnitFormattingSettingsProvider): Promise<void> | set the settings provider and if not imodel specific initialize setting for user. |
Properties
| Name | Type | Description | |
|---|---|---|---|
| _activeFormatSpecsByType Protected | Map<string, FormatterSpec> | ||
| _activeParserSpecsByType Protected | Map<string, ParserSpec> | ||
| _activeUnitSystem Protected | UnitSystemKey | ||
| _overrideFormatPropsByUnitSystem Protected | Map<UnitSystemKey, Map<string, FormatProps>> | ||
| _quantityTypeRegistry Protected | Map<string, QuantityTypeDefinition> | ||
| _unitFormattingSettingsProvider Protected | undefined | UnitFormattingSettingsProvider | ||
| activeUnitSystem Accessor ReadOnly | UnitSystemKey | True if tool quantity values should be displayed in imperial units; false for metric. | |
| onActiveFormattingUnitSystemChanged Readonly | BeUiEvent<FormattingUnitSystemChangedArgs> | Called after the active unit system is changed. | |
| onActiveUnitSystemChanged Readonly | BeUiEvent<{ useImperial: boolean }> | Called after the active unit system is changed. | Deprecated |
| onQuantityFormatsChanged Readonly | BeUiEvent<QuantityFormatsChangedArgs> | Called when the format of a QuantityType is overriden or the override is cleared. | |
| onUnitsProviderChanged Readonly | BeUiEvent<void> | Fired when the active UnitsProvider is updated. | |
| quantityTypesRegistry Accessor ReadOnly | Map<string, QuantityTypeDefinition> | ||
| unitsProvider Accessor | UnitsProvider | ||
| useImperialFormats Accessor | boolean |
Defined in
Last Updated: 11 June, 2024