kanzi::ExclusiveActivityHost2D Class Reference

An Activity Host that displays Activity nodes one at a time. More...

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

Inheritance diagram for kanzi::ExclusiveActivityHost2D:

Public Types
using	ConceptClass
	Exclusive Activity Host 2D concept used to implement this class.
Public Types inherited from kanzi::ActivityHostConcept
enum class	ActivationStatus { PreparingForActivation , ParallelAnimation , ExclusiveAnimation }
	Specifies possible stages for internal tracking of activation of an Activity. More...
using	ActivityInfoContainer
enum class	DeactivationStatus { ExclusiveAnimation , ParallelAnimation , WaitingForRelease }
	Specifies possible stages for internal tracking of deactivation of an Activity. More...
Public Types inherited from kanzi::ExclusiveActivityHostConcept
enum class	ExclusiveActivityHostFocusingPolicy { WhenHostHasFocus , AlwaysFocus , NeverFocus }
	Specifies the focusing policy that Kanzi applies to an activating Activity in an Exclusive Activity Host. More...

Static Public Member Functions
static ExclusiveActivityHost2DSharedPtr	create (Domain *domain, string_view name)
	Creates a 2D Exclusive Activity Host node.
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()
Static Public Member Functions inherited from kanzi::ExclusiveActivityHostImpl< ContentLayout2D, ExclusiveActivityHost2D >
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::ActivityHostConcept
template<typename Type >
static bool	isActivityHost (const Type &object)
	Determines if an object is an ActivityHost.
static bool	isActivityHostMetaclass (const Metaclass *metaclass)
	Checks whether the given Metaclass is an ActivityHostConcept metaclass or contains it as a mixin metaclass.
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()
Static Public Member Functions inherited from kanzi::ExclusiveActivityHostConcept
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()
	Returns PropertyType editor info of exclusive activity concept.
Static Public Member Functions inherited from kanzi::ValueControlledExclusiveActivityHostConcept
static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()
	Provides the editor information to Kanzi Studio.

Protected Member Functions
	ExclusiveActivityHost2D (Domain *domain, string_view name)
	Constructor.
Protected Member Functions inherited from kanzi::ExclusiveActivityHostImpl< ContentLayout2D, ExclusiveActivityHost2D >
void	addBindingRuntime (AbstractBindingRuntimeSharedPtr entry) final
	ExclusiveActivityHostConcept::addBindingRuntime implementation;.
	ExclusiveActivityHostImpl (Domain *domain, string_view name)
	Constructor.
string	getInputProviderPath () const override
	ValueControlledExclusiveActivityHostConcept::getInputProviderPath implementation.
void	onAttachedOverride () override
	Overrides onAttached method.
void	onDetached () override
	Node::onDetached implementation.
void	onNodePropertyChanged (AbstractPropertyType propertyType, PropertyNotificationReason reason) override
	Node::onNodePropertyChanged implementation.
Protected Member Functions inherited from kanzi::ExclusiveActivityHostBaseImpl< TBaseClass, TDerivedClass >
void	activate (const ActivityHostConcept::ActivityInfo &activity)
	Requests the ExclusiveActivityHost to activate an Activity node.
void	activate (const ActivityHostConcept::ActivityInfo &activity, string_view activationPath)
	Requests the ExclusiveActivityHost to activate an Activity node, and to forward the activation path to activate the children of the Activity node, if the Activity node is already active or activating.
void	deactivate ()
	Requests the ExclusiveActivityHost to deactivate the currently active Activity node.
	ExclusiveActivityHostBaseImpl (Domain *domain, string_view name)
	Constructor.
vector< string >	getActivatingNames () override
	ActivityHostConcept::getActivatingNames implementation.
string	getActiveOrActivatingName () const
	Gets the currently active or activating Activity node.
vector< NodeWeakPtr >	getActiveOrAttachedActivating () override
	ActivityHostConceptImpl::getActiveOrAttachedActivating implementation.
optional< ActivityHostConcept::ActivityInfo >	getActivityInfo (string_view name) const override
	ActivityHostConceptImpl::getActivityInfo implementation.
vector< NodeWeakPtr >	getAttachedActivityNodes () override
	ActivityHostConceptImpl::getAttachedActivityNodes implementation.
void	initialize ()
	Initializes this exclusive activity host.
