SoftwareCursors

SoftwareCursors

#Overview

name: SoftwareCursors

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 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of SoftwareCursors is to manage and store custom software cursor designs for different mouse cursor types in Unreal Engine 5. It is part of the user interface system and allows developers to define custom cursor appearances for various interaction states.

This setting variable is primarily used by the Engine module, specifically within the user interface and viewport subsystems. It is referenced in the UUserInterfaceSettings class and utilized by the UGameViewportClient class.

The value of this variable is set in the UUserInterfaceSettings class, which inherits from UDeveloperSettings. It is defined as a TMap that associates EMouseCursor::Type enums with FSoftClassPath objects, allowing developers to specify custom UserWidget classes for different cursor types.

SoftwareCursors interacts with other deprecated variables such as DefaultCursor_DEPRECATED, TextEditBeamCursor_DEPRECATED, CrosshairsCursor_DEPRECATED, etc. These deprecated variables are used to populate the SoftwareCursors map for backward compatibility.

Developers should be aware that:

  1. This variable allows for customization of software cursors for different mouse states.
  2. It replaces the deprecated individual cursor variables from earlier engine versions.
  3. The custom cursor classes should inherit from UserWidget.

Best practices when using this variable include:

  1. Ensure that all necessary cursor types are defined in the SoftwareCursors map.
  2. Use appropriate UserWidget subclasses for each cursor type to maintain consistency and performance.
  3. Be mindful of the performance impact of software cursors, especially on lower-end devices.
  4. Consider using hardware cursors (HardwareCursors) for better performance when possible.
  5. Regularly update and maintain cursor designs to ensure they remain compatible with engine updates and project requirements.

#Setting Variables

#References In INI files

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

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
class        class UUserInterfaceSettings : public UDeveloperSettings

Source code excerpt:


	UPROPERTY(config, EditAnywhere, Category = "Software Cursors", meta = ( MetaClass = "/Script/UMG.UserWidget" ))
	TMap<TEnumAsByte<EMouseCursor::Type>, FSoftClassPath> SoftwareCursors;

	// DEPRECATED 4.16
	UPROPERTY(config)
	FSoftClassPath DefaultCursor_DEPRECATED;

	// DEPRECATED 4.16

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameViewportClient.cpp:559

Scope (from outer to inner):

file
function     void UGameViewportClient::Init

Source code excerpt:


	// Set all the software cursors.
	for ( auto& Entry : UISettings->SoftwareCursors )
	{
		SetSoftwareCursorFromClassPath(Entry.Key, Entry.Value);
	}

	// Set all the hardware cursors.
	for ( auto& Entry : UISettings->HardwareCursors )

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameViewportClient.cpp:575

Scope (from outer to inner):

file
function     void UGameViewportClient::RebuildCursors

Source code excerpt:

	UUserInterfaceSettings* UISettings = GetMutableDefault<UUserInterfaceSettings>(UUserInterfaceSettings::StaticClass());
	// Set all the software cursors.
	for (auto& Entry : UISettings->SoftwareCursors)
	{
		SetSoftwareCursorFromClassPath(Entry.Key, Entry.Value);
	}

	// Set all the hardware cursors.
	for (auto& Entry : UISettings->HardwareCursors)

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

Scope (from outer to inner):

file
function     void UUserInterfaceSettings::PostInitProperties

Source code excerpt:

	if ( !DefaultCursor_DEPRECATED.IsNull() )
	{
		SoftwareCursors.Add(EMouseCursor::Default, DefaultCursor_DEPRECATED);
		DefaultCursor_DEPRECATED.Reset();
	}

	if ( !TextEditBeamCursor_DEPRECATED.IsNull() )
	{
		SoftwareCursors.Add(EMouseCursor::TextEditBeam, TextEditBeamCursor_DEPRECATED);
		TextEditBeamCursor_DEPRECATED.Reset();
	}

	if ( !CrosshairsCursor_DEPRECATED.IsNull() )
	{
		SoftwareCursors.Add(EMouseCursor::Crosshairs, CrosshairsCursor_DEPRECATED);
		CrosshairsCursor_DEPRECATED.Reset();
	}

	if ( !HandCursor_DEPRECATED.IsNull() )
	{
		SoftwareCursors.Add(EMouseCursor::Hand, HandCursor_DEPRECATED);
		HandCursor_DEPRECATED.Reset();
	}

	if ( !GrabHandCursor_DEPRECATED.IsNull() )
	{
		SoftwareCursors.Add(EMouseCursor::GrabHand, GrabHandCursor_DEPRECATED);
		GrabHandCursor_DEPRECATED.Reset();
	}

	if ( !GrabHandClosedCursor_DEPRECATED.IsNull() )
	{
		SoftwareCursors.Add(EMouseCursor::GrabHandClosed, GrabHandClosedCursor_DEPRECATED);
		GrabHandClosedCursor_DEPRECATED.Reset();
	}

	if ( !SlashedCircleCursor_DEPRECATED.IsNull() )
	{
		SoftwareCursors.Add(EMouseCursor::SlashedCircle, SlashedCircleCursor_DEPRECATED);
		SlashedCircleCursor_DEPRECATED.Reset();
	}

	// Allow the assets to be replaced in the editor, but make sure they're part of the root set in cooked games
#if WITH_EDITOR
	if ( IsTemplate() == false )

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

Scope (from outer to inner):

file
function     void UUserInterfaceSettings::ForceLoadResources

Source code excerpt:


		TArray<UObject*> LoadedClasses;
		for ( auto& Entry : SoftwareCursors )
		{
			LoadedClasses.Add(Entry.Value.TryLoad());
		}

		for (int32 i = 0; i < LoadedClasses.Num(); ++i)
		{