Tree¶
用于在分层结构中显示一组内部TreeItem的控件。
描述¶
一种用于以分层结构显示一组内部 TreeItem 的控件。树项可以被选中、展开和折叠。该树可以有多列，并且可包含诸如 LineEdit、按钮和弹出窗口等自定义控件。这对于结构化显示和交互很有用。
func _ready():
var tree = Tree.new()
var root = tree.create_item()
tree.hide_root = true
var child1 = tree.create_item(root)
var child2 = tree.create_item(root)
var subchild1 = tree.create_item(child1)
subchild1.set_text(0, "Subchild1")
public override void _Ready()
{
var tree = new Tree();
TreeItem root = tree.CreateItem();
tree.HideRoot = true;
TreeItem child1 = tree.CreateItem(root);
TreeItem child2 = tree.CreateItem(root);
TreeItem subchild1 = tree.CreateItem(child1);
subchild1.SetText(0, "Subchild1");
}
要遍历 Tree 对象中的所有 TreeItem 对象，需先通过 get_root() 获取根节点，然后使用 TreeItem.get_next() 和 TreeItem.get_first_child()。你可以对 TreeItem 使用 Object.free() 来将其从 Tree 中移除。n 渐进式搜索： 与 ItemList 和 PopupMenu 类似，当 Tree 控件获得焦点时，它支持在列表内进行搜索。按下与某个项目名称首字母匹配的键，即可选中以该字母开头的第一个项目。在这之后，有两种进行渐进式搜索的方式：1）在超时时间内再次按下相同的键，以选中下一个以该字母开头的项目。2）在超时时间内按下与单词其余部分匹配的字母键，以直接选中相应的项目。如果自上次记录按键操作起已超过超时时间，那么上述两种操作都将从列表开头重新开始。你可以通过更改 ProjectSettings.gui/timers/incremental_search_max_interval_msec 来调整超时时间
属性¶
方法¶
主题属性¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
信号¶
button_clicked(item: TreeItem, column: int, id: int, mouse_button_index: int) 🔗
按下树上的按钮时发出（参见TreeItem.add_button()）。
cell_selected() 🔗
选择单元格时发出。
check_propagated_to_item(item: TreeItem, column: int) 🔗
调用TreeItem.propagate_check()时发出。连接到此信号以处理调用TreeItem.propagate_check()时受影响的项目。处理受影响项目的顺序如下：调用该方法的项目、该项目的子项目以及该项目的父项目。
column_title_clicked(column: int, mouse_button_index: int) 🔗
当使用@GlobalScope.MOUSE_BUTTON_LEFT或@GlobalScope.MOUSE_BUTTON_RIGHT单击列标题时发出。
custom_item_clicked(mouse_button_index: int) 🔗
当用鼠标按钮单击具有TreeItem.CELL_MODE_CUSTOM的项目时发出。
custom_popup_edited(arrow_clicked: bool) 🔗
当单击具有TreeItem.CELL_MODE_CUSTOM的单元格进行编辑时发出。
empty_clicked(click_position: Vector2, mouse_button_index: int) 🔗
在树的空白区域单击鼠标按钮时发出。
item_activated() 🔗
双击项目时发出，或使用ui_accept输入事件选择（例如在键盘上使用Enter或Space）。
item_collapsed(item: TreeItem) 🔗
通过点击折叠箭头折叠项目时发出。
item_edited() 🔗
编辑项目时发出。
item_icon_double_clicked() 🔗
双击项目的图标时发出。有关双击项目的任何部分时发出的信号，请参阅item_activated。
item_mouse_selected(mouse_position: Vector2, mouse_button_index: int) 🔗
使用鼠标按钮选择项目时发出。
item_selected() 🔗
选择项目时发出。
multi_selected(item: TreeItem, column: int, selected: bool) 🔗
如果select_mode设置为SELECT_MULTI，则发出代替item_selected。
nothing_selected() 🔗
当鼠标左键单击未选择任何项目时发出。
枚举¶
enum SelectMode: 🔗
SelectMode SELECT_SINGLE = 0
允许一次选择单个单元格。从项目的角度来看，只允许选择单个项目。并且所选项目中只有一列被选中。
焦点光标在此模式下始终隐藏，但它位于当前选择处，使当前选择的项目成为当前焦点项目。
SelectMode SELECT_ROW = 1
允许一次选择单行。从项目的角度来看，只允许选择单个项目。并且所有列都选在所选项目中。
焦点光标在此模式下始终隐藏，但它位于当前选择的第一列，使当前选择的项目成为当前焦点项目。
SelectMode SELECT_MULTI = 2
允许同时选择多个单元格。从项目的角度来看，允许选择多个项目。并且在每个选择的项目中可以选择多个列。
焦点光标在此模式下可见，不一定选择光标下的项目或列。
enum DropModeFlags: 🔗
DropModeFlags DROP_MODE_DISABLED = 0
禁用所有放置部分，但仍然允许通过get_drop_section_at_position()检测“on item”放置部分。
注意：这是默认标志，与其他标志组合时无效。
DropModeFlags DROP_MODE_ON_ITEM = 1
启用“on item”放置部分。此放置部分涵盖整个项目。
当与DROP_MODE_INBETWEEN结合时，这个下降部分将高度减半，并保持垂直居中。
DropModeFlags DROP_MODE_INBETWEEN = 2
启用“上面项”和“下面项”下拉部分。“上面项”下拉部分覆盖项目的上半部分，“下面项”下拉部分覆盖项目的下半部分。
当与DROP_MODE_ON_ITEM结合时，这些下降部分将高度减半，并相应地停留在顶部/底部。
属性说明¶
如果true，则可以再次选择当前选择的单元格。
bool allow_rmb_select = false 🔗
如果true，单击鼠标右键可以选择项目。
如果true，则允许通过增量搜索使用字母键导航Tree。
如果true，则未分配工具提示的树项将其文本显示为工具提示。另请参见TreeItem.get_tooltip_text()和TreeItem.get_button_tooltip_text()。
bool column_titles_visible = false 🔗
如果true，则列标题可见。
列数。
删除模式作为标志的OR组合。请参阅DropModeFlags常量。删除完成后，恢复为DROP_MODE_DISABLED。建议在Control._can_drop_data()期间设置此值。
这控制了放置部分，即根据鼠标位置决定和绘制可能的放置位置。
bool enable_recursive_folding = true 🔗
如果true，则为此Tree启用递归折叠。单击折叠箭头或使用ui_right/ui_left快捷方式时按住Shift折叠或解折叠TreeItem及其所有后代。
如果true，则隐藏折叠箭头。
如果true，则隐藏树的根。
bool scroll_horizontal_enabled = true 🔗
如果true，则启用水平滚动。
bool scroll_vertical_enabled = true 🔗
如果true，则启用垂直滚动。
SelectMode select_mode = 0 🔗
void set_select_mode(value: SelectMode)
SelectMode get_select_mode()
允许单次或多次选择。请参阅SelectMode常量。
方法说明¶
void clear() 🔗
清除树。这将删除所有项目。
TreeItem create_item(parent: TreeItem = null, index: int = -1) 🔗
在树中创建一个项目并将其添加为parent的子项目，它可以是有效的TreeItem或null。
如果parent为null，则根项将是父项，或者如果树为空，则新项将是根本身。
新项将是父项的index-th子项，或者如果没有足够的兄弟项，它将是最后一个子项。
void deselect_all() 🔗
取消选择所有树项（行和列）。在SELECT_MULTI模式下也删除选择光标。
bool edit_selected(force_edit: bool = false) 🔗
编辑选定的树项，就像单击它一样。
项目必须设置为可编辑TreeItem.set_editable()或force_edit必须为true。
如果可以编辑项目，则返回true。如果未选择任何项目，则失败。
void ensure_cursor_is_visible() 🔗
使当前聚焦的单元格可见。
如果需要，这将滚动树。在SELECT_ROW模式下，这不会进行水平滚动，因为所选行中的所有单元格都在逻辑上聚焦。
注意：尽管此方法的名称，焦点光标本身仅在SELECT_MULTI模式下可见。
int get_button_id_at_position(position: Vector2) const 🔗
返回position处的按钮ID，如果没有按钮，则返回-1。
int get_column_at_position(position: Vector2) const 🔗
返回position处的列索引，如果没有项目，则返回-1。
int get_column_expand_ratio(column: int) const 🔗
返回分配给列的展开比率。
String get_column_title(column: int) const 🔗
返回列的标题。
HorizontalAlignment get_column_title_alignment(column: int) const 🔗
返回列标题对齐方式。
TextDirection get_column_title_direction(column: int) const 🔗
返回列标题基础书写方向。
String get_column_title_language(column: int) const 🔗
返回列标题语言代码。
int get_column_width(column: int) const 🔗
返回列的宽度（以像素为单位）。
Rect2 get_custom_popup_rect() const 🔗
返回自定义弹出窗口的矩形。帮助创建显示弹出窗口的自定义单元格控件。请参阅TreeItem.set_cell_mode()。
int get_drop_section_at_position(position: Vector2) const 🔗
返回position处的放置部分，如果没有项目，则返回-100。
将分别为“上面的项目”、“上面的项目”和“下面的项目”删除部分返回值-1、0或1。有关每个删除部分的描述，请参阅DropModeFlags。
要获取与返回的放置部分相关的项，请使用get_item_at_position()。
返回当前编辑的项目。可与 item_edited 一起使用，以获取被修改的项目。
func _ready():
$Tree.item_edited.connect(on_Tree_item_edited)
func on_Tree_item_edited():
print($Tree.get_edited()) # This item just got edited (e.g. checked).
public override void _Ready()
{
GetNode<Tree>("Tree").ItemEdited += OnTreeItemEdited;
}
public void OnTreeItemEdited()
{
S3.Print(GetNode<Tree>("Tree").GetEdited()); // This item just got edited (e.g. checked).
}
int get_edited_column() const 🔗
返回当前编辑项目的列。
Rect2 get_item_area_rect(item: TreeItem, column: int = -1, button_index: int = -1) const 🔗
返回指定TreeItem的矩形区域。如果指定了column，则只获取该列的位置和大小，否则获取包含所有列的矩形。如果指定了按钮索引，则将返回该按钮的矩形。
TreeItem get_item_at_position(position: Vector2) const 🔗
返回指定位置（相对于树原点位置）的树项。
TreeItem get_next_selected(from: TreeItem) 🔗
返回给定TreeItem之后的下一个选定TreeItem，如果到达末尾，则返回null。
如果from为null，则返回第一个选定的项目。
int get_pressed_button() const 🔗
返回最后按下的按钮的索引。
返回树的根项，如果树为空，则返回null。
返回当前滚动位置。
TreeItem get_selected() const 🔗
返回当前聚焦的项目，如果没有项目被聚焦，则返回null。
在SELECT_ROW和SELECT_SINGLE模式下，聚焦的项目与选中的项目相同；在SELECT_MULTI模式下，聚焦的项目是焦点光标下的项目，不一定是选中的。
要获取当前选定的项，请使用get_next_selected()。
int get_selected_column() const 🔗
返回当前聚焦的列，如果没有聚焦列，则返回-1。
在SELECT_SINGLE模式下，聚焦的列就是选中的列；在SELECT_ROW模式下，选中任何一项，聚焦的列始终为0；在SELECT_MULTI模式下，聚焦的列就是聚焦光标下的列，不一定有选中的列。
要判断是否选择了项目的一列，请使用TreeItem.is_selected()。
bool is_column_clipping_content(column: int) const 🔗
如果列已启用剪辑，则返回true（参见set_column_clip_content()）。
bool is_column_expanding(column: int) const 🔗
如果列已启用展开，则返回true（参见set_column_expand()）。
void scroll_to_item(item: TreeItem, center_on_item: bool = false) 🔗
使Tree跳转到指定的TreeItem。
void set_column_clip_content(column: int, enable: bool) 🔗
允许为列的内容启用剪辑，使内容大小被忽略。
void set_column_custom_minimum_width(column: int, min_width: int) 🔗
覆盖计算出的列的最小宽度。可以将其设置为0以恢复默认行为。具有“展开”标志的列将以类似于Control.size_flags_stretch_ratio。
void set_column_expand(column: int, expand: bool) 🔗
如果true，则该列将具有Control的“展开”标志。具有“展开”标志的列将以与Control.size_flags_stretch_ratio类似的方式使用其展开比率（参见set_column_expand_ratio()）。
void set_column_expand_ratio(column: int, ratio: int) 🔗
设置列的相对展开比率。参见set_column_expand()。
void set_column_title(column: int, title: String) 🔗
设置列的标题。
void set_column_title_alignment(column: int, title_alignment: HorizontalAlignment) 🔗
设置列标题对齐方式。请注意，列标题不支持@GlobalScope.HORIZONTAL_ALIGNMENT_FILL。
void set_column_title_direction(column: int, direction: TextDirection) 🔗
设置列标题的基本书写方向。
void set_column_title_language(column: int, language: String) 🔗
设置用于换行和文本整形算法的列标题的语言代码，如果留空则使用当前语言环境。
void set_selected(item: TreeItem, column: int) 🔗
选择指定的TreeItem和列。
主题属性说明¶
Color children_hl_line_color = Color(0.27, 0.27, 0.27, 1) 🔗
Color custom_button_font_highlight = Color(0.95, 0.95, 0.95, 1) 🔗
TreeItem.CELL_MODE_CUSTOM模式单元格悬停时的文本Color。
Color drop_position_color = Color(1, 1, 1, 1) 🔗
Color用于绘制可能的放置位置。有关放置位置的进一步描述，请参阅DropModeFlags常量。
Color font_color = Color(0.7, 0.7, 0.7, 1) 🔗
项目的默认文本Color。
Color font_disabled_color = Color(0.875, 0.875, 0.875, 0.5) 🔗
TreeItem.CELL_MODE_CHECK模式单元格不可编辑时的文本Color（参见TreeItem.set_editable()）。
Color font_hovered_color = Color(0.95, 0.95, 0.95, 1) 🔗
悬停项目时使用的文本Color。
Color font_hovered_dimmed_color = Color(0.875, 0.875, 0.875, 1) 🔗
当项目悬停时使用文本Color，同时悬停同一项目的按钮。
Color font_outline_color = Color(0, 0, 0, 1) 🔗
项目的文本轮廓的色调。
Color font_selected_color = Color(1, 1, 1, 1) 🔗
选择项目时使用的文本Color。
Color guide_color = Color(0.7, 0.7, 0.7, 0.25) 🔗
指南的Color。
Color parent_hl_line_color = Color(0.27, 0.27, 0.27, 1) 🔗
Color relationship_line_color = Color(0.27, 0.27, 0.27, 1) 🔗
关系线的默认Color。
Color title_button_color = Color(0.875, 0.875, 0.875, 1) 🔗
标题按钮的默认文本Color。
单元格中每个按钮之间的水平空间。
int children_hl_line_width = 1 🔗
选定的TreeItem与其子级之间的关系线的宽度。
绘制指南，如果不是零，则充当布尔值。指南是在每个项目底部绘制的水平线。
int draw_relationship_lines = 0 🔗
绘制关系线，如果不是零，则充当布尔值。关系线绘制在子项的开头以显示层次结构。
项目单元格之间的水平空间。这也用作禁用折叠时项目开头的边距。
项目单元格中图标的最大允许宽度。此限制应用于图标的默认大小之上，但在使用TreeItem.set_icon_max_width()设置的值之前。高度根据图标的比例进行调整。
int inner_item_margin_bottom = 0 🔗
单元格的内底边距。
int inner_item_margin_left = 0 🔗
单元格的左内边距。
int inner_item_margin_right = 0 🔗
单元格的右内边距。
int inner_item_margin_top = 0 🔗
单元格的内顶部边距。
项目开始处的水平边距。这在为项目启用折叠时使用。
文本大纲的大小。
注意：如果使用启用了FontFile.multichannel_signed_distance_field的字体，则其FontFile.msdf_pixel_range必须设置为至少两倍outline_size的值才能使轮廓渲染看起来正确。否则，轮廓可能会比预期的更早被切断。
int parent_hl_line_margin = 0 🔗
选定TreeItem的父关系行与未选定的兄弟关系行之间的空间。
int parent_hl_line_width = 1 🔗
选定的TreeItem与其父级之间的关系线的宽度。
int relationship_line_width = 1 🔗
关系行的默认宽度。
拖动时鼠标光标与控件边框之间触发边框滚动的最大距离。
边框滚动的速度。
int scrollbar_h_separation = 4 🔗
树内容和滚动条的水平分离。
int scrollbar_margin_bottom = -1 🔗
滚动条的下边距。如果为负数，则使用panel下边距。
int scrollbar_margin_left = -1 🔗
水平滚动条的左边距。如果为负数，则使用panel左边距。
int scrollbar_margin_right = -1 🔗
滚动条的右边距。如果为负数，则使用panel右边距。
int scrollbar_margin_top = -1 🔗
垂直滚动条的上边距。当为负数时，使用panel上边距。
int scrollbar_v_separation = 4 🔗
树内容和滚动条的垂直分离。
每个项目内的垂直填充，即项目内容与上/下边框之间的距离。
项目文本的Font。
标题按钮文本的Font。
项目文本的字体大小。
标题按钮文本的字体大小。
可折叠项目未折叠时使用的箭头图标。
折叠可折叠项目时使用的箭头图标（用于从左到右的布局）。
Texture2D arrow_collapsed_mirrored 🔗
折叠可折叠项目时使用的箭头图标（用于从右到左的布局）。
TreeItem.CELL_MODE_CHECK模式单元格被选中并可编辑时显示的检查图标（参见TreeItem.set_editable()）。
TreeItem.CELL_MODE_CHECK模式单元格被选中且不可编辑时显示的检查图标（参见TreeItem.set_editable()）。
TreeItem.CELL_MODE_CHECK模式单元格不确定且可编辑时显示的检查图标（参见TreeItem.set_editable()）。
Texture2D indeterminate_disabled 🔗
TreeItem.CELL_MODE_CHECK模式单元格不确定且不可编辑时显示的检查图标（参见TreeItem.set_editable()）。
TreeItem.CELL_MODE_RANGE模式单元格显示的箭头图标。
TreeItem.CELL_MODE_CHECK模式单元格未选中且可编辑时显示的检查图标（参见TreeItem.set_editable()）。
Texture2D unchecked_disabled 🔗
TreeItem.CELL_MODE_CHECK模式单元格未选中且不可编辑时显示的检查图标（参见TreeItem.set_editable()）。
为TreeItem.CELL_MODE_RANGE模式单元格显示的向上箭头图标。
StyleBox当树中的按钮悬停时使用。
StyleBox在按下树中的按钮时使用。
StyleBox用于光标，当Tree被聚焦时。
StyleBox用于光标，当Tree未被聚焦时。
使用TreeItem.set_custom_as_button()启用按钮时TreeItem.CELL_MODE_CUSTOM模式单元格的默认StyleBox。
StyleBox custom_button_hover 🔗
StyleBox用于TreeItem.CELL_MODE_CUSTOM悬停时的模式按钮单元格。
StyleBox custom_button_pressed 🔗
StyleBox用于TreeItem.CELL_MODE_CUSTOM按下时的模式按钮单元格。
Tree的专注风格，绘制在一切之上。
StyleBox用于悬停的项目。
StyleBox表示正在悬停的项目，同时悬停同一项目的按钮。
Tree的背景样式。
StyleBox用于选定项目，在Tree未聚焦时使用。
StyleBox用于选定项目，在Tree被聚焦时使用。
StyleBox在悬停标题按钮时使用。
StyleBox title_button_normal 🔗
标题按钮的默认StyleBox。
StyleBox title_button_pressed 🔗
StyleBox在按下标题按钮时使用。