Kanzi 3.9.10
kanzi::Activity2D Class Reference

An Activity is a part of application UI that is responsible for a task. More...

#include <kanzi/ui/node/activity2d.hpp>

Inheritance diagram for kanzi::Activity2D:
[legend]

Public Types

using ConceptClass
 Activity 2D concept used to implement this class.
 
- Public Types inherited from kanzi::ActivityConcept
enum class  Status { Active , Inactive , Activating , Deactivating }
 Defines possible states of an Activity. More...
 

Static Public Member Functions

static Activity2DSharedPtr create (Domain *domain, string_view name)
 Creates a 2D activity node.
 
static PropertyTypeEditorInfoSharedPtr makeEditorInfo ()
 Provides editor info.
 
- Static Public Member Functions inherited from kanzi::ActivityElement
static string getFirstElement (string_view activationSequence)
 Gets the first element of the activation sequence.
 
static string getRestToForward (string_view activationSequence)
 Gets the remainder of the activation sequence.
 
template<typename Type >
static bool isActivityElement (const Type &object)
 Returns whether an object is an ActivityElement.
 
static PropertyTypeEditorInfoSharedPtr makeEditorInfo ()
 
- Static Public Member Functions inherited from kanzi::ActivityConcept
template<typename Type >
static bool isActivity (const Type &object)
 Returns whether an object is an Activity.
 
static bool isActivityMetaclass (const Metaclass *metaclass)
 Checks whether the given Metaclass is an ActivityConcept metaclass or contains it as a mixin metaclass.
 
static PropertyTypeEditorInfoSharedPtr makeEditorInfo ()
 

Protected Member Functions

 Activity2D (Domain *domain, string_view name)
 Constructor.
 
- Protected Member Functions inherited from kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >
 ActivityConceptImpl (Domain *domain, string_view name)
 Constructor.
 
void initialize ()
 Initializes this activity.
 
void onAttached () override
 Node::onAttached implementation.
 
void onDetached () override
 Node::onDetached implementation.
 
void onInputOutsideOverlay (FocusManager::InputOutsideOverlayMessageArguments &args)
 Message handler for InputOutsideOverlayMessage message.
 
void registerInParentActivityElement () final
 ActivityElement::registerInParentActivityElement implementation.
 
void unregisterInParentActivityElement () final
 ActivityElement::registerInParentActivityElement implementation.
 
 ~ActivityConceptImpl () override=default
 Destructor.
 
- Protected Member Functions inherited from kanzi::ActivityElementImpl< TBaseClass, TDerivedClass >
 ActivityElementImpl (Domain *domain, string_view name)
 Constructor.
 
void initialize ()
 Initializes the activity element.
 
void onAttached () override
 Node::onAttached implementation.
 
virtual void onAttachedOverride ()
 Overrides the onAttached method.
 
void onDetached () override
 Node::onDetached implementation.
 
void onNodePropertyChanged (AbstractPropertyType propertyType, PropertyNotificationReason reason) override
 Node::onNodePropertyChanged implementation.
 
 ~ActivityElementImpl () override=default
 Destructor.
 
- Protected Member Functions inherited from kanzi::ActivityElement
optional< ActivityBrowserController::ActivityIDgetActivityID () const
 Gets the unique ID that is used by the implementation of the Activity Browser.
 
string getPathInParent ()
 Gets the activation path of this activity element relative to its parent.
 
void initialize ()
 Initializes the activity element.
 
bool isRootActivityElement () const
 Returns whether an ActivityElement is the root Activity Host node of the Screen node.
 
virtual void notifyChildrenNodeTreeAvailable ()
 Notifies child activity elements that node info tree is available.
 
void onForceTrigger (const ActivityBrowserController::ForceTriggerMessageArguments &args)
 Message handler for ActivityBrowserController::ForceTriggerMessage.
 
void onNodeInfoTreeAvailable (const ActivityBrowserController::NodeInfoTreeAvailableArguments &)
 Message handler for ActivityBrowserController::NodeInfoTreeAvailableMessage.
 
void registerChildHost (string_view hostPath)
 Registers a child host in this activity element.
 
void setActivityID (optional< ActivityBrowserController::ActivityID > activityID)
 Sets the unique ID that is used by the implementation of the Activity Browser.
 
void unregisterChildHost (string_view hostName)
 Unregisters a child host from this activity element.
 
void updateActivityBrowserProperties ()
 Triggers the Activity Browser to update the properties of the Activity Element.
 

Additional Inherited Members

- Public Member Functions inherited from kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >
bool collectActivatingDescendantActivities () override
 Implements ActivityConcept::collectActivatingDescendantActivities.
 
