PreferredLandscapeOrientation

PreferredLandscapeOrientation

#Overview

name: PreferredLandscapeOrientation

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 3 C++ source files. Also referenced in 2 C# build files meaning it may affect the build system logic.

#Summary

#Usage in the C++ source code

The purpose of PreferredLandscapeOrientation is to specify the initial orientation of the application when it launches on iOS devices, specifically when both landscape left and landscape right orientations are supported.

This setting variable is primarily used by the iOS platform-specific subsystem of Unreal Engine 5. It is referenced in the IOSPlatformEditor and IOSRuntimeSettings modules, which are responsible for iOS-specific configurations and runtime behavior.

The value of this variable is set in the project settings, specifically under the iOS Runtime Settings. It is defined as a property in the UIOSRuntimeSettings class, which suggests it can be modified through the Unreal Engine editor interface.

PreferredLandscapeOrientation interacts with other orientation-related variables, such as bSupportsLandscapeLeftOrientation and bSupportsLandscapeRightOrientation. These variables work together to determine the supported orientations for the iOS application.

Developers must be aware that this variable only takes effect when both landscape left and landscape right orientations are supported. If only one landscape orientation is supported, this setting will have no impact.

Best practices when using this variable include:

  1. Ensure that both landscape orientations are supported if you want this setting to take effect.
  2. Consider the user experience and the nature of your application when choosing the preferred orientation.
  3. Test the application thoroughly in both landscape orientations to ensure smooth transitions and proper UI layout.
  4. Be aware that this setting only affects the initial orientation at launch, and the device may still rotate based on user interaction and system settings.
  5. Coordinate this setting with your application’s UI design to provide the best possible user experience from the moment the app launches.

#Setting Variables

#References In INI files

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

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/IOS/IOSPlatformEditor/Private/IOSTargetSettingsCustomization.cpp:804

Scope: file

Source code excerpt:

	SETUP_PLIST_PROP(bSupportsLandscapeLeftOrientation, OrientationCategory);
	SETUP_PLIST_PROP(bSupportsLandscapeRightOrientation, OrientationCategory);
	SETUP_PLIST_PROP(PreferredLandscapeOrientation, OrientationCategory);
	
	SETUP_PLIST_PROP(bSupportsITunesFileSharing, FileSystemCategory);
	SETUP_PLIST_PROP(bSupportsFilesApp, FileSystemCategory);
	
	SETUP_PLIST_PROP(bSupportsMetal, RenderCategory);

#Loc: <Workspace>/Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSView.cpp:1100

Scope: file

Source code excerpt:

- (UIInterfaceOrientation)preferredInterfaceOrientationForPresentation
{
	FString PreferredLandscapeOrientation = "";
	bool bSupportsLandscapeLeft = false;
	bool bSupportsLandscapeRight = false;

	GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("bSupportsLandscapeLeftOrientation"), bSupportsLandscapeLeft, GEngineIni);
	GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("bSupportsLandscapeRightOrientation"), bSupportsLandscapeRight, GEngineIni);
	GConfig->GetString(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("PreferredLandscapeOrientation"), PreferredLandscapeOrientation, GEngineIni);

	if(bSupportsLandscapeLeft && bSupportsLandscapeRight)
	{
		if (PreferredLandscapeOrientation.Equals("LandscapeRight"))
		{
			return UIInterfaceOrientationLandscapeRight;
		}
		return UIInterfaceOrientationLandscapeLeft;
	}

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Classes/IOSRuntimeSettings.h:388

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

	// The Preferred Orientation will be used as the initial orientation at launch when both Landscape Left and Landscape Right orientations are to be supported.
	UPROPERTY(GlobalConfig, EditAnywhere, Category = DeviceOrientations, meta = (DisplayName = "Preferred Landscape Orientation"))
	EIOSLandscapeOrientation PreferredLandscapeOrientation;

	// Specifies the the display name for the application. This will be displayed under the icon on the device.
	UPROPERTY(GlobalConfig, EditAnywhere, Category = BundleInformation)
	FString BundleDisplayName;

	// Specifies the the name of the application bundle. This is the short name for the application bundle.

#References in C# build files

This variable is referenced in the following C# build files:

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/UEDeployIOS.cs:558

			string InterfaceOrientation = "";
			string PreferredLandscapeOrientation = "";
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "PreferredLandscapeOrientation", out PreferredLandscapeOrientation);

			string SupportedOrientations = "";
			bool bSupported = true;
			Ini.GetBool("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "bSupportsPortraitOrientation", out bSupported);
			SupportedOrientations += bSupported ? "\t\t<string>UIInterfaceOrientationPortrait</string>\n" : "";
			bool bSupportsPortrait = bSupported;

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/UEDeployIOS.cs:225

			string InterfaceOrientation = "";
			string PreferredLandscapeOrientation = "";
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "PreferredLandscapeOrientation", out PreferredLandscapeOrientation);

			string SupportedOrientations = "";
			bool bSupported = true;
			Ini.GetBool("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "bSupportsPortraitOrientation", out bSupported);
			SupportedOrientations += bSupported ? "\t\t<string>UIInterfaceOrientationPortrait</string>\n" : "";
			bool bSupportsPortrait = bSupported;