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?: false | true): FormatterSpec | undefined Synchronous call to get a FormatterSpec of a QuantityType.  
findParserSpecByQuantityType(type: QuantityTypeArg): ParserSpec | undefined 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: FormatterSpec | undefined): 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?: imperial, ignoreOverrides?: false | true): undefined | FormatProps    
getFormatterSpecByQuantityType(type: QuantityTypeArg, isImperial?: false | true): Promise<FormatterSpec | undefined> Asynchronous Call to get a FormatterSpec for a QuantityType.  
getFormatterSpecByQuantityTypeAndSystem(type: QuantityTypeArg, system?: imperial): Promise<FormatterSpec | undefined> Asynchronous Call to get a FormatterSpec of a QuantityType.  
getParserSpecByQuantityType(type: QuantityTypeArg, isImperial?: false | true): Promise<ParserSpec | undefined> Asynchronous Call to get a ParserSpec for a QuantityType.  
getParserSpecByQuantityTypeAndSystem(type: QuantityTypeArg, system?: imperial): Promise<ParserSpec | undefined>    
getQuantityDefinition(type: QuantityTypeArg): undefined | QuantityTypeDefinition    
getQuantityTypeKey(type: QuantityTypeArg): string Converts a QuantityTypeArg into a QuantityTypeKey/string value.  
getUnitSystemFromString(inputSystem: string, fallback?: imperial): imperial Get a UnitSystemKey from a string that may have been entered via a key-in.  
getUnitsByFamily(phenomenon: string): Promise<UnitProps[]>    
hasActiveOverride(type: QuantityTypeArg, checkOnlyActiveUnitSystem?: false | true): boolean    
initializeQuantityTypesRegistry(): Promise<void> Protected    
parseToQuantityValue(inString: string, parserSpec: ParserSpec | undefined): QuantityParseResult Parse input string into quantity given the ParserSpec  
registerQuantityType(entry: CustomQuantityTypeDefinition, replace?: false | true): Promise<boolean>    
reinitializeFormatAndParsingsMaps(overrideFormatPropsByUnitSystem: Map<imperial, Map<QuantityTypeKey, FormatProps>>, unitSystemKey?: imperial, fireUnitSystemChanged?: false | true, startDefaultTool?: false | true): Promise<void> Reinitialize caches. Beta  
setActiveUnitSystem(isImperialOrUnitSystem: imperial | boolean, restartActiveTool?: false | true): 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 imperial    
_overrideFormatPropsByUnitSystem Protected Map<"metric" = undefined | "imperial" = undefined | "usCustomary" = undefined | "usSurvey" = undefined, Map<string, FormatProps>>    
_quantityTypeRegistry Protected Map<QuantityTypeKey, QuantityTypeDefinition>    
_unitFormattingSettingsProvider Protected UnitFormattingSettingsProvider | undefined    
activeUnitSystem Accessor ReadOnly imperial True if tool quantity values should be displayed in imperial units; false for metric.  
onActiveFormattingUnitSystemChanged BeUiEvent<FormattingUnitSystemChangedArgs> Called after the active unit system is changed.  
onActiveUnitSystemChanged BeUiEvent<{ useImperial: boolean }> Called after the active unit system is changed. Deprecated  
onQuantityFormatsChanged BeUiEvent<QuantityFormatsChangedArgs> Called when the format of a QuantityType is overriden or the override is cleared.  
onUnitsProviderChanged BeUiEvent<void> Fired when the active UnitsProvider is updated.  
quantityTypesRegistry Accessor ReadOnly Map<string, QuantityTypeDefinition>    
unitsProvider Accessor UnitsProvider    
useImperialFormats Accessor boolean   Deprecated  

Defined in

Last Updated: 18 March, 2021