template<typename Iterator >
string	nextToActivate (Iterator iterBegin, Iterator iterEnd, string_view current, bool looping) const
	Calculates which Activity node is going to be activated if the current active Activity node deactivates.
void	onActivateActivityOverride (string_view activationPath, bool resetHistory) override
	ActivityHostConcept::onActivateActivityOverride implementation.
void	onActivityActivated (NodeSharedPtr activity, string_view prefabPath) override
	ExclusiveActivityHostConcept::onActivityActivated implementation.
void	onActivityDeactivated (NodeSharedPtr activity) override
	ExclusiveActivityHostConcept::onActivityDeactivated implementation.
void	onDetached () override
	Node::onDetached implementation.
void	onNodePropertyChanged (AbstractPropertyType propertyType, PropertyNotificationReason reason) override
	Node::onNodePropertyChanged implementation.
void	resolveFocusWithPolicy (Node &activityNode) override
	ActivityHostConcept::resolveFocusWithPolicy implementation.
virtual	~ExclusiveActivityHostBaseImpl ()=default
	Destructor.
Protected Member Functions inherited from kanzi::ActivityHostConceptImpl< TBaseClass, TDerivedClass >
	ActivityHostConceptImpl (Domain *domain, string_view name)
	Constructor.
void	clearCurrentActivationTarget () const
	Clears current activation target.
void	initialize ()
	Initializes this Activity Host Concept.
void	registerInParentActivityElement () final
	ActivityElement::registerInParentActivityElement implementation.
void	resolveFocusOnActivated (Node &activityNode)
	Performs the necessary operations to fix the application focus when an Activity has activated in this Activity Host.
void	unregisterInParentActivityElement () final
	ActivityElement::unregisterInParentActivityElement implementation.
virtual	~ActivityHostConceptImpl ()=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.
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.
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::ExclusiveActivityHostImpl< ContentLayout2D, ExclusiveActivityHost2D >
void	deserialize (string_view data) override
	ActivityElement::deserialize implementation.
const vector< ExclusiveActivityHostConcept::ActivityInExclusiveHostInfo > &	getActivitiesInfo () const override
	ValueControlledExclusiveActivityHostConcept::getActivitiesInfo implementation.
PropertyDataType	getControllerInputType () const override
	ValueControlledExclusiveActivityHostConcept::getControllerInputType implementation.
const Node *	getNode () const override
	ValueControlledExclusiveActivityHostConcept::getNode const implementation.
Node *	getNode () override
	ValueControlledExclusiveActivityHostConcept::getNode const implementation.
Public Member Functions inherited from kanzi::ExclusiveActivityHostBaseImpl< TBaseClass, TDerivedClass >
void	onFinishedExclusiveDeactivatingAnimationInternal (const ActivityConcept::StatusChangedInternalMessageArguments &args)
	Message handler for FinishedExclusiveDeactivatingAnimationInternal message.
void	onFinishedParallelActivatingAnimationInternal (const ActivityConcept::StatusChangedInternalMessageArguments &args)
	Message handler for FinishedParallelActivatingAnimationInternal message.
void	onFinishedParallelDeactivatingAnimationInternal (const ActivityConcept::StatusChangedInternalMessageArguments &args)
	Message handler for FinishedParallelDeactivatingAnimationInternal message.
NodeSharedPtr	onPrefabLoaded (PrefabTemplateSharedPtr prefabTemplate, string_view activityName) override
	ExclusiveActivityHostConcept::onPrefabLoaded implementation.
void	setActivationModifier (string_view activityName, BindingTokenWeakPtr weakModifier) override
	ActivityHostConcept::setActivationModifier implementation.
Public Member Functions inherited from kanzi::ActivityHostConceptImpl< TBaseClass, TDerivedClass >
void	notifyChildrenNodeTreeAvailable () override
	ActivityElement::notifyChildrenNodeTreeAvailable implementation.
string	serialize () override
	ActivityElement::serialize implementation.
Public Member Functions inherited from kanzi::ActivityElement
vector< NodeSharedPtr >::const_iterator	beginChildHosts () const
	Returns the begin iterator to the registered child Activity Host.
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::ActivityHostConcept
virtual	~ActivityHostConcept ()=default
	Destructor.
Public Member Functions inherited from kanzi::ExclusiveActivityHostConcept
virtual	~ExclusiveActivityHostConcept ()=default
	Destructor.
