UIStateItem
CJFinc.​UItools.​UIItem
[DisallowMultipleComponent]
public
CJFinc.​UItools.​UIStateItem

UIStateItem implements different UI item states and provides API to switch between them.

States

UIStateItem contains three built-in states: active, inactive and disabled, that ideally fits most of UI elements use cases.

UIStateItem-editor-builtin-states

Besides of that you can add any additional states that you need.

UIStateItem-editor-custom-states

Usually at initialization it's required to set UIStateItem to default state.

You can set default state to one of your state. Use "Flush" button if you don't need a default state.

UIStateItem-default-state

States UI game objects:

UIStateItem is automatically uses nested gameobject for each state with exact name.

UIStateItem-editor-ui-gameobjects-automatic-mode

Alternatively you can switch to "Manual" mode. It will allow you to link each state game object manually to any game object from hierarchy.

UIStateItem-editor-ui-gameobjects-manual-mode

On state change UIStateItem uses GameObject.SetActive to enable new state UI game object and to disable other states.

You can easily test state change directly in editor as well as in player mode.

UIStateItem-ui-gameobjects-state-change
Callbacks

UIStateItem implements callback event OnStateChange that called at any state change

UIStateItem-editor-callbacks
Details

Check the next additional components to add extra features to UIStateItem * UIStateItemMirror * UIStateItemAnimation

Constants
STATE_INACTIVE
public const string STATE_INACTIVE

Built-in state "inactive"

STATE_ACTIVE
public const string STATE_ACTIVE

Built-in state "active"

STATE_DISABLED
public const string STATE_DISABLED

Built-in state "disabled"

Properties
States
public string [] States { get }

String array of states names

Default tree states are: - inactive - active - disabled

Debug.Log("UIStateItem states count = " + GetComponent<UIStateItem>().States.Length);
StatesUi
public GameObject [] StatesUi { get }

GameObject array of States UI game objects

You can assign game objects in run time. Just make sure that "UI game objects" mode is set to "manual" in editor. See UIStateItem editor manual for details.

Note: You can't change a StatesUi array size. The StatesUi array size is always equals to States array size and controlling automatically.

CurrentState
public string CurrentState { get }

Current state name

DefaultState
public string DefaultState { get }

Default state name

PreviousState
public string PreviousState { get }

Previous state name before last state change

StateGroup
public UIStateGroup StateGroup { get }

Link to UIStateGroup object this item belongs to

If group defined then UIStateGroup.ItemStateChanged (itemName) function will be called for each state change.

Functions
SetDefaultStateTo (state)
public void SetDefaultStateTo(
string state
)

Set default state to new state by name

GetComponent<UIStateItem>().SetDefaultStateTo(UIStateItem.STATE_ACTIVE);
GetComponent<UIStateItem>().SetStateDefault();
Parameters
state
string

state name from States array

FlushDefaultState ()
public void FlushDefaultState()

Flush default state

GetStateName (stateId)
public string GetStateName(
int stateId
)

Get state name by its id from States array

Parameters
stateId
int

state id from States array

Returns

Found state name or empty string

GetStateId (state)
public int GetStateId(
string state
)

Get state id by its name from States array

Parameters
state
string

state name from States array

Returns

Found state id or -1

AddState (state)
public int AddState (
string state
)

Add new state with given name

Parameters
state
string

new state name

Returns

new state id from States array or -1 in case of duplicate state name

RemoveState (state)
public void RemoveState (
string state
)

Remove state by given name

Note: Built-in states could not be removed!

Parameters
state
string

state name to remove

SetState (state, force)
public void SetState(
string state,
bool force
)

Change CurrentState to given state

For force = true

all state change actions will be processed even if CurrentState is already equals to given state.

For force = false

all actions will be skipped if CurrentState is already equals to given state.

Parameters
state
string

state name from States array

force
bool

bool, should state change be forced?

SetState (state)
public void SetState(
string state
)

Change CurrentState to given state if it's not in given state yet

This function will skip all actions if CurrentState is already equals to given state.

See SetState (state, force) for details.

Parameters
state
string

state name from States array

ForceSetState (state)
public void ForceSetState(
string state
)

Force change CurrentState to given state

This function will set CurrentState to given state even if CurrentState is already equals to given state.

See SetState (state, force) for details.

Parameters
state
string

state name from States array

SetStateDefault (force)
public void SetStateDefault(
bool force =  false
)

Shortcut function to set CurrentState to DefaultState

Use force parameter to control state change behavior. See SetState (state, force) for details.

SetStateActive (force)
public void SetStateActive(
bool force =  false
)

Shortcut function to set CurrentState to built-in state UIStateItem.STATE_ACTIVE

Use force parameter to control state change behavior. See SetState (state, force) for details.

Parameters
force
bool

bool, should state change be forced?

SetStateInactive (force)
public void SetStateInactive(
bool force =  false
)

Shortcut function to set CurrentState to built-in state UIStateItem.STATE_INACTIVE

Use force parameter to control state change behavior. See SetState (state, force) for details.

Parameters
force
bool

bool, should state change be forced?

SetStateDisabled (force)
public void SetStateDisabled(
bool force =  false
)

Shortcut function to set CurrentState to built-in state STATE_DISABLED

Use force parameter to control state change behavior. See SetState (state, force) for details.

Parameters
force
bool

bool, should state change be forced?

Variables
OnStateChange
public UnityEvent OnStateChange

This UnityEvent is called on each state change

You can subscribe any of your functions to this event.

GetComponent<UIStateItem>().OnStateChange.AddListener(StateChanged);

...

void StateChanged() {
    Debug.Log("State has been changed!");
}