ForceUnits

ForceUnits

#Overview

name: ForceUnits

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ForceUnits is to specify a fixed unit of measurement for displaying property values in the Unreal Engine editor, without allowing for locale or other conversions. This setting variable is primarily used for property metadata and editor display purposes.

ForceUnits is mainly utilized by the Property Editor system within Unreal Engine’s editor tools. It’s particularly relevant to the following subsystems and modules:

  1. Property Editor module
  2. UnrealEd module
  3. CoreUObject module
  4. Animation system (specifically the Pose Search plugin)

The value of this variable is typically set in property declarations using the meta specifier. For example:

UPROPERTY(EditAnywhere, config, Category=Units, AdvancedDisplay, meta=(DisplayName="Force", Tooltip="Choose the units in which to display forces.", ValidEnumValues="Newtons, PoundsForce, KilogramsForce, KilogramCentimetersPerSecondSquared"))
EUnit ForceUnits;

ForceUnits interacts with other unit-related variables and systems, such as:

  1. Other unit-specific variables (e.g., TorqueUnits, ImpulseUnits)
  2. The FUnitConversion system
  3. The TNumericUnitTypeInterface

Developers should be aware of the following when using ForceUnits:

  1. It overrides the default unit display behavior, forcing a specific unit regardless of user preferences or locale settings.
  2. It’s used in conjunction with the EUnit enum to specify the desired unit.
  3. It affects how properties are displayed in the editor, not necessarily how they’re stored or processed internally.

Best practices for using ForceUnits include:

  1. Use it sparingly, only when a specific unit display is absolutely necessary for clarity or consistency.
  2. Ensure the forced unit is appropriate for the property and its typical use cases.
  3. Provide clear documentation or tooltips to explain the unit being used, especially if it’s not immediately obvious.
  4. Consider the impact on localization and whether forcing a specific unit might cause confusion for users in different regions.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEditor.ini:533, section: [/Script/UnrealEd.EditorProjectAppearanceSettings]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Plugins/Animation/PoseSearch/Source/Editor/Private/PoseSearchDatabaseEditorReflection.cpp:221

Scope (from outer to inner):

file
function     void UPoseSearchDatabaseStatistics::Initialize

Source code excerpt:

		// Kinematic Information
	
		// using FText instead of meta = (ForceUnits = "cm/s") to keep properties consistent
		AverageSpeed = FText::Format(LOCTEXT("StatsAverageSpeed", "{0} cm/s"), SearchIndex.Stats.AverageSpeed);
		MaxSpeed = FText::Format(LOCTEXT("StatsMaxSpeed", "{0} cm/s"), SearchIndex.Stats.MaxSpeed);
		AverageAcceleration = FText::Format(LOCTEXT("StatsAverageAcceleration", "{0} cm/s²"), SearchIndex.Stats.AverageAcceleration);
		MaxAcceleration = FText::Format(LOCTEXT("StatsMaxAcceleration", "{0} cm/s²"), SearchIndex.Stats.MaxAcceleration);

		// Principal Component Analysis

#Loc: <Workspace>/Engine/Source/Editor/PropertyEditor/Private/UserInterface/PropertyEditor/SPropertyEditorNumeric.h:280

Scope (from outer to inner):

file
class        class SPropertyEditorNumeric : public SCompoundWidget
function     void Construct

Source code excerpt:

			// Set up the correct type interface if we want to display units on the property editor

			// First off, check for ForceUnits= meta data. This meta tag tells us to interpret, and always display the value in these units. FUnitConversion::Settings().ShouldDisplayUnits does not apply to such properties
			const FString& ForcedUnits = MetaDataGetter.Execute("ForceUnits");
			TOptional<EUnit> PropertyUnits = FUnitConversion::UnitFromString(*ForcedUnits);
			if (PropertyUnits.IsSet())
			{
				// Create the type interface and set up the default input units if they are compatible
				TypeInterface = MakeShareable(new TNumericUnitTypeInterface<NumericType>(PropertyUnits.GetValue()));

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Settings/EditorProjectSettings.cpp:117

Scope: file

Source code excerpt:

		Settings.SetDisplayUnits(EUnitType::Temperature, TemperatureUnits);
	}
	else if (Name == GET_MEMBER_NAME_CHECKED(UEditorProjectAppearanceSettings, ForceUnits))
	{
		Settings.SetDisplayUnits(EUnitType::Force, ForceUnits);
	}
	else if (Name == GET_MEMBER_NAME_CHECKED(UEditorProjectAppearanceSettings, TorqueUnits))
	{
		Settings.SetDisplayUnits(EUnitType::Torque, TorqueUnits);
	}
	else if (Name == GET_MEMBER_NAME_CHECKED(UEditorProjectAppearanceSettings, ImpulseUnits))

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Settings/EditorProjectSettings.cpp:181

Scope (from outer to inner):

file
function     void UEditorProjectAppearanceSettings::PostInitProperties

Source code excerpt:

	Settings.SetDisplayUnits(EUnitType::Speed, SpeedUnits);
	Settings.SetDisplayUnits(EUnitType::Temperature, TemperatureUnits);
	Settings.SetDisplayUnits(EUnitType::Force, ForceUnits);

	Settings.SetShouldDisplayUnits(bDisplayUnits);
}


/* ULevelEditor2DSettings

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Public/Settings/EditorProjectSettings.h:99

Scope (from outer to inner):

file
class        class UEditorProjectAppearanceSettings : public UDeveloperSettings

Source code excerpt:


	UPROPERTY(EditAnywhere, config, Category=Units, AdvancedDisplay, meta=(DisplayName="Force", Tooltip="Choose the units in which to display forces.", ValidEnumValues="Newtons, PoundsForce, KilogramsForce, KilogramCentimetersPerSecondSquared"))
	EUnit ForceUnits;

	UPROPERTY(EditAnywhere, config, Category = Units, AdvancedDisplay, meta = (DisplayName = "Torque", Tooltip = "Choose the units in which to display torques.", ValidEnumValues = "NewtonMeters, KilogramCentimetersSquaredPerSecondSquared"))
	EUnit TorqueUnits;

	UPROPERTY(EditAnywhere, config, Category = Units, AdvancedDisplay, meta = (DisplayName = "Impulse", Tooltip = "Choose the units in which to display impulses.", ValidEnumValues = "NewtonSeconds"))
	EUnit ImpulseUnits;

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Public/UObject/ObjectMacros.h:1465

Scope (from outer to inner):

file
namespace    UM

Source code excerpt:


		/// [PropertyMetadata] Used instead of 'Units' metadata to forcibly show a property in a fixed unit, without locale or other conversion
		ForceUnits,

		/// [PropertyMetadata] Used for SoftObjectPtr/SoftObjectPath properties to specify a reference should not be tracked. This reference will not be automatically cooked or saved into the asset registry for redirector/delete fixup.
		Untracked,

		/// [PropertyMetadata] For functions that should be compiled in development mode only.
		DevelopmentOnly,