CustomScalingRuleClass

CustomScalingRuleClass

#Overview

name: CustomScalingRuleClass

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 CustomScalingRuleClass is to define a custom scaling rule for the user interface in Unreal Engine 5. It allows developers to implement their own logic for scaling UI elements based on different screen resolutions and DPI settings.

This setting variable is primarily used by the User Interface subsystem of Unreal Engine. It is referenced in the UMGEditor module for displaying current DPI scale information in the designer view, and in the Engine module for calculating and applying the custom 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 stored as an FSoftClassPath, which allows for lazy loading of the class.

CustomScalingRuleClass interacts with other variables such as UIScaleRule (which must be set to EUIScalingRule::Custom for this variable to take effect) and CustomScalingRule (which is an instance of the class specified by CustomScalingRuleClass).

Developers must be aware that:

  1. If CustomScalingRuleClass is set but the class cannot be loaded, it will result in a warning message and potentially incorrect UI scaling.
  2. Changes to this variable trigger a reset of the CustomScalingRuleClassInstance and CustomScalingRule, requiring them to be reloaded.
  3. The specified class must inherit from UDPICustomScalingRule to be valid.

Best practices when using this variable include:

  1. Ensure the custom scaling rule class is properly implemented and inherits from UDPICustomScalingRule.
  2. Test the custom scaling across various resolutions and DPI settings to ensure it behaves as expected.
  3. Use this in conjunction with the UIScaleRule set to EUIScalingRule::Custom.
  4. Be mindful of performance implications, as the custom scaling rule will be called frequently to calculate UI scales.
  5. Provide fallback behavior in case the custom rule class fails to load.

#Setting Variables

#References In INI files

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

#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:3191

Scope (from outer to inner):

file
function     FText SDesignerView::GetCurrentDPIScaleText

Source code excerpt:

	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:3208

Scope (from outer to inner):

file
function     FSlateColor SDesignerView::GetCurrentDPIScaleColor

Source code excerpt:

	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:177

Scope (from outer to inner):

file
class        class UUserInterfaceSettings : public UDeveloperSettings

Source code excerpt:

	 */
	UPROPERTY(config, EditAnywhere, Category="DPI Scaling", meta=( MetaClass="/Script/Engine.DPICustomScalingRule" ))
	FSoftClassPath CustomScalingRuleClass;

	/**
	 * Controls how the UI is scaled at different resolutions based on the DPI Scale Rule
	 */
	UPROPERTY(config, EditAnywhere, Category="DPI Scaling", meta=(
		DisplayName="DPI Curve",

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

Scope (from outer to inner):

file
function     float UUserInterfaceSettings::CalculateScale

Source code excerpt:

		if (CustomScalingRuleClassInstance == nullptr)
		{
			CustomScalingRuleClassInstance = CustomScalingRuleClass.TryLoadClass<UDPICustomScalingRule>();

			if (CustomScalingRuleClassInstance == nullptr)
			{
				FMessageLog("MapCheck").Error()
					->AddToken(FTextToken::Create(FText::Format(LOCTEXT("CustomScalingRule_NotFound", "Project Settings - User Interface Custom Scaling Rule '{0}' could not be found."), FText::FromString(CustomScalingRuleClass.ToString()))));
				bError = true;
				return 1;
			}
		}

		if (CustomScalingRule == nullptr)

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

Scope (from outer to inner):

file
function     void UUserInterfaceSettings::PostEditChangeProperty

Source code excerpt:

	const FName MemberPropertyName = (PropertyChangedEvent.MemberProperty != nullptr) ? PropertyChangedEvent.MemberProperty->GetFName() : NAME_None;

	if (MemberPropertyName == GET_MEMBER_NAME_CHECKED(UUserInterfaceSettings, CustomScalingRuleClass))
	{
		CustomScalingRuleClassInstance = nullptr;
		CustomScalingRule = nullptr;
	}

	LastViewportSize.Reset();

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

Scope (from outer to inner):

file
function     void UUserInterfaceSettings::ForceLoadResources

Source code excerpt:

		}

		CustomScalingRuleClassInstance = CustomScalingRuleClass.TryLoadClass<UDPICustomScalingRule>();
	}
}

#undef LOCTEXT_NAMESPACE