Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/tree.h.md	Thu Mar 27 18:24:09 2025 +0100
+++ b/docs/Writerside/topics/tree.h.md	Fri Mar 28 21:51:31 2025 +0100
@@ -27,6 +27,10 @@
 The macro `cx_tree_node_base_layout` expands to the offsets of the above-mentioned pointers.
 It will become handy when calling the low-level tree functions which expect all offsets to be passed as arguments. 
 
+<warning>
+TODO: forgot to mention that loc_last_child and loc_prev are optional in all functions.
+</warning>
+
 Before diving into the function definitions, there are four function pointer declarations you should know.
 
 ```C
@@ -58,8 +62,9 @@
 In combination with the `cx_tree_node_create_func`, when inserting nodes with the high-level functions, a `new_node` is created first,
 and then an appropriate insertion point is searched with the `cx_tree_search_func`.
 
-A `cx_tree_relink_func` is used when an intermediate node is removed from the tree and it's children need to be detached from
+A `cx_tree_relink_func` is called when an intermediate node was removed from the tree and it's children need to be detached from
 the removed `old_parent` and attached to a `new_parent`.
+The function is called for every child of the removed node and can be used, for example, to update the contents of the node when needed.
 
 ## Create
 
@@ -256,9 +261,18 @@
 void cxTreeRemoveSubtree(CxTree *tree, void *node);
 ```
 
-<warning>
-TODO: document
-</warning>
+The low-level function `cx_tree_unlink()` removes the specified `node`,
+as well as the entire subtree beneath that node, from its parent.
+The high-level counterpart is `cxTreeRemoveSubtree()`.
+
+The function `cxTreeRemoveNode()`, on the other hand, _only_ removes the `node` from the tree,
+links all children of `node` to the former parent of `node`, 
+and calls the optional `relink_func` for every former child of `node` which will be relinked to a new parent.
+Therefore, calling `cxTreeRemoveNode()` on the `root` node is an error and the function returns non-zero.
+In all other cases, the function returns zero.
+
+> When your tree is storing a scene graph, for example, a possible use-case for the `relink_func` might be updating
+> the world transform matrices in the subtree of the removed node. 
 
 ## Dispose
 
@@ -275,9 +289,24 @@
 void cxTreeFree(CxTree *tree);
 ```
 
-<warning>
-TODO: document and mention the destructor support
-</warning>
+The function `cxTreeDestroyNode()` first [removes](#remove) the `node` from the tree, like `cxTreeRemoveNode()`,
+and then invokes the [destructor functions](collection.h.md#destructor-functions).
+It is guaranteed, that the simple destructor is called before the advanced destructor.
+If no destructor function is registered at all, the behavior is identical to `cxTreeRemoveNode()`.
+That means, this function does not deallocate the memory for the node on its own and leaves that entirely to the destructor functions.
+
+The function `cxTreeDestroySubtree()` performs the above actions for the entire subtree starting with `node`.
+The order in which the destructor functions for the nodes of the subtree are called are determined by a [tree iterator](#iterator-and-visitor).
+
+The function `cxTreeClear()` is a shorthand for invoking `cxTreeDestroySubtree()` on the root node of the tree.
+
+The function `cxTreeFree()` behaves like `cxTreeClear()` and then deallocates the memory for the `CxTree` structure.
+
+> Although `CxTree` supports the general concept of [destructor functions](collection.h.md#destructor-functions),
+> it is not based on `CX_COLLECTION_BASE`.
+> Therefore, the `cxDefineDestructor()` and `cxDefineAdvancedDestructor()` macros cannot be used on a `CxTree` and
+> the fields must be set manually.
+>{style="note"}
 
 <seealso>
 <category ref="apidoc">