void enableFocusGain (bool enable) override
 Overrides ActivityConcept::enableFocusGain().
 
void enableFocusRecovery (bool enable) override
 Overrides ActivityConcept::enableFocusRecovery().
 
void enableInput (bool enable) override
 Overrides ActivityConcept::enableInput().
 
const NodegetNode () const override
 Gets the underlying Node object.
 
NodegetNode () override
 Gets the underlying Node object.
 
ActivityConceptgetParentActivity () override
 ActivityConcept::getParentActivity implementation.
 
bool isAutoClosingBecauseFocusMove () const override
 Overrides ActivityConcept::isAutoClosingBecauseFocusMove().
 
void notifyPendingActivationBeforeFocusFinished (string_view activityName) override
 Implements ActivityConcept::notifyPendingActivationBeforeFocusFinished.
 
void notifyReadyForFocus ()
 
void restoreLastFocusedNode () final
 ActivityConcept::restoreLastFocusedNode implementation.
 
string serialize () override
 ActivityElement::serialize implementation.
 
void setLastFocusedNodePath () final
 ActivityConcept::setLastFocusedNodePath implementation.
 
void tryRestoreLastFocusedPathCompletely (const Node *candidateChild) final
 ActivityConcept::tryRestoreLastFocusedPathCompletely implementation.
 
void updateFocusScopeInfo (FocusScopePtr &nodeScopeInfo) override
 Overrides Node::updateFocusScopeInfo().
 
- Public Member Functions inherited from kanzi::ActivityElementImpl< TBaseClass, TDerivedClass >
const NodegetNode () const override
 Gets the underlying Node object.
 
NodegetNode () override
 Gets the underlying Node object.
 
- Public Member Functions inherited from kanzi::ActivityElement
vector< NodeSharedPtr >::const_iterator beginChildHosts () const
 Returns the begin iterator to the registered child Activity Host.
 
virtual void deserialize (string_view data)
 Deserializes the activity element from a byte buffer.
 
vector< NodeSharedPtr >::const_iterator endChildHosts () const
 Returns the end iterator to the registered child Activity Host.
 
NodefindChildHost (string_view hostName)
 Finds a child Activity Host by name.
 
vector< string > getCommands () const
 Gets the list of commands handled by code behind of this activity element.
 
ActivityHistoryManagergetHistoryManager () const
 Gets the history manager of this activity element.
 
ActivityElementgetParentElement ()
 Gets the parent ActivityElement type node.
 
bool isLeafActivityNode () const
 Returns whether an ActivityElement has a child Activity Host.
 
void setCodeBehind (CodeBehindSharedPtr codeBehind)
 Attaches a code behind object.
 
void setCodeBehind (const Metaclass *metaclass)
 Instantiates and attaches a code behind object by specifying its metaclass.
 
virtual ~ActivityElement ()=default
 Destructor.
 
- Public Member Functions inherited from kanzi::ActivityConcept
void cancelWaitBeforeFocus ()
 Makes an Activity no longer wait for any pending activations.
 
optional< string > getPathToActivity (ActivityConcept *activity) const
 Returns a path from this Activity to a given Activity, if that Activity is a descendant node of this Activity.
 
bool isWaitingActivationsBeforeFocus () const
 Returns whether an Activity is waiting for its descendant Activities to activate before Kanzi applies the focus policy to the activated Activity.
 
bool isWaitingForActivation (ActivityConcept *activity) const
 Returns whether an Activity is waiting for the activation of a given Activity.
 
virtual ~ActivityConcept ()=default
 Destructor.
 
- Static Public Attributes inherited from kanzi::ActivityElement
static PropertyType< boolAttachedProperty
 
static PropertyType< boolPreserveHistoryProperty
 Enables the preservation of Activity property values when that Activity becomes inactive.
 
- Static Public Attributes inherited from kanzi::ActivityConcept
static NodeWeakPtr s_activationTargetActivity
 The Activity that is the activation target.
 
static PropertyType< StatusStatusProperty
 Specifies the status of this Activity.
 
static PropertyType< floatDummyStateManagerProperty
 Lack of a queuing mechanism for incoming messages from an Activity Host can cause Kanzi to enter a recursive call in the setProperty().
 
static PropertyType< boolActivatedByActivationModifierProperty
 Specifies whether the activation of an Activity is requested by modifier bindings callbacks of an ApplyAction of a DataTrigger.
 
static PropertyType< boolSaveLastFocusedNodeProperty
 Indicates whether to serialize the last focused child node of a focus scope Activity and restore the focus on deserialization.
 
static MessageType< StatusChangedMessageArgumentsStatusChangedMessage
 Subscribe to this message to receive notifications when the ActivityConcept::Status of this Activity changes.
 
