ItemList

继承： Control < CanvasItem < Node < Object

可选项目的垂直列表，可以有一列或多列。

描述

该控件提供了可选项目的垂直列表，这些项目可能位于单列或多列中，每个项目都有文本和图标选项。支持工具提示，并且列表中的每个项目可能会有所不同。

可以选择或取消选择列表中的可选项目，并且可以启用多项选择。也可以启用用鼠标右键进行选择，以允许使用弹出上下文菜单。项目也可以通过双击它们，或按 Enter 来“激活”。

项目文本只支持单行字符串。字符串中的换行符（例如 \n）不会产生换行。在 ICON_MODE_TOP 模式下会启用文本换行，但默认情况下会调整列的宽度以完全适合其内容。需要将 fixed_column_width 设置得大于零，才能换行文本。

所有 set_* 方法都允许负的项目索引，例如 -1 访问的是最后一个项目，-2 选择的是倒数第二个项目，以此类推。

增量搜索：与 PopupMenu 和 Tree 一样，ItemList 支持在控件获得焦点时在列表内进行搜索。按下与项目名称的第一个字母匹配的键，以选择以给定字母开头的第一个项目。在该点之后，有两种方法可以执行增量搜索： 1) 在超时持续时间之前再次按下相同的键，以选择下一个以相同字母开头的项目。 2) 在超时时间前，按匹配单词剩余部分的字母键，将直接选择问题项。如果自上次击键被注册后，超时持续时间已过，则这两个动作都将被重置为列表的开头。可以通过更改 ProjectSettings.gui/timers/incremental_search_max_interval_msec 来调整超时持续时间。

属性

方法

主题属性

信号

empty_clicked ( Vector2 at_position, int mouse_button_index )

在列表矩形内的非空白区域点击鼠标时触发。

item_activated ( int index )

通过双击或按回车键激活指定的列表项时触发。

item_clicked ( int index, Vector2 at_position, int mouse_button_index )

鼠标按键单击指定的列表项时触发。

还提供了单击的位置，这样就能够在正确位置弹出相应的上下文菜单。

item_selected ( int index )

选择指定项目时触发。

allow_reselect 必须启用才能重新选择项目。

multi_selected ( int index, bool selected )

在允许多选的列表上更改多选时触发。

枚举

enum IconMode:

IconMode ICON_MODE_TOP = 0

图标绘制在文本上方。

IconMode ICON_MODE_LEFT = 1

图标绘制在文本的左侧。

enum SelectMode:

SelectMode SELECT_SINGLE = 0

仅允许选择单个项目。

SelectMode SELECT_MULTI = 1

允许通过按住 Ctrl 或 Shift 来选择多个项目。

属性说明

bool allow_reselect = false

• void set_allow_reselect ( bool value )

• bool get_allow_reselect ( )

如果为 true，则可以再次选择当前选中的项目。

bool allow_rmb_select = false

• void set_allow_rmb_select ( bool value )

• bool get_allow_rmb_select ( )

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

bool allow_search = true

• void set_allow_search ( bool value )

• bool get_allow_search ( )

如果为 true，则允许用字母键通过增量搜索导航 ItemList。

bool auto_height = false

• void set_auto_height ( bool value )

• bool has_auto_height ( )

如果为 true，控件将自动调整高度以适合其内容。

int fixed_column_width = 0

• void set_fixed_column_width ( int value )

• int get_fixed_column_width ( )

所有列的宽度将调整为。

零值禁用调整，每个项目的宽度将等于其内容的宽度，列的宽度将不均匀。

Vector2i fixed_icon_size = Vector2i(0, 0)

• void set_fixed_icon_size ( Vector2i value )

• Vector2i get_fixed_icon_size ( )

所有图标将被调整到的尺寸。

如果 X 或 Y 分量不大于 0，图标的大小将不会受到影响。

IconMode icon_mode = 1

• void set_icon_mode ( IconMode value )

• IconMode get_icon_mode ( )

图标的位置，是在文本的上方还是在文本的左边。参阅 IconMode 常量。

float icon_scale = 1.0

• void set_icon_scale ( float value )

• float get_icon_scale ( )

在 fixed_icon_size 和转置生效后应用的图标比例。

int item_count = 0

• void set_item_count ( int value )

• int get_item_count ( )

当前列表中的项目数。

int max_columns = 1

