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.

PopupMenu

繼承: Popup < Window < Viewport < Node < Object

用於顯示選項列表的模態視窗。

說明

PopupMenu 是用於顯示選項清單的模態視窗,常見於工具列和情境選單。

PopupMenu 的大小可以使用 Window.max_size 限制。如果選單項清單的高度大於 PopupMenu 的最大高度,則會在彈出框中使用 ScrollContainer 讓使用者捲動內容。如果沒有設定最大尺寸或者設為了 0,則該 PopupMenu 的高度會被限制在父級的矩形框之中。

所有的 set_* 方法都允許使用負數選單項索引,即 -1 存取的是最後一個選單項,-2 選擇的是倒數第二個選單項,依次類推。

增量搜尋:與 ItemList 和 Tree 類似,PopupMenu 也支援在聚焦控制項時在清單中進行搜尋。按下與某個條目名稱首字母一致的按鍵,就會選中以該字母開頭的第一個條目。在此之後,進行增量搜尋的辦法有兩種:1)在超時前再次按下同一個按鍵,選中以該字母開頭的下一個條目。2)在超時前按下剩餘字母對應的按鍵,直接匹配並選中所需的條目。這兩個動作都會在最後一次按鍵超時後重設回清單頂端。你可以通過 ProjectSettings.gui/timers/incremental_search_max_interval_msec 修改超時時長。

注意:PopupMenu 預設情況下是隱藏的。若要顯示,呼叫節點上來自 Window 的 popup_* 方法中的其中一個,比如 Window.popup_centered_clamped()。

注意:選單項的 ID 有 32 位元的限制,不是完整 int 的 64 位元。取值範圍為 -2^32 到 2^32 - 1,即 -2147483648 到 2147483647。

屬性

bool

allow_search

true

DefaultCanvasItemTextureFilter

canvas_item_default_texture_filter

4 (overrides Viewport)

DefaultCanvasItemTextureRepeat

canvas_item_default_texture_repeat

3 (overrides Viewport)

bool

hide_on_checkable_item_selection

true

bool

hide_on_item_selection

true

bool

hide_on_state_item_selection

false

int

item_count

0

int

item_{index}/checkable

0

bool

item_{index}/checked

false

bool

item_{index}/disabled

false

Texture2D

item_{index}/icon

int

item_{index}/id

0

bool

item_{index}/indeterminate

false

bool

item_{index}/separator

false

String

item_{index}/text

""

bool

prefer_native_menu

false

bool

search_bar_enabled

false

bool

search_bar_fuzzy_search_enabled

true

int

search_bar_fuzzy_search_max_misses

2

int

search_bar_min_item_count

0

bool

shrink_height

true

bool

shrink_width

true

float

submenu_popup_delay

0.2

SystemMenus

system_menu_id

0

bool

transparent

true (overrides Window)

bool

transparent_bg

true (overrides Viewport)

方法

bool

activate_item_by_event(event: InputEvent, for_global_only: bool = false)

void

add_check_item(label: String, id: int = -1, accel: Key = 0)

void

add_check_shortcut(shortcut: Shortcut, id: int = -1, global: bool = false)

void

add_icon_check_item(texture: Texture2D, label: String, id: int = -1, accel: Key = 0)

void

add_icon_check_shortcut(texture: Texture2D, shortcut: Shortcut, id: int = -1, global: bool = false)

void

add_icon_item(texture: Texture2D, label: String, id: int = -1, accel: Key = 0)

void

add_icon_radio_check_item(texture: Texture2D, label: String, id: int = -1, accel: Key = 0)

void

add_icon_radio_check_shortcut(texture: Texture2D, shortcut: Shortcut, id: int = -1, global: bool = false)

void

add_icon_shortcut(texture: Texture2D, shortcut: Shortcut, id: int = -1, global: bool = false, allow_echo: bool = false)

void

add_item(label: String, id: int = -1, accel: Key = 0)

void

add_multistate_item(label: String, max_states: int, default_state: int = 0, id: int = -1, accel: Key = 0)

void

add_radio_check_item(label: String, id: int = -1, accel: Key = 0)

void

add_radio_check_shortcut(shortcut: Shortcut, id: int = -1, global: bool = false)

void

add_separator(label: String = "", id: int = -1)

void

add_shortcut(shortcut: Shortcut, id: int = -1, global: bool = false, allow_echo: bool = false)

void

add_submenu_item(label: String, submenu: String, id: int = -1)

void

add_submenu_node_item(label: String, submenu: PopupMenu, id: int = -1)

void

clear(free_submenus: bool = false)

int

get_focused_item() const

Key

get_item_accelerator(index: int) const

AutoTranslateMode

get_item_auto_translate_mode(index: int) const

Texture2D

get_item_icon(index: int) const

int

get_item_icon_max_width(index: int) const

Color

get_item_icon_modulate(index: int) const

int

get_item_id(index: int) const

int

get_item_indent(index: int) const

