Parallel Activity Host

Parallel Activity Host can activate more than one of its child Activities at a time. When you activate an Activity, a Parallel Activity Host brings that Activity to the front.

In a Parallel Activity Host you can group Activities, to show the groups in the same order that you defined in the node tree. When you activate an Activity in a group, a Parallel Activity Host brings to the front the Activity in that group. For example, this way you can implement the showing of critical messages, such as engine failure, in front of regular notifications, such as a phone call notification. In both groups a Parallel Activity Host shows the Activities in order of activation.

Using a Parallel Activity Host

To use a Parallel Activity Host:

1. In the Activity Browser click and create a root Parallel Activity Host.

   Kanzi Studio creates a Parallel Activity Host node in the RootPage node.

   

2. In the Activity Browser below the root Parallel Activity Host click to create an Activity and create or assign a prefab to that Activity.

   For example, create Activities named Seatbelt, Phone Call, and Engine Failure. For each Activity use the same name for the Activity prefab.

   Kanzi Studio creates Activities, adds them to the Parallel Activity Host, and for each Activity creates a prefab in the Prefabs.

   

3. Create a node with a trigger that you want to use to activate or deactivate an Activity.

   For example, create a Toggle Button node and use the Toggle Button: Toggled On and Toggle Button: Toggled Off triggers.

   

4. In the Node Tree select the node that you created in the previous step, in the Node Components > Triggers press Alt and right-click the trigger that you want to use to activate an Activity, select the Activate Activity action, and in the action set:

   • Target Item to the Parallel Activity Host that contains the Activity that you want to activate.

   • Activation Path to the path in the Parallel Activity Host to the Activity that you want to activate.

     If you nest Activity nodes in other types of nodes, include in the path only the ancestor Activity nodes.

     Tip

     To get the full activation path to an Activity node, in the Activity Browser right-click an Activity node and select Copy Activation Path. This command copies the entire path from the top-level Activity Host node to that Activity node.

     The Activity Activation Path contains only Activities and Activity Hosts.

     
   

5. In the Node Components > Triggers press Alt and right-click the trigger that you want to use to deactivate an Activity, select the Deactivate Activity action, and in the action set:

   • Activation Path to the path in the Parallel Activity Host to the Activity that you want to deactivate.

     If you nest Activity nodes in other types of nodes, include in the path only the ancestor Activity nodes.

   • Target Item to the Parallel Activity Host that contains the Activity that you want to deactivate.

   

In the Preview click the toggle buttons to activate and deactivate the Activities in the Parallel Activity Host.

Activating Activities

When you activate an Activity, Kanzi:

1. Creates an Activity node using its prefab.

2. Attaches the Activity node to the node tree.

3. Makes the Activity visible.

4. Sets keyboard focus to the Activity if the Activity Host has keyboard focus, unless configured otherwise. Controlling whether to set focus to an activating Activity.

You can activate an Activity using:

• An Activate Activity Message. See Activating an Activity with the Activate Activity Message.

• An Apply Activation Action. See Activating Activities with an Apply Activation Action.

Finding out whether an Activity is active

To find out whether an Activity is active, check the value of the Activity Status property for that Activity node.

Activating an Activity with the Activate Activity Message

Use the Activate Activity Message when:

• The condition for activating an Activity is too complex to be expressed with the value of a property

• You do not know in advance the number of Activities in an Activity Host

To activate an Activity with the Activate Activity Message:

1. Create an Activity Host with several Activities.

   

2. Create a node with a trigger that you want to use to activate an Activity.

   For example, create a Toggle Button node and use the Toggle Button: Toggled On and Toggle Button: Toggled Off triggers to activate and deactivate an Activity in a Parallel Activity Host.

   

3. In the Node Tree select the node with the trigger that you created in the previous step, in the Node Components > Triggers press Alt and right-click the trigger that you want to use to activate an Activity, select Dispatch Message Action > Activate Activity Message, and in the action set:

   • Target Item to the Activity Host that contains the Activity that you want to activate.

   • Activation Path to the path from the Activity Host to the Activity that you want to activate.

     If you nest Activity nodes in other types of nodes, include in the path only the ancestor Activity nodes.

     Tip

     To get the full activation path to an Activity node, in the Activity Browser right-click an Activity node and select Copy Activation Path. This command copies the entire path from the top-level Activity Host node to that Activity node.

     The Activity Activation Path contains only Activities and Activity Hosts.

     
   

