Base class for Kanzi nodes.

Messages

Use the interface provided by Node to dispatch messages and enable the nodes in the node tree to react to messages.

When you dispatch a message it travels in two phases: first tunneling, then bubbling. During the tunneling phase the message travels from the root node to the node where the message originated. From there the message bubbles back to the root node.

When you want a node to react to a message when that message passes, add message handlers to those nodes. A message handler listens only to messages from a specific source node. To register message handlers, use addMessageHandler() API.

To remove all types of handlers and filters use removeMessageHandler().

To dispatch a single message, use dispatchMessage().

Example

-- Define a message arguments class for the message.
CustomMessageArguments = MessageArguments.createMessageArgumentsClass({
    CaptionArgument = PropertyType:find("project.CaptionPropertyType")
})

-- Create an instance of MessageType for the message type from the project.
CustomMessage = MessageType:find("CustomMessage", CustomMessageArguments)

-- Define message handler function.
function handleMessage(arguments)
    -- Kanzi creates the instance of correct message arguments class and passes it to the message handler.
    print(arguments:getCaptionArgument())
end

-- Add the message handler to a node.
local token = contextNode:addMessageHandler(CustomMessage, handleMessage)

-- Dispatch message.
local args = CustomMessage:newMessageArguments()
args:setCaptionArgument("Hello Lua world!")
contextNode:dispatchMessage(CustomMessage, args)

-- Remove message handler.
contextNode:removeMessageHandler(token)

Node Components

Use node components to add functionality to a node.

Example

-- Use ClickManipulatorComponent to allow users to click nodes in your application.
local clickManipulator = ClickManipulatorComponent:create("ClickComponent")
contextNode:addNodeComponent(clickManipulator)
-- Enable HitTestable property for the Node to receive click events.
contextNode:setProperty(Node.HitTestableProperty, true)
-- Add click message handler.
contextNode:addMessageHandler(ClickManipulator.ClickMessage,
    function(args)
        print("Click!")
    end
)

To access node components owned by the node, use lookupNodeComponent(). To remove node component from a node, use removeNodeComponent().

Example

-- Find the click manipulator component previously added to the node.
local manipulatorComponent = contextNode:lookupNodeComponent("ClickComponent")
assert(manipulatorComponent)
-- Remove the click manipulator component from the node to remove the click functionality.
contextNode:removeNodeComponent(manipulatorComponent)

To iterate through all the node components owned by the node, use iterateNodeComponents().

Example

-- Iterate through node components.
for component in contextNode:iterateNodeComponents() do
    print(component:getProperty(NodeComponent.NameProperty))
end

Property types

To set node properties see KanziObject:setProperty() and KanziObject:getProperty().

Example

local objectNode = EmptyNode2D:create("TestNode")
objectNode:setProperty(Node.NameProperty, "NewTestNodeName");
objectNode:setProperty(Node.WidthProperty, 25);
objectNode:setProperty(Node.HorizontalAlignmentProperty, Node.HorizontalAlignment.HorizontalAlignmentCenter)
objectNode:setProperty(Node.HorizontalMarginProperty, Vector2(5, 7))
objectNode:setProperty(Node.VisibleProperty, false)

local name = objectNode:getProperty(Node.NameProperty)
local width = objectNode:getProperty(Node.WidthProperty)
local hAlign = objectNode:getProperty(Node.HorizontalAlignmentProperty)
local hMargin = objectNode:getProperty(Node.HorizontalMarginProperty)
local visible = objectNode:getProperty(Node.VisibleProperty)

Inherits properties and message types from NodeMetadata.

Node.Node:getName() ¶

Sets the value of NodeMetadata.NameProperty.

Return Values

(string)

Node name.

Node.Node:lookupNode(path) ¶

Returns a node by looking it up using a path or an alias. Kanzi Lua deduces the correct node type and returns an instance of the corresponding type.

Example

-- Look up a sibling node named "Text".
local siblingTextNode = contextNode:lookupNode("../Text")
-- If found, Kanzi instantiates the node, so that you can access its methods.
if siblingTextNode ~= nil then
    siblingTextNode:setText("Hello Lua world!")
end

Parameters

path

(string)

Relative path to use for lookup.

Return Values

(Node or nil)

An instance of the cooresponding node type. If node is not found, nil.

Node.Node:lookupObject(path) ¶

Lookup for an object from a node. Object found may be another node or a resource within a node. Kanzi Lua deduces the correct node type and returns an instance of the corresponding type.

Parameters

path

(string)

Relative path to use for lookup.

Return Values

(Node or nil)

Shared pointer referencing object. May be empty if no object found.

Node.Node:trySetFocus() ¶

Tries to move the focus to this node. If this node is a focus scope node, this method tries to focus the preserved focus of the focus scope, or tries to focus on the first focusable descendant node of this node.

Return Values

(Node)

If this method successfully moved focus, returns this node or a descendant node of this node. If this method did not move focus, returns nil.

Node.Node:getParent() ¶

Returns the parent of the node.

Return Values

(Node or nil)

Pointer to the parent node or nil.

Node.Node:setHorizontalAlignment(value) ¶

Sets the value of NodeMetadata.HorizontalAlignmentProperty.

Parameters

value

(Node.HorizontalAlignment)

The new value of NodeMetadata.HorizontalAlignmentProperty.

Node.Node:tryAcquireResource(resourceID) ¶

Acquires a resource from the node or its closest ancestor that has the resource ID in the resource dictionary. Kanzi Lua deduces the correct type of the Resource and returns an ObjectRef that holds an owning reference to the instance of corresponding type.

Example

-- Acquire the prefab resource and then instantiate the prefab.
local prefab = contextNode:tryAcquireResource("kzb://project/Prefabs/Caption")
local node = prefab:instantiate("Caption Node")

-- Acquire the color brush and set the background of the instantiated prefab.
local brush = contextNode:tryAcquireResource("kzb://project/Brushes/Color Brush")
node:setProperty(Node2D.BackgroundBrushProperty, brush)

Parameters

resourceID

(string)

Name of the resource.

Return Values

(ObjectRef or nil)

An ObjectRef that holds an owning reference to the instance of the corresponding type of the Resource. If the resource ID or URL do not map to any resource, nil.

Node.Node:dispatchMessage(messageType, messageArguments) ¶

Dispatches a message from this node with specified arguments.

Parameters

messageType	(MessageType)	The type of the dispatched message.
messageArguments	(MessageArguments)	The arguments of the dispatched message.

Node.Node:addMessageHandler(messageType, handler) ¶

Adds a message handler where the handler is a function. The handler is invoked when a message of messageType is signaled in the node to which you add the handler.

Message handler function accepts as parameter only the instance of the MessageArguments specific for a given messageType. To later manage message subscription, store the returned MessageSubscriptionToken.

Parameters

messageType	(MessageType)	The message type to listen to.
handler	(function)	The function invoked when the node that owns the handler receives a matching message.

Return Values

(MessageSubscriptionToken)

The MessageSubscriptionToken that identifies the added handler.

Node.Node:addMessageHandlerFromSource(messageType, messageSourceFilter, handler) ¶

Adds a message handler where the handler is a function and you explicitly define the accepted source. The handler is invoked when a message of messageType bubbles through the node to which you add the handler, but only when you dispatch it from the given source node.

Parameters

messageType	(MessageType)	The message type to listen to.
messageSourceFilter	(Node)	Source node of the messages.
handler	(function)

Return Values

(MessageSubscriptionToken)

The MessageSubscriptionToken which identifies the added handler.

Node.Node:addMessageFilter(messageType, handler) ¶

Adds a message filter where the filter is a function. The filter is invoked when a message of messageType bubbles through the node the filter is added to.

Parameters

messageType	(MessageType)	The message type to listen to.
handler	(function)

Return Values

(MessageSubscriptionToken)

The MessageSubscriptionToken which identifies the added filter.

Node.Node:addTunnelingMessageHandler(messageType, messageSourceFilter, handler) ¶

Adds a message handler where the handler is a function and you explicitly define the accepted source. The handler is invoked when a message of messageType tunnels through the node to which you add the handler, but only when you dispatch it from the given source node.

Parameters

messageType	(MessageType)	The message type to listen to.
messageSourceFilter	(Node)	Source node of the messages.
handler	(function)

Return Values

(MessageSubscriptionToken)

The MessageSubscriptionToken which identifies the added handler.

Node.Node:addTunnelingMessageFilter(messageType, handler) ¶

Adds a message filter where the filter is a function. The filter is invoked when a message of messageType tunnels through the node to which you add this filter.

Parameters

messageType	(MessageType)	The message type to listen to.
handler	(function)

Return Values

(MessageSubscriptionToken)

The MessageSubscriptionToken which identifies the added filter.

