ItemList

Inherits: Control < CanvasItem < Node < Object

该控件提供了一个单列的可选择项目（和/或图标）的列表，也可以选择多列的。

描述

This control provides a selectable list of items that may be in a single (or multiple columns) with option of text, icons, or both text and icon. Tooltips are supported and may be different for every item in the list.

Selectable items in the list may be selected or deselected and multiple selection may be enabled. Selection with right mouse button may also be enabled to allow use of popup context menus. Items may also be “activated” by double-clicking them or by pressing Enter.

Item text only supports single-line strings, newline characters (e.g. \n) in the string won’t produce a newline. Text wrapping is enabled in ICON_MODE_TOP mode, but column’s width is adjusted to fully fit its content by default. You need to set fixed_column_width greater than zero to wrap the text.

属性

方法

主题属性

信号

• item_activated ( int index )

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

• item_rmb_selected ( int index, Vector2 at_position )

当指定的列表项目通过鼠标右键被选中时，会被触发。

还提供了单击位置，以便在正确的位置恰当地弹出上下文菜单。

必须启用 allow_rmb_select 。

• item_selected ( int index )

选择指定项目时触发。

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

• multi_selected ( int index, bool selected )

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

• nothing_selected ( )

当鼠标左键在列表的矩形(rect)范围内但在空白处单击时，会被触发。

• rmb_clicked ( Vector2 at_position )

当在列表的矩形(rect)范围内但在空白处单击鼠标右键时被触发。

allow_rmb_select必须被启用。

枚举

enum IconMode:

• ICON_MODE_TOP = 0 —- 图标绘制在文本上方。

• ICON_MODE_LEFT = 1 —- 图标绘制在文本的左侧。

enum SelectMode:

• SELECT_SINGLE = 0 —- 仅允许选择单个项目。

• SELECT_MULTI = 1 —- 允许通过按住Ctrl或Shift选择多个项目。

属性说明

• bool allow_reselect

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

• bool allow_rmb_select

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

• bool auto_height

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

• int fixed_column_width

所有列的宽度将调整为。

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

• Vector2 fixed_icon_size

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

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

• IconMode icon_mode

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

• float icon_scale

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

• int max_columns

列表将具有的最大列。

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

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

• int max_text_lines

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

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

• bool same_column_width

是否所有列的宽度相同。

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

• SelectMode select_mode

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

方法说明

• void add_icon_item ( Texture icon, bool selectable=true )

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

• void add_item ( String text, Texture icon=null, bool selectable=true )

将一个项目添加到项目列表中，并指定文本。指定一个图标icon，或者图标icon使用空null作为没有图标的列表项。

如果可选择填true，列表项将是可选择的。

• void clear ( )

移除列表中的所有项目。

• void ensure_current_is_visible ( )

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

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

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

当此时没有项目时，如果精确 exact 是真 true，则将返回 -1，否则将返回最近的项目索引。

• int get_item_count ( ) const

返回当前列表中的项目数。

• Color get_item_custom_bg_color ( int idx ) const

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

• Color get_item_custom_fg_color ( int idx ) const

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

• Texture get_item_icon ( int idx ) const

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

• Color get_item_icon_modulate ( int idx ) const

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

• Rect2 get_item_icon_region ( int idx ) const

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

• Variant get_item_metadata ( int idx ) const

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

• String get_item_text ( int idx ) const

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

• String get_item_tooltip ( int idx ) const

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

• PoolIntArray get_selected_items ( )

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

• VScrollBar get_v_scroll ( )

返回与列表相关的ObjectID。

警告： 这是一个必要的内部节点，移除和释放它可能会导致崩溃。如果你想隐藏它或它的任意子节点，请使用其的 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, Texture icon )

设置（或替换）与指定索引相关的图标的纹理Texture。

• 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_metadata ( int idx, Variant metadata )

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

• void set_item_selectable ( int idx, bool selectable )

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

• void set_item_text ( int idx, String text )

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

• void set_item_tooltip ( int idx, String tooltip )

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

• void set_item_tooltip_enabled ( int idx, bool enable )

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

• void sort_items_by_text ( )

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

• void unselect ( int idx )

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

• void unselect_all ( )

确保没有选择任何项目。

Theme Property Descriptions

• Color font_color

项目的默认文本颜色 Color。

• Color font_color_selected

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

• Color guide_color

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

• int hseparation

项目菜单之间的水平间距。

• int icon_margin

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

• int line_separation

每行文字之间的行距。

• int vseparation

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

• Font font

项目文本的字体 Font 。

• StyleBox bg

ItemList 的默认样式盒 StyleBox，即在控件未获得焦点时使用。

• StyleBox bg_focus

当ItemList被聚焦时使用的样式盒StyleBox。

• StyleBox cursor

当ItemList被聚焦时，用于光标的样式盒StyleBox。

• StyleBox cursor_unfocused

当ItemList没有被聚焦时，用于光标的样式盒StyleBox。

• StyleBox selected

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

• StyleBox selected_focus

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