4. To deactivate an Activity in a Parallel Activity Host, repeat the previous step but add the Dispatch Message Action > Deactivate Activity Message to the trigger that you want to use to deactivate that Activity.

   

In the Preview click the toggle buttons to activate and deactivate the Activities in the Parallel Activity Host.

Activating Activities with an Apply Activation Action

An Apply Activation Action keeps an Activity activated for as long as the condition is met in a Data Trigger that contains this action. When the trigger condition is no longer met, Kanzi rolls back the state of the Activity to the state before the action was applied. Use the Apply Activation Action only with a Data Trigger.

Use the Apply Activation Action when you want to synchronize the activation of an Activity with your application logic.

For example, use an Apply Activation Action to show a cluster indicator when a property has a specific value, and then hide the same indicator when the value of that property no longer has that value.

When using a Data Trigger, keep in mind that actions of a Data Trigger have higher priority than the actions of any other trigger.

You can learn how use a Data Trigger with a Apply Activation Action to control the activation state of Activities by completing Tutorial: Control application UI.

To activate an Activity with an Apply Activation Action:

1. In the Activity Browser create a Parallel Activity Host with an Activity.

   For example, create a Parallel Activity Host node with an Activity named LowBattery that contains an image.

   

2. Create a node with which you want to control the activation state of the Activity that you created in the previous step.

   For example, from the Asset Packages drag the Slider to the Preview.

   

3. Create a Data Trigger with an Apply Activation Action:

   1. In the Node Tree select the Parallel Activity Host node, in the Node Components press Alt and right-click Triggers, and select Data Trigger.

      

   2. In the Data Trigger in the Expression click , in the Node Tree select the Slider, and from the Properties drag the Value property to the Expression field and edit the expression to

      {@Slider/RangeConcept.Value}<=20
      

      This condition expression must evaluate to either True or False. As a source you can use either a property or a data object from a data source.

      Click Save.

      This way you set the Data Trigger to execute the Apply Activation Action when the value of the Value property in the Slider equals or is lower than 20.

      

   3. In the Data Trigger press Alt and right-click Actions, and select Apply Activation Action.

      

   4. In the Apply Activation Action set:

      • Activity Host Path to .

      • Activity Activation Path to LowBattery

      The path to the Activity that that you set in the Activity Activation Path property is relative to the Activity Host node that you set in the Activity Host Path property.

      The Activity Browser indicates that an Activity Host has a Data Trigger with the icon.

      

   Tip

   To get the full activation path to an Activity node, in the Activity Browser right-click an Activity node and select Copy Activation Path. This command copies the entire path from the top-level Activity Host node to that Activity node.

   The Activity Activation Path contains only Activities and Activity Hosts.

   

In the Preview drag the slider knob:

• When the value of the Value property of the slider equals or is lower than 20, the Data Trigger activates the Activity that you set in the Apply Activation Action.

  An Apply Activation Action keeps an Activity activated for as long as the condition is met in a Data Trigger that contains this action.

• When the value of the Value property of the slider equals 21 or higher, the Data Trigger deactivates the Activity that you set in the Apply Activation Action.

  When the trigger condition is no longer met, Kanzi rolls back the state of the Activity to the state before the action was applied.

Tip

During the application development, use these Data Trigger tools in the Activity Browser side panel:

Tool	Description
	Shows where a Data Trigger is and where the source and target Activity nodes of that Data Trigger are.
	Simulates the state when you apply a Data Trigger. This enables you to see the state of your application when the conditions for a Data Trigger are met without having to change the property values in your application.
	Shows a Data Trigger in the Node Components window.

Using Activities in the API

For details, see the Activity2D, Activity3D, ParallelActivityHost2D, and ParallelActivityHost3D classes in the Kanzi Engine API reference.

See also

Tutorial: Structure application UI

Tutorial: Control application UI