Public Member Functions inherited from kanzi::ValueControlledExclusiveActivityHostConcept
virtual	~ValueControlledExclusiveActivityHostConcept ()=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::ActivityHostConcept
static MessageType< ActivationMessageArguments >	ActivateActivityMessage
	You can send ActivateActivity to the Activity Host to activate an Activity.
static MessageType< ActivationMessageArguments >	DeactivateActivityMessage
	You can send DeactivateActivity to the Activity Host to deactivate an Activity.
static MessageType< ActivityPrefabMessageArguments >	ActivityPrefabAttachedMessage
	An Activity Host sends this message when it attaches the prefab of the Activity that is activated.
static MessageType< ActivityPrefabMessageArguments >	ActivityPrefabDetachedMessage
	An Activity Host sends this message when it attaches the prefab of the Activity that is activated.
static MessageType< RegisterActivityElementInternalMessageArguments >	RegisterHostInternalMessage
	Internal message sent by an Activity Host to its parent Activity or Activity Host to register the Activity Host in the parent.
static MessageType< UnregisterActivityElementInternalMessageArguments >	UnregisterHostInternalMessage
	Internal message sent by an Activity Host to its parent Activity or Activity Host to unregister the Activity Host from the parent.
Static Public Attributes inherited from kanzi::ExclusiveActivityHostConcept
static MessageType< ImplicitActivityChangeRequestMessageArguments >	NavigateNextMessage
	In an Exclusive Activity Host requests the activation of the next Activity node in that Exclusive Activity Host node.
static MessageType< ImplicitActivityChangeRequestMessageArguments >	NavigatePreviousMessage
	In an Exclusive Activity Host requests the activation of the previous Activity node in that Exclusive Activity Host node.
static PropertyType< string >	ExclusiveActivityHostContentProperty
	Describes the content of an Exclusive Activity Host node.
static PropertyType< string >	ActiveActivityProperty
	The name of the child Activity node of an Exclusive Activity Host, that is either in ActivityConcept::Status::Active or in ActivityConcept::Status::Activating state.
static PropertyType< string >	ActivationPathProperty
	The activation path containing the branch of the Activity tree that is requested to be activated.
static PropertyType< ExclusiveActivityHostFocusingPolicy >	FocusOnActivatingActivityProperty
	Sets the policy that an Exclusive Activity Host uses to decide whether it tries to set focus to an activating Activity.
Static Public Attributes inherited from kanzi::ValueControlledExclusiveActivityHostConcept
static PropertyType< string >	ControllerProperty
	Sets the property type that the Exclusive Activity host uses to switch between its child Activities.
static PropertyType< string >	DataSourceControllerPropertyPathProperty
	Sets the path in the DataSource object of an Exclusive Activity Host to a DataObject item that Exclusive Activity Host uses as the ControllerProperty.
Protected Attributes inherited from kanzi::ActivityHostConceptImpl< TBaseClass, TDerivedClass >
string	m_activationTarget
	The name of the Activity that is the candidate to be the activation target.
bool	m_deserializing
	Indicates that this Activity Host is performing property deserialization.
bool	m_hostHadFocus
	Indicates that the Activity Host had focus before it started to activate new activation target Activity.

Detailed Description

An Activity Host that displays Activity nodes one at a time.

An Activity Host node defines the rules for when its Activity nodes are active. Kanzi has these Activity Host nodes:

• Data-Driven Exclusive Activity Host and Exclusive Activity Host nodes can have only one of its child Activity nodes active at a time. When one child Activity node of a Data-Driven Exclusive Activity Host or an Exclusive Activity Host node is active, all other Activity nodes of that Activity Host node are inactive.

  For example, you can use a Data-Driven Exclusive Activity Host or an Exclusive Activity Host node to toggle between views in your application.

  See DataDrivenExclusiveActivityHost2D and DataDrivenExclusiveActivityHost3D.

• Parallel Activity Host node can activate more than one of its child Activity nodes at a time.

  See ParallelActivityHost2D and ParallelActivityHost3D.

For example, you can use an Exclusive Activity Host node to toggle between views in your application.

You can add Activity nodes to an Activity Host node in real-time. This enables you to use the Kanzi Engine API to generate Activity nodes or to add to the application another application for which the structure of Activity nodes is not known until you run the application. For example, you can use the API to generate a large number of menu pages that you want to show to the user.

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 Activity2D and Activity3D.

