ItemList类
ItemList
Inherits: Control < CanvasItem < Node < Object
Control that provides a list of selectable items (and/or icons) in a single column, or optionally in multiple columns.
控件提供一个单列或多列的可选择项目（和/或图标）列表。
Description
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.
列表中的可选择项目可以选择或取消选择，也可以启用多重选择。也可以启用鼠标右键选择，以允许使用弹出式上下文菜单。也可以通过双击或按 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.
项目文本只支持单行字符串，字符串中的换行字符（如：\n）不会产生换行。在ICON_MODE_TOP模式下，文本包装被启用，但默认情况下，列的宽度被调整为完全适合其内容。你需要将fixed_column_width设置为大于0才能包住文本。
Properties
| bool | allow_reselect | false |
| bool | allow_rmb_select | false |
| bool | auto_height | false |
| int | fixed_column_width | 0 |
| Vector2 | fixed_icon_size | Vector2( 0, 0 ) |
| FocusMode | focus_mode | 2 (parent override) |
| IconMode | icon_mode | 1 |
| float | icon_scale | 1.0 |
| int | max_columns | 1 |
| int | max_text_lines | 1 |
| bool | rect_clip_content | true (parent override) |
| bool | same_column_width | false |
| SelectMode | select_mode | 0 |
Methods
| void | add_icon_item ( Texture icon, bool selectable=true ) |
| void | add_item ( String text, Texture icon=null, bool selectable=true ) |
| void | clear ( ) |
| void | ensure_current_is_visible ( ) |
| int | get_item_at_position ( Vector2 position, bool exact=false ) const |
| int | get_item_count ( ) const |
| Color | get_item_custom_bg_color ( int idx ) const |
| Color | get_item_custom_fg_color ( int idx ) const |
| Texture | get_item_icon ( int idx ) const |
| Color | get_item_icon_modulate ( int idx ) const |
| Rect2 | get_item_icon_region ( int idx ) const |
| 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 ( ) |
| 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, Texture 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_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 Properties
| StyleBox | bg | |
| StyleBox | bg_focus | |
| StyleBox | cursor | |
| StyleBox | cursor_unfocused | |
| Font | font | |
| Color | font_color | Color( 0.63, 0.63, 0.63, 1 ) |
| Color | font_color_selected | Color( 1, 1, 1, 1 ) |
| Color | guide_color | Color( 0, 0, 0, 0.1 ) |
| int | hseparation | 4 |
| int | icon_margin | 4 |
| int | line_separation | 2 |
| StyleBox | selected | |
| StyleBox | selected_focus | |
| int | vseparation | 2 |
Signals
- item_activated ( int index )
Triggered when specified list item is activated via double-clicking or by pressing Enter.
通过双击或按 Enter 键激活指定的列表项时触发。
- item_rmb_selected ( int index, Vector2 at_position )
Triggered when specified list item has been selected via right mouse clicking.
The click position is also provided to allow appropriate popup of context menus at the correct location.
allow_rmb_select must be enabled.
当通过鼠标右键点击指定的列表项时触发。
点击位置也被提供，以便在正确的位置弹出上下文菜单。
allow_rmb_select必须启用。
- item_selected ( int index )
Triggered when specified item has been selected.
allow_reselect must be enabled to reselect an item.
当指定的项目被选中时触发，必须启用allow_reselect才能重新选择项目。
要重新选择一个项目，必须启用allow_reselect。
- multi_selected ( int index, bool selected )
Triggered when a multiple selection is altered on a list allowing multiple selection.
当允许多选的列表上的多选被改变时触发。
- nothing_selected ( )
Triggered when a left mouse click is issued within the rect of the list but on empty space.
当在列表的区域内但在空白区域上单击鼠标左键时触发。
- rmb_clicked ( Vector2 at_position )
Triggered when a right mouse click is issued within the rect of the list but on empty space.
allow_rmb_select must be enabled.
在列表的矩形内但在空白区域上单击鼠标右键时触发。
必须启用allow_rmb_select。
Enumerations
enum IconMode:
- ICON_MODE_TOP = 0 --- Icon is drawn above the text.图标在文本上方绘制。
- ICON_MODE_LEFT = 1 --- Icon is drawn to the left of the text.图标被绘制在文本的左侧。
enum SelectMode:
- SELECT_SINGLE = 0 --- Only allow selecting a single item.只允许选择一个项目。
- SELECT_MULTI = 1 --- Allows selecting multiple items by holding Ctrl or Shift.允许通过按住Ctrl或Shift来选择多个项目。
Property Descriptions
- bool allow_reselect
| Default | false |
| Setter | set_allow_reselect(value) |
| Getter | get_allow_reselect() |
If true, the currently selected item can be selected again.
如果为true，则可以再次选择当前选择的项目。
- bool allow_rmb_select
| Default | false |
| Setter | set_allow_rmb_select(value) |
| Getter | get_allow_rmb_select() |
If true, right mouse button click can select items.
如果为true，则单击鼠标右键可以选择项目。
- bool auto_height
| Default | false |
| Setter | set_auto_height(value) |
| Getter | has_auto_height() |
If true, the control will automatically resize the height to fit its content.
如果为true，则控件将自动调整高度大小以适合其内容。
- int fixed_column_width
| Default | 0 |
| Setter | set_fixed_column_width(value) |
| Getter | get_fixed_column_width() |
The width all columns will be adjusted to.
A value of zero disables the adjustment, each item will have a width equal to the width of its content and the columns will have an uneven width.
所有列的宽度将被调整为指定宽度，如果调整不当可能会堆叠项目（或图标）
零值将禁用该调整，每个项目的宽度等于其内容的宽度，并且各列的宽度不均匀。
- Vector2 fixed_icon_size
| Default | Vector2( 0, 0 ) |
| Setter | set_fixed_icon_size(value) |
| Getter | get_fixed_icon_size() |
The size all icons will be adjusted to.
If either X or Y component is not greater than zero, icon size won't be affected.
所有图标的大小将被调整为指定大小。
如果X或Y分量不大于零，则图标大小不会受到影响。
- IconMode icon_mode
| Default | 1 |
| Setter | set_icon_mode(value) |
| Getter | get_icon_mode() |
The icon position, whether above or to the left of the text. See the IconMode constants.
图标的位置，无论在文本的上方还是左侧。 参见IconMode常量。
- float icon_scale
| Default | 1.0 |
| Setter | set_icon_scale(value) |
| Getter | get_icon_scale() |
The scale of icon applied after fixed_icon_size and transposing takes effect.
fixed_icon_size和转置生效后应用的图标比例。
- int max_columns
| Default | 1 |
| Setter | set_max_columns(value) |
| Getter | get_max_columns() |
Maximum columns the list will have.
If greater than zero, the content will be split among the specified columns.
A value of zero means unlimited columns, i.e. all items will be put in the same row.
列表的最大列数。
如果大于零，内容将被分割到指定的列中。
值为0表示不限列数，即所有的项目将被放在同一行。（将根据控件大小自动换行。）
- int max_text_lines
| Default | 1 |
| Setter | set_max_text_lines(value) |
| Getter | get_max_text_lines() |
Maximum lines of text allowed in each item. Space will be reserved even when there is not enough lines of text to display.
Note: This property takes effect only when icon_mode is ICON_MODE_TOP. To make the text wrap, fixed_column_width should be greater than zero.
每个项目允许的最大文字行数。即使没有足够的文字行来显示，也会保留空间。
注意：此属性只在icon_mode为ICON_MODE_TOP时生效。要使文字包住，fixed_column_width应该大于0。
- bool same_column_width
| Default | false |
| Setter | set_same_column_width(value) |
| Getter | is_same_column_width() |
Whether all columns will have the same width.
If true, the width is equal to the largest column width of all columns.
是否所有的列都有相同的宽度。
如果为真，宽度等于所有列中最大的列宽。
- SelectMode select_mode
| Default | 0 |
| Setter | set_select_mode(value) |
| Getter | get_select_mode() |
Allows single or multiple item selection. See the SelectMode constants.
允许选择单个或多个项目。 参见SelectMode常量。
Method Descriptions
- void add_icon_item ( Texture icon, bool selectable=true )
Adds an item to the item list with no text, only an icon.
在项目列表中添加一个项目，没有文字，只有图标。
- void add_item ( String text, Texture icon=null, bool selectable=true )
Adds an item to the item list with specified text. Specify an icon, or use null as the icon for a list item with no icon.
If selectable is true, the list item will be selectable.
在项目列表中添加指定文字的项目。指定一个图标，或者使用空值作为列表项的图标。
如果可选为真，则列表项目可选。
- void clear ( )
Removes all items from the list.
从列表中删除所有项目。
- void ensure_current_is_visible ( )
Ensure current selection is visible, adjusting the scroll position as necessary.
确保当前选择可见，必要时调整滚动位置。
- int get_item_at_position ( Vector2 position, bool exact=false ) const
Returns the item index at the given position.
When there is no item at that point, -1 will be returned if exact is true, and the closest item index will be returned otherwise.
返回给定位置上的物品索引
如果此时没有项目，则返回true -1（如果exact 是 true），否则返回最接近的项目索引。
- int get_item_count ( ) const
Returns the number of items currently in the list.
返回列表中当前的项目数。
- Color get_item_custom_bg_color ( int idx ) const
Returns the custom background color of the item specified by idx index.
返回由idx索引指定的项目的自定义背景色。
- Color get_item_custom_fg_color ( int idx ) const
Returns the custom foreground color of the item specified by idx index.
返回idx索引指定的项目的自定义前景色。
- Texture get_item_icon ( int idx ) const
Returns the icon associated with the specified index.
返回与指定索引关联的图标。
- Color get_item_icon_modulate ( int idx ) const
Returns a Color modulating item's icon at the specified index.
返回指定索引处的颜色调制项图标。
- Rect2 get_item_icon_region ( int idx ) const
Returns the region of item's icon used. The whole icon will be used if the region has no area.
返回项目图标的使用区域。如果该区域没有区域，则会使用整个图标。
- Variant get_item_metadata ( int idx ) const
Returns the metadata value of the specified index.
返回指定索引的元数据值。
- String get_item_text ( int idx ) const
Returns the text associated with the specified index.
返回与指定索引相关联的文本。
- String get_item_tooltip ( int idx ) const
Returns the tooltip hint associated with the specified index.
返回与指定索引相关联的工具提示。
- PoolIntArray get_selected_items ( )
Returns an array with the indexes of the selected items.
返回一个包含所选项目索引的数组。
- VScrollBar get_v_scroll ( )
Returns the Object ID associated with the list.
返回与列表相关联的对象ID。
- bool is_anything_selected ( )
Returns true if one or more items are selected.
如果选择了一个或多个项目，返回true。
- bool is_item_disabled ( int idx ) const
Returns true if the item at the specified index is disabled.
如果指定索引处的项目被禁用，则返回true。
- bool is_item_icon_transposed ( int idx ) const
Returns true if the item icon will be drawn transposed, i.e. the X and Y axes are swapped.
如果项目图标将被移位绘制，即X轴和Y轴互换，则返回true。
- bool is_item_selectable ( int idx ) const
Returns true if the item at the specified index is selectable.
如果指定索引处的项目可以选择，则返回true。
- bool is_item_tooltip_enabled ( int idx ) const
Returns true if the tooltip is enabled for specified item index.
如果对指定的项目索引启用工具提示，则返回true。
- bool is_selected ( int idx ) const
Returns true if the item at the specified index is currently selected.
如果当前指定索引的项目被选中，则返回true。
- void move_item ( int from_idx, int to_idx )
Moves item from index from_idx to to_idx.
将项目从索引 from_idx 移到 to_idx。
- void remove_item ( int idx )
Removes the item specified by idx index from the list.
从列表中删除由idx索引指定的项目。
- void select ( int idx, bool single=true )
Select the item at the specified index.
Note: This method does not trigger the item selection signal.
选择指定索引处的项目。
注意：本方法不触发项目选择信号。
- void set_item_custom_bg_color ( int idx, Color custom_bg_color )
Sets the background color of the item specified by idx index to the specified Color.
将 idx 索引指定的项目的背景色设置为指定的颜色。
var some_string = "Some text"
some_string.set_item_custom_bg_color(0,Color(1, 0, 0, 1) # This will set the background color of the first item of the control to red.这将把控件第一项的背景色设置为红色。
- void set_item_custom_fg_color ( int idx, Color custom_fg_color )
Sets the foreground color of the item specified by idx index to the specified Color.
将 idx 索引指定的项目的前景色设置为指定的颜色。
var some_string = "Some text"
some_string.set_item_custom_fg_color(0,Color(1, 0, 0, 1) # This will set the foreground color of the first item of the control to red.
- void set_item_disabled ( int idx, bool disabled )
Disables (or enables) the item at the specified index.
Disabled items cannot be selected and do not trigger activation signals (when double-clicking or pressing Enter).
禁用（或启用）指定索引处的项目。
禁用的项目不能选择，也不会触发激活信号（双击或按回车键时）。
- void set_item_icon ( int idx, Texture icon )
Sets (or replaces) the icon's Texture associated with the specified index.
设置（或替换）与指定索引相关联的图标的Texture。
- void set_item_icon_modulate ( int idx, Color modulate )
Sets a modulating Color of the item associated with the specified index.
设置与指定索引相关联的项目的调制颜色。
- void set_item_icon_region ( int idx, Rect2 rect )
Sets the region of item's icon used. The whole icon will be used if the region has no area.
设置项目图标的使用区域。如果该区域没有区域，则使用整个图标。
- void set_item_icon_transposed ( int idx, bool transposed )
Sets whether the item icon will be drawn transposed.
设置项目图标是否会被移位绘制。
- void set_item_metadata ( int idx, Variant metadata )
Sets a value (of any type) to be stored with the item associated with the specified index.
设置一个值（任何类型），该值将与与指定索引关联的项目一起存储。
- void set_item_selectable ( int idx, bool selectable )
Allows or disallows selection of the item associated with the specified index.
允许或不允许选择与指定索引关联的项目
- void set_item_text ( int idx, String text )
Sets text of the item associated with the specified index.
设置与指定索引关联的项目的文本。
- void set_item_tooltip ( int idx, String tooltip )
Sets the tooltip hint for the item associated with the specified index.
设置与指定索引关联的项目的工具提示提示。
- void set_item_tooltip_enabled ( int idx, bool enable )
Sets whether the tooltip hint is enabled for specified item index.
设置是否启用指定项目索引的工具提示。
- void sort_items_by_text ( )
Sorts items in the list by their text.
根据文本对列表中的项目进行排序。
- void unselect ( int idx )
Ensures the item associated with the specified index is not selected.
确保不选择与指定索引相关联的项目。
- void unselect_all ( )
Ensures there are no items selected.
确保没有项目被选中。