int

get_item_index(id: int) const

String

get_item_language(index: int) const

Variant

get_item_metadata(index: int) const

int

get_item_multistate(index: int) const

int

get_item_multistate_max(index: int) const

Shortcut

get_item_shortcut(index: int) const

String

get_item_submenu(index: int) const

PopupMenu

get_item_submenu_node(index: int) const

String

get_item_text(index: int) const

TextDirection

get_item_text_direction(index: int) const

String

get_item_tooltip(index: int) const

bool

is_item_checkable(index: int) const

bool

is_item_checked(index: int) const

bool

is_item_disabled(index: int) const

bool

is_item_indeterminate(index: int) const

bool

is_item_radio_checkable(index: int) const

bool

is_item_separator(index: int) const

bool

is_item_shortcut_disabled(index: int) const

bool

is_native_menu() const

bool

is_system_menu() const

void

remove_item(index: int)

void

scroll_to_item(index: int)

void

set_focused_item(index: int)

void

set_item_accelerator(index: int, accel: Key)

void

set_item_as_checkable(index: int, enable: bool)

void

set_item_as_radio_checkable(index: int, enable: bool)

void

set_item_as_separator(index: int, enable: bool)

void

set_item_auto_translate_mode(index: int, mode: AutoTranslateMode)

void

set_item_checked(index: int, checked: bool)

void

set_item_disabled(index: int, disabled: bool)

void

set_item_icon(index: int, icon: Texture2D)

void

set_item_icon_max_width(index: int, width: int)

void

set_item_icon_modulate(index: int, modulate: Color)

void

set_item_id(index: int, id: int)

void

set_item_indent(index: int, indent: int)

void

set_item_indeterminate(index: int, indeterminate: bool)

void

set_item_index(index: int, target_index: int)

void

set_item_language(index: int, language: String)

void

set_item_metadata(index: int, metadata: Variant)

void

set_item_multistate(index: int, state: int)

void

set_item_multistate_max(index: int, max_states: int)

void

set_item_shortcut(index: int, shortcut: Shortcut, global: bool = false)

void

set_item_shortcut_disabled(index: int, disabled: bool)

void

set_item_submenu(index: int, submenu: String)

void

set_item_submenu_node(index: int, submenu: PopupMenu)

void

set_item_text(index: int, text: String)

void

set_item_text_direction(index: int, direction: TextDirection)

void

set_item_tooltip(index: int, tooltip: String)

void

toggle_item_checked(index: int)

void

toggle_item_multistate(index: int)

主題屬性

Color

font_accelerator_color

Color(0.7, 0.7, 0.7, 0.8)

Color

font_color

Color(0.875, 0.875, 0.875, 1)

Color

font_disabled_color

Color(0.4, 0.4, 0.4, 0.8)

Color

font_hover_color

Color(0.875, 0.875, 0.875, 1)

Color

font_outline_color

Color(0, 0, 0, 1)

Color

font_separator_color

Color(0.875, 0.875, 0.875, 1)

Color

font_separator_outline_color

Color(0, 0, 0, 1)

int

gutter_compact

1

int

h_separation

4

int

icon_max_width

0

int

indent

10

int

item_end_padding

2

int

item_start_padding

2

int

outline_size

0

int

search_bar_separation

4

int

separator_outline_size

0

int

v_separation

4

Font

font

Font

font_separator

int

font_separator_size

int

font_size

Texture2D

checked

Texture2D

checked_disabled

Texture2D

indeterminate

Texture2D

indeterminate_disabled

Texture2D

radio_checked

Texture2D

radio_checked_disabled

Texture2D

radio_unchecked

Texture2D

radio_unchecked_disabled

Texture2D

search

Texture2D

submenu

Texture2D

submenu_mirrored

Texture2D

unchecked

Texture2D

unchecked_disabled

AudioStream

item_activated_disabled_sound

AudioStream

item_activated_sound

AudioStream

item_hovered_sound

StyleBox

hover

StyleBox

labeled_separator_left

StyleBox

labeled_separator_right

StyleBox

panel

StyleBox

separator


訊號

id_focused(id: int) 🔗

使用者使用 ProjectSettings.input/ui_up 或 ProjectSettings.input/ui_down 輸入動作移動至 ID 為 id 的功能表專案時發出。


id_pressed(id: int) 🔗

ID 為 id 的項目被按下時發出。在 macOS 系統上,當其快捷鍵被啟用時也會發出。

注意:如果 id 為負數(無論是明確指定的還是由於溢出導致的),將回傳相應的索引來代替。


index_pressed(index: int) 🔗

索引為 index 的項目被按下時發出。在 macOS 系統上,當其快捷鍵被啟用時也會發出。


menu_changed() 🔗

發生選單項的新增、修改、刪除時發出。


屬性說明

  • void set_allow_search(value: bool)

  • bool get_allow_search()

如果為 true,允許用字母鍵導覽 PopupMenu。