static MessageType< ActivityMessageArgumentsActivityActivatingMessage
 Subscribe to this message to receive notifications when this Activity is in the activating state.
 
static MessageType< ActivityMessageArgumentsActivityActivatedMessage
 Subscribe to this message to receive notifications when this Activity is activated.
 
static MessageType< ActivityMessageArgumentsActivityDeactivatingMessage
 Subscribe to this message to receive notifications when this Activity is in the deactivating state.
 
static MessageType< ActivityMessageArgumentsActivityDeactivatedMessage
 Subscribe to this message to receive notifications when this Activity is deactivated.
 
static MessageType< StartActivationInternalMessageArgumentsStartActivationInternalMessage
 Internal message sent by an Activity Host to the Activity to initialize the resources of the Activity.
 
static MessageType< ActivityInternalMessageArgumentsStartDeactivationInternalMessage
 Internal message sent by an Activity Host to the Activity to deactivate the Activity.
 
static MessageType< StatusChangedInternalMessageArgumentsReadyForActivationAnimationInternalMessage
 Internal message sent by the Activity to its parent Activity Host when the Activity has finished initializing its resources.
 
static MessageType< ActivityInternalMessageArgumentsStartParallelActivatingAnimationInternalMessage
 Internal message sent by an Activity Host to the Activity to start the parallel activation animation of the Activity.
 
static MessageType< StatusChangedInternalMessageArgumentsFinishedParallelActivatingAnimationInternalMessage
 Internal message sent by the Activity to its parent Activity Host when the Activity has finished the parallel activation animation of the Activity.
 
static MessageType< ActivityInternalMessageArgumentsStartExclusiveActivatingAnimationInternalMessage
 Internal message sent by an Activity Host to the Activity to start the exclusive activation animation of the Activity.
 
static MessageType< ActivityInternalMessageArgumentsStartExclusiveDeactivatingAnimationInternalMessage
 Internal message sent by an Activity Host to the Activity to start the exclusive deactivation animation of the Activity.
 
static MessageType< StatusChangedInternalMessageArgumentsFinishedExclusiveDeactivatingAnimationInternalMessage
 Internal message sent by the Activity to its parent Activity Host when the Activity has finished the exclusive deactivation animation of the Activity.
 
static MessageType< ActivityInternalMessageArgumentsStartParallelDeactivatingAnimationInternalMessage
 Internal message sent by an Activity Host to the Activity to start the parallel deactivation animation of the Activity.
 
static MessageType< StatusChangedInternalMessageArgumentsFinishedParallelDeactivatingAnimationInternalMessage
 Internal message sent by the Activity to its parent Activity Host when the Activity has finished the parallel deactivation animation of the Activity.
 
- Static Protected Member Functions inherited from kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >
static PropertyTypeEditorInfoSharedPtr makeEditorInfo ()
 
- Protected Attributes inherited from kanzi::ActivityConcept
vector< string > m_pendingActivationsBeforeFocus
 The paths of the activating Activities that this Activity is waiting to be activated.
 

Detailed Description

An Activity is a part of application UI that is responsible for a task.

For example, a media player application can have Activity nodes, such as radio, music player, and AUX. However, an Activity can also be a smaller task, such as an Activity for the popup volume indicator that appears only when the user changes the volume in a media player. An Activity can be visual, but does not have to be. For example, an Activity that is visual can instantiate a prefab to show a popup window, while an Activity that is not visual can be music playback which plays music in the background regardless of other Activity nodes.

Application UI structure and navigation

The Activity, Data-Driven Exclusive Activity Host, Exclusive Activity Host, and Parallel Activity Host nodes together enable you to create the UI that user can navigate in your application. You implement the navigation as a reaction to user interaction or changes to data coming to the application, by activating and deactivating Activity nodes to switch application views and to show different application layers, such as popup windows. That way you can control which parts of your application UI the user can see and interact with.

Use the Activity, Data-Driven Exclusive Activity Host, Exclusive Activity Host, and Parallel Activity Host nodes to form the navigation graph. Activity nodes define the content elements and the Activity Host nodes define the navigation pattern in your application UI. In each Activity Host node, use Activity nodes to create UI content within applications that an Activity Host represents. When you use these nodes in your application, you navigate application UI by sending to the Activity Host node the address of the Activity node to which you want to navigate. For example, with Activity Host and Activity nodes you can organize your UI to show a different views in your application, such as media player, contacts, and phone view, and to show content in popup windows.

Use Activity Host nodes to activate and deactivate Activity nodes:

  • When an Activity node is active, the Activity prefab is attached to the node tree, is visible, and the user can interact with its content.
  • When an Activity node is inactive, the Activity prefab is not attached to the node tree, is not visible, and the user cannot interact with its content.

