Improve TreeItem API and allow to move nodes

doc/classes/Tree.xml

@@ -30,7 +30,7 @@
 		}
 		[/csharp]
 		[/codeblocks]
-		To iterate over all the [TreeItem] objects in a [Tree] object, use [method TreeItem.get_next] and [method TreeItem.get_children] after getting the root through [method get_root]. You can use [method Object.free] on a [TreeItem] to remove it from the [Tree].
+		To iterate over all the [TreeItem] objects in a [Tree] object, use [method TreeItem.get_next] and [method TreeItem.get_first_child] after getting the root through [method get_root]. You can use [method Object.free] on a [TreeItem] to remove it from the [Tree].
 	</description>
 	<tutorials>
 	</tutorials>

doc/classes/TreeItem.xml

@@ -63,6 +63,16 @@
 				Removes all OpenType features.
 			</description>
 		</method>
+		<method name="create_child">
+			<return type="TreeItem">
+			</return>
+			<argument index="0" name="idx" type="int" default="-1">
+			</argument>
+			<description>
+				Creates an item and adds it as a child.
+				The new item will be inserted as position [code]idx[/code] (the default value [code]-1[/code] means the last position), or it will be the last child if [code]idx[/code] is higher than the child count.
+			</description>
+		</method>
 		<method name="deselect">
 			<return type="void">
 			</return>
@@ -123,11 +133,28 @@
 				Returns the column's cell mode.
 			</description>
 		</method>
-		<method name="get_children">
+		<method name="get_child">
 			<return type="TreeItem">
 			</return>
+			<argument index="0" name="idx" type="int">
+			</argument>
+			<description>
+				Returns a child item by its index (see [method get_child_count]). This method is often used for iterating all children of an item.
+				Negative indices access the children from the last one.
+			</description>
+		</method>
+		<method name="get_child_count">
+			<return type="int">
+			</return>
 			<description>
-				Returns the TreeItem's first child item or a null object if there is none.
+				Returns the number of child items.
+			</description>
+		</method>
+		<method name="get_children">
+			<return type="Array">
+			</return>
+			<description>
+				Returns an array of references to the item's children.
 			</description>
 		</method>
 		<method name="get_custom_bg_color" qualifiers="const">
@@ -157,6 +184,13 @@
 				Returns [code]true[/code] if [code]expand_right[/code] is set.
 			</description>
 		</method>
+		<method name="get_first_child">
+			<return type="TreeItem">
+			</return>
+			<description>
+				Returns the TreeItem's first child.
+			</description>
+		</method>
 		<method name="get_icon" qualifiers="const">
 			<return type="Texture2D">
 			</return>
@@ -193,6 +227,13 @@
 				Returns the icon [Texture2D] region as [Rect2].
 			</description>
 		</method>
+		<method name="get_index">
+			<return type="int">
+			</return>
+			<description>
+				Returns the node's order in the tree. For example, if called on the first child item the position is [code]0[/code].
+			</description>
+		</method>
 		<method name="get_language" qualifiers="const">
 			<return type="String">
 			</return>
@@ -342,6 +383,13 @@
 				Returns the given column's tooltip.
 			</description>
 		</method>
+		<method name="get_tree">
+			<return type="Tree">
+			</return>
+			<description>
+				Returns the [Tree] that owns this TreeItem.
+			</description>
+		</method>
 		<method name="is_button_disabled" qualifiers="const">
 			<return type="bool">
 			</return>
@@ -397,18 +445,24 @@
 				Returns [code]true[/code] if column [code]column[/code] is selected.
 			</description>
 		</method>
-		<method name="move_to_bottom">
+		<method name="move_after">
 			<return type="void">
 			</return>
+			<argument index="0" name="item" type="Object">
+			</argument>
 			<description>
-				Moves this TreeItem to the bottom in the [Tree] hierarchy.
+				Moves this TreeItem right after the given [code]item[/code].
+				[b]Note:[/b] You can't move to the root or move the root.
 			</description>
 		</method>
-		<method name="move_to_top">
+		<method name="move_before">
 			<return type="void">
 			</return>
+			<argument index="0" name="item" type="Object">
+			</argument>
 			<description>
-				Moves this TreeItem to the top in the [Tree] hierarchy.
+				Moves this TreeItem right before the given [code]item[/code].
+				[b]Note:[/b] You can't move to the root or move the root.
 			</description>
 		</method>
 		<method name="remove_child">