bool hide_on_checkable_item_selection = true 🔗

  • void set_hide_on_checkable_item_selection(value: bool)

  • bool is_hide_on_checkable_item_selection()

如果為 true,則在選中核取方塊或選項按鈕時隱藏 PopupMenu。


bool hide_on_item_selection = true 🔗

  • void set_hide_on_item_selection(value: bool)

  • bool is_hide_on_item_selection()

如果為 true,當一個專案被選中時隱藏 PopupMenu。


bool hide_on_state_item_selection = false 🔗

  • void set_hide_on_state_item_selection(value: bool)

  • bool is_hide_on_state_item_selection()

如果為 true,則在選中狀態項時隱藏 PopupMenu。


int item_count = 0 🔗

  • void set_item_count(value: int)

  • int get_item_count()

目前列表中的專案數。


int item_{index}/checkable = 0 🔗

索引為 index 的可勾選選單項的型別。

注意: index 的取值必須在 0 .. item_count - 1 範圍內。


bool item_{index}/checked = false 🔗

如果設定為 true,那麼位於 index 位置的選項就會被勾選。

注意: index 的取值範圍在 0 到 item_count - 1 之間。


bool item_{index}/disabled = false 🔗

如果為 true,則停用位於 index 處的項目。

注意: index 的取值範圍為 0 .. item_count - 1。


Texture2D item_{index}/icon 🔗

位於 index 處的項目的圖示。

注意: index 的取值範圍為 0 .. item_count - 1。


int item_{index}/id = 0 🔗

索引為 index 的選單項的 ID。

注意: index 的取值必須在 0 .. item_count - 1 範圍內。


bool item_{index}/indeterminate = false 🔗

If true, the item at index is in an indeterminate state.

Note: index is a value in the 0 .. item_count - 1 range.


bool item_{index}/separator = false 🔗

如果為 true,則索引為 index 的選單項是一個分隔符。

注意: index 的取值必須在 0 .. item_count - 1 範圍內。


String item_{index}/text = "" 🔗

位於 index 處的項目的文字。

注意: index 的取值範圍為 0 .. item_count - 1。


bool prefer_native_menu = false 🔗

  • void set_prefer_native_menu(value: bool)

  • bool is_prefer_native_menu()

如果為 true,則支援原生選單時 MenuBar 會使用原生選單。

注意:如果 PopupMenu 與 StatusIndicator、MenuBar 或其他 PopupMenu 選單項之間存在連結,則無論該屬性為何值,均可使用原生選單,請使用 is_native_menu() 檢查。


bool search_bar_enabled = false 🔗

  • void set_search_bar_enabled(value: bool)

  • bool is_search_bar_enabled()

如果為 true,則在 PopupMenu 頂部顯示一個用於篩選項目項的搜尋欄。請參閱 search_bar_min_item_count,以瞭解基於項目項數量動態控制其可見性的方法。

注意: 啟用後,allow_search 將被忽略。


bool search_bar_fuzzy_search_enabled = true 🔗

  • void set_search_bar_fuzzy_search_enabled(value: bool)

  • bool is_search_bar_fuzzy_search_enabled()

如果為 true,則在 PopupMenu 的搜尋欄中啟用模糊搜尋。這允許搜尋結果包含與搜尋查詢幾乎匹配的條目,以及那些單獨字元與搜尋查詢匹配但不按順序排列的條目。

請使用 search_bar_fuzzy_search_max_misses 來設定搜尋結果中允許的最大不匹配數量。


int search_bar_fuzzy_search_max_misses = 2 🔗

  • void set_search_bar_fuzzy_search_max_misses(value: int)

  • int get_search_bar_fuzzy_search_max_misses()

設定為 PopupMenu 的搜尋欄啟用模糊搜尋時,每個搜尋結果中允許的最大不匹配數量。任何超過該數量的選單項都將從搜尋結果中被隱藏。


int search_bar_min_item_count = 0 🔗

  • void set_search_bar_min_item_count(value: int)

  • int get_search_bar_min_item_count()

設定搜尋欄可見所需的最少條目數。必須將 search_bar_enabled 設定為 true,此設定才會生效。分隔符條目不計入總數。


bool shrink_height = true 🔗

  • void set_shrink_height(value: bool)

  • bool get_shrink_height()

如果為 true,則在顯示 PopupMenu 時將其縮小到最小高度。


bool shrink_width = true 🔗

  • void set_shrink_width(value: bool)

  • bool get_shrink_width()

如果為 true,則在顯示 PopupMenu 時會將其寬度縮小到最小。


float submenu_popup_delay = 0.2 🔗

  • void set_submenu_popup_delay(value: float)

  • float get_submenu_popup_delay()

設定滑鼠懸停時子選單項彈出的延遲時間,單位為秒。如果將彈出選單新增為另一個選單的子級(充當子選單),它將繼承父選單項的延遲時間。

