UIScaleRule

UIScaleRule

#Overview

name: UIScaleRule

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of UIScaleRule is to determine how the user interface should be scaled across different screen resolutions and DPI settings. It is a crucial setting for maintaining consistent UI appearance and usability across various devices and display configurations.

This setting variable is primarily used in the Unreal Engine’s user interface and rendering systems. Based on the callsites, it is referenced in the UMGEditor module (for the editor’s UI) and the Engine module (for runtime UI scaling).

The value of this variable is set in the User Interface Project Settings, as indicated by the UPROPERTY macro in the UserInterfaceSettings.h file. It is of type EUIScalingRule, which is an enumeration of different scaling rules.

UIScaleRule interacts with other variables such as CustomScalingRuleClass, which is used when UIScaleRule is set to EUIScalingRule::Custom. It also indirectly affects the calculation of the UI scale factor in the CalculateScale function.

Developers must be aware that:

1. When set to EUIScalingRule::Custom, a valid CustomScalingRuleClass must be provided, or the system will fall back to a default behavior.
2. The choice of scaling rule can significantly impact the UI appearance across different devices and resolutions.
3. The SDesignerView in the UMG Editor uses this setting to display warnings and color-code the UI when custom scaling is used without a proper rule class.

Best practices when using this variable include:

1. Carefully consider the target platforms and typical display configurations when choosing a scaling rule.
2. If using a custom scaling rule, ensure that the CustomScalingRuleClass is properly set and implemented.
3. Test the UI on various screen sizes and resolutions to ensure the chosen scaling rule provides a consistent and usable interface.
4. Use the editor’s warnings and color-coding (in SDesignerView) to quickly identify and resolve issues with custom scaling rules.
5. Consider the performance implications of complex custom scaling rules, especially on lower-end devices.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1287, section: [/Script/Engine.UserInterfaceSettings]

• INI Section: /Script/Engine.UserInterfaceSettings
• Raw value: ShortestSide
• Is Array: False

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:238, section: [/Script/Engine.UserInterfaceSettings]

• INI Section: /Script/Engine.UserInterfaceSettings
• Raw value: ScaleToFit
• Is Array: False

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/UMGEditor/Private/Designer/SDesignerView.cpp:3189

Scope (from outer to inner):

file
function     FText SDesignerView::GetCurrentDPIScaleText

Source code excerpt:

	const UUserInterfaceSettings* UISettings = GetDefault<UUserInterfaceSettings>();
	if (UISettings->UIScaleRule == EUIScalingRule::Custom)
	{
		UClass* CustomScalingRuleClassInstance = UISettings->CustomScalingRuleClass.TryLoadClass<UDPICustomScalingRule>();

		if (CustomScalingRuleClassInstance == nullptr)
		{
			return LOCTEXT("NoCustomRuleWarning", "Warning: Using Custom DPI Rule with no rules class set. Set a class in User Interface Project Settings. ");

#Loc: <Workspace>/Engine/Source/Editor/UMGEditor/Private/Designer/SDesignerView.cpp:3206

Scope (from outer to inner):

file
function     FSlateColor SDesignerView::GetCurrentDPIScaleColor

Source code excerpt:

{
	const UUserInterfaceSettings* UISettings = GetDefault<UUserInterfaceSettings>();
	if (UISettings->UIScaleRule == EUIScalingRule::Custom)
	{
		UClass* CustomScalingRuleClassInstance = UISettings->CustomScalingRuleClass.TryLoadClass<UDPICustomScalingRule>();

		if (CustomScalingRuleClassInstance == nullptr)
		{
			return FSlateColor(FLinearColor::Yellow);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/UserInterfaceSettings.h:171

Scope (from outer to inner):

file
class        class UUserInterfaceSettings : public UDeveloperSettings

Source code excerpt:

	 */
	UPROPERTY(config, EditAnywhere, Category="DPI Scaling", meta=( DisplayName="DPI Scale Rule" ))
	EUIScalingRule UIScaleRule;

	/**
	 * Set DPI Scale Rule to Custom, and this class will be used instead of any of the built-in rules.
	 */
	UPROPERTY(config, EditAnywhere, Category="DPI Scaling", meta=( MetaClass="/Script/Engine.DPICustomScalingRule" ))
	FSoftClassPath CustomScalingRuleClass;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UserInterfaceSettings.cpp:111

Scope (from outer to inner):

file
function     float UUserInterfaceSettings::CalculateScale

Source code excerpt:

	bError = false;

	if (UIScaleRule == EUIScalingRule::Custom)
	{
		if (CustomScalingRuleClassInstance == nullptr)
		{
			CustomScalingRuleClassInstance = CustomScalingRuleClass.TryLoadClass<UDPICustomScalingRule>();

			if (CustomScalingRuleClassInstance == nullptr)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UserInterfaceSettings.cpp:136

Scope (from outer to inner):

file
function     float UUserInterfaceSettings::CalculateScale

Source code excerpt:

	{
		int32 EvalPoint = 0;
		switch (UIScaleRule)
		{
		case EUIScalingRule::ShortestSide:
			EvalPoint = FMath::Min(Size.X, Size.Y);
			break;
		case EUIScalingRule::LongestSide:
			EvalPoint = FMath::Max(Size.X, Size.Y);