editor/action_map_editor.cpp

@@ -122,9 +122,9 @@ void InputEventConfigurationDialog::_set_event(const Ref<InputEvent> &p_event) {
 
 		// Update selected item in input list for keys, joybuttons and joyaxis only (since the mouse cannot be "listened" for).
 		if (k.is_valid() || joyb.is_valid() || joym.is_valid()) {
-			TreeItem *category = input_list_tree->get_root()->get_children();
+			TreeItem *category = input_list_tree->get_root()->get_first_child();
 			while (category) {
-				TreeItem *input_item = category->get_children();
+				TreeItem *input_item = category->get_first_child();
 
 				// has_type this should be always true, unless the tree structure has been misconfigured.
 				bool has_type = input_item->get_parent()->has_meta("__type");

editor/animation_track_editor.cpp

@@ -5216,7 +5216,7 @@ void AnimationTrackEditor::_edit_menu_pressed(int p_option) {
 			track_clipboard.clear();
 			TreeItem *root = track_copy_select->get_root();
 			if (root) {
-				TreeItem *it = root->get_children();
+				TreeItem *it = root->get_first_child();
 				while (it) {
 					Dictionary md = it->get_metadata(0);
 					int idx = md["track_idx"];
@@ -5602,7 +5602,7 @@ void AnimationTrackEditor::_show_imported_anim_warning() {
 }
 
 void AnimationTrackEditor::_select_all_tracks_for_copy() {
-	TreeItem *track = track_copy_select->get_root()->get_children();
+	TreeItem *track = track_copy_select->get_root()->get_first_child();
 	if (!track) {
 		return;
 	}
@@ -5616,7 +5616,7 @@ void AnimationTrackEditor::_select_all_tracks_for_copy() {
 		track = track->get_next();
 	}
 
-	track = track_copy_select->get_root()->get_children();
+	track = track_copy_select->get_root()->get_first_child();
 	while (track) {
 		track->set_checked(0, !all_selected);
 		track = track->get_next();
@@ -5681,7 +5681,7 @@ void AnimationTrackEditor::_pick_track_select_recursive(TreeItem *p_item, const
 		p_select_candidates.push_back(node);
 	}
 
-	TreeItem *c = p_item->get_children();
+	TreeItem *c = p_item->get_first_child();
 
 	while (c) {
 		_pick_track_select_recursive(c, p_filter, p_select_candidates);

editor/connections_dialog.cpp

@@ -655,7 +655,7 @@ void ConnectionsDock::_disconnect_all() {
 		return;
 	}
 
-	TreeItem *child = item->get_children();
+	TreeItem *child = item->get_first_child();
 	String signalName = item->get_metadata(0).operator Dictionary()["name"];
 	undo_redo->create_action(vformat(TTR("Disconnect all from signal: '%s'"), signalName));
 

editor/debugger/script_editor_debugger.cpp

@@ -220,7 +220,7 @@ void ScriptEditorDebugger::_file_selected(const String &p_file) {
 			file->store_csv_line(headers);
 
 			if (vmem_tree->get_root()) {
-				TreeItem *ti = vmem_tree->get_root()->get_children();
+				TreeItem *ti = vmem_tree->get_root()->get_first_child();
 				while (ti) {
 					Vector<String> values;
 					values.resize(vmem_tree->get_columns());
@@ -1319,7 +1319,7 @@ bool ScriptEditorDebugger::is_skip_breakpoints() {
 void ScriptEditorDebugger::_error_activated() {
 	TreeItem *selected = error_tree->get_selected();
 
-	TreeItem *ci = selected->get_children();
+	TreeItem *ci = selected->get_first_child();
 	if (ci) {
 		selected->set_collapsed(!selected->is_collapsed());
 	}
@@ -1341,7 +1341,7 @@ void ScriptEditorDebugger::_expand_errors_list() {
 		return;
 	}
 
-	TreeItem *item = root->get_children();
+	TreeItem *item = root->get_first_child();
 	while (item) {
 		item->set_collapsed(false);
 		item = item->get_next();
@@ -1354,7 +1354,7 @@ void ScriptEditorDebugger::_collapse_errors_list() {
 		return;
 	}
 
-	TreeItem *item = root->get_children();
+	TreeItem *item = root->get_first_child();
 	while (item) {
 		item->set_collapsed(true);
 		item = item->get_next();
@@ -1403,7 +1403,7 @@ void ScriptEditorDebugger::_item_menu_id_pressed(int p_option) {
 			int rpad_len = text.length();
 
 			text = type + text + ti->get_text(1) + "\n";
-			TreeItem *ci = ti->get_children();
+			TreeItem *ci = ti->get_first_child();
 			while (ci) {
 				text += "  " + ci->get_text(0).rpad(rpad_len) + ci->get_text(1) + "\n";
 				ci = ci->get_next();
@@ -1419,7 +1419,7 @@ void ScriptEditorDebugger::_item_menu_id_pressed(int p_option) {
 			}
 
 			// We only need the first child here (C++ source stack trace).
-			TreeItem *ci = ti->get_children();
+			TreeItem *ci = ti->get_first_child();
 			// Parse back the `file:line @ method()` string.
 			const Vector<String> file_line_number = ci->get_text(1).split("@")[0].strip_edges().split(":");
 			ERR_FAIL_COND_MSG(file_line_number.size() < 2, "Incorrect C++ source stack trace file:line format (please report).");

editor/dependency_editor.cpp

@@ -725,8 +725,8 @@ void OrphanResourcesDialog::_find_to_delete(TreeItem *p_item, List<String> &path
 			paths.push_back(p_item->get_metadata(0));
 		}
 
-		if (p_item->get_children()) {
-			_find_to_delete(p_item->get_children(), paths);
+		if (p_item->get_first_child()) {
+			_find_to_delete(p_item->get_first_child(), paths);
 		}
 
 		p_item = p_item->get_next();

editor/editor_asset_installer.cpp

@@ -45,8 +45,8 @@ void EditorAssetInstaller::_update_subitems(TreeItem *p_item, bool p_check, bool
 		p_item->set_checked(0, false);
 	}
 
-	if (p_item->get_children()) {
-		_update_subitems(p_item->get_children(), p_check);
+	if (p_item->get_first_child()) {
+		_update_subitems(p_item->get_first_child(), p_check);
 	}
 
 	if (!p_first && p_item->get_next()) {
@@ -60,7 +60,7 @@ void EditorAssetInstaller::_uncheck_parent(TreeItem *p_item) {
 	}
 
 	bool any_checked = false;
-	TreeItem *item = p_item->get_children();
+	TreeItem *item = p_item->get_first_child();
 	while (item) {
 		if (item->is_checked(0)) {
 			any_checked = true;

editor/editor_sectioned_inspector.cpp

@@ -135,7 +135,7 @@ void SectionedInspector::_section_selected() {
 	}
 
 	selected_category = sections->get_selected()->get_metadata(0);
-	filter->set_section(selected_category, sections->get_selected()->get_children() == nullptr);
+	filter->set_section(selected_category, sections->get_selected()->get_first_child() == nullptr);
 	inspector->set_property_prefix(selected_category + "/");
 }
 
@@ -187,8 +187,8 @@ void SectionedInspector::edit(Object *p_object) {
 
 		TreeItem *first_item = sections->get_root();
 		if (first_item) {
-			while (first_item->get_children()) {
-				first_item = first_item->get_children();
+			while (first_item->get_first_child()) {
+				first_item = first_item->get_first_child();
 			}
 
 			first_item->select(0);

editor/filesystem_dock.cpp

@@ -180,20 +180,20 @@ Vector<String> FileSystemDock::_compute_uncollapsed_paths() {
 	Vector<String> uncollapsed_paths;
 	TreeItem *root = tree->get_root();
 	if (root) {
-		TreeItem *favorites_item = root->get_children();
+		TreeItem *favorites_item = root->get_first_child();
 		if (!favorites_item->is_collapsed()) {
 			uncollapsed_paths.push_back(favorites_item->get_metadata(0));
 		}
 
-		TreeItem *resTree = root->get_children()->get_next();
+		TreeItem *resTree = root->get_first_child()->get_next();
 		if (resTree) {
 			Vector<TreeItem *> needs_check;
 			needs_check.push_back(resTree);
 
 			while (needs_check.size()) {
 				if (!needs_check[0]->is_collapsed()) {
 					uncollapsed_paths.push_back(needs_check[0]->get_metadata(0));
-					TreeItem *child = needs_check[0]->get_children();
+					TreeItem *child = needs_check[0]->get_first_child();
 					while (child) {
 						needs_check.push_back(child);
 						child = child->get_next();
@@ -464,7 +464,7 @@ void FileSystemDock::_tree_multi_selected(Object *p_item, int p_column, bool p_s
 		return;
 	}
 
-	TreeItem *favorites_item = tree->get_root()->get_children();
+	TreeItem *favorites_item = tree->get_root()->get_first_child();
 	if (selected->get_parent() == favorites_item && !String(selected->get_metadata(0)).ends_with("/")) {
 		// Go to the favorites if we click in the favorites and the path has changed.
 		path = "Favorites";
@@ -1644,7 +1644,7 @@ Vector<String> FileSystemDock::_tree_get_selected(bool remove_self_inclusion) {
 	// Build a list of selected items with the active one at the first position.
 	Vector<String> selected_strings;
 
-	TreeItem *favorites_item = tree->get_root()->get_children();
+	TreeItem *favorites_item = tree->get_root()->get_first_child();
 	TreeItem *active_selected = tree->get_selected();
 	if (active_selected && active_selected != favorites_item) {
 		selected_strings.push_back(active_selected->get_metadata(0));
@@ -1700,7 +1700,7 @@ void FileSystemDock::_tree_rmb_option(int p_option) {
 				while (needs_check.size()) {
 					needs_check[0]->set_collapsed(is_collapsed);
 
-					TreeItem *child = needs_check[0]->get_children();
+					TreeItem *child = needs_check[0]->get_first_child();
 					while (child) {
 						needs_check.push_back(child);
 						child = child->get_next();
@@ -2062,13 +2062,13 @@ Variant FileSystemDock::get_drag_data_fw(const Point2 &p_point, Control *p_from)
 		// Check if the first selected is in favorite.
 		TreeItem *selected = tree->get_next_selected(tree->get_root());
 		while (selected) {
-			TreeItem *favorites_item = tree->get_root()->get_children();
+			TreeItem *favorites_item = tree->get_root()->get_first_child();
 			if (selected == favorites_item) {
 				// The "Favorites" item is not draggable.
 				return Variant();
 			}
 
-			bool is_favorite = selected->get_parent() != nullptr && tree->get_root()->get_children() == selected->get_parent();
+			bool is_favorite = selected->get_parent() != nullptr && tree->get_root()->get_first_child() == selected->get_parent();
 			all_favorites &= is_favorite;
 			all_not_favorites &= !is_favorite;
 			selected = tree->get_next_selected(selected);
@@ -2114,7 +2114,7 @@ bool FileSystemDock::can_drop_data_fw(const Point2 &p_point, const Variant &p_da
 		}
 
 		int drop_section = tree->get_drop_section_at_position(p_point);
-		TreeItem *favorites_item = tree->get_root()->get_children();
+		TreeItem *favorites_item = tree->get_root()->get_first_child();
 
 		TreeItem *resources_item = favorites_item->get_next();
 
@@ -2190,7 +2190,7 @@ void FileSystemDock::drop_data_fw(const Point2 &p_point, const Variant &p_data,
 
 		int drop_position;
 		Vector<String> files = drag_data["files"];
-		TreeItem *favorites_item = tree->get_root()->get_children();
+		TreeItem *favorites_item = tree->get_root()->get_first_child();
 		TreeItem *resources_item = favorites_item->get_next();
 
 		if (ti == favorites_item) {
@@ -2328,10 +2328,10 @@ void FileSystemDock::_get_drag_target_folder(String &target, bool &target_favori
 		int section = tree->get_drop_section_at_position(p_point);
 		if (ti) {
 			// Check the favorites first.
-			if (ti == tree->get_root()->get_children() && section >= 0) {
+			if (ti == tree->get_root()->get_first_child() && section >= 0) {
 				target_favorites = true;
 				return;
-			} else if (ti->get_parent() == tree->get_root()->get_children()) {
+			} else if (ti->get_parent() == tree->get_root()->get_first_child()) {
 				target_favorites = true;
 				return;
 			} else {
@@ -2347,7 +2347,7 @@ void FileSystemDock::_get_drag_target_folder(String &target, bool &target_favori
 						return;
 					}
 				} else {
-					if (ti->get_parent() != tree->get_root()->get_children()) {
+					if (ti->get_parent() != tree->get_root()->get_first_child()) {
 						// Not in the favorite section.
 						if (fpath != "res://") {
 							// We drop between two files