A Navigation Group holds a set of selectables that it manages for navigation.

When it becomes focused, one of its selectables are selected and the user cannot navigate to any selectable outside the Navigation Group (unless a Navigation Group Switch Controller allows this).


Inspector Properties


Focus Time

This defines if and when the Navigation Group becomes automatically focused.

  • On Enable
    The Navigation Group is focused as soon as the Navigation Group becomes active in the scene (when OnEnable() is called).
  • One Frame After On Enable
    When the Navigation group becomes active, it waits one frame and then focuses itself. This behavior is useful when Selectables of the Navigation Group are instantiated on runtime. As they wouldn't be present on enable, they hopefully are one frame later.
  • Do Not Focus Automatically
    The group is not automatically focused by itself. It can still be focused via code or through a Navigation Group Switch Controller or a Tab Switch Controller (these actually set their Navigation Groups to "Do Not Focus Automatically" to function properly)


Focus Priority

The Focus Priority can be used to prevent other Navigation Groups to become focused, when the current navigation group is already focused. In other words: If the currently focused navigation group has a higher Focus Priority than another Navigation Group, that other group will not be focused.

The Focus Priority can also be used to evaluate the initial element of a NavigationGroupCollection.


Cancel Action

When an input for "Cancel" was detected, there are several behaviors you can define here.

  • None
    The Navigation Group does nothing on Cancel.
  • Unfocus
    The Navigation Group releases its focus. This usually leads to the previously focused Navigation Group gaining focus again. If there are no previous groups or the previous groups cannot be interacted with, it might result in a state where no group is focused.
  • Deactivate Game Object
    The game objects active state is set to false, making it invisible and non-interactable. This will also unfocus the Navigation Group (see above).
  • Destroy Game Object
    The game object with the Navigation group is destroyed. This will also unfocus the Navigation Group (see above).
  • Trigger Button Click
    If a (Better) Button is assigned to the field that appears when this option is selected, that buttons "onClick" event is invoked. This button is typically a close- or cancel button.
  • Trigger Custom Event
    You can assign any event you want in this case.


If the cancel action is not "None", a field will appear:

Cancel When No Selectable Present

When this is checked, the cancel action will also trigger when the Group could not select any selectable (either because none is present or none is interactable).


Exclude Sub Navigation Groups

This property is closely related to "Selectable Group" (see below) and only affects it if it is not a Fixed Set.

It defines which Selectables are collected by the Selectable Group.

Specifically, if checked, it will not include any selectables that are children of other Navigation Groups down in the hierarchy.

If you are sure that there are no sub-navigation groups, you can uncheck it to gain a bit performance.


Selectable Group

A Selectable Collection defining the selectables of this Navigation Group.


Focus Transitions

A set of Better Transitions with Focus and Unfocus states. The Focus state will be active as long as the navigation group is focused.



Code Access


Static


Current

The currently focused Navigation Group. Null, if there is no navigation group focused.


OnFocusChanged

A callback that is called when another navigation group is focused or unfocused.

void NavigationGroupFocusChanged(NavigationGroup previousGroup, NavigationGroup currentGroup)

Note that any of the parameters can be null.


Non-Static


SelectableGroup

See Inspector Properties (Selectable Group).

FocusTiming

See Inspector Properties (Focus Time)

FocusPriority

See Inspector Properties (Focus Priority)

CancelAction

Gets the Cancel Action (See Inspector Properties).
The Cancel Action cannot be changed from code in this version of Better UI.

IsFocused

Returns true, if the Navigation Group is the Current group.

Focus()

Focuses the Navigation Group. By default, the stacking "Remember Previous" is passed. This will go back to the previous Navigation Group as soon as this group becomes unfocused. You can also pass "ForgetPrevious", to go back to the group before the previous on unfocus, or "ForgetAll" to go back to the root selectables of Better Navigation on unfocus.

If you pass "force: true", the navigation group will be focused even if the current navigation group has a higher Focus Priority (see above),

FocusDelayed()

Focuses the Navigation Group after a defined delay. By default, this delay is one frame, but you can pass any YieldInstruction you want instead. You can also pass the stacking like in Focus() (see above).


Unfocus()

Unfocuses the navigation group if it is currently focused. This will focus the latest previously focused Navigation Group, that is still interactable (unless is was "forgotten", see Focus() above).


TransitionToFocusState()

Transitions to the Focus State. This does not focus the navigation group.

TransitionToUnfocusState()

Transitions to the Unfocus State. This does not unfocus the navigation group.

TriggerCancelAction()

Triggers the cancel action as if the input for "Cancel" was pressed (see above).