注意:如果滑鼠離開一個已打開子選單的子選單項並進入另一個子選單項,子選單彈出延遲時間會受到滑鼠移動方向的影響。如果滑鼠朝已打開的子選單移動,則已打開的子選單會等待大約 0.5 秒後關閉,然後允許目前懸停的子選單項打開。這種額外的延遲使滑鼠有時間穿過其他選單項移動到已打開的子選單,而不會過早關閉。如果滑鼠沒有朝向已打開的子選單移動,例如向下移動,則已打開的子選單會立即關閉。


SystemMenus system_menu_id = 0 🔗

如果設定為 SystemMenus 的值之一,則該 PopupMenu 將綁定到特殊系統選單。每個特殊選單在同一時間只能綁定一個 PopupMenu。


方法說明

bool activate_item_by_event(event: InputEvent, for_global_only: bool = false) 🔗

根據 PopupMenu 的捷徑和加速器檢查提供的 event,並啟動具有配對事件的第一個專案。如果 for_global_only 為 true,只有 global 設定為 true 的捷徑和加速器才會被呼叫。

如果專案已成功啟用,則傳回 true。

注意:某些Control,例如MenuButton,會自動呼叫此方法。


void add_check_item(label: String, id: int = -1, accel: Key = 0) 🔗

新增一個帶有文字 label 的新的可勾選項。

可以選擇提供一個 id 以及一個加速器(accel)。如果未提供 id,將從索引中建立一個。如果未提供 accel,則預設值 0(對應於 @GlobalScope.KEY_NONE)將被分配給該項(這意味著它不會有任何加速器)。有關加速器的更多資訊,請參閱 get_item_accelerator()。

注意:可勾選的項只顯示一個勾選標記,但沒有任何內建的勾選行為,必須手動勾選/取消勾選。有關如何控制它的更多資訊,請參閱 set_item_checked()。


void add_check_shortcut(shortcut: Shortcut, id: int = -1, global: bool = false) 🔗

新增一個新的可勾選項並為其分配指定的 Shortcut。將核取方塊的標籤設定為 Shortcut 的名稱。

可以選擇提供一個 id。如果未提供 id,將從索引中建立一個。

注意:可勾選項只顯示一個勾選標記,但沒有任何內建的勾選行為,必須手動勾選/取消勾選。有關如何控制它的更多資訊,請參閱 set_item_checked()。


void add_icon_check_item(texture: Texture2D, label: String, id: int = -1, accel: Key = 0) 🔗

新增一個帶有文字 label 和圖示 texture 的新的可勾選項。

可以選擇提供一個 id 以及一個加速器(accel)。如果未提供 id,將從索引中建立一個。如果未提供 accel,則預設值 0(對應於 @GlobalScope.KEY_NONE)將被分配給該項(這意味著它不會有任何加速器)。有關加速器的更多資訊,請參閱 get_item_accelerator()。

注意:可勾選項只顯示一個勾選標記,但沒有任何內建的勾選行為,必須手動勾選/取消勾選。有關如何控制它的更多資訊,請參閱 set_item_checked()。


void add_icon_check_shortcut(texture: Texture2D, shortcut: Shortcut, id: int = -1, global: bool = false) 🔗

新增一個新的可勾選項並為其分配指定的 Shortcut 和圖示 texture。將核取方塊的標籤設定為 Shortcut 的名稱。

可以選擇提供一個 id。如果未提供 id,將從索引中建立一個。

注意:可勾選項只顯示一個勾選標記,但沒有任何內建的勾選行為,必須手動勾選/取消勾選。有關如何控制它的更多資訊,請參閱 set_item_checked()。


void add_icon_item(texture: Texture2D, label: String, id: int = -1, accel: Key = 0) 🔗

新增帶有文字 label 和圖示 texture 的新功能表專案。

還可以提供 id 和快捷鍵(accel)。如果沒有提供 id,則會根據索引來建立。如果沒有提供 accel,則會為該功能表專案分配預設的 0(對應 @GlobalScope.KEY_NONE,在這裡表示沒有快捷鍵)。更多快捷鍵相關的資訊見 get_item_accelerator()。


void add_icon_radio_check_item(texture: Texture2D, label: String, id: int = -1, accel: Key = 0) 🔗

與 add_icon_check_item() 相同,但使用選項按鈕。


void add_icon_radio_check_shortcut(texture: Texture2D, shortcut: Shortcut, id: int = -1, global: bool = false) 🔗

與 add_icon_check_shortcut() 相同,但使用一個選項按鈕。


void add_icon_shortcut(texture: Texture2D, shortcut: Shortcut, id: int = -1, global: bool = false, allow_echo: bool = false) 🔗

新增新的選單項,並為其分配指定的 Shortcut 和圖示 texture。核取方塊的標籤會被設為 Shortcut 的名稱。

還可以提供 id。如果沒有提供 id,則會根據索引來建立。

如果 allow_echo 為 true,則快捷鍵可以被回響事件啟用。


