Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

ItemList

继承: Control < CanvasItem < Node < Object

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

描述

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

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

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

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

增量搜索:PopupMenuTree 一样,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

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

方法

int

add_icon_item ( Texture2D icon, bool selectable=true )

int

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

void

clear ( )

void

deselect ( int idx )

void

deselect_all ( )

void

ensure_current_is_visible ( )

void

force_update_list_size ( )

int

get_item_at_position ( Vector2 position, bool exact=false ) const

Color

get_item_custom_bg_color ( int idx ) const

Color

get_item_custom_fg_color ( int idx ) const

Texture2D

get_item_icon ( int idx ) const

Color

get_item_icon_modulate ( int idx ) const

Rect2

get_item_icon_region ( int idx ) const

String

get_item_language ( int idx ) const

Variant

get_item_metadata ( int idx ) const

Rect2

get_item_rect ( int idx, bool expand=true ) const

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 ( )

bool

is_anything_selected ( )

bool

is_item_disabled ( int idx ) const

bool

is_item_icon_transposed ( int idx ) const

bool

is_item_selectable ( int idx ) const

bool

is_item_tooltip_enabled ( int idx ) const

bool

is_selected ( int idx ) const

void

move_item ( int from_idx, int to_idx )

void

remove_item ( int idx )

void

select ( int idx, bool single=true )

void

set_item_custom_bg_color ( int idx, Color custom_bg_color )

void

set_item_custom_fg_color ( int idx, Color custom_fg_color )

void

set_item_disabled ( int idx, bool disabled )

void

set_item_icon ( int idx, Texture2D icon )

void

set_item_icon_modulate ( int idx, Color modulate )

void

set_item_icon_region ( int idx, Rect2 rect )

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

font_hovered_color

Color(0.95, 0.95, 0.95, 1)

Color

font_outline_color

Color(1, 1, 1, 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

2

Font

font

int

font_size

StyleBox

cursor

StyleBox

cursor_unfocused

StyleBox

focus

StyleBox

hovered

StyleBox

panel

StyleBox

selected

StyleBox

selected_focus


信号

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

允许通过按住 CtrlShift 来选择多个项目。


属性说明

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,点击鼠标右键可以选中项目。


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

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

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


IconMode icon_mode = 1

图标的位置,是在文本的上方还是在文本的左边。参阅 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_modeICON_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

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


OverrunBehavior text_overrun_behavior = 3

设置文本超出项目的边界矩形时的裁剪行为。所有模式的说明见 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 的项目的索引。

这个位置没有项目时,如果 exacttrue 则会返回 -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 节点的坐标系。如果 expandtrue,则会将最后一列进行扩展,充满该行剩余的大小。

注意:如果修改 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 获得焦点时使用。