🛠️ UI Processors

Short Description

Processors are the "brains" of the UI system, handling logic, theming, and signals for specific widget types.

Long Description

By moving logic into shared UGorgeousUIProcessor objects, the CommonUI Foundation keeps widget assets lightweight and focused purely on layout and aesthetics. This "Flyweight" approach ensures that 100 buttons in your UI share a single logic instance, reducing memory overhead and centralizing behavior updates.

🧠 The Processor Concept

A Processor is a C++ class that knows how to "talk" to a specific type of widget. For example, the UGorgeousProgressBarProcessor knows that to update a progress bar, it needs to call SetPercent.

Key Responsibilities

  • Signal Handling: Translates incoming Signal Bridge payloads into widget updates.
  • Theme Application: Maps theme properties (Colors, Fonts) to the correct widget slots.
  • Interpolation: Manages smooth transitions for colors and opacity over time.

🔍 Automatic Property Mapping

Processors use a powerful reflection-based resolution system to apply values to widgets without needing hard-coded pointers. When a value needs to be applied to a property named TargetValue, the system searches in this order:

  1. Direct Property: Looks for a UPROPERTY named exactly TargetValue.
  2. Setter Function: Looks for a UFUNCTION named SetTargetValue.
  3. Boolean Strip: If not found, it tries stripping a leading b (e.g., bIsActive -> IsActive) and repeats steps 1 and 2.

[!TIP] This allows the same processor to work with both standard Unreal widgets (which use functions like SetPercent) and custom widgets (which might expose raw properties).

🛡️ Style Property Allow List

To prevent the theming system from accidentally overwriting gameplay-critical properties, widgets can define an Allow List.

  • Enforcement: If UseStylePropertyAllowList returns true, only properties in the list will be updated by the theme system.
  • Safety: This ensures that a "Red" theme doesn't accidentally change a widget's "Visibility" or "IsEnabled" state unless explicitly intended.

📋 Standard Processors

The foundation includes several pre-built processors for common UI elements:

Processor Target Type Primary Logic
Button UButton, UCommonButton Hover/Click states, Icon swapping, Label colors.
Text UTextBlock, URichText Typography sets, dynamic color injection.
ProgressBar UProgressBar Percent interpolation, fill color theming.
Image UImage, ULazyImage Texture/Brush loading, platform-specific icons.
Carousel UCommonCarousel Index tracking, navigation animations.

🛠️ Creating a Custom Processor

If you create a unique widget type (e.g., a custom Inventory Slot), you can create a dedicated processor for it:

  1. Inherit: Create a class inheriting from UGorgeousUIProcessor.
  2. Define Target: Set TargetWidgetClass to your custom widget class.
  3. Override: Implement OnSignalReceived or ApplyThemeToWidget to handle custom behavior.
  4. Register: Add your processor to the Processor Classes map in the UGorgeousUIFoundationSubsystem configuration.

🔗 Related Documents