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

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

Inheritance diagram for kanzi::Activity3D:

Public Types
using	ConceptClass
	Activity 3D 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 Activity3DSharedPtr	create (Domain *domain, string_view name)
	Creates a 3D activity node.

static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()

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
	Activity3D (Domain *domain, string_view name)
	Constructor.

Protected Member Functions inherited from kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >
	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::ActivityID >	getActivityID () 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< ContentLayout3D, Activity3D >
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 Node *	getNode () const override
	Gets the underlying Node object.

Node *	getNode () override
	Gets the underlying Node object.

ActivityConcept *	getParentActivity () 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 Node *	getNode () const override
	Gets the underlying Node object.

Node *	getNode () 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.

Node *	findChildHost (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.

ActivityHistoryManager *	getHistoryManager () const
	Gets the history manager of this activity element.

ActivityElement *	getParentElement ()
	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< bool >	AttachedProperty

static PropertyType< bool >	PreserveHistoryProperty
	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< Status >	StatusProperty
	Specifies the status of this Activity.

static PropertyType< float >	DummyStateManagerProperty
	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< bool >	ActivatedByActivationModifierProperty
	Specifies whether the activation of an Activity is requested by modifier bindings callbacks of an ApplyAction of a DataTrigger.

static PropertyType< bool >	SaveLastFocusedNodeProperty
	Indicates whether to serialize the last focused child node of a focus scope Activity and restore the focus on deserialization.

static MessageType< StatusChangedMessageArguments >	StatusChangedMessage
	Subscribe to this message to receive notifications when the ActivityConcept::Status of this Activity changes.

static MessageType< ActivityMessageArguments >	ActivityActivatingMessage
	Subscribe to this message to receive notifications when this Activity is in the activating state.

static MessageType< ActivityMessageArguments >	ActivityActivatedMessage
	Subscribe to this message to receive notifications when this Activity is activated.

static MessageType< ActivityMessageArguments >	ActivityDeactivatingMessage
	Subscribe to this message to receive notifications when this Activity is in the deactivating state.

static MessageType< ActivityMessageArguments >	ActivityDeactivatedMessage
	Subscribe to this message to receive notifications when this Activity is deactivated.

static MessageType< StartActivationInternalMessageArguments >	StartActivationInternalMessage
	Internal message sent by an Activity Host to the Activity to initialize the resources of the Activity.

static MessageType< ActivityInternalMessageArguments >	StartDeactivationInternalMessage
	Internal message sent by an Activity Host to the Activity to deactivate the Activity.

static MessageType< StatusChangedInternalMessageArguments >	ReadyForActivationAnimationInternalMessage
	Internal message sent by the Activity to its parent Activity Host when the Activity has finished initializing its resources.

static MessageType< ActivityInternalMessageArguments >	StartParallelActivatingAnimationInternalMessage
	Internal message sent by an Activity Host to the Activity to start the parallel activation animation of the Activity.

static MessageType< StatusChangedInternalMessageArguments >	FinishedParallelActivatingAnimationInternalMessage
	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< ActivityInternalMessageArguments >	StartExclusiveActivatingAnimationInternalMessage
	Internal message sent by an Activity Host to the Activity to start the exclusive activation animation of the Activity.

static MessageType< ActivityInternalMessageArguments >	StartExclusiveDeactivatingAnimationInternalMessage
	Internal message sent by an Activity Host to the Activity to start the exclusive deactivation animation of the Activity.

static MessageType< StatusChangedInternalMessageArguments >	FinishedExclusiveDeactivatingAnimationInternalMessage
	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< ActivityInternalMessageArguments >	StartParallelDeactivatingAnimationInternalMessage
	Internal message sent by an Activity Host to the Activity to start the parallel deactivation animation of the Activity.

static MessageType< StatusChangedInternalMessageArguments >	FinishedParallelDeactivatingAnimationInternalMessage
	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< ContentLayout3D, Activity3D >
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:

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.
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.
Activity A becomes inactive. Kanzi virtualizes the properties of Activity A.
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:

Create a state manager and set its Controller Property to the Status property.
In Activity nodes set the Status Manager property to the state manager that you created in the previous step.
Create the states that map to the different statuses of Activity nodes.
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

using kanzi::Activity3D::ConceptClass

Activity 3D concept used to implement this class.

Constructor & Destructor Documentation

◆ Activity3D()

kanzi::Activity3D::Activity3D	(	Domain *	domain,
		string_view	name )

explicitprotected

Constructor.

Parameters

domain	The domain the new node belongs to.
name	The name of the node.

Member Function Documentation

◆ create()

static Activity3DSharedPtr kanzi::Activity3D::create	(	Domain *	domain,
		string_view	name )

static

Creates a 3D activity node.