Up to date
This page is up to date for Godot 4.0
.
If you still find outdated information, please open an issue.
PopupMenu¶
Inherits: Popup < Window < Viewport < Node < Object
PopupMenu displays a list of options.
Description¶
PopupMenu is a modal window used to display a list of options. They are popular in toolbars or context menus.
The size of a PopupMenu can be limited by using Window.max_size. If the height of the list of items is larger than the maximum height of the PopupMenu, a ScrollContainer within the popup will allow the user to scroll the contents.
If no maximum size is set, or if it is set to 0, the PopupMenu height will be limited by its parent rect.
All set_*
methods allow negative item index, which makes the item accessed from the last one.
Incremental search: Like ItemList and Tree, PopupMenu supports searching within the list while the control is focused. Press a key that matches the first letter of an item's name to select the first item starting with the given letter. After that point, there are two ways to perform incremental search: 1) Press the same key again before the timeout duration to select the next item starting with the same letter. 2) Press letter keys that match the rest of the word before the timeout duration to match to select the item in question directly. Both of these actions will be reset to the beginning of the list if the timeout duration has passed since the last keystroke was registered. You can adjust the timeout duration by changing ProjectSettings.gui/timers/incremental_search_max_interval_msec.
Properties¶
|
||
|
||
|
||
|
||
|
||
|
Methods¶
void |
add_check_item ( String label, int id=-1, Key accel=0 ) |
void |
add_check_shortcut ( Shortcut shortcut, int id=-1, bool global=false ) |
void |
add_icon_check_item ( Texture2D texture, String label, int id=-1, Key accel=0 ) |
void |
add_icon_check_shortcut ( Texture2D texture, Shortcut shortcut, int id=-1, bool global=false ) |
void |
add_icon_item ( Texture2D texture, String label, int id=-1, Key accel=0 ) |
void |
add_icon_radio_check_item ( Texture2D texture, String label, int id=-1, Key accel=0 ) |
void |
add_icon_radio_check_shortcut ( Texture2D texture, Shortcut shortcut, int id=-1, bool global=false ) |
void |
add_icon_shortcut ( Texture2D texture, Shortcut shortcut, int id=-1, bool global=false ) |
void |
|
void |
add_multistate_item ( String label, int max_states, int default_state=0, int id=-1, Key accel=0 ) |
void |
add_radio_check_item ( String label, int id=-1, Key accel=0 ) |
void |
add_radio_check_shortcut ( Shortcut shortcut, int id=-1, bool global=false ) |
void |
add_separator ( String label="", int id=-1 ) |
void |
add_shortcut ( Shortcut shortcut, int id=-1, bool global=false ) |
void |
add_submenu_item ( String label, String submenu, int id=-1 ) |
void |
clear ( ) |
get_focused_item ( ) const |
|
get_item_accelerator ( int index ) const |
|
get_item_icon ( int index ) const |
|
get_item_id ( int index ) const |
|
get_item_indent ( int index ) const |
|
get_item_index ( int id ) const |
|
get_item_language ( int index ) const |
|
get_item_metadata ( int index ) const |
|
get_item_shortcut ( int index ) const |
|
get_item_submenu ( int index ) const |
|
get_item_text ( int index ) const |
|
get_item_text_direction ( int index ) const |
|
get_item_tooltip ( int index ) const |
|
is_item_checkable ( int index ) const |
|
is_item_checked ( int index ) const |
|
is_item_disabled ( int index ) const |
|
is_item_radio_checkable ( int index ) const |
|
is_item_separator ( int index ) const |
|
is_item_shortcut_disabled ( int index ) const |
|
void |
remove_item ( int index ) |
void |
scroll_to_item ( int index ) |
void |
set_focused_item ( int index ) |
void |
set_item_accelerator ( int index, Key accel ) |
void |
set_item_as_checkable ( int index, bool enable ) |
void |
set_item_as_radio_checkable ( int index, bool enable ) |
void |
set_item_as_separator ( int index, bool enable ) |
void |
set_item_checked ( int index, bool checked ) |
void |
set_item_disabled ( int index, bool disabled ) |
void |
set_item_icon ( int index, Texture2D icon ) |
void |
set_item_id ( int index, int id ) |
void |
set_item_indent ( int index, int indent ) |
void |
set_item_language ( int index, String language ) |
void |
set_item_metadata ( int index, Variant metadata ) |
void |
set_item_multistate ( int index, int state ) |
void |
set_item_shortcut ( int index, Shortcut shortcut, bool global=false ) |
void |
set_item_shortcut_disabled ( int index, bool disabled ) |
void |
set_item_submenu ( int index, String submenu ) |
void |
set_item_text ( int index, String text ) |
void |
set_item_text_direction ( int index, TextDirection direction ) |
void |
set_item_tooltip ( int index, String tooltip ) |
void |
toggle_item_checked ( int index ) |
void |
toggle_item_multistate ( int index ) |
Theme Properties¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Signals¶
id_focused ( int id )
Emitted when the user navigated to an item of some id
using the ProjectSettings.input/ui_up or ProjectSettings.input/ui_down input action.
id_pressed ( int id )
Emitted when an item of some id
is pressed or its accelerator is activated.
Note: If id
is negative (either explicitly or due to overflow), this will return the corresponding index instead.
index_pressed ( int index )
Emitted when an item of some index
is pressed or its accelerator is activated.
menu_changed ( )
Emitted when any item is added, modified or removed.
Property Descriptions¶
bool allow_search = true
If true
, allows navigating PopupMenu with letter keys.
bool hide_on_checkable_item_selection = true
void set_hide_on_checkable_item_selection ( bool value )
bool is_hide_on_checkable_item_selection ( )
If true
, hides the PopupMenu when a checkbox or radio button is selected.
bool hide_on_item_selection = true
If true
, hides the PopupMenu when an item is selected.
bool hide_on_state_item_selection = false
If true
, hides the PopupMenu when a state item is selected.
int item_count = 0
The number of items currently in the list.
float submenu_popup_delay = 0.3
Sets the delay time in seconds for the submenu item to popup on mouse hovering. If the popup menu is added as a child of another (acting as a submenu), it will inherit the delay time of the parent menu item.
Method Descriptions¶
void add_check_item ( String label, int id=-1, Key accel=0 )
Adds a new checkable item with text label
.
An id
can optionally be provided, as well as an accelerator (accel
). If no id
is provided, one will be created from the index. If no accel
is provided, then the default value of 0 (corresponding to @GlobalScope.KEY_NONE) will be assigned to the item (which means it won't have any accelerator). See get_item_accelerator for more info on accelerators.
Note: Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See set_item_checked for more info on how to control it.
void add_check_shortcut ( Shortcut shortcut, int id=-1, bool global=false )
Adds a new checkable item and assigns the specified Shortcut to it. Sets the label of the checkbox to the Shortcut's name.
An id
can optionally be provided. If no id
is provided, one will be created from the index.
Note: Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See set_item_checked for more info on how to control it.
void add_icon_check_item ( Texture2D texture, String label, int id=-1, Key accel=0 )
Adds a new checkable item with text label
and icon texture
.
An id
can optionally be provided, as well as an accelerator (accel
). If no id
is provided, one will be created from the index. If no accel
is provided, then the default value of 0 (corresponding to @GlobalScope.KEY_NONE) will be assigned to the item (which means it won't have any accelerator). See get_item_accelerator for more info on accelerators.
Note: Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See set_item_checked for more info on how to control it.
void add_icon_check_shortcut ( Texture2D texture, Shortcut shortcut, int id=-1, bool global=false )
Adds a new checkable item and assigns the specified Shortcut and icon texture
to it. Sets the label of the checkbox to the Shortcut's name.
An id
can optionally be provided. If no id
is provided, one will be created from the index.
Note: Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See set_item_checked for more info on how to control it.
void add_icon_item ( Texture2D texture, String label, int id=-1, Key accel=0 )
Adds a new item with text label
and icon texture
.
An id
can optionally be provided, as well as an accelerator (accel
). If no id
is provided, one will be created from the index. If no accel
is provided, then the default value of 0 (corresponding to @GlobalScope.KEY_NONE) will be assigned to the item (which means it won't have any accelerator). See get_item_accelerator for more info on accelerators.
void add_icon_radio_check_item ( Texture2D texture, String label, int id=-1, Key accel=0 )
Same as add_icon_check_item, but uses a radio check button.
void add_icon_radio_check_shortcut ( Texture2D texture, Shortcut shortcut, int id=-1, bool global=false )
Same as add_icon_check_shortcut, but uses a radio check button.
void add_icon_shortcut ( Texture2D texture, Shortcut shortcut, int id=-1, bool global=false )
Adds a new item and assigns the specified Shortcut and icon texture
to it. Sets the label of the checkbox to the Shortcut's name.
An id
can optionally be provided. If no id
is provided, one will be created from the index.
void add_item ( String label, int id=-1, Key accel=0 )
Adds a new item with text label
.
An id
can optionally be provided, as well as an accelerator (accel
). If no id
is provided, one will be created from the index. If no accel
is provided, then the default value of 0 (corresponding to @GlobalScope.KEY_NONE) will be assigned to the item (which means it won't have any accelerator). See get_item_accelerator for more info on accelerators.
Note: The provided id
is used only in id_pressed and id_focused signals. It's not related to the index
arguments in e.g. set_item_checked.
void add_multistate_item ( String label, int max_states, int default_state=0, int id=-1, Key accel=0 )
Adds a new multistate item with text label
.
Contrarily to normal binary items, multistate items can have more than two states, as defined by max_states
. Each press or activate of the item will increase the state by one. The default value is defined by default_state
.
An id
can optionally be provided, as well as an accelerator (accel
). If no id
is provided, one will be created from the index. If no accel
is provided, then the default value of 0 (corresponding to @GlobalScope.KEY_NONE) will be assigned to the item (which means it won't have any accelerator). See get_item_accelerator for more info on accelerators.
void add_radio_check_item ( String label, int id=-1, Key accel=0 )
Adds a new radio check button with text label
.
An id
can optionally be provided, as well as an accelerator (accel
). If no id
is provided, one will be created from the index. If no accel
is provided, then the default value of 0 (corresponding to @GlobalScope.KEY_NONE) will be assigned to the item (which means it won't have any accelerator). See get_item_accelerator for more info on accelerators.
Note: Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See set_item_checked for more info on how to control it.
void add_radio_check_shortcut ( Shortcut shortcut, int id=-1, bool global=false )
Adds a new radio check button and assigns a Shortcut to it. Sets the label of the checkbox to the Shortcut's name.
An id
can optionally be provided. If no id
is provided, one will be created from the index.
Note: Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See set_item_checked for more info on how to control it.
void add_separator ( String label="", int id=-1 )
Adds a separator between items. Separators also occupy an index, which you can set by using the id
parameter.
A label
can optionally be provided, which will appear at the center of the separator.
void add_shortcut ( Shortcut shortcut, int id=-1, bool global=false )
Adds a Shortcut.
An id
can optionally be provided. If no id
is provided, one will be created from the index.
void add_submenu_item ( String label, String submenu, int id=-1 )
Adds an item that will act as a submenu of the parent PopupMenu node when clicked. The submenu
argument is the name of the child PopupMenu node that will be shown when the item is clicked.
An id
can optionally be provided. If no id
is provided, one will be created from the index.
void clear ( )
Removes all items from the PopupMenu.
int get_focused_item ( ) const
Returns the index of the currently focused item. Returns -1
if no item is focused.
Key get_item_accelerator ( int index ) const
Returns the accelerator of the item at the given index
. An accelerator is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The return value is an integer which is generally a combination of KeyModifierMasks and Keys using boolean OR such as KEY_MASK_CTRL | KEY_A
(Ctrl + A). If no accelerator is defined for the specified index
, get_item_accelerator returns 0
(corresponding to @GlobalScope.KEY_NONE).
Texture2D get_item_icon ( int index ) const
Returns the icon of the item at the given index
.
int get_item_id ( int index ) const
Returns the ID of the item at the given index
. id
can be manually assigned, while index can not.
int get_item_indent ( int index ) const
Returns the horizontal offset of the item at the given index
.
int get_item_index ( int id ) const
Returns the index of the item containing the specified id
. Index is automatically assigned to each item by the engine and can not be set manually.
String get_item_language ( int index ) const
Returns item's text language code.
Variant get_item_metadata ( int index ) const
Returns the metadata of the specified item, which might be of any type. You can set it with set_item_metadata, which provides a simple way of assigning context data to items.