Tree

Inherits: Control < CanvasItem < Node < Object

控件显示项目树。

描述

这展示了一个可以选择、展开和折叠的项目树。该树可以有多列的自定义控件，如文本编辑、按钮和弹出窗口。它对于结构化显示和互动很有用。

树通过代码建立，使用TreeItem对象来构建结构。它们有一个单独根节点，但如果添加一个虚拟的隐藏根节点，就可以模拟多个根。

func _ready():
    var tree = Tree.new()
    var root = tree.create_item()
    tree.set_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")

要遍历一个Tree对象中的所有TreeItem对象，在通过get_root获得根之后，使用TreeItem.get_next和TreeItem.get_children方法。你可以对一个TreeItem使用Object.free来把它从Tree中移除。

属性

方法

主题属性

信号

• button_pressed ( TreeItem item, int column, int id )

当树中按钮被按下时触发，参阅TreeItem.add_button。

• cell_selected ( )

当单元格被选中时触发。

• column_title_pressed ( int column )

当列的标题被按下时触发。

• custom_popup_edited ( bool arrow_clicked )

当具有TreeItem.CELL_MODE_CUSTOM的单元格被点击，进行编辑时触发。

• empty_rmb ( Vector2 position )

当在树的空白处按下鼠标右键时触发。

• empty_tree_rmb_selected ( Vector2 position )

如果鼠标右键选择处于活动状态，并且树是空的，则在按下鼠标右键时触发。

• item_activated ( )

当一个项目的标签被双击时触发。

• item_collapsed ( TreeItem item )

当一个项目的折叠箭头被点击折叠时触发。

• item_custom_button_pressed ( )

当自定义按钮被按下时触发，即在TreeItem.CELL_MODE_CUSTOM模式单元格中。

• item_double_clicked ( )

当项目的图标被双击时触发。

• item_edited ( )

当项目被编辑时触发。

• item_rmb_edited ( )

当使用鼠标右键编辑项目时触发。

• item_rmb_selected ( Vector2 position )

当用鼠标右键选择项目时触发。

• item_selected ( )

当项目被选中时触发。

• multi_selected ( TreeItem item, int column, bool selected )

如果select_mode是SELECT_MULTI，则触发代替item_selected。

• nothing_selected ( )

当鼠标左键点击未选择任何项目时触发。

枚举

enum SelectMode:

• SELECT_SINGLE = 0 —- 允许一次选择一个单元格。从项的角度看，只允许选择一个项。而且在所选项中只有一列被选中。

在这种模式下，焦点光标总被隐藏，被定位在当前的选择处，使当前的选择项成为当前的焦点项。

• SELECT_ROW = 1 —- 允许一次选择单行。从项的角度看，只允许选择单个项。而所有的列都被选择在所选项中。

在这种模式下，焦点光标总被隐藏，被定位在当前选择的第一列，使当前选择项成为当前焦点项。

• SELECT_MULTI = 2 —- 允许同时选择多个单元格。从项的角度看，允许选择多个项。而且每个被选中的项中可以有多个列被选中。

在这种模式下，焦点光标可见，光标下的项或列不一定被选中。

enum DropModeFlags:

• DROP_MODE_DISABLED = 0 —- 禁用所有放置部分，但仍然允许通过get_drop_section_at_position检测 “物品上” 的放置部分。

注意：这是默认的标志，当与其他标志结合时，它没有效果。

• DROP_MODE_ON_ITEM = 1 —- 启用 “项目上” 的放置部分。这个放置部分覆盖整个项。

当与DROP_MODE_INBETWEEN结合使用时，这个放置部分的高度减半，并保持垂直居中。

• DROP_MODE_INBETWEEN = 2 —- 启用 “项目上方” 和 “项目下方” 的放置部分。”项目上方” 的放置部分覆盖项目的上半部分，”项目下方” 的放置部分覆盖下半部分。

当与DROP_MODE_ON_ITEM结合时，这些放置部分的高度减半，并相应地停留在顶部或底部。

属性说明

• bool allow_reselect

如果true，可以再次选择当前选定的单元。

• bool allow_rmb_select

如果true，鼠标右键点击可以选择项目。

• bool column_titles_visible

如果true，列标题可见。

• int columns

列数。

• int drop_mode_flags

作为一个标志的OR组合的放置模式。参阅DropModeFlags常量。一旦拖动完成，将恢复到DROP_MODE_DISABLED。建议在Control.can_drop_data中设置这个。

控件放置部分，即根据鼠标位置决定和绘制可能的放置位置。

• bool hide_folding

如果true，隐藏折叠箭头。

• bool hide_root

如果true，则隐藏树的根节点。

• SelectMode select_mode

允许单选或多选。参阅SelectMode常量。

方法说明

• void clear ( )

清除树。这将删除所有项目。

• TreeItem create_item ( Object parent=null, int idx=-1 )

在树中创建一个项目，并将其作为parent的一个子项。

如果parent是null，根项将是父项，如果树是空的，新项将是根本身。

新项将是父项的idx个子顶，如果没有足够的兄弟姐妹，它将是最后一个子项。

• bool edit_selected ( )

编辑选中的树项，就像它被点击一样。该项必须通过TreeItem.set_editable设置为可编辑。其可被编辑，则返回true。如果没有项被选中，则失败。

• void ensure_cursor_is_visible ( )

使当前获得焦点的单元可见。

如果有必要，将滚动树。在SELECT_ROW模式下，不会做水平滚动，因为所选行中的所有单元都按逻辑获得焦点。

注意：尽管这个方法的名称是这样的，但焦点光标本身只在 SELECT_MULTI 模式下可见。