The Activity and Activity Host nodes inherit from the ContentLayout class to lay out their content like a Content Layout node. See ContentLayout2D and ContentLayout3D.

See ParallelActivityHost2D, ParallelActivityHost3D, ExclusiveActivityHost2D, and ExclusiveActivityHost3D.

Status management of Activity nodes

Each Activity node has the Status property that indicates the status of that Activity. When an Activity becomes active or inactive, the Status property changes and in your application you can react to these changes. You can use the Is Initially Active property to set which Activity node in an Exclusive Activity Host or Parallel Activity Host node is active at application startup. However, only one Activity node can be active at a time in a Data-Driven Exclusive Activity Host and Exclusive Activity Host nodes.

When one Activity node (Activity A) is active and you decide to activate another Activity node (Activity B), this is how the Activity status changes:

  1. Activity A goes to exclusive deactivation and, if content of the Activity B prefab is not yet loaded, Activity Host node gets a request to load the Activity B prefab and asynchronously load the content of the Activity B prefab.
  2. When the Activity B prefab is loaded, Activity A goes to parallel deactivation. Once Kanzi loads the content of the Activity B prefab, Kanzi instantiates the Activity B prefab and goes into parallel activation.
  3. Activity A becomes inactive. Kanzi virtualizes the properties of Activity A.
  4. Activity B goes to exclusive activation.

Programming

See Code behind.

Creating transitions between Activity nodes

You can create transitions for status changes of Activity nodes.

To create transitions between Activity nodes:

  1. Create a state manager and set its Controller Property to the Status property.
  2. In Activity nodes set the Status Manager property to the state manager that you created in the previous step.
  3. Create the states that map to the different statuses of Activity nodes.
  4. In the state manager define the transitions that you want to use.

Data and logic programming of Activity nodes

For each Activity node you can define properties that are specific to that Activity node. For example, Activity node for a music player can switch music on and off, or change the volume level.

When you create a property for an Activity node, set the namespace of that property to ActivityProperty. You can create properties with int, bool, float, and enum data types. If you use code behind for an Activity, Kanzi adds the properties of that Activity to the code behind.

The values of these properties implement the state machine and logic of your Kanzi application, which is why Kanzi preserves the values of these properties even when an Activity is virtual. When Kanzi virtualizes an Activity, it serializes the properties of that Activity and when Kanzi devirtualizes that Activity, it deserializes the state of that Activity and restores its property values.

Code behind

Code behind is a workflow where you associate code with an instance of an Activity instead of a type. In Kanzi Studio in the Activity Browser window, you can generate a code behind stub for any Activity node. This stub is associated with that particular Activity and has access to the properties of that Activity. In code behind you can write code that you can associate with the view or controller parts of the model-view-controller pattern. For example, you can:

  • React to Activity status changes.
  • Connect to a remote service when the Activity is activated and save data and disconnect when an Activity is deactivated.
  • Install Kanzi command handlers and define their implementations, such as increase the volume when the user presses a button.
  • Implement complex UI interaction, such as drag-and-drop of data between UI elements.
  • React to changes of status of an Activity.

Virtualization

The main goal of Activity virtualization is to enable you to manage the memory consumption in your application. The navigation graph of the entire application can be large, which is why loading and keeping in memory the UI and assets of an application at all times is rarely feasible. When either an Exclusive Activity Host or Parallel Activity Host node is available, all the child Activity nodes of that Activity Host node are available so that you can activate them. However, only the content of the Activity nodes that you activate is loaded and visible, because only a part of the UI is needed at a time. You can configure each Activity prefab how you want to manage the memory it consumes.

When you activate a visual Activity, the Activity Host of that Activity dynamically loads the prefab and asynchronously loads the content of the prefab of that Activity. When an Activity is not active, that Activity prefab is not attached to the node tree.

Member Typedef Documentation

◆ ConceptClass

Activity 2D concept used to implement this class.

Constructor & Destructor Documentation

◆ Activity2D()

kanzi::Activity2D::Activity2D ( Domain * domain,
string_view name )
explicitprotected

Constructor.

Parameters
domainThe domain the new node belongs to.
nameThe name of the node.

Member Function Documentation

◆ create()

static Activity2DSharedPtr kanzi::Activity2D::create ( Domain * domain,
string_view name )
static

Creates a 2D activity node.

Parameters
domainThe domain the new node belongs to.
nameThe name of the node.

◆ makeEditorInfo()

static PropertyTypeEditorInfoSharedPtr kanzi::Activity2D::makeEditorInfo ( )
static

Provides editor info.


The documentation for this class was generated from the following file: