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 Node.addMessageHandler() API.

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

To dispatch a single message, use Node.dispatchMessage().

Example

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

-- Create an instance of MessageType for the message type from the project.
CustomMessage = MessageType:new("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)

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: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:setHorizontalAlignment(value) ¶

Sets the value of NodeMetadata.HorizontalAlignmentProperty.

Parameters

value

(Node.HorizontalAlignment)

The new value of NodeMetadata.HorizontalAlignmentProperty.

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: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: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:removeMessageHandler(token) ¶

Removes a message subscription.

Parameters

token

(MessageSubscriptionToken)

The message subscription token that identifies the handler.