Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
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 来调整超时持续时间。
属性¶
|
||
|
||
|
||
|
||
clip_contents |
|
|
|
||
|
||
focus_mode |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法¶
主题属性¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
信号¶
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
如果为 true，则可以再次选择当前选中的项目。
bool allow_rmb_select = false
如果为 true，点击鼠标右键可以选中项目。
bool allow_search = true
如果为 true，则允许用字母键通过增量搜索导航 ItemList。
bool auto_height = false
如果为 true，控件将自动调整高度以适合其内容。
int fixed_column_width = 0
所有列的宽度将调整为。
零值禁用调整，每个项目的宽度将等于其内容的宽度，列的宽度将不均匀。
Vector2i fixed_icon_size = Vector2i(0, 0)
所有图标将被调整到的尺寸。
如果 X 或 Y 分量不大于 0，图标的大小将不会受到影响。
IconMode icon_mode = 1
图标的位置，是在文本的上方还是在文本的左边。参阅 IconMode 常量。
float icon_scale = 1.0
在 fixed_icon_size 和转置生效后应用的图标比例。
int item_count = 0
当前列表中的项目数。
int max_columns = 1
列表将具有的最大列。
如果大于零，内容将被拆分为指定列。
零值意味着无限列，即所有项目将放在同一行中。
int max_text_lines = 1
每个子项中允许的最大文本行数。即使没有足够的文本行数来显示，也会保留空间。
注意：这个属性只有在 icon_mode 是 ICON_MODE_TOP 时才会生效。要使文本自动换行，fixed_column_width应大于零。
bool same_column_width = false
是否所有列的宽度相同。
如果为 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 获得焦点时使用。