• void set_max_columns ( int value )

• int get_max_columns ( )

列表将具有的最大列。

如果大于零，内容将被拆分为指定列。

零值意味着无限列，即所有项目将放在同一行中。

int max_text_lines = 1

• void set_max_text_lines ( int value )

• int get_max_text_lines ( )

每个子项中允许的最大文本行数。即使没有足够的文本行数来显示，也会保留空间。

注意：这个属性只有在 icon_mode 是 ICON_MODE_TOP 时才会生效。要使文本自动换行，fixed_column_width应大于零。

bool same_column_width = false

• void set_same_column_width ( bool value )

• bool is_same_column_width ( )

是否所有列的宽度相同。

如果为 true，则宽度等于所有列的最大列宽度。

SelectMode select_mode = 0

• void set_select_mode ( SelectMode value )

• SelectMode get_select_mode ( )

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

OverrunBehavior text_overrun_behavior = 3

• void set_text_overrun_behavior ( OverrunBehavior value )

• OverrunBehavior get_text_overrun_behavior ( )

设置文本超出项目的边界矩形时的裁剪行为。所有模式的说明见 OverrunBehavior。

方法说明

int add_icon_item ( Texture2D icon, bool selectable=true )

将一个项目添加到项目列表中，没有文本，只有一个图标。返回添加的项的索引。

int add_item ( String text, Texture2D icon=null, bool selectable=true )

将一个项目添加到项目列表中，并指定文本。返回添加的项目的索引。

指定一个 icon，或列表项没有图标时使用 null 作为 icon。

如果 selectable 为 true，则列表项将是可选择的。

void clear ( )

移除列表中的所有项目。

void deselect ( int idx )

确保与指定索引相关的项目不被选中。

void deselect_all ( )

确保没有选择任何项目。

void ensure_current_is_visible ( )

确保当前选择可见，根据需要调整滚动位置。

void force_update_list_size ( )

根据列表项强制更新该列表大小。每当项目的大小或其他相关设置（例如 auto_height）发生变化时，这种情况就会自动发生。该方法可被用于在下一次绘制阶段之前触发更新。

int get_item_at_position ( Vector2 position, bool exact=false ) const

返回位于给定位置 position 的项目的索引。

这个位置没有项目时，如果 exact 为 true 则会返回 -1，否则会返回距离最近的项目的索引。

注意：如果修改 ItemList 后立即调用，尚未在下一帧中重绘，则返回值不可靠。

Color get_item_custom_bg_color ( int idx ) const

返回项目的自定义背景色，项目由索引 idx 指定。

Color get_item_custom_fg_color ( int idx ) const

返回项目的自定义前景色，项目由索引 idx 指定。

Texture2D get_item_icon ( int idx ) const

返回与指定索引相关的图标。

Color get_item_icon_modulate ( int idx ) const

返回指定索引处的 Color 颜色调制项的图标。

Rect2 get_item_icon_region ( int idx ) const

返回项目图标的使用区域。如果该区域大小为 0，整个图标将被使用。

String get_item_language ( int idx ) const

返回项目文本的语言代码。

Variant get_item_metadata ( int idx ) const

返回指定索引的元数据值。

Rect2 get_item_rect ( int idx, bool expand=true ) const

返回具有给定索引的项目的位置和大小，使用 ItemList 节点的坐标系。如果 expand 为 true，则会将最后一列进行扩展，充满该行剩余的大小。

注意：如果修改 ItemList 后立即调用，尚未在下一帧中重绘，则返回值不可靠。

String get_item_text ( int idx ) const

返回与指定索引关联的文本。

TextDirection get_item_text_direction ( int idx ) const

返回项目文本的基础书写方向。

String get_item_tooltip ( int idx ) const

返回与指定索引关联的工具提示。

PackedInt32Array get_selected_items ( )

返回一个包含所选项目索引的数组。

VScrollBar get_v_scroll_bar ( )

返回垂直滚动条。

警告：这是一个必需的内部节点，删除和释放它可能会导致崩溃。如果你希望隐藏它或其任何子项，请使用它们的 CanvasItem.visible 属性。

bool is_anything_selected ( )

选中了一个或多个项目时，返回 true。

bool is_item_disabled ( int idx ) const

索引所对应的项目被禁用时，返回 true。

bool is_item_icon_transposed ( int idx ) const