void add_item(label: String, id: int = -1, accel: Key = 0) 🔗

新增一個帶有文字 label 的新項。

可以選擇提供一個 id 以及一個加速器(accel)。如果未提供 id,將從索引中建立一個。如果未提供 accel,則預設值 0(對應於 @GlobalScope.KEY_NONE)將被分配給該項(這意味著它不會有任何加速器)。有關加速器的更多資訊,請參閱 get_item_accelerator()。

注意:提供的 id 僅用於 id_pressed 和 id_focused 訊號。它與在函式中,例如在 set_item_checked() 中的 index 參數無關。


void add_multistate_item(label: String, max_states: int, default_state: int = 0, id: int = -1, accel: Key = 0) 🔗

新增新的多狀態選單項,使用 label 作為文字。

與普通的雙態選單項不同,多狀態選單項的狀態可以超過兩個,數量由 max_states 定義。預設值由 default_state 定義。

還可以提供 id 和快捷鍵(accel)。如果沒有提供 id,則會根據索引來建立。如果沒有提供 accel,則會為該選單項分配預設的 0(對應 @GlobalScope.KEY_NONE,在這裡表示沒有快捷鍵)。更多快捷鍵相關的資訊見 get_item_accelerator()。

func _ready():
    add_multistate_item("選單項", 3, 0)

    index_pressed.connect(func(index: int):
            toggle_item_multistate(index)
            match get_item_multistate(index):
                0:
                    print("甲狀態")
                1:
                    print("乙狀態")
                2:
                    print("丙狀態")
        )

注意:多狀態選單項的狀態不會自動變化,必須手動修改。控制方法見 toggle_item_multistate()、set_item_multistate()、get_item_multistate()。


void add_radio_check_item(label: String, id: int = -1, accel: Key = 0) 🔗

新增一個帶有文字 label 的新單選勾選按鈕。

可以選擇提供一個 id 以及一個加速器(accel)。如果未提供 id,將從索引中建立一個。如果未提供 accel,則預設值 0(對應於 @GlobalScope.KEY_NONE)將被分配給該項(這意味著它不會有任何加速器)。有關加速器的更多資訊,請參閱 get_item_accelerator()。

注意:可勾選項只顯示一個勾選標記,但沒有任何內建的勾選行為,必須手動勾選/取消勾選。有關如何控制它的更多資訊,請參閱 set_item_checked()。


void add_radio_check_shortcut(shortcut: Shortcut, id: int = -1, global: bool = false) 🔗

新增一個新的單選勾選按鈕並為其分配一個 Shortcut。將核取方塊的標籤設定為 Shortcut 的名稱。

可以選擇提供一個 id。如果未提供 id,將從索引中建立一個。

注意:可勾選項只顯示一個勾選標記,但沒有任何內建的勾選行為,必須手動勾選/取消勾選。有關如何控制它的更多資訊,請參閱 set_item_checked()。


void add_separator(label: String = "", id: int = -1) 🔗

在功能表專案之間新增分隔線。分隔線也佔用索引,可以使用 id 參數設定。

還可以提供 label,會在分隔線的中間位置顯示。


void add_shortcut(shortcut: Shortcut, id: int = -1, global: bool = false, allow_echo: bool = false) 🔗

新增 Shortcut。

還可以提供 id。如果沒有提供 id,則會根據索引來建立。

如果 allow_echo 為 true,則快捷鍵可以被回響事件啟用。


void add_submenu_item(label: String, submenu: String, id: int = -1) 🔗

已棄用: Prefer using add_submenu_node_item() instead.

新增選單項,點選時會作為父級 PopupMenu 節點的子選單。submenu 參數必須是已作為子節點新增到此節點的現有 PopupMenu 的名稱。當點選該項目、懸停足夠長的時間或使用 ui_select 或 ui_right 輸入操作啟用該子選單時,將顯示該子選單。

還可以提供 id。如果沒有提供 id,則會根據索引來建立。


void add_submenu_node_item(label: String, submenu: PopupMenu, id: int = -1) 🔗

新增一個選單項,點選時會作為父級 PopupMenu 節點的子選單。當點選該項目、懸停足夠長的時間或使用 ui_select 或 ui_right 輸入操作啟用該子選單時,將顯示該子選單。

submenu 必須是該 PopupMenu 的子節點,或者沒有父節點(在這種情況下,它將自動新增為子節點)。如果 submenu 彈出視窗有另一個父級節點,則該方法將失敗。

還可以選擇提供 id。如果沒有提供 id,則將從索引建立一個。


void clear(free_submenus: bool = false) 🔗

從 PopupMenu 刪除所有專案。如果 free_submenus 為 true,則自動釋放子選單節點。


int get_focused_item() const 🔗

返回目前焦點專案的索引。如果沒有焦點,則返回 -1。


Key get_item_accelerator(index: int) const 🔗

