A modal window used to display a list of options.
PopupMenu is a modal window used to display a list of options. Useful for toolbars and 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 indices, i.e. -1 to access the last item, -2 to select the second-to-last item, and so on.
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.
Note: PopupMenu is invisible by default. To make it visible, call one of the popup_* methods from Window on the node, such as Window.popup_centered_clamped().
Note: The ID values used for items are limited to 32 bits, not full 64 bits of int. This has a range of -2^32 to 2^32 - 1, i.e. -2147483648 to 2147483647.
If true, hides the PopupMenu when a checkbox or radio button is selected.
If true, hides the PopupMenu when a state item is selected.
The checkable item type of the item at index.
Note: index is a value in the 0 .. item_count - 1 range.
If true, shows a search bar at the top of the PopupMenu for filtering items. See search_bar_min_item_count for dynamically controlling its visibility based on the number of items.
Note: When enabled, allow_search is ignored.
If true, enables fuzzy searching in the PopupMenu search bar. This allows the search results to include items that almost match the search query, as well items that match the individual characters of the search query, but not in sequence.
Use search_bar_fuzzy_search_max_misses to set the maximum number of mismatches allowed in the search results.
Sets the maximum number of mismatches allowed in each search result when fuzzy searching is enabled for the PopupMenu search bar. Any item with more mismatches will be hidden from the search results.
Sets the minimum number of items required for the search bar to be visible. search_bar_enabled must be true for this to have any effect. Separator items are not counted.
Checks the provided event against the PopupMenu's shortcuts and accelerators, and activates the first item with matching events. If for_global_only is true, only shortcuts and accelerators with global set to true will be called.
Returns true if an item was successfully activated.
Note: Certain Controls, such as MenuButton, will call this method automatically.
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 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.
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.
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 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.
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.
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 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.
Same as add_icon_check_item(), but uses a radio check button.
Same as add_icon_check_shortcut(), but uses a radio check button.
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 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().
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. 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 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.
func _ready():
add_multistate_item("Item", 3, 0)
index_pressed.connect(func(index: int):
toggle_item_multistate(index)
match get_item_multistate(index):
0:
print("First state")
1:
print("Second state")
2:
print("Third state")
)Note: Multistate items don't update their state automatically and must be done manually. See toggle_item_multistate(), set_item_multistate() and get_item_multistate() for more info on how to control it.
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 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.
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.
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.
Adds a Shortcut.
An id can optionally be provided. If no id is provided, one will be created from the index.
If allow_echo is true, the shortcut can be activated with echo events.
Removes all items from the PopupMenu. If free_submenus is true, the submenu nodes are automatically freed.
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 bitwise 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 KEY_NONE).
Returns a Color modulating the item's icon at the given index.
Returns the index of the item containing the specified id. The index is automatically assigned to each item by the engine when added and represents the order items will be displayed.
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.
Returns the Shortcut associated with the item at the given index.
Returns true if the item at the given index is checkable in some way, i.e. if it has a checkbox or radio button.
Note: Checkable items just display a checkmark or radio button, but don't have any built-in checking behavior and must be checked/unchecked manually.
Returns true if the item at the given index is disabled. When it is disabled it can't be selected, or its action invoked.
See set_item_disabled() for more info on how to disable an item.
Returns true if the item at the given index has radio button-style checkability.
Note: This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups.
Returns true if the item is a separator. If it is, it will be displayed as a line. See add_separator() for more info on how to add a separator.
Removes the item at the given index from the menu.
Note: The indices of items after the removed item will be shifted by one.
Sets the currently focused item as the given index.
Passing -1 as the index makes so that no item is focused.
Sets 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. accel is generally a combination of KeyModifierMasks and Keys using bitwise OR such as KEY_MASK_CTRL | KEY_A (Ctrl + A).
Sets whether the item at the given index has a checkbox. If false, sets the type of the item to plain text.
Note: Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually.
Sets the type of the item at the given index to radio button. If false, sets the type of the item to plain text.
Mark the item at the given index as a separator, which means that it would be displayed as a line. If false, sets the type of the item to plain text.
Sets the auto translate mode of the item at the given index.
Items use Node.AUTO_TRANSLATE_MODE_INHERIT by default, which uses the same auto translate mode as the PopupMenu itself.
Enables/disables the item at the given index. When it is disabled, it can't be selected and its action can't be invoked.
Replaces the Texture2D icon of the item at the given index.
Sets the maximum allowed width of the icon for the item at the given index. This limit is applied on top of the default size of the icon and on top of icon_max_width. The height is adjusted according to the icon's ratio.
Sets a modulating Color of the item's icon at the given index.
Sets the id of the item at the given index.
The id is used in id_pressed and id_focused signals.
Changes the index of the item at index index to be at index target_index. This can be used to move an item above other items. The moved item will keep the same ID, even if it was generated from the original index.
Note: The indices of any items between index index and index target_index will be shifted by one.
Sets the language code of the text for the item at the given index to language. This is used for line-breaking and text shaping algorithms. If language is empty, the current locale is used.
Sets the metadata of an item, which may be of any type. You can later get it with get_item_metadata(), which provides a simple way of assigning context data to items.
Sets the state of a multistate item. See add_multistate_item() for details.
Sets the max states of a multistate item. See add_multistate_item() for details.
Sets a Shortcut for the item at the given index.
Disables the Shortcut of the item at the given index.
Sets the String tooltip of the item at the given index.
Cycle to the next state of a multistate item. See add_multistate_item() for details.
Emitted when the user navigated to an item of some id using the ProjectSettings.input/ui_up or ProjectSettings.input/ui_down input action.
Emitted when an item of some id is pressed. Also emitted when its accelerator is activated on macOS.
Note: If id is negative (either explicitly or due to overflow), this will return the corresponding index instead.
Emitted when an item of some index is pressed. Also emitted when its accelerator is activated on macOS.