Node.Node:removeMessageHandler(token) ¶

Removes a message subscription.

Parameters

token

(MessageSubscriptionToken)

The message subscription token that identifies the handler.

Node.Node:addNodeComponent(nodeComponent) ¶

Transfers the ownership of a node component to an object node.

Parameters

nodeComponent

(NodeComponent)

The node component to be added to the node.

Node.Node:removeNodeComponent(nodeComponent) ¶

Removes the ownership of a node component from an object node.

Parameters

nodeComponent

(NodeComponent)

The node component to be removed from the node.

Node.Node:lookupNodeComponent(name) ¶

Returns a node component with the specified name that is owned by the node.

Parameters

name

(string)

The name of the node component.

Return Values

(NodeComponent or nil)

The NodeComponent with the specified name that is owned by the node, or nil if none is found.

Node.Node:iterateNodeComponents() ¶

Returns an iterator used to iterate over node components owned by this node.

Node.Node:addInputManipulator(inputManipulator) ¶

Transfers the ownership and attaches an input manipulator to an object node.

Parameters

inputManipulator

(InputManipulator)

The input manipulator to add.

Node.Node:removeInputManipulator(inputManipulator) ¶

Removes the ownership and detaches an input manipulator from an object node.

Parameters

inputManipulator

(InputManipulator)

The input manipulator to remove.

Node.Node:isNamed(name) ¶

Checks if the node has the given name. \param name Name to compare against.

Parameters

name

(string)

Name to compare against.

Return Values

(boolean)

If the name matches true, false otherwise.

Node.Node:isEffectivelyVisible() ¶

Returns whether a node and its ancestor nodes are visible.

Return Values

(boolean)

Node.Node:isEffectivelyEnabled() ¶

Returns the value of NodeMetadata.EffectivelyEnabledProperty.

Return Values

(boolean)

Node.Node:isEffectivelyFocusable() ¶

Returns whether a node is focusable. A node is focusable when it is a focus scope node or has FocusableProperty attached and set to true, or both.

Return Values

(boolean)

If the node is focusable, returns true, otherwise false.

Node.Node:isInitialized() ¶

Gets the initialized status.

Return Values

(boolean)

true if initialize() has been called, false otherwise.

Node.Node:isAttached() ¶

Gets the attached status.

Return Values

(boolean)

true if the node is attached to a screen or one of its descendants, false otherwise.

Node.Node:isAttaching() ¶

Gets the attaching status.

Return Values

(boolean)

true if node is currently in the process of attaching, false otherwise.

Node.Node:isDetaching() ¶

Gets the detaching status.

Return Values

(boolean)

true if the node currently in the process of detaching, false otherwise.

Node.Node:addAbstractChild(child) ¶

Transfers the ownership and attaches an input manipulator to an object node.

Parameters

child

(Node)

The node to add as a child.

Return Values

(boolean)

Node.Node:getAbstractChildCount() ¶

Return Values

(number)

Node.Node:getAbstractChildIndex(child) ¶

Parameters

child

(Node)

Return Values

(number)

Node.Node:getAbstractChild(index) ¶

Parameters

index

(number)

Return Values

(Node)

Node.Node:removeAbstractChild(child) ¶

Parameters

child

(Node)

Return Values

(boolean)

Node.Node:getChangeFlags() ¶

Get current change flags.

Return Values

(number)

Change flags directly.

Node.Node:getChildChangeFlags() ¶

Get current child change flags.

Return Values

(number)

Child change flags directly.

Node.Node:setChangeFlag(flag) ¶

Sets a change flag.

Parameters

flag

(number)

Node.Node:clearChangeFlag(flag) ¶

Clears a change flag.

Parameters

flag

(number)

Node.isValidLayoutValue(value) ¶

Indicates whether a value is valid layout value. Valid layout value is a non-negative floating point number. Valid layout value can be positive infinity (unbounded layout value).

Parameters

value

(number)

Value to test if it is unbound layout value.

Return Values

(boolean)

true if the value if valid layout value, false otherwise.

Node.unboundedLayoutValue() ¶

Returns an unbounded layout value.

Return Values

(number)

Unbounded layout value.

Node.isUnboundedLayoutValue(layoutValue) ¶

Indicates whether a value is an unbound layout value.

Parameters

layoutValue

(number)

Value to test if it is unbound layout value.

Return Values

(boolean)

true if the layoutValue is unbound layout value, false otherwise.