Node3D
¶
Node3D is the base class of 3D nodes.
Node3D implements functionality common to all 3D nodes, such as rendering, layouting, and hit testing.
To create UI graphs, use classes derived from Node3D, such as TextBlock3D, EmptyNode3D, and StackLayout3D.
To create a 3D node, call a create function that returns an ObjectRef, which contains an owning reference to a corresponding KanziObject.
-- Create an EmptyNode3D.
local emptyNodeRef = EmptyNode3D:create("Node Name")
-- Access the referenced EmptyNode3D 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.
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.
You can manipulate the node tree by adding children to nodes:
-- 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.
-- 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.
-- 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()
You can iterate the node tree from a node by enumerating its children.
local count = contextNode:getChildCount()
for i = 0, count - 1 do
local node = contextNode:getChild(i)
print(node:getProperty(Node.NameProperty))
end
Finding nodes in the node tree is inherited from the Node base class. You can look for nodes using a path.
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.
local parentNode = contextNode:lookupNode("..")
If lookup fails, Kanzi returns nil.
Inherits properties and message types from Node3DMetadata.
| 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 |
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.
| child | (Node3D) | A node to add. |
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.
| index | (number) | An index at which the child node needs to be inserted. |
| child | (Node3D) | A node to add. |
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.
-- 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)
| child | (Node) | A child node to remove. |
Removes the child node at the given index.
| index | (number) | An index of the child node to remove. |
Removes all child nodes.
Returns a child node at the given index.
| index | (number) | An index of the child node. |
| (Node3D) | A child node at the given index. |
Returns a total amount of child nodes.
| (number) | The number of child nodes of the node. |
Returns the index of a child in an object node.
| child | (Node) | A child node whose index to retrieve. |
| (number) | An index of the child node. |
Returns whether the given node is a child of this node.
| (boolean) | If the given node is a child of this node, true, otherwise false. |
Repositions the node as the first node of its parent, so that this child node is drawn first.
Repositions the node as the last node of its parent, so that the child node is drawn last.