ItemList

继承： Control < Item < 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来调整超时时间。

属性

bool

allow_reselect

false

bool

allow_rmb_select

false

bool

allow_search

true

bool

auto_height

false

bool

auto_width

false

bool

clip_contents

true (overrides Control)

int

fixed_column_width

0

Vector2i

fixed_icon_size

Vector2i(0, 0)

FocusMode

focus_mode

2 (overrides Control)

IconMode

icon_mode

1

float

icon_scale

1.0

int

item_count

0

int

max_columns

1

int

max_text_lines

1

bool

same_column_width

false

SelectMode

select_mode

0

OverrunBehavior

text_overrun_behavior

3

bool

wraparound_items

true

方法

int

add_icon_item(icon: Texture2D, selectable: bool = true)

int

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

void

clear()

void

deselect(idx: int)

void

deselect_all()

void

ensure_current_is_visible()

void

force_update_list_size()

HScrollBar

get_h_scroll_bar()

int

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

AutoTranslateMode

get_item_auto_translate_mode(idx: int) const

Color

get_item_custom_bg_color(idx: int) const

Color

get_item_custom_fg_color(idx: int) const

Texture2D

get_item_icon(idx: int) const

Color

get_item_icon_modulate(idx: int) const

Rect2

get_item_icon_region(idx: int) const

String

get_item_language(idx: int) const

Variant

get_item_metadata(idx: int) const

Rect2

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

String

get_item_text(idx: int) const

TextDirection

get_item_text_direction(idx: int) const

String

get_item_tooltip(idx: int) const

PackedInt32Array

get_selected_items()

VScrollBar

get_v_scroll_bar()

bool

is_anything_selected()

bool

is_item_disabled(idx: int) const

bool

is_item_icon_transposed(idx: int) const

bool

is_item_selectable(idx: int) const

bool

is_item_tooltip_enabled(idx: int) const

bool

is_selected(idx: int) const

void

move_item(from_idx: int, to_idx: int)

void

remove_item(idx: int)

void

select(idx: int, single: bool = true)

void

set_item_auto_translate_mode(idx: int, mode: AutoTranslateMode)

void

set_item_custom_bg_color(idx: int, custom_bg_color: Color)

void

set_item_custom_fg_color(idx: int, custom_fg_color: Color)

void

set_item_disabled(idx: int, disabled: bool)

void

set_item_icon(idx: int, icon: Texture2D)

void

set_item_icon_modulate(idx: int, modulate: Color)

void

set_item_icon_region(idx: int, rect: Rect2)

void

set_item_icon_transposed(idx: int, transposed: bool)

void

set_item_language(idx: int, language: String)

void

set_item_metadata(idx: int, metadata: Variant)

void

set_item_selectable(idx: int, selectable: bool)

void

set_item_text(idx: int, text: String)

void

set_item_text_direction(idx: int, direction: TextDirection)

void

set_item_tooltip(idx: int, tooltip: String)

void

set_item_tooltip_enabled(idx: int, enable: bool)

void

sort_items_by_text()

主题属性

Color

font_color

Color(0.65, 0.65, 0.65, 1)

Color

font_hovered_color

Color(0.95, 0.95, 0.95, 1)

Color

font_hovered_selected_color

Color(1, 1, 1, 1)

Color

font_outline_color

Color(0, 0, 0, 1)

Color

font_selected_color

Color(1, 1, 1, 1)

Color

guide_color

Color(0.7, 0.7, 0.7, 0.25)

int

h_separation

4

int

icon_margin

4

int

line_separation

2

int

outline_size

0

int

v_separation

4

Font

font

int

font_size

StyleBox

cursor

StyleBox

cursor_unfocused

StyleBox

focus

StyleBox

hovered

StyleBox

hovered_selected

StyleBox

hovered_selected_focus

StyleBox

panel

StyleBox

selected

StyleBox

selected_focus

信号

empty_clicked(at_position: Vector2, mouse_button_index: int) 🔗

当在列表的矩形内但在空白区域发出任何鼠标单击时发出。

at_position是该控件本地坐标系中的单击位置。

item_activated(index: int) 🔗

通过双击或按Enter激活指定的列表项时发出。

item_clicked(index: int, at_position: Vector2, mouse_button_index: int) 🔗

当使用任何鼠标按钮单击指定的列表项时发出。

at_position是该控件本地坐标系中的单击位置。

item_selected(index: int) 🔗

选择指定项目时发出。仅适用于单选模式。

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

multi_selected(index: int, selected: bool) 🔗

