UI/State Groups

From SC2Mapster Wiki
< UI
Jump to: navigation, search

STATEGROUPS

What are StateGroups?

StateGroups are an easy way to track the different states of a UI item and then execute certain actions based upon which state the item is in or a combination of possible states. When one state activates, the others deactivate. Conditions can listen for animation states, stategroup states, and frame properties. Animation states are something Blizzard UI engineers can set on a frame through code, but they can also be set by using triggers/script using the "Dialog Item Send Animation Event 2" action (DialogControlSetAnimationState).


Example StateGroup

Here is a quick example StateGroup with only two states. This StateGroup sits inside of a frame, and toggles its visibility to be the opposite of a sibling frame.

        <StateGroup name="VisibilityToggle">
            <DefaultState val="NotVisible"/>
            
            <State name="Visible">
                <When type="Property" frame="$parent/sibling" Visible="False"/>
                <Action type="SetProperty" frame="$this" Visible="True"/>
            </State>
        
            <State name="NotVisible">
                <When type="Property" frame="$parent/sibling" Visible="True"/>
                <Action type="SetProperty" frame="$this" Visible="False"/>
            </State>
        </StateGroup>

States

StateGroups are made up of a set of exclusive "States" which can check conditions and then fire off actions when those conditions are met. A StateGroup can only be active in one state at a time. States must have unique names from the other states inside of the StateGroup. When checking the conditions of its states a StateGroup will run in order from first to last state as they exist in the layout file. It will stop as soon as one of the states meets its conditions and remain there until that state no longer meets its conditions, or one of the states before it in the list has met theirs.


When Conditions

There are currently only three types of "When" conditions for StateGroups. They are:

Type Description Sample XML
Property Checks the value of a property for the target frame. Most properties work, but there are some exceptions. <When type="Property" frame="TargetFramePath" Visible="true"/>
AnimationState Checks the state of an AnimationState on the target frame. <When type="AnimationState" frame="TargetFramePath" PurchasedState="true"/>
StateGroup Checks the state of a StateGroup on the target frame. <When type="StateGroup" frame="TargetFramePath" stateGroupName="stateName"/>
Option Checks the setting a player has for a specific game option. <When type="Option" localeiddata="ruRU"/>


Actions

There are currently six "Action" types for StateGroups. They are:

Type Description Sample XML
SetProperty Sets the property value for the specified property on the target frame. <Action type="SetProperty" frame="TargetFramePath" visible="True"/>
SendEvent Sends an animation event to the target frame. <Action type="SendEvent" frame="TargetFramePath" event="SomeAnimationEventName"/>
ApplyTemplate Applies the specified template to the target frame. Be aware that templates will not "undo" like most changes you make with StateGroups so be certain to setup a default template and apply that in your other states if you want to restore it. <Action type="ApplyTemplate" frame="TargetFramePath" template="SomeNewTemplatePath"/>
SetState Sets the current state of a StateGroup in the target frame. Only works with StateGroups that have NO conditions in any of their states. <Action type="SetState" frame="TargetFramePath" group="SomeStateGroupName" state="SomeStateName"/>
SetAnchor Sets the specified anchor point of the target frame to the specified values. <Action type="SetAnchor" frame="TargetFramePath" side="Top" relative="FrameToAnchorTo" pos="Min" offset="0"/>
PlaySound Plays a sound or actor sound. Put * before the sound for actor sounds. (Ex: sound="*@SomeActorSoundId") This probably won't work until patch 3.13 <Action type="PlaySound" sound="@SomeSoundId"/>
SetAnimationProperty -
<Action type="SetAnimationProperty" animation="AnimationName" enabled="false"/>

Operators

Operators allow you to control how a when condition checks itself. For example, you can check whether something is False by putting a "NotEqual" operator attribute into a when condition checking a boolean property set to equal True.


Available operators:

  • Equal (Default behavior)
  • NotEqual
  • GreaterThan
  • GreaterThanOrEqual
  • LessThan
  • LessThanOrEqual


Examples:

This will check to see if the target frame's "Visible" property is not equal to "True".
<When type="Property" frame="TargetFramePath" operator="NotEqual" Visible="True"/>
This will check to see if the target frame's "HeroesAlive" property is less than 5.
<When type="Property" frame="TargetFramePath" operator="LessThan" HeroesAlive="5"/>


On Enter/Exit

You can set whether an action should execute when the StateGroup enters or exits a state by using the "On" attribute. In the following example special animation events are being sent when exiting a state so that you can create nice transition animations between them.

Example:

    <Frame type="TrafficLight" name="TrafficLight">
        <StateGroup name="Signal">
            <DefaultState val="Green"/>
            
            <State name="Red">
                <When type="AnimationState" light="Red"/>
                <Action type="SendEvent" frame="RedLight" event="Show"/>
                <Action type="SendEvent" frame="RedLight" event="Hide" on="Exit"/>
            </State>
            
            <State name="Yellow">
                <When type="AnimationState" light="Yellow"/>
                <Action type="SendEvent" frame="YellowLight" event="Show"/>
                <Action type="SendEvent" frame="YellowLight" event="Hide" on="Exit"/>
            </State>
            
            <State name="Green">
                <When type="AnimationState" light="Green"/>
                <Action type="SendEvent" frame="GreenLight" event="Show"/>
                <Action type="SendEvent" frame="GreenLight" event="Hide" on="Exit"/>
            </State>  
        </StateGroup>
    </Frame>

Overriding

Overriding StateGroups from a template supports overriding actions and conditions separately.

  • For a State with same name, if you define an action, all actions from parent template will be ignored.
  • For a State with same name, if you define a condition all conditions from parent template will be ignored.

In the following example, all of the conditions from the "RedTeamHealthBar" are inherited into the states in the "BlueTeamHealthBar".

Example:

    <Frame type="Image" name="RedTeamHealthBar">
        <StateGroup name="Health">
            <State name="Low">
                <When type="Property" health="Low"/>
                <When ... />
                <When ... />
                <Action type="Property" frame="$this" texture="@UI/RedBorderLow"/>
            </State>
            <State name="High">
                <When type="Property" health="High"/>
                <When ...="" />
                <When ...="" />
                <Action type="Property" frame="$this" texture="@UI/RedBorderHigh"/>
            </State>
        </StateGroup>
    </Frame>
         
    <Frame type="Image" name="BlueTeamHealthBar" template="RedTeamHealthBar">
        <StateGroup name="Health">
            <State name="Low">
                <!-- All conditions are inherited. -->
                <Action type="Property" frame="$this" texture="@UI/BlueBorderLow"/>
            </State>
            <State name="High">
                <!-- All conditions are inherited. -->
                <Action type="Property" frame="$this" texture="@UI/BlueBorderHigh"/>
            </State>
        </StateGroup>
    </Frame>

Debug Overlay

When running test document or when in developer mode in a replay you can bring up the UI Debug Overlay by pressing "Ctrl+Alt+F12". From here you can press F10 to view tooltips on frames as you mouse over them on the screen or select them in the frame tree on the right side of the screen. Inside of these tooltips you can see the StateGroups that are on a frame, as well as what state they are in. You can also see the AnimationStates on a frame, and what state those are in. Very helpful for figuring out what your StateGroups are actually doing.

Another helpful tool for debugging StateGroups is the property viewer, which can be found by clicking the last book icon on the left side of the UI Debug Overlay. The property viewer allows you to see what value all of the properties on a frame are currently set to with few exceptions.