Luna UI Documentation

The UIView is the base class responsible for managing the lifecycle and visibility of an UI Element. It provides control over UI visibility states, fade animations, and allows for custom actions during these transitions.

Constructor

csharp

public UIView(
  GameObject parent,
  VisualElement parentElement,
  VisualElement focusElement = null,
  float fadeDuration = 0.5f,
  EasingMode easingMode = EasingMode.EaseOutCirc,
  bool disableOtherViewsOnFadeIn = false,
  bool debug = false
)

Name	Type	Description
parent	GameObject	Parent GameObject used to control lifecycle of the UIView.
parentElement	VisualElement	The VisualElement that serves as the parent for this UIView.
focusElement	VisualElement	The VisualElement to focus whenever the UIView becomes visible. When `null`, no element is focused on fade-in. (UIViewComponent passes the view root when its Focus Name field is empty — the fallback happens there, not in UIView.)
fadeDuration	float	Specifies the duration of the fade transition, in seconds.
easingMode	EasingMode	Defines the easing effect applied during fade transitions.
disableOtherViewsOnFadeIn	bool	Blocks input on the elements of other views whenever this view becomes visible. This is particularly useful for UI navigation with keys when opening a modal or screen on top of another view. This will prevent the auto navigation from interacting with the elements behind this view. See Input blocking.
debug	bool	Logs fade transitions, enable/disable events, and UI Actions.

There is no start-visibility parameter. The view's born state is applied separately with ApplyStartVisibility — UIViewComponent calls it right after construction (visible for node-less views; the node's StartVisible for navigation destinations).

Public Properties

Name	Type	Description
Parent	GameObject	Parent GameObject used to control lifecycle of the UIView.
ParentElement	VisualElement	The VisualElement that serves as the parent for this UIView.
LunaUIManager	LunaUIManager	LunaUIManager tracks interactable visual elements, enabling mass activation or deactivation within a UIView. You can also set a blocking element to prevent interaction with other elements until it is clicked.
Fade	FadeUIElement	Manage fade transitions of the UIView.
IsVisible	bool	Returns `true` if the UIView is currently visible (faded in).
FocusElement	VisualElement	Element that receives keyboard focus when this view fades in. Read-only — set at construction; `null` (no focus) when none was given. UIViewComponent passes the view root for an empty Focus Name.
PushArgs	object	Per-push args set by the navigation system right before fade-in. `null` when the view was activated without args. See Push args.
DisableOtherViewsOnFadeIn	bool	Blocks input on the elements of other views whenever this view becomes visible. This is particularly useful for UI navigation with keys when opening a modal or screen on top of another view. This will prevent the auto navigation from interacting with the elements behind this view. See Input blocking.

Input blocking

When DisableOtherViewsOnFadeIn is set, fading this view in calls LunaUIManager.SetInputBlockedAllPages with every other registered page. Blocked elements get pickingMode = Ignore and focusable = false — they ignore pointer events and are skipped by keyboard navigation, but their visual styling is untouched. Unlike SetEnabled(false), no :disabled USS rules fire, so nothing behind a modal visibly greys out during the fade. Each element's original pickingMode is snapshotted at block time and restored exactly when this view fades out.

Public Methods

ApplyStartVisibility

Apply the configured born-state visibility. Call once, right after construction (UIViewComponent does this at the first PanelRenderer reload).

csharp

public void ApplyStartVisibility(bool startVisible)

This is a pure snap — no animations, no FadeEventTrigger transitions fire. true snaps to opacity: 1 / display: flex and fires the enable lifecycle; false snaps to opacity: 0 / display: none and fires the disable lifecycle. Subsequent visibility changes go through Fade.FadeIn / Fade.FadeOut (or the component wrappers Show / Hide); this method is not re-entrant.

SetVisualState

Instant style write — sets opacity and display to the visible or hidden steady-state without going through the fade transition pipeline.

csharp

public void SetVisualState(bool visible)

AddAction

Adds a new action to the view's action list.

If the view is currently faded in, the action's OnFadeInStart method will be triggered immediately.

The action will be automatically enabled or disabled in sync with the view's fade-in or fade-out state.

csharp

public void AddAction(IUIViewAction action, bool activate = true)

Name	Type	Description
action	IUIViewAction	Action to add to the UIView.
activate	bool	Activates the Action immediately if the UIView is currently enabled. If the UIView is not enabled, the Action is not triggered even if this is true.

Example

csharp

myUIView.AddAction(new UIViewActionEscape(ReturnToPreviousScreen));

Learn more at UI Actions.

See Example: Multi Page UI which demonstrates usage of UIViewActionEscape.

AddChild

csharp

public void AddChild(UIView child)

When you have nested UIViews with UI Actions, you might need to register their parent-child relationships.

Whenever a parent UIView is enabled or disabled, it will trigger the UI Actions of its children.

The Example: Multi Page UI also demonstrates parent-child relationships.

SetParentElement

Swap the cached parent VisualElement when the panel delivers a fresh tree — driven by UIViewComponent on subsequent PanelRenderer reloads (property changes, re-enables). Propagates the new reference to the FadeUIElement so subsequent FadeIn/FadeOut and transition lookups resolve against the live panel. No-op when the element is unchanged.

csharp

public void SetParentElement(VisualElement parentElement)

ClearTransitions

Removes all transition entries from the UIView. In-flight plays are not cancelled.

csharp

public void ClearTransitions()

Push args

When a view is opened through navigation, the nav system hands it a per-push args object immediately before fade-in:

csharp

public object PushArgs { get; }              // null when no args were set
public T GetArgs<T>() where T : class        // typed read; null on mismatch
public void SetPushArgs(object args)         // called by nav; re-push overwrites stale args

