Class UnityUiInputComponent

Unity UI input component that provides text editing functionality with cancel and submit capabilities.
Manages input field editing states, character limits, and validation while integrating with the Serenity UI system.
Implements IUiEditable and IUiCancellable interfaces for comprehensive text input management.

CORE RULE: Selection Before Edit

  • Text editing is ONLY allowed when this component is the currently selected option in the foundation.
  • Unity's TMP_InputField allows editing on any pointer click, even if the component isn't selected.
  • This creates an invalid state where typing is possible while navigation continues elsewhere.
  • We enforce selection-before-edit by intercepting pointer events (IPointerDownHandler).

    Click-to-submit behavior:
  • Implements IPointerDownHandler to intercept clicks BEFORE TMP_InputField can process them.
  • On click, checks if this component is the selected option (_wantsHighlightVisible).
  • If not selected: forces selection through the foundation, then triggers Submit/Activate.
  • If already selected: allows the click to propagate to TMP_InputField for editing.
  • Implements ISelectHandler as backup for controller/keyboard selection.

    PREFAB INTEGRATION NOTE:
    This component handles ALL pointer events via code. The prefab's EventTrigger component
    (if present) is automatically cleared to prevent conflicts. Specifically:
  • Pointer Enter → SetFocus: REMOVED (conflicts with keyboard/gamepad navigation)
  • Pointer Down → SetFocus/Submit: REMOVED (handled by IPointerDownHandler)
    TMP_InputField callbacks (OnSelect, OnDeselect) should NOT be wired to Submit/Cancel
    in the prefab; this is handled via code subscriptions (onSelect, onEndEdit listeners).
Inheritance
object
UnityUiComponent
UnityUiInteractableComponent
UnityUiInputComponent
Implements
ISelectHandler
IEventSystemHandler
IPointerDownHandler
IPointerEnterHandler
Inherited Members
Namespace: Serenity.Ui.Infrastructure.Components
Assembly: Serenity.UnityUi.Infrastructure.dll
Syntax
public class UnityUiInputComponent : UnityUiInteractableComponent, IUiInteractable, IUiComponent, IUiEditable, IUiSubmittable, IComponent, IFoundationSettings, IUiCancellable, ISelectHandler, IEventSystemHandler, IPointerDownHandler, IPointerEnterHandler

Constructors

UnityUiInputComponent()

Initializes a new Unity UI input component with input interaction type configuration.
Sets up the component for text input operations within the UI system.

Declaration
public UnityUiInputComponent()

Fields

_inputField

Declaration
protected TMP_InputField _inputField
Field Value
Type Description
TMP_InputField

_isEditing

Declaration
protected bool _isEditing
Field Value
Type Description
bool

Properties

CancellableActions

Gets or sets the cancellable actions interface for input field cancellation handling.
Manages callbacks for cancel operations during text editing.

Declaration
public IUiCancellableActions CancellableActions { get; set; }
Property Value
Type Description
IUiCancellableActions

The cancellable actions interface

EditableActions

Gets or sets the editable actions interface for input field event handling.
Manages callbacks for text editing events like start/end editing and value changes.

Declaration
public IUiEditableActions EditableActions { get; set; }
Property Value
Type Description
IUiEditableActions

The editable actions interface

EditableParameters

Gets or sets the editable parameters interface for input field configuration.
Provides access to value, character limits, and other text input specific settings.

Declaration
public IUiEditableParameters EditableParameters { get; set; }
Property Value
Type Description
IUiEditableParameters

The editable parameters interface

SubmittableActions

Gets or sets the submittable actions interface for input field submission handling.
Manages callbacks for submit operations when confirming text input.

Declaration
public IUiSubmittableActions SubmittableActions { get; set; }
Property Value
Type Description
IUiSubmittableActions

The submittable actions interface

Methods

Blur()

Overrides blur behavior to respect editing state.
Prevents losing focus while in editing mode to maintain input functionality.
Calls base blur when not editing for normal focus management.

Declaration
public override void Blur()
Overrides

Cancel()

Handles cancel operations for the input field with context-aware behavior.
If editing, reverts changes and ends editing mode; otherwise triggers cancel callbacks.
Provides user-friendly cancellation functionality for text input operations.

Declaration
public override void Cancel()
Overrides

EndEdition()

Ends text editing mode for the input field.
Deactivates the input field and triggers editing end callbacks.
Updates internal editing state to restore normal navigation behavior.

NOTE: This method is idempotent - safe to call multiple times.
OnInputFieldEndEdit callback may also end editing, so we guard against double-call.

Declaration
public virtual void EndEdition()

Focus()

Overrides focus behavior to respect editing state and prevent recursive calls.
Prevents gaining focus while in editing mode to maintain input focus.
Uses _isFocusing flag to prevent recursive Focus() calls from SetFocus(true) → Focus() → OnFocus → SetFocus(true) chain.

Declaration
public override void Focus()
Overrides

OnDestroy()

Unity lifecycle method called when the component is destroyed.
Ensures mouse interaction lock is released.

Declaration
public override void OnDestroy()

OnDisable()

Unity lifecycle method called when the component is disabled.
Unsubscribes from TMP_InputField callbacks and resets all interaction state.
Stops any pending deferred submit coroutines.

Declaration
public override void OnDisable()
Overrides

OnEnable()

Unity lifecycle method called when the component is enabled.
Initializes the TMP_InputField reference, mouse interaction lock service, subscribes to callbacks,
and clears any EventTrigger entries to prevent conflicts with code-driven event handling.