返回給定 index 處專案的加速器。加速器是一種鍵盤快捷鍵,即使目前未打開功能表按鈕,也可以按下它來觸發功能表按鈕。返回值是一個整數,通常是 KeyModifierMask 和 Key 使用按位元或操作的組合,例如 KEY_MASK_CTRL | KEY_A(Ctrl + A)。如果沒有為指定的 index 定義加速器,則 get_item_accelerator() 返回 0(對應於 @GlobalScope.KEY_NONE)。


AutoTranslateMode get_item_auto_translate_mode(index: int) const 🔗

回傳索引為 index 的選單項的自動翻譯模式。


Texture2D get_item_icon(index: int) const 🔗

返回給定 index 處功能表專案的圖示。


int get_item_icon_max_width(index: int) const 🔗

返回給定 index 處功能表專案所允許的最大圖示寬度。


Color get_item_icon_modulate(index: int) const 🔗

返回給定 index 處用於調變功能表專案圖示的 Color。


int get_item_id(index: int) const 🔗

回傳給定 index(索引)處的項目 ID。


int get_item_indent(index: int) const 🔗

返回給定 index 處功能表專案的水平偏移量。


int get_item_index(id: int) const 🔗

回傳包含指定 id 的項目的索引。該索引會在項目被新增時由引擎自動分配,它代表了項目顯示的先後順序。


String get_item_language(index: int) const 🔗

返回專案文字的語言程式碼。


Variant get_item_metadata(index: int) const 🔗

返回指定功能表專案的中繼資料,可能是任何型別。可以使用 set_item_metadata() 來設定中繼資料,這樣就能很很方便地將本文資料分配給功能表專案。


int get_item_multistate(index: int) const 🔗

回傳索引為 index 的選單項的狀態。


int get_item_multistate_max(index: int) const 🔗

回傳索引為 index 的選單項的最大狀態數。


Shortcut get_item_shortcut(index: int) const 🔗

返回給定 index 處功能表專案所關聯的 Shortcut。


String get_item_submenu(index: int) const 🔗

已棄用: Prefer using get_item_submenu_node() instead.

返回給定 index 處功能表專案的子功能表名稱。有關如何新增子功能表的更多資訊,請參見 add_submenu_item()。


PopupMenu get_item_submenu_node(index: int) const 🔗

回傳給定 index 處選單項的子選單,如果尚未新增子選單,則回傳 null。有關如何新增子選單的更多資訊,請參閱 add_submenu_node_item()。


String get_item_text(index: int) const 🔗

返回索引為 index 的功能表專案的文字。


TextDirection get_item_text_direction(index: int) const 🔗

返回專案文字的基礎書寫方向。


String get_item_tooltip(index: int) const 🔗

返回索引為 index 的功能表專案所關聯的工具提示。


bool is_item_checkable(index: int) const 🔗

如果給定 index 處的功能表專案可以某種方式勾選,即如果它有一個核取方塊或選項按鈕,則返回 true。

注意:可勾選項僅顯示一個勾選標記或選項按鈕,但沒有任何內建的勾選行為,必須手動勾選/取消勾選。


bool is_item_checked(index: int) const 🔗

如果給定的 index 處的功能表專案被勾選,則返回 true。


bool is_item_disabled(index: int) const 🔗

如果給定 index 處的功能表專案被停用,則返回 true。功能表專案被停用時無法被選擇,對應的動作也無法被呼叫。

有關如何停用功能表專案的更多資訊,請參閱 set_item_disabled()。


bool is_item_indeterminate(index: int) const 🔗

Returns true if the item at the given index is in an indeterminate state. This only applies to checkable items and is represented visually by a horizontal line instead of a checkmark or radio button.

See set_item_indeterminate() for more info on how to set an item as indeterminate.

Note: Indeterminate items just display a horizontal line, but don't have any built-in behavior and must be set as indeterminate manually.


bool is_item_radio_checkable(index: int) const 🔗

如果給定 index 處的功能表專案具有選項按鈕樣式的可勾選性,則返回 true。

注意:這純粹是裝飾性的;必須新增用於單選組中勾選/取消勾選專案的邏輯。


bool is_item_separator(index: int) const 🔗

如果功能表專案是分隔符號,則返回 true。分隔符號會顯示為一條線。有關如何新增分隔符號的更多資訊,請參閱 add_separator()。


bool is_item_shortcut_disabled(index: int) const 🔗

如果指定功能表專案的快捷方式被停用,則返回 true。


bool is_native_menu() const 🔗

如果系統原生選單受支援,且目前由該 PopupMenu 使用,則回傳 true。


bool is_system_menu() const 🔗

如果選單與特殊系統選單進行了綁定,則回傳 true。


void remove_item(index: int) 🔗

從選單中移除給定 index 處的功能表專案。

注意:被移除的功能表專案後面的功能表專案的索引將移動一位元。


void scroll_to_item(index: int) 🔗

移動捲動視圖,使位於給定 index 的功能表專案可見。