项目图标被转置绘制，即 X 和 Y 轴互换时，返回 true。

bool is_item_selectable ( int idx ) const

索引所对应的项目可以被选中时，返回 true。

bool is_item_tooltip_enabled ( int idx ) const

索引所对应的项目已启用工具提示时，返回 true。

bool is_selected ( int idx ) const

索引所对应的项目被选中时，返回 true。

void move_item ( int from_idx, int to_idx )

将项目从索引 from_idx 移到 to_idx。

void remove_item ( int idx )

从列表中删除索引 idx 指定的项目。

void select ( int idx, bool single=true )

选择指定索引处的项目。

注意：此方法不触发项目选择信号。

void set_item_custom_bg_color ( int idx, Color custom_bg_color )

将索引 idx 指定的项目的背景色设置为指定的 Color。

void set_item_custom_fg_color ( int idx, Color custom_fg_color )

将索引 idx 指定的项目的前景色设置为指定的 Color。

void set_item_disabled ( int idx, bool disabled )

禁用（或启用）指定索引处的项目。

禁用的项目不能被选中，也不会触发（双击或按 Enter 时的）激活信号。

void set_item_icon ( int idx, Texture2D icon )

设置（或替换）与指定索引关联的图标 Texture2D。

void set_item_icon_modulate ( int idx, Color modulate )

设置与指定索引相关的项目的调制颜色 Color。

void set_item_icon_region ( int idx, Rect2 rect )

设置项目图标的使用区域。如果该区域大小为 0，将使用整个图标。

void set_item_icon_transposed ( int idx, bool transposed )

设置项目图标是否将被转置绘制。

void set_item_language ( int idx, String language )

设置项目文本的语言代码，用于断行和文本塑形算法，如果留空则使用当前区域设置。

void set_item_metadata ( int idx, Variant metadata )

设置与指定索引相关的项目存储的值（任何类型的值）。

void set_item_selectable ( int idx, bool selectable )

允许或禁止选择与指定索引关联的项目。

void set_item_text ( int idx, String text )

设置与指定索引相关的项目的文本。

void set_item_text_direction ( int idx, TextDirection direction )

设置项目文本的基础书写方向。

void set_item_tooltip ( int idx, String tooltip )

设置与指定索引相关的项目的工具提示。

void set_item_tooltip_enabled ( int idx, bool enable )

设置是否为指定的项目索引启用工具提示。

void sort_items_by_text ( )

按文本对列表中的项目进行排序。

主题属性说明

Color font_color = Color(0.65, 0.65, 0.65, 1)

项目的默认文本颜色 Color。

Color font_hovered_color = Color(0.95, 0.95, 0.95, 1)

项目处于悬停但未选中状态时使用的文本 Color。

Color font_outline_color = Color(1, 1, 1, 1)

项目文本轮廓的色调。

Color font_selected_color = Color(1, 1, 1, 1)

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

Color guide_color = Color(0.7, 0.7, 0.7, 0.25)

参考线的颜色 Color。参考线是在每行项目之间画的一条线。

int h_separation = 4

项目之间的水平间距。

int icon_margin = 4

项目的图标和文本之间的间距。

int line_separation = 2

每行文字之间的行距。

int outline_size = 0

项目文本轮廓的大小。

注意：如果使用启用了 FontFile.multichannel_signed_distance_field 的字体，其 FontFile.msdf_pixel_range 必须至少设置为 outline_size 的两倍，轮廓渲染才能看起来正确。否则，轮廓可能会比预期的更早被切断。

int v_separation = 2

项目菜单之间的垂直间距。

Font font

项目文本的字体 Font 。

int font_size

项目文本的字体大小。

StyleBox cursor

当该 ItemList 获得焦点时，用作光标的样式盒 StyleBox。

StyleBox cursor_unfocused

当该 ItemList 未获得焦点时，用作光标的样式盒 StyleBox。

StyleBox focus

该 ItemList 的焦点样式，绘制在背景之上，但低于其他东西。

StyleBox hovered

悬停但未被选中的项目的 StyleBox。

StyleBox panel

该 ItemList 的默认背景。

StyleBox selected

所选项的样式盒 StyleBox，当该 ItemList 未获得焦点时使用。

StyleBox selected_focus

所选项的样式盒 StyleBox，当该 ItemList 获得焦点时使用。

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.