UIStateItem

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.

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

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.

States UI game objects

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

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

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.

Callbacks

UIStateItem implements callback event OnStateChange that called at any state change

Details

Check the next additional components to add extra features to UIStateItem

Summary
UIStateItemUIStateItem implements different UI item states and provides API to switch between them.
Constants
STATE_INACTIVEBuilt-in state “inactive”
STATE_ACTIVEBuilt-in state “active”
STATE_DISABLEDBuilt-in state “disabled”
Properties
StatesString array of states names
StatesUiGameObject array of States UI game objects
CurrentStateCurrent state name
DefaultStateDefault state name
PreviousStatePrevious state name before last state change
StateGroupLink to UIStateGroup object this item belongs to
Functions
SetDefaultStateTo (state)Set default state to new state by name
FlushDefaultState ()Flush default state
GetStateName (stateId)Get state name by its id from States array
GetStateId (state)Get state id by its name from States array
AddState (state)Add new state with given name
RemoveState (state)Remove state by given name
SetState (state, force)Change CurrentState to given state
SetState (state)Change CurrentState to given state if it’s not in given state yet
ForceSetState (state)Force change CurrentState to given state
SetStateDefault (force)Shortcut function to set CurrentState to DefaultState
SetStateActive (force)Shortcut function to set CurrentState to built-in state UIStateItem.STATE_ACTIVE
SetStateInactive (force)Shortcut function to set CurrentState to built-in state UIStateItem.STATE_INACTIVE
SetStateDisabled (force)Shortcut function to set CurrentState to built-in state STATE_DISABLED
Variables
OnStateChangeThis UnityEvent is called on each state change

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

statestate 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

stateIdstate 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

statestate name from States array

Returns

Found state id or -1

AddState (state)

public int AddState (string state)

Add new state with given name

Parameters

statenew 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

statestate name to remove

SetState (state, force)

public void SetState(string state,
bool force)

Change CurrentState to given state

For force = trueall state change actions will be processed even if CurrentState is already equals to given state.
For force = falseall actions will be skipped if CurrentState is already equals to given state.

Parameters

statestate name from States array
forcebool, 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

statestate 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

statestate 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

forcebool, 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

forcebool, 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

forcebool, 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!");
}
UIItem is one of the base components that implements core item properties.
UIStateItem implements different UI item states and provides API to switch between them.
public const string STATE_INACTIVE
Built-in state “inactive”
public const string STATE_ACTIVE
Built-in state “active”
public const string STATE_DISABLED
Built-in state “disabled”
public string [] States { get }
String array of states names
public GameObject [] StatesUi { get }
GameObject array of States UI game objects
public string CurrentState { get }
Current state name
public string DefaultState { get }
Default state name
public string PreviousState { get }
Previous state name before last state change
public UIStateGroup StateGroup { get }
Link to UIStateGroup object this item belongs to
UIStateGroup allows to manage group of UIStateItem items and perform bulk state change
public void SetDefaultStateTo(string state)
Set default state to new state by name
public void FlushDefaultState()
Flush default state
public string GetStateName(int stateId)
Get state name by its id from States array
public int GetStateId(string state)
Get state id by its name from States array
public int AddState (string state)
Add new state with given name
public void RemoveState (string state)
Remove state by given name
public void SetState(string state,
bool force)
Change CurrentState to given state
public void SetState(string state)
Change CurrentState to given state if it’s not in given state yet
public void ForceSetState(string state)
Force change CurrentState to given state
public void SetStateDefault(bool force =  false)
Shortcut function to set CurrentState to DefaultState
public void SetStateActive(bool force =  false)
Shortcut function to set CurrentState to built-in state UIStateItem.STATE_ACTIVE
public void SetStateInactive(bool force =  false)
Shortcut function to set CurrentState to built-in state UIStateItem.STATE_INACTIVE
public void SetStateDisabled(bool force =  false)
Shortcut function to set CurrentState to built-in state STATE_DISABLED
public UnityEvent OnStateChange
This UnityEvent is called on each state change
UIStateItemMirror allows to synchronize main UIStateItem item state to another UIStateItem items
UIStateItemAnimation allows to animate UIStateItem state change transition
public virtual void ItemStateChanged(string itemName)
Internal function.
Close