HardwareCursors

HardwareCursors

#Overview

name: HardwareCursors

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

#Summary

#Usage in the C++ source code

The purpose of HardwareCursors is to manage and store hardware cursor mappings for different mouse cursor types in Unreal Engine 5. It is primarily used for the user interface and input handling system.

This setting variable is relied upon by the Engine module, specifically within the GameViewportClient class. It is used to manage hardware cursor shapes for different cursor types.

The value of this variable is set in multiple places:

  1. In the UserInterfaceSettings class, where it’s defined as a config property.
  2. In the GameViewportClient::Init and GameViewportClient::RebuildCursors functions, where it’s populated from the UISettings.
  3. In the GameViewportClient::SetHardwareCursor function, where individual cursor shapes can be added or updated.

HardwareCursors interacts with other variables and systems:

  1. It works alongside the CursorWidgets and bUseSoftwareCursorWidgets variables for cursor management.
  2. It interacts with the PlatformCursor system to set cursor shapes.

Developers should be aware of the following when using this variable:

  1. It’s a map that associates EMouseCursor::Type with hardware cursor data.
  2. Changes to this variable affect the appearance of the mouse cursor in the game.
  3. It’s used in conjunction with the UserInterfaceSettings to initialize cursor shapes.

Best practices when using this variable include:

  1. Use the SetHardwareCursor function to modify cursor shapes at runtime.
  2. Ensure that cursor assets are properly set up in the UserInterfaceSettings.
  3. Be mindful of performance implications when frequently changing cursor shapes.
  4. Consider the interaction between hardware cursors and software cursor widgets when designing the UI system.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:235, 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/GameViewportClient.h:1008

Scope (from outer to inner):

file
class        class UGameViewportClient : public UScriptViewportClient, public FExec

Source code excerpt:


	/** Hardware cursor mapping for default cursor shapes. */
	TMap<EMouseCursor::Type, void*> HardwareCursors;

	/** Map of Software Cursor Widgets*/
	TMap<EMouseCursor::Type, TSharedPtr<SWidget>> CursorWidgets;

	/** Controls if the Map of Software Cursor Widgets is used */
	bool bUseSoftwareCursorWidgets;

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

Scope (from outer to inner):

file
class        class UUserInterfaceSettings : public UDeveloperSettings

Source code excerpt:


	UPROPERTY(config, EditAnywhere, Category = "Hardware Cursors")
	TMap<TEnumAsByte<EMouseCursor::Type>, FHardwareCursorReference> HardwareCursors;

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

	// DEPRECATED 4.16
	UPROPERTY(config)

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

Scope (from outer to inner):

file
function     void UGameViewportClient::Init

Source code excerpt:


	// Set all the hardware cursors.
	for ( auto& Entry : UISettings->HardwareCursors )
	{
		SetHardwareCursor(Entry.Key, Entry.Value.CursorPath, Entry.Value.HotSpot);
	}
}

void UGameViewportClient::RebuildCursors()

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

Scope (from outer to inner):

file
function     void UGameViewportClient::RebuildCursors

Source code excerpt:


	// Set all the hardware cursors.
	for (auto& Entry : UISettings->HardwareCursors)
	{
		SetHardwareCursor(Entry.Key, Entry.Value.CursorPath, Entry.Value.HotSpot);
	}
}

UWorld* UGameViewportClient::GetWorld() const

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

Scope (from outer to inner):

file
function     void UGameViewportClient::MouseEnter

Source code excerpt:

	if ( ICursor* Cursor = PlatformCursor.Get() )
	{
		for ( auto& Entry : HardwareCursors )
		{
			Cursor->SetTypeShape(Entry.Key, Entry.Value);
		}
	}

	bIsMouseOverClient = true;

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

Scope (from outer to inner):

file
function     void UGameViewportClient::ResetHardwareCursorStates

Source code excerpt:

	if (ICursor* Cursor = PlatformCursor.Get())
	{
		for (auto& Entry : HardwareCursors)
		{
			Cursor->SetTypeShape(Entry.Key, nullptr);
		}
	}
}

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

Scope (from outer to inner):

file
function     bool UGameViewportClient::SetHardwareCursor

Source code excerpt:

	}

	HardwareCursors.Add(CursorShape, HardwareCursor);

	if ( bIsMouseOverClient )
	{
		PlatformCursor->SetTypeShape(CursorShape, HardwareCursor);
	}