You are viewing documentation for v1.1. Switch to current version โ†’

๐ŸŽจ Dynamic Theming

Short Description

The Dynamic Theming system provides a centralized way to manage and swap visual styles (colors, fonts, icons, sounds) at runtime.

Long Description

Gorgeous UI themes are defined using UGorgeousUITheme_DA, which leverages Instanced Structs to allow any property type (e.g., FLinearColor, FSlateBrush, FProgressBarStyle) to be stored in a single properties map. Widgets register with the UGorgeousUIFoundationSubsystem to receive theme updates. This enables instant "skinning" of the entire UI, support for seasonal themes, and platform-specific icon swapping without modifying individual widget assets.

๐Ÿš€ Features

  • Any-Type Properties: Store colors, floats, brushes, and custom structs in a single StyleProperties map.
  • Platform-Aware Icons: Automatically switch button prompts (Xbox vs. PlayStation vs. Keyboard) based on the current input method.
  • Themed Audio: Centralize UI sound effects (Click, Hover, Open) in a tag-indexed SoundMap.
  • Typography Sets: Manage complex font settings (Typeface, Size, Outline, Shadow) as single themed assets.
  • Runtime Swapping: Apply new themes instantly across all registered widgets using SetCurrentTheme.

๐Ÿ“š Usage Examples

Create a Gorgeous UI Theme Data Asset. Add an entry to Style Properties with the key PrimaryColor and the type Linear Color. Set it to a vibrant blue.

// Getting a color from the current theme
FLinearColor MyColor = GetCurrentTheme()->GetColor("PrimaryColor");

GetColor

Retrieves a FLinearColor property from the theme by its name.

Parameter Name Type Description
PropertyName FName The name of the property in the StyleProperties map.
DefaultValue FLinearColor Value to return if the property is missing or not a color.

GetFloat

Retrieves a numerical float property from the theme. Useful for margins, thicknesses, or opacity levels.

Parameter Name Type Description
PropertyName FName The name of the property.
DefaultValue float Fallback value.

GetBrush

Retrieves an FSlateBrush (image/texture) property. Used for backgrounds, borders, and custom widget shapes.

Parameter Name Type Description
PropertyName FName The name of the property.

GetActionIcon

Resolves an icon for a specific input action based on the requested platform. Handles fallbacks (e.g., falling back to "Generic" if "PlayStation" icons are missing).

Parameter Name Type Description
ActionTag FGameplayTag The action tag (e.g., UI.Action.Confirm).
PlatformName FName The target platform (e.g., Xbox).

GetThemedSound

Retrieves a themed USoundBase for a given tag.

Parameter Name Type Description
SoundTag FGameplayTag The sound tag (e.g., UI.Sound.Click).

GetTypography

Retrieves a full typography configuration (font, size, etc.) by its tag.

Parameter Name Type Description
Tag FGameplayTag The tag identifying the typography style.

GetProgressBarStyle

Retrieves a complex FProgressBarStyle for themed progress bars.

Parameter Name Type Description
PropertyName FName The name of the property.

Best Practices

  • Naming Conventions: Use a consistent naming scheme for your properties (e.g., Color.Text.Primary, Margin.Small).
  • Generic Fallbacks: Always provide a "Generic" or "Keyboard" icon in your ActionIcons to ensure some visual prompt is always visible.
  • Centralized Audio: Play sounds via GetThemedSound rather than hardcoding audio assets in widgets to allow audio redesigns via theme swaps.

Troubleshooting

  • Properties Not Resolving: Double check that the property name in your code matches the key in the StyleProperties map exactly (keys are case-sensitive FName).
  • Cast Failed: If GetColor returns the default value even though the key exists, ensure the type in the FInstancedStruct is actually Linear Color.

?? Related Documents