void set_focused_item(index: int) 🔗

將目前聚焦的功能表專案設定為給定的 index。

將 -1 作為索引傳入將不會聚焦任何功能表專案。


void set_item_accelerator(index: int, accel: Key) 🔗

在給定的 index 處設定專案的加速器。加速器是一種鍵盤快捷鍵,即使目前未打開功能表按鈕,也可以按下它來觸發功能表按鈕。accel 通常是 KeyModifierMask 和 Key 使用按位元或操作的組合,例如 KEY_MASK_CTRL | KEY_A(Ctrl + A)。


void set_item_as_checkable(index: int, enable: bool) 🔗

設定給定 index 處的項是否具有一個核取方塊。如果為 false,則將項的型別設定為純文字。

注意:可勾選的項只顯示一個核取記號,但沒有任何內建的勾選行為,必須手動勾選/取消勾選。


void set_item_as_radio_checkable(index: int, enable: bool) 🔗

將給定 index 處的項的型別設定為一個選項按鈕。如果為 false,則將項的型別設定為純文字。


void set_item_as_separator(index: int, enable: bool) 🔗

將給定 index 處的項標記為分隔符號,這意味著它將顯示為直線段。如果為 false,則將項的型別設定為純文字。


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

設定索引為 index 的選單項的自動翻譯模式。

項目預設使用 Node.AUTO_TRANSLATE_MODE_INHERIT,表示使用與 PopupMenu 相同的自動翻譯模式。


void set_item_checked(index: int, checked: bool) 🔗

設定位於給定的 index 的功能表專案的勾選狀態。


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

啟用/停用位於給定 index 的功能表專案。處於停用狀態的功能表專案無法被選中,也無法呼叫其動作。


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

替換索引為 index 的功能表專案的 Texture2D 圖示。


void set_item_icon_max_width(index: int, width: int) 🔗

設定給定 index 處功能表專案所允許的最大圖示寬度。這是在圖示預設大小和 icon_max_width 的基礎上的限制。高度會根據圖示的長寬比調整。


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

設定索引為 index 的功能表專案圖示的調變 Color。


void set_item_id(index: int, id: int) 🔗

設定位於給定 index 的功能表專案的 id。

id_pressed 和 id_focused 等訊號中會用到 id。


void set_item_indent(index: int, indent: int) 🔗

設定索引為 index 的功能表專案的水平偏移量。


void set_item_indeterminate(index: int, indeterminate: bool) 🔗

Sets the indeterminate status of the item at the given index. This only applies to checkable items and is represented visually by a horizontal line instead of a checkmark or radio button.

Note: Indeterminate items just display a horizontal line, but don't have any built-in behavior and must be set as indeterminate manually.


void set_item_index(index: int, target_index: int) 🔗

將位於索引 index 處的選單項的索引更改為 target_index。這可用於將一個選單項移動到其他選單項的上方。即使被移動的選單項的 ID 是從原始索引生成的,它也會保持相同的 ID。

注意: 位於索引 index 和索引 target_index 之間的任何選單項的索引都將移動一位。


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

將給定索引處項目的文字語言程式碼設定為 language。這是用於換行和文字塑形算法的。如果 language 為空,則使用目前區域設定。


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

設定項的中繼資料,該項可以是任何型別。稍後你可以使用get_item_metadata()取得它,它提供了一種將本文資料分配給項的簡單方法。


void set_item_multistate(index: int, state: int) 🔗

設定一個多態專案的狀態。詳情請參閱 add_multistate_item()。


void set_item_multistate_max(index: int, max_states: int) 🔗

設定多狀態選單項的最大狀態數。詳見 add_multistate_item()。


void set_item_shortcut(index: int, shortcut: Shortcut, global: bool = false) 🔗

設定索引為 index 的功能表專案的 Shortcut。


void set_item_shortcut_disabled(index: int, disabled: bool) 🔗

停用索引為 index 的功能表專案的 Shortcut。


void set_item_submenu(index: int, submenu: String) 🔗

已棄用: Prefer using set_item_submenu_node() instead.

設定位於給定 index 的功能表專案的子功能表。子功能表為點選該功能表專案後應該顯示的子 PopupMenu 節點的名稱。


void set_item_submenu_node(index: int, submenu: PopupMenu) 🔗

設定給定 index 處的項目的子選單。子選單是一個 PopupMenu 節點,點選該項目時將顯示該節點。它必須是該 PopupMenu 的子級或沒有父級(在這種情況下,它將自動新增為子級)。如果 submenu 彈出視窗有另一個父級,則該方法將失敗。


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

設定索引為 index 的功能表專案的文字。


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

設定專案文字的基礎書寫方向。


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

設定索引為 index 的功能表專案的 String 工具提示。


void toggle_item_checked(index: int) 🔗

切換索引為 index 的功能表專案的選中狀態。


void toggle_item_multistate(index: int) 🔗