• int get_column_at_position ( Vector2 position ) const

返回在position的列索引，如果那里没有项目，则返回-1。

• String get_column_title ( int column ) const

返回列的标题。

• int get_column_width ( int column ) const

返回列的宽度，单位是像素。

• Rect2 get_custom_popup_rect ( ) const

返回自定义弹出窗口的矩形。帮助创建显示弹出式的自定义单元格控件。参阅TreeItem.set_cell_mode。

• int get_drop_section_at_position ( Vector2 position ) const

返回位于position的放置部分，如果没有项目，则返回-100。

在 “项目上方”、”项目之上”和 “项目下方”的放置部分将分别返回-1、0或1的值。请参阅DropModeFlags以了解每个放置部分的描述。

要获得返回的放置部分相对项，请使用get_item_at_position。

• TreeItem get_edited ( ) const

返回当前被编辑的项。可以和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).

• int get_edited_column ( ) const

返回当前编辑项的列。

• Rect2 get_item_area_rect ( Object item, int column=-1 ) const

返回指定项目的矩形区域。如果column被指定，只得到该列的位置和大小，否则得到包含所有列的矩形。

• TreeItem get_item_at_position ( Vector2 position ) const

返回指定位置，即相对于树的原点位置的树中项。

• TreeItem get_next_selected ( Object from )

返回指定项后的下一个选择项，如果到达终点则返回null。

如果from是null，将返回第一个被选中的项。

• int get_pressed_button ( ) const

返回最后按下的按钮的索引。

• TreeItem get_root ( )

返回树的根项，如果树是空的，则返回null。

• Vector2 get_scroll ( ) const

返回当前的滚动位置。

• 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。

• void scroll_to_item ( Object item )

使 Tree 跳转到指定的项。

• void set_column_expand ( int column, bool expand )

如果 true，该列将拥有 Control 的“Expand”标志。拥有“Expand”标志的列，将以类似于 Control.size_flags_stretch_ratio 的方式使用其“min_width”最小宽度。

• void set_column_min_width ( int column, int min_width )

设置一个列的最小宽度。拥有“Expand”标志的列将以类似于 Control.size_flags_stretch_ratio 的方式使用其“min_width”最小宽度。

• void set_column_title ( int column, String title )

设置一个列的标题。

Theme Property Descriptions

• Color custom_button_font_highlight

当TreeItem.CELL_MODE_CUSTOM模式的单元格被悬停时的文本Color颜色。

• Color drop_position_color

用于绘制可能的放置位置的Color颜色。有关放置位置的描述，参阅DropModeFlags常量。

• Color font_color

项目的默认文本颜色 Color。

• Color font_color_selected

选择项目时使用的文本颜色Color。

• Color guide_color

参考线的Color颜色。

• Color relationship_line_color

关系线的Color颜色。

• Color title_button_color

标题按钮的默认文本Color颜色。

• int button_margin

一个单元中每个按钮之间的水平空间。

• int draw_guides

如果不为零就绘制参考线，这作为一个布尔值。参考线是在每个项的底部画的一条水平线。

• int draw_relationship_lines

如果不为零，则绘制关系线，这作为一个布尔值。关系线在子项的开始处绘制，以显示层次结构。

• int hseparation

项目单元之间的水平空间。这也用作禁用折叠时项目开头的边距。

• int item_margin

项目开头的水平边距。在项目启用折叠功能时使用。

• int scroll_border

拖动时，鼠标指针与控件边框之间触发边框滚动的最大距离。

• int scroll_speed

边框滚动的速度。

• int vseparation

每个项内的垂直填充，即项内容与上或下边框之间的距离。

• Font font

项目文本的字体 Font 。

• Font title_button_font

标题按钮文本的Font字体。

• Texture arrow

当一个可折叠的项没有被折叠时，使用的箭头图标。

• Texture arrow_collapsed

当一个可折叠的项被折叠时，使用的箭头图标。

• Texture checked

当TreeItem.CELL_MODE_CHECK模式单元格被选中时，显示的选中图标。

• Texture select_arrow

为TreeItem.CELL_MODE_RANGE模式单元显示的箭头图标。

• Texture unchecked

当TreeItem.CELL_MODE_CHECK模式单元未被选中时，要显示的选中图标。

• Texture updown

为TreeItem.CELL_MODE_RANGE模式单元显示的向下箭头图标。

• StyleBox bg

Tree的默认StyleBox，即在控件没有获得焦点时使用。

• StyleBox bg_focus

当Tree获得焦点时使用的StyleBox。

• StyleBox button_pressed

当树中的按钮被按下时使用的StyleBox。

• StyleBox cursor

当Tree获得焦点时，用于光标的StyleBox。

• StyleBox cursor_unfocused

当Tree未获聚焦时，用于光标的StyleBox。

• StyleBox custom_button

为TreeItem.CELL_MODE_CUSTOM模式的单元格默认的StyleBox。

• StyleBox custom_button_hover

当TreeItem.CELL_MODE_CUSTOM模式的单元格被悬停时的StyleBox。

• StyleBox custom_button_pressed

当TreeItem.CELL_MODE_CUSTOM模式的单元格被按下时的StyleBox。

• StyleBox selected

所选项的StyleBox，当Tree没有获得焦点时使用。

• StyleBox selected_focus

所选项目的StyleBox，在Tree获得焦点时使用。

• StyleBox title_button_hover

当标题按钮被悬停时使用的StyleBox。

• StyleBox title_button_normal

标题按钮的默认StyleBox。

• StyleBox title_button_pressed

当标题按钮被按下时使用的StyleBox。