在允许多重选择的列表上更改多重选择时发出。

枚举

enum IconMode: 🔗

IconMode ICON_MODE_TOP = 0

图标绘制在文本上方。

IconMode ICON_MODE_LEFT = 1

图标绘制在文本的左侧。

enum SelectMode: 🔗

SelectMode SELECT_SINGLE = 0

只允许选择单个项目。

SelectMode SELECT_MULTI = 1

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

SelectMode SELECT_TOGGLE = 2

允许通过打开和关闭来选择多个项目。

属性说明

bool allow_reselect = false 🔗

  • void set_allow_reselect(value: bool)

  • bool get_allow_reselect()

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

bool allow_rmb_select = false 🔗

  • void set_allow_rmb_select(value: bool)

  • bool get_allow_rmb_select()

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

  • void set_allow_search(value: bool)

  • bool get_allow_search()

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

bool auto_height = false 🔗

  • void set_auto_height(value: bool)

  • bool has_auto_height()

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

bool auto_width = false 🔗

  • void set_auto_width(value: bool)

  • bool has_auto_width()

如果true，控件将自动调整宽度以适应其内容。

int fixed_column_width = 0 🔗

  • void set_fixed_column_width(value: int)

  • int get_fixed_column_width()

将调整所有列的宽度。

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

Vector2i fixed_icon_size = Vector2i(0, 0) 🔗

所有图标的大小都将调整为。

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

IconMode icon_mode = 1 🔗

图标位置，无论是在文本上方还是左侧。请参阅IconMode常量。

float icon_scale = 1.0 🔗

  • void set_icon_scale(value: float)

  • float get_icon_scale()

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

int item_count = 0 🔗

  • void set_item_count(value: int)

  • int get_item_count()

当前在列表中的项目数。

int max_columns = 1 🔗

  • void set_max_columns(value: int)

  • int get_max_columns()

列表将具有的最大列。

如果大于零，内容将在指定列之间拆分。

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

int max_text_lines = 1 🔗

  • void set_max_text_lines(value: int)

  • int get_max_text_lines()

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

注意：此属性仅在icon_mode为ICON_MODE_TOP时生效。要使文本换行，fixed_column_width应大于零。

bool same_column_width = false 🔗

  • void set_same_column_width(value: bool)

  • bool is_same_column_width()

是否所有列都具有相同的宽度。

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

SelectMode select_mode = 0 🔗

允许选择单个或多个项目。请参阅SelectMode常量。

OverrunBehavior text_overrun_behavior = 3 🔗

当文本超过项目的边界矩形时设置剪辑行为。有关所有模式的描述，请参阅OverrunBehavior。

bool wraparound_items = true 🔗

  • void set_wraparound_items(value: bool)

  • bool has_wraparound_items()

如果true，控件将自动将项目移动到新行以适应其内容。有关此行为，请参阅HFlowContainer。

如果false，控件将添加一个水平滚动条以使所有项目可见。

方法说明

int add_icon_item(icon: Texture2D, selectable: bool = true) 🔗

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

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

将具有指定文本的项目添加到项目列表中。返回添加项目的索引。

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

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

void clear() 🔗

从列表中删除所有项目。

void deselect(idx: int) 🔗

确保未选择与指定索引关联的项目。

void deselect_all() 🔗

确保没有选择任何项目。

void ensure_current_is_visible() 🔗

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

void force_update_list_size() 🔗

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

HScrollBar get_h_scroll_bar() 🔗

返回水平滚动条。

警告：这是一个必需的内部节点，删除和释放它可能会导致崩溃。

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

返回给定position处的项目索引。

当此时没有项目时，如果exact为true，则返回-1，否则返回最接近的项目索引。

注意：如果在修改ItemList后立即调用，则返回值在下一帧中重新绘制之前是不可靠的。

AutoTranslateMode get_item_auto_translate_mode(idx: int) const 🔗

返回项目的自动翻译模式。

Color get_item_custom_bg_color(idx: int) const 🔗

返回idxindex指定的项目的自定义背景颜色。

Color get_item_custom_fg_color(idx: int) const 🔗

返回idxindex指定的项目的自定义前景色。

Texture2D get_item_icon(idx: int) const 🔗

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

Color get_item_icon_modulate(idx: int) const 🔗

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

Rect2 get_item_icon_region(idx: int) const 🔗

返回使用的项目图标的区域。如果该区域没有区域，则将使用整个图标。

String get_item_language(idx: int) const 🔗

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