迴圈到一個多態專案的下一個狀態。詳情請參閱 add_multistate_item()。


主題屬性說明

Color font_accelerator_color = Color(0.7, 0.7, 0.7, 0.8) 🔗

文字 Color 用於快捷鍵和加速器,當定義時顯示在功能表專案名稱旁邊。有關加速器的更多資訊,請參閱 get_item_accelerator()。


Color font_color = Color(0.875, 0.875, 0.875, 1) 🔗

功能表專案名稱的預設文字 Color。


Color font_disabled_color = Color(0.4, 0.4, 0.4, 0.8) 🔗

用於停用功能表專案的文字 Color。


Color font_hover_color = Color(0.875, 0.875, 0.875, 1) 🔗

用於懸停文字的 Color。


Color font_outline_color = Color(0, 0, 0, 1) 🔗

功能表專案文字輪廓的色調。


Color font_separator_color = Color(0.875, 0.875, 0.875, 1) 🔗

用於標注分隔符號文字的顏色 Color。見 add_separator()。


Color font_separator_outline_color = Color(0, 0, 0, 1) 🔗

帶標籤分隔符號的文字輪廓的色調。


int gutter_compact = 1 🔗

如果不是 0,則圖示邊欄將在可能的情況下與核取方塊邊欄合併。它充當布林值。


int h_separation = 4 🔗

功能表專案元素之間的水平間距。


int icon_max_width = 0 🔗

功能表專案圖示所允許的最大寬度。這是在圖示預設大小的基礎上的限制,在 set_item_icon_max_width() 所設定的值之前生效。高度會根據圖示的長寬比調整。


int indent = 10 🔗

單個縮進級別的寬度。


int item_end_padding = 2 🔗

所有功能表專案右側的水平內邊距(RTL 佈局中為左側)。


int item_start_padding = 2 🔗

所有功能表專案左側的水平內邊距(RTL 佈局中為右側)。


int outline_size = 0 🔗

專案文字輪廓的大小。

注意:如果使用啟用了 FontFile.multichannel_signed_distance_field 的字形,其 FontFile.msdf_pixel_range 必須至少設定為 outline_size 的兩倍,輪廓渲染才能看起來正確。否則,輪廓可能會比預期的更早被切斷。


int search_bar_separation = 4 🔗

搜尋欄與選單項之間的垂直間距。


int separator_outline_size = 0 🔗

帶標籤分隔符號的文字輪廓的大小。


int v_separation = 4 🔗

每個功能表專案之間的垂直間距。


Font font 🔗

用於功能表專案的 Font 字形。


Font font_separator 🔗

用於帶文字分隔線的 Font 字形。


int font_separator_size 🔗

帶標籤分隔符號的字形大小。


int font_size 🔗

功能表專案的字形大小。


Texture2D checked 🔗

Texture2D 圖示,用於處於選中狀態的複選項。


Texture2D checked_disabled 🔗

Texture2D 圖示,用於處於選中狀態的已停用複選項。


Texture2D indeterminate 🔗

Texture2D icon for the indeterminate checkbox items.


Texture2D indeterminate_disabled 🔗

Texture2D icon for the indeterminate checkbox items when they are disabled.


Texture2D radio_checked 🔗

Texture2D 圖示,用於處於選中狀態的單選項。


Texture2D radio_checked_disabled 🔗

Texture2D 圖示,用於處於選中狀態的已停用單選項。


Texture2D radio_unchecked 🔗

Texture2D 圖示,用於處於未選狀態的單選項。


Texture2D radio_unchecked_disabled 🔗

Texture2D 圖示,用於處於未選狀態的已停用單選項。


搜尋欄中搜尋圖示的 Texture2D(2D紋理/圖片)。


Texture2D submenu 🔗

Texture2D 圖示,用於子功能表箭頭(用於從左至右佈局)。


Texture2D submenu_mirrored 🔗

Texture2D 圖示,用於子功能表箭頭(用於從右至左佈局)。


Texture2D unchecked 🔗

Texture2D 圖示,用於處於未選狀態的複選項。


Texture2D unchecked_disabled 🔗

Texture2D 圖示,用於處於未選狀態的已停用複選項。


AudioStream item_activated_disabled_sound 🔗

Played when activating a disabled item is attempted.


AudioStream item_activated_sound 🔗

Played when an item is activated.


AudioStream item_hovered_sound 🔗

Played when an item is hovered. Disabled items do not play a hover sound.


StyleBox hover 🔗

當 PopupMenu 功能表專案被懸停時顯示的 StyleBox。


StyleBox labeled_separator_left 🔗

用於標籤分隔器的左側 StyleBox。請參閱 add_separator()。


StyleBox labeled_separator_right 🔗

用於標籤分隔器的右側 StyleBox。請參閱 add_separator()。


StyleBox panel 🔗

用於背景面板的 StyleBox。


StyleBox separator 🔗

用於分隔符號的 StyleBox。請參閱 add_separator()。