Class Node2D

Class Hierarchy

Node2D is the base class of 2D nodes.

Node2D implements functionality common to all 2D nodes, such as rendering, layouting, and hit testing.

To create UI graphs, use classes derived from Node2D, such as TextBlock2D, EmptyNode2D, and StackLayout2D.

Creating nodes

To create a 2D node, call a create function that returns an ObjectRef, which contains an owning reference to a corresponding KanziObject.

Example
-- Create an EmptyNode2D.
local emptyNodeRef = EmptyNode2D:create("Node Name")
-- Access the referenced EmptyNode2D object. This is optional, because in Lua API calls, you can use ObjectRef instead of KanziObject.
local emptyNode = emptyNodeRef:get()

Each node has its own type of create function.

Node initialization happens within the create function, after constructing the node.

Node tree

Kanzi arranges nodes in a tree that you can think of as a directed acyclic graph with no loops. Each node can have multiple children but only one parent.

The root node of the node tree is always a 2D node. The root node does not have a parent, and it is usually of type Screen.

The Viewport2D node serves as a window to a 3D scene graph that Kanzi displays in the viewport area. A Viewport2D node must have a child Scene node as the root of the 3D scene graph. The child nodes of the Scene node are Node3D nodes.

Constructing the node tree

You can manipulate the node tree by adding children to nodes:

Example
-- Add a previously created Empty Node to the context node of the script.
contextNode:addChild(emptyNode)

You can remove child nodes from a parent node.

Example
-- Remove the previously added child node from the context node of the script.
contextNode:removeChild(emptyNode)

Parents take ownership, and hold a reference to the children.

See also ObjectRef
Example
-- Release a Lua reference. Kanzi passes the ownership to the parent node.
emptyNodeRef = nil
-- The reference is kept alive by Lua until garbage collected. You can optionally force Lua garbage collection.
collectgarbage()

Iterating the node tree

You can iterate the node tree from a node by enumerating its children.

Example
local count = contextNode:getChildCount()
for i = 0, count - 1 do
    local node = contextNode:getChild(i)
    print(node:getProperty(Node.NameProperty))
end

Finding nodes

Finding nodes in the node tree is inherited from the Node base class. You can look for nodes using a path.

Example
local childNode = contextNode:lookupNode("./Child/GrandChild")

The paths a relative to the node where you perform the lookup. You can also move up the tree.

Example
local parentNode = contextNode:lookupNode("..")

If lookup fails, Kanzi returns nil.

Inherits properties and message types from Node2DMetadata.

Synopsis

Methods
addChild()

Adds a child node

insertChild()

Adds a child node for an object node to the given index

removeChild()

Removes child node

removeChildAtIndex()

Removes the child node at the given index

removeAllChildren()

Removes all child nodes

getChild()

Returns a child node at the given index

getChildCount()

Returns a total amount of child nodes

getChildIndex()

Returns the index of a child in an object node

hasChild()

Returns whether the given node is a child of this node

moveToBack()

Repositions the node as the first node of its parent, so that this child node is drawn first

moveToFront()

Repositions the node as the last node of its parent, so that the child node is drawn last

Node2D:addChild(child)

Adds a child node.

Adding a 3D node node as a child of a 2D node is only allowed when you add a Scene node to a Viewport2D node. A Screen node can have only one child that must be a 2D node.

Parameters
child (Node2D)

A node to add.

Node2D:insertChild(index, child)

Adds a child node for an object node to the given index.

Adding a 3D node node as a child of a 2D node is only allowed when you add a Scene node to a Viewport2D node. A Screen node can have only one child that must be a 2D node.

Parameters
index (number)

An index at which the child node needs to be inserted.

child (Node2D)

A node to add.

Node2D:removeChild(child)

Removes child node.

Removing a child node from the node tree can destroy the node. This makes the corresponding Lua KanziObject object stale. You cannot use stale objects in Kanzi Lua calls. If you want to keep a removed node alive after removal, create an ObjectRef for that node.

Example
-- Get the child node and create an owning reference for it.
local childNode = contextNode:lookupNode("Child")
local childNodeRef = contextNode:tryCreateReference()

-- Remove child node from the node tree.
contextNode:removeChild(childNode)

-- You still can use the child node even after removal from the node tree.
local siblingNode = contextNode:lookupNode("../Sibling")
siblingNode:addChild(childNode)
Parameters
child (Node)

A child node to remove.

Node2D:removeChildAtIndex(index)

Removes the child node at the given index.

Parameters
index (number)

An index of the child node to remove.

Node2D:removeAllChildren()

Removes all child nodes.

Node2D:getChild(index)

Returns a child node at the given index.

Parameters
index (number)

An index of the child node.

Return Values
(Node2D)

A child node at the given index.

Node2D:getChildCount()

Returns a total amount of child nodes.

Return Values
(number)

The number of child nodes of the node.

Node2D:getChildIndex(child)

Returns the index of a child in an object node.

Parameters
child (Node)

A child node whose index to retrieve.

Return Values
(number)

An index of the child node.

Node2D:hasChild(child)

Returns whether the given node is a child of this node.

Return Values
(boolean)

If the given node is a child of this node, true, otherwise false.

Node2D:moveToBack()

Repositions the node as the first node of its parent, so that this child node is drawn first.

Node2D:moveToFront()

Repositions the node as the last node of its parent, so that the child node is drawn last.