Declaration
public override void OnEnable()
Overrides

OnPointerDown(PointerEventData)

Intercepts pointer down events BEFORE TMP_InputField can process them.
This is critical for enforcing selection-before-edit rule.

WHY THIS IS NEEDED:
Unity's TMP_InputField will activate editing on any pointer click, even if the component
isn't the currently selected option in the foundation. This creates an invalid state where:

  • User can type text while navigation continues elsewhere
  • Pointer lock is not acquired
  • Foundation doesn't know editing is happening

    THE FIX:
    By implementing IPointerDownHandler, we intercept the click before TMP_InputField sees it.
    If this component isn't selected:
  1. Set _pendingSelectionForEdit = true (blocks TMP editing in OnInputFieldSelect)
  2. Force selection via Focus()
  3. DEFER submit to next frame (guarantees selection completes before editing starts)

    SELECTION MECHANISM:
  • Focus() invokes InteractableActions.OnFocus which is mapped to the menu's OnComponentSelect
  • OnComponentSelect calls view.ExecuteSelectOption(component.GetIndex())
  • This updates the foundation's selected option index and sets _wantsHighlightVisible

    RACE CONDITION PREVENTION:
  • TMP_InputField may try to start editing in the same frame as OnPointerDown
  • OnInputFieldSelect callback checks _pendingSelectionForEdit and blocks editing if set
  • Deferring submit to next frame ensures selection is fully applied before editing starts
Declaration
public void OnPointerDown(PointerEventData eventData)
Parameters
Type Name Description
PointerEventData eventData

Pointer event data from Unity's event system.

OnPointerEnter(PointerEventData)

Implements IPointerEnterHandler to intercept pointer enter events.
This method intentionally does NOTHING for input components.

WHY THIS IS NEEDED:
Legacy prefabs may have EventTrigger with "Pointer Enter → SetFocus(true)".
While we clear EventTrigger entries in OnEnable, implementing IPointerEnterHandler
provides an additional layer of protection:

  1. Intercepts the event before any remaining EventTrigger entries can process it
  2. Prevents accidental re-wiring of EventTrigger from causing focus conflicts

    THE PROBLEM WITH POINTER ENTER → SETFOCUS:
  • User navigates to a different option using keyboard/gamepad
  • Mouse is still hovering over this input (PointerEnter already fired)
  • Any mouse movement re-triggers PointerEnter
  • SetFocus(true) is called, overriding the keyboard/gamepad selection
  • Result: Two options appear "selected" (navigation + mouse hover)

    By implementing this interface and doing nothing, we prevent hover from
    interfering with navigation-based selection. Selection happens only via:
  • Keyboard/gamepad navigation (foundation's selection system)
  • Mouse click (OnPointerDown → Focus() → select then submit)
Declaration
public void OnPointerEnter(PointerEventData eventData)
Parameters
Type Name Description
PointerEventData eventData

Pointer event data (unused).

OnSelect(BaseEventData)

Implements ISelectHandler to catch selection events from Unity's EventSystem.
This fires when the component's Selectable (Button) gains selection via keyboard/controller.
Used to trigger Submit when navigating to this option and pressing submit.

Declaration
public void OnSelect(BaseEventData eventData)
Parameters
Type Name Description
BaseEventData eventData

Base event data from the selection.

SelectNextComponent()

Overrides next component selection to respect editing state.
Prevents navigation to next component while in editing mode to maintain input focus.
Calls base navigation when not editing for normal UI flow.

Declaration
public override void SelectNextComponent()
Overrides

SelectPreviousComponent()

Overrides previous component selection to respect editing state.
Prevents navigation to previous component while in editing mode to maintain input focus.
Calls base navigation when not editing for normal UI flow.

Declaration
public override void SelectPreviousComponent()
Overrides

SetFocus(bool)

Overrides SetFocus to prevent focus changes during editing or pending selection.

WHY THIS OVERRIDE IS NEEDED:
Even after clearing EventTrigger entries, other code paths may call SetFocus:

  • Foundation navigation changing selection
  • Mouse hover on other components calling SetFocus(false) then SetFocus(true)
  • Race conditions during deferred submit (pending selection)

    GUARDS:
  1. If editing: ignore all SetFocus calls (user is typing, don't change focus)
  2. If pending selection and active=false: ignore (don't blur during selection-before-edit transition)
Declaration
public override void SetFocus(bool active)
Parameters
Type Name Description
bool active

True to focus, false to blur.
Overrides

SetValue(string)

Sets the input field value and triggers associated update events.
Updates both the parameter storage and the visual TMP_InputField component.
Invokes edit callbacks to notify system of value changes.

Declaration
public override void SetValue(string value)
Parameters
Type Name Description
string value

The new text value to set in the input field
Overrides

StartEdition()

Starts text editing mode for the input field.
Activates the input field, sets focus, and triggers editing start callbacks.
Updates internal editing state to manage navigation and interaction behavior.

Declaration
public virtual void StartEdition()

Submit()

Handles submit actions for the input component with dual-mode behavior.
If not editing, starts text editing mode; if editing, ends editing and confirms the input value.
Calls base submit functionality for additional UI system integration.

Declaration
public override void Submit()
Overrides

Implements

UnityEngine.EventSystems.ISelectHandler
UnityEngine.EventSystems.IEventSystemHandler
UnityEngine.EventSystems.IPointerDownHandler
UnityEngine.EventSystems.IPointerEnterHandler