Controlling Activity nodes in an Exclusive Activity Host node

The type of the Activity Host node determines the way you control its child Activity nodes. When you use an Exclusive Activity Host node, you can control its Activity nodes using:

• Implicit state control. You can enable navigation with keys and touch that implicitly controls which Activity nodes are active and inactive.
• Explicit state control. To activate an Activity node explicitly, use one of these approaches:
  • Direct value matching. In an Exclusive Activity Host node set the ValueControlledExclusiveActivityHostConcept::ControllerProperty to the property whose value you want to match to activate Activity nodes and in each child Activity node set the unique value of that property. When the value of the ValueControlledExclusiveActivityHostConcept::ControllerProperty matches the value of the property that you set in an Activity node, the Exclusive Activity Host node activates that Activity node.

  • Synchronize the activation of an Activity node with your logic:

    1. In an Activity Host node create a DataTrigger.
    2. In the DataTrigger add a condition expression which evaluates to true or false, and which uses as input either Properties or a Data Source.
    3. Add to the DataTrigger either:
       • An ApplyActivationAction where you set the ApplyActivationAction::ActivationPathProperty to the Activity node that you want to activate.
       • An ApplyPropertyAction where you set the ValueControlledExclusiveActivityHostConcept::ControllerProperty to the controller property that you use to control the activation of Activity nodes in that Exclusive Activity Host node.

    The Activity node stays active as long as the condition expression in the DataTrigger evaluates to true. When the condition in the DataTrigger is no longer true, Kanzi reverts the activation. When using this approach, keep in mind that actions of a DataTrigger have higher priority than the actions of any other Trigger. See DataTrigger, ApplyPropertyAction, and ApplyActivationAction.

  • Activate an Activity node with an ActivateActivityMessage:

    1. In an Activity Host node create a Trigger.
    2. Add to the Trigger an ActivateActivityMessage to activate an Activity node.
    3. Add to the Trigger a condition that, when met, sets off the ActivateActivityMessage.

    When using this approach, keep in mind that actions of a DataTrigger have higher priority than the actions of any other Trigger. For example, if you use a DataTrigger with an ApplyActivationAction to activate an Activity node and you use any other Trigger to send an ActivateActivityMessage, the effect of the ActivateActivityMessage becomes visible only after Kanzi unapplies the ApplyActivationAction. See Trigger.

Data and logic programming of Activity nodes

For each Exclusive Activity Host node you can define properties that are specific to that Exclusive Activity Host node. For example, Exclusive Activity Host node for a music player keeps currently selected player type.

When you create a property for an Exclusive Activity Host node, set the namespace of that property to Activity Property. You can create properties with int, bool, float, and enum data types. If you use code behind for an Exclusive Activity Host, Kanzi adds the properties of that Exclusive Activity Host 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 Exclusive Activity Host is virtual. When Kanzi virtualizes an Exclusive Activity Host, it serializes the properties of that Exclusive Activity Host and when Kanzi devirtualizes that Exclusive Activity Host, it deserializes the state of that Exclusive Activity Host and restores its property values.

Code behind

Code behind is a workflow where you associate code with an instance of an Exclusive Activity Host instead of a type. In Kanzi Studio in the Activity Browser window, you can generate a code behind stub for any Exclusive Activity Host node. This stub is associated with that particular Exclusive Activity Host and has access to the properties of that Exclusive Activity Host. 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:

• Connect to a remote service when the Exclusive Activity Host is instantiated and attached.
• 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.

Member Typedef Documentation

ConceptClass

using kanzi::ExclusiveActivityHost2D::ConceptClass

Exclusive Activity Host 2D concept used to implement this class.

Constructor & Destructor Documentation

ExclusiveActivityHost2D()

kanzi::ExclusiveActivityHost2D::ExclusiveActivityHost2D ( 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 ExclusiveActivityHost2DSharedPtr kanzi::ExclusiveActivityHost2D::create ( Domain * domain, string_view name )

static

Creates a 2D Exclusive Activity Host node.

Parameters

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

makeEditorInfo()

static PropertyTypeEditorInfoSharedPtr kanzi::ExclusiveActivityHost2D::makeEditorInfo ( )

static

---

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

• kanzi/ui/node/exclusive_activity_host2d.hpp