SetPushArgs may also legitimately be called by storybook/test code that wants to seed a scene-active view without going through the nav stack — call it before the view's first fade-in so OnFadeInStart handlers read the right value.

State reset

csharp

public event Action<object> StateResetRequested;
public void RequestStateReset(object args);

StateResetRequested fires when this view should clear and re-seed its internal state — typically before a reopen for views whose nav destination authors ResetStateOnReopen = true. The argument is the args object being passed for this push. RequestStateReset invokes the event; the nav system calls it on reopen. UIViewComponent subscribes automatically and dispatches to its OnStateReset(object args) virtual, which is the consumer extension point.

Fade-in semantics

Fade.FadeIn() fires OnFadeInStart on the first call of a visible session even when the element is already at full opacity — the born-visible reveal case, where ApplyStartVisibility(true) snapped the view visible during boot and the first real fade-in still needs to run authored transitions and enable UI Actions. A second FadeIn() on the same still-visible element no-ops instead of re-running every transition. The guard resets when the element completes a fade-out.

Lifecycle Management

UIView implements IDisposable and manages its lifecycle through automatic registration with the global registry.

Automatic Registration

When a UIView is constructed, it automatically registers itself with the global registry managed by LunaUIManager. This allows the system to track all UIViews in the scene and apply global USS classes to them when needed.

Automatic Unregistration

Unregistration happens automatically when the parent GameObject is destroyed via UIViewReference.OnDestroy(). You typically don't need to manually unregister UIViews.

Manual Disposal

If you need to manually dispose of a UIView (e.g., when it doesn't have a GameObject lifecycle), you can call Dispose():

csharp

myUIView.Dispose();

This unsubscribes the fade event handlers, stops any in-flight fade, releases the page registration (restoring any input-block this view held on other views), and unregisters from the global registry. UIViewComponent calls it from its OnDestroy.

Transition Animations

UIViews can automatically play Transition Animations when fading in or out. This enables rich entrance/exit animations without manual event wiring.

FadeEventTrigger

The FadeEventTrigger enum defines when an animation should play:

Value	Description
`None`	No automatic trigger
`FadeInStart`	When fade-in begins
`FadeInComplete`	When fade-in finishes
`FadeOutStart`	When fade-out begins
`FadeOutComplete`	When fade-out finishes

Adding Transitions

Use AddTransition() to register animations. Entries with no Animation or no Target are rejected (they would be silent no-ops):

csharp

// Add a single transition — target the modal-content child by name.
myUIView.AddTransition(new UIViewTransitionEntry
{
    Animation = popBounceInAsset,      // TransitionSequenceAsset
    Trigger = FadeEventTrigger.FadeInStart,
    Target = new ElementSelector { Name = "modal-content" }
});

// Add multiple transitions at once — the default Target is the view root.
myUIView.AddTransitions(new[]
{
    new UIViewTransitionEntry
    {
        Animation = fadeInAsset,
        Trigger = FadeEventTrigger.FadeInStart
    },
    new UIViewTransitionEntry
    {
        Animation = slideOutAsset,
        Trigger = FadeEventTrigger.FadeOutStart
    }
});

UIViewTransitionEntry

Property	Type	Description
Animation	TransitionSequenceAsset	The animation preset to play on each matched element
Target	ElementSelector	Which element(s) to play on. Default = the UIView's parent element. See ElementSelector below
Trigger	FadeEventTrigger	Which fade event triggers the animation
StepMs	long	Delay between successive matches in milliseconds. `0` = simultaneous. Non-zero gives the DOM-order stagger pass

ElementSelector

ElementSelector resolves elements in two steps: Name/ClassName (AND-ed; empty = no constraint) pick anchor element(s) under the view root; ScopeValue says what to return relative to each anchor; ElementTypeValue then filters the returned set to that UITK type (Any = no constraint):

ScopeValue	Returns
`Self` (default)	The anchor element itself. With no filters set, that's the view root
`Children`	The anchor's direct children (the CSS `X > *` pattern)
`Descendants`	Every descendant of the anchor (the CSS `X *` pattern)

Common shapes:

csharp

new ElementSelector()                                   // the view root
new ElementSelector { Name = "content-panel" }          // the element named content-panel
new ElementSelector { ClassName = "stagger" }           // every element tagged .stagger
new ElementSelector { Name = "list",                    // direct children of #list
    ScopeValue = ElementSelector.Scope.Children }

Pairing a ClassName selector with a non-zero StepMs gives the canonical DOM-order entry bounce.

csharp

public class ModalView : UIView
{
    public ModalView(GameObject parent, VisualElement root, TransitionSequenceAsset popIn)
        : base(parent, root)
    {
        // Play bounce animation on the content panel when modal fades in
        AddTransition(new UIViewTransitionEntry
        {
            Animation = popIn,
            Trigger = FadeEventTrigger.FadeInStart,
            Target = new ElementSelector { Name = "content-panel" }
        });
    }
}

Using TransitionAnimator Component

For Inspector-based setup, you can use the TransitionAnimator component with a UIViewComponent reference:

Add TransitionAnimator to the same GameObject
Reference the UIViewComponent
Set Fade Trigger to the desired event
Add your animation nodes

The TransitionAnimator will automatically subscribe to the UIView's fade events.

UIView

Constructor

Public Properties

Input blocking

Public Methods

ApplyStartVisibility

SetVisualState

AddAction

Example

AddChild

SetParentElement

ClearTransitions

Push args

State reset

Fade-in semantics

Lifecycle Management

Automatic Registration

Automatic Unregistration

Manual Disposal

Transition Animations

FadeEventTrigger

Adding Transitions

UIViewTransitionEntry

ElementSelector

Example: Modal with Entrance Animation

Using TransitionAnimator Component