Variant get_item_metadata(idx: int) const 🔗

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

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

返回ItemList节点坐标系中具有指定索引的项目的位置和大小。如果expand为true，则最后一列展开以填充行的其余部分。

注意：如果在修改ItemList后立即调用，则返回值在下一帧中重新绘制之前是不可靠的。

String get_item_text(idx: int) const 🔗

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

TextDirection get_item_text_direction(idx: int) const 🔗

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

String get_item_tooltip(idx: int) const 🔗

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

PackedInt32Array get_selected_items() 🔗

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

VScrollBar get_v_scroll_bar() 🔗

返回垂直滚动条。

警告：这是一个必需的内部节点，删除和释放它可能会导致崩溃。

bool is_anything_selected() 🔗

如果选择了一个或多个项目，则返回true。

bool is_item_disabled(idx: int) const 🔗

如果指定索引处的项目被禁用，则返回true。

bool is_item_icon_transposed(idx: int) const 🔗

如果项目图标将被转置绘制，即X和Y轴被交换，则返回true。

bool is_item_selectable(idx: int) const 🔗

如果指定索引处的项目是可选择的，则返回true。

bool is_item_tooltip_enabled(idx: int) const 🔗

如果为指定的项目索引启用了工具提示，则返回true。

bool is_selected(idx: int) const 🔗

如果当前选择了指定索引处的项目，则返回true。

void move_item(from_idx: int, to_idx: int) 🔗

将项目从索引from_idx移动到to_idx。

void remove_item(idx: int) 🔗

从列表中删除idxindex指定的项。

void select(idx: int, single: bool = true) 🔗

选择指定索引处的项目。

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

void set_item_auto_translate_mode(idx: int, mode: AutoTranslateMode) 🔗

设置与指定索引关联的项目的自动翻译模式。

项目默认使用Item.AUTO_TRANSLATE_MODE_INHERIT，它使用与ItemList本身相同的自动翻译模式。

void set_item_custom_bg_color(idx: int, custom_bg_color: Color) 🔗

将idxindex指定的项目的背景颜色设置为指定的Color。

void set_item_custom_fg_color(idx: int, custom_fg_color: Color) 🔗

将idxindex指定的项目的前景色设置为指定的Color。

void set_item_disabled(idx: int, disabled: bool) 🔗

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

无法选择禁用项目，也不会触发激活信号（双击或按Enter时）。

void set_item_icon(idx: int, icon: Texture2D) 🔗

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

void set_item_icon_modulate(idx: int, modulate: Color) 🔗

设置与指定索引关联的项目的调制Color。

void set_item_icon_region(idx: int, rect: Rect2) 🔗

设置项目图标的使用区域。如果该区域没有区域，将使用整个图标。

void set_item_icon_transposed(idx: int, transposed: bool) 🔗

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

void set_item_language(idx: int, language: String) 🔗

设置用于换行和文本整形算法的项目文本的语言代码，如果留空则使用当前语言环境。

void set_item_metadata(idx: int, metadata: Variant) 🔗

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

void set_item_selectable(idx: int, selectable: bool) 🔗

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

void set_item_text(idx: int, text: String) 🔗

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

void set_item_text_direction(idx: int, direction: TextDirection) 🔗

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

void set_item_tooltip(idx: int, tooltip: String) 🔗

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

void set_item_tooltip_enabled(idx: int, enable: bool) 🔗

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

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_hovered_selected_color = Color(1, 1, 1, 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。指南是在每一行项目之间画一条线。

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 = 4 🔗

项之间的垂直行间距。

Font font 🔗

项目文本的Font。

int font_size 🔗

项目文本的字体大小。

StyleBox cursor 🔗

StyleBox用于光标，当ItemList被聚焦时。

StyleBox cursor_unfocused 🔗

StyleBox用于游标，当ItemList未被聚焦时。

StyleBox focus 🔗

ItemList的焦点样式，绘制在背景顶部，但低于其他所有内容。

StyleBox hovered 🔗

StyleBox用于悬停但未选中的项目。

StyleBox hovered_selected 🔗

StyleBox用于悬停和选定的项目，在ItemList未聚焦时使用。

StyleBox hovered_selected_focus 🔗

StyleBox用于悬停和选定的项目，在ItemList被聚焦时使用。

StyleBox panel 🔗

ItemList的背景样式。

StyleBox selected 🔗

StyleBox用于选定项目，在ItemList未聚焦时使用。

StyleBox selected_focus 🔗

StyleBox用于选定项目，在ItemList被聚焦时使用。