Table of Contents

Class PopupMenu

Namespace
Godot
Assembly
GodotSharp.dll

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 MaxSize. 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: 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.

public class PopupMenu : Popup, IDisposable
Inheritance
PopupMenu
Implements
Inherited Members

Constructors

PopupMenu() 

public PopupMenu()

Properties

AllowSearch

If true, allows navigating PopupMenu with letter keys.

public bool AllowSearch { get; set; }

Property Value

bool

HideOnCheckableItemSelection

If true, hides the PopupMenu when a checkbox or radio button is selected.

public bool HideOnCheckableItemSelection { get; set; }

Property Value

bool

HideOnItemSelection

If true, hides the PopupMenu when an item is selected.

public bool HideOnItemSelection { get; set; }

Property Value

bool

HideOnStateItemSelection

If true, hides the PopupMenu when a state item is selected.

public bool HideOnStateItemSelection { get; set; }

Property Value

bool

ItemCount

The number of items currently in the list.

public int ItemCount { get; set; }

Property Value

int

SubmenuPopupDelay

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.

public float SubmenuPopupDelay { get; set; }

Property Value

float

Methods

ActivateItemByEvent(InputEvent, bool)

Checks the provided event against the PopupMenu's shortcuts and accelerators, and activates the first item with matching events. If forGlobalOnly 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.

public bool ActivateItemByEvent(InputEvent @event, bool forGlobalOnly = false)

Parameters

event InputEvent
forGlobalOnly bool

Returns

bool

AddCheckItem(string, int, Key)

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 None) will be assigned to the item (which means it won't have any accelerator). See GetItemAccelerator(int) 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 SetItemChecked(int, bool) for more info on how to control it.

public void AddCheckItem(string label, int id = -1, Key accel = Key.None)

Parameters

label string
id int
accel Key

AddCheckShortcut(Shortcut, int, bool)

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 SetItemChecked(int, bool) for more info on how to control it.

public void AddCheckShortcut(Shortcut shortcut, int id = -1, bool global = false)

Parameters

shortcut Shortcut
id int
global bool

AddIconCheckItem(Texture2D, string, int, Key)

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 None) will be assigned to the item (which means it won't have any accelerator). See GetItemAccelerator(int) 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 SetItemChecked(int, bool) for more info on how to control it.

public void AddIconCheckItem(Texture2D texture, string label, int id = -1, Key accel = Key.None)

Parameters

texture Texture2D
label string
id int
accel Key

AddIconCheckShortcut(Texture2D, Shortcut, int, bool)

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 SetItemChecked(int, bool) for more info on how to control it.

public void AddIconCheckShortcut(Texture2D texture, Shortcut shortcut, int id = -1, bool global = false)

Parameters

texture Texture2D
shortcut Shortcut
id int
global bool

AddIconItem(Texture2D, string, int, Key)

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 None) will be assigned to the item (which means it won't have any accelerator). See GetItemAccelerator(int) for more info on accelerators.

public void AddIconItem(Texture2D texture, string label, int id = -1, Key accel = Key.None)

Parameters

texture Texture2D
label string
id int
accel Key

AddIconRadioCheckItem(Texture2D, string, int, Key)

Same as AddIconCheckItem(Texture2D, string, int, Key), but uses a radio check button.

public void AddIconRadioCheckItem(Texture2D texture, string label, int id = -1, Key accel = Key.None)

Parameters

texture Texture2D
label string
id int
accel Key

AddIconRadioCheckShortcut(Texture2D, Shortcut, int, bool)

Same as AddIconCheckShortcut(Texture2D, Shortcut, int, bool), but uses a radio check button.

public void AddIconRadioCheckShortcut(Texture2D texture, Shortcut shortcut, int id = -1, bool global = false)

Parameters

texture Texture2D
shortcut Shortcut
id int
global bool

AddIconShortcut(Texture2D, Shortcut, int, bool, bool)

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.

If allowEcho is true, the shortcut can be activated with echo events.

public void AddIconShortcut(Texture2D texture, Shortcut shortcut, int id = -1, bool global = false, bool allowEcho = false)

Parameters

texture Texture2D
shortcut Shortcut
id int
global bool
allowEcho bool

AddItem(string, int, Key)

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 None) will be assigned to the item (which means it won't have any accelerator). See GetItemAccelerator(int) for more info on accelerators.

Note: The provided id is used only in IdPressed and IdFocused signals. It's not related to the index arguments in e.g. SetItemChecked(int, bool).

public void AddItem(string label, int id = -1, Key accel = Key.None)

Parameters

label string
id int
accel Key

AddMultistateItem(string, int, int, int, Key)

Adds a new multistate item with text label.

Contrarily to normal binary items, multistate items can have more than two states, as defined by maxStates. Each press or activate of the item will increase the state by one. The default value is defined by defaultState.

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 None) will be assigned to the item (which means it won't have any accelerator). See GetItemAccelerator(int) for more info on accelerators.

public void AddMultistateItem(string label, int maxStates, int defaultState = 0, int id = -1, Key accel = Key.None)

Parameters

label string
maxStates int
defaultState int
id int
accel Key

AddRadioCheckItem(string, int, Key)

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 None) will be assigned to the item (which means it won't have any accelerator). See GetItemAccelerator(int) 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 SetItemChecked(int, bool) for more info on how to control it.

public void AddRadioCheckItem(string label, int id = -1, Key accel = Key.None)

Parameters

label string
id int
accel Key

AddRadioCheckShortcut(Shortcut, int, bool)

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 SetItemChecked(int, bool) for more info on how to control it.

public void AddRadioCheckShortcut(Shortcut shortcut, int id = -1, bool global = false)

Parameters

shortcut Shortcut
id int
global bool

AddSeparator(string, int)

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.

public void AddSeparator(string label = "", int id = -1)

Parameters

label string
id int

AddShortcut(Shortcut, int, bool, bool)

Adds a Shortcut.

An id can optionally be provided. If no id is provided, one will be created from the index.

If allowEcho is true, the shortcut can be activated with echo events.

public void AddShortcut(Shortcut shortcut, int id = -1, bool global = false, bool allowEcho = false)

Parameters

shortcut Shortcut
id int
global bool
allowEcho bool

AddSubmenuItem(string, string, int)

Adds an item that will act as a submenu of the parent PopupMenu node when clicked. The submenu argument must be the name of an existing PopupMenu that has been added as a child to this node. This submenu will be shown when the item is clicked, hovered for long enough, or activated using the ui_select or ui_right input actions.

An id can optionally be provided. If no id is provided, one will be created from the index.

public void AddSubmenuItem(string label, string submenu, int id = -1)

Parameters

label string
submenu string
id int

Clear(bool)

Removes all items from the PopupMenu. If freeSubmenus is true, the submenu nodes are automatically freed.

public void Clear(bool freeSubmenus = false)

Parameters

freeSubmenus bool

GetFocusedItem()

Returns the index of the currently focused item. Returns -1 if no item is focused.

public int GetFocusedItem()

Returns

int

GetItemAccelerator(int)

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, GetItemAccelerator(int) returns 0 (corresponding to None).

public Key GetItemAccelerator(int index)

Parameters

index int

Returns

Key

GetItemIcon(int)

Returns the icon of the item at the given index.

public Texture2D GetItemIcon(int index)

Parameters

index int

Returns

Texture2D

GetItemIconMaxWidth(int)

Returns the maximum allowed width of the icon for the item at the given index.

public int GetItemIconMaxWidth(int index)

Parameters

index int

Returns

int

GetItemIconModulate(int)

Returns a Color modulating the item's icon at the given index.

public Color GetItemIconModulate(int index)

Parameters

index int

Returns

Color

GetItemId(int)

Returns the ID of the item at the given index. id can be manually assigned, while index can not.

public int GetItemId(int index)

Parameters

index int

Returns

int

GetItemIndent(int)

Returns the horizontal offset of the item at the given index.

public int GetItemIndent(int index)

Parameters

index int

Returns

int

GetItemIndex(int)

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.

public int GetItemIndex(int id)

Parameters

id int

Returns

int

GetItemLanguage(int)

Returns item's text language code.

public string GetItemLanguage(int index)

Parameters

index int

Returns

string

GetItemMetadata(int)

Returns the metadata of the specified item, which might be of any type. You can set it with SetItemMetadata(int, Variant), which provides a simple way of assigning context data to items.

public Variant GetItemMetadata(int index)

Parameters

index int

Returns

Variant

GetItemShortcut(int)

Returns the Shortcut associated with the item at the given index.

public Shortcut GetItemShortcut(int index)

Parameters

index int

Returns

Shortcut

GetItemSubmenu(int)

Returns the submenu name of the item at the given index. See AddSubmenuItem(string, string, int) for more info on how to add a submenu.

public string GetItemSubmenu(int index)

Parameters

index int

Returns

string

GetItemText(int)

Returns the text of the item at the given index.

public string GetItemText(int index)

Parameters

index int

Returns

string

GetItemTextDirection(int)

Returns item's text base writing direction.

public Control.TextDirection GetItemTextDirection(int index)

Parameters

index int

Returns

Control.TextDirection

GetItemTooltip(int)

Returns the tooltip associated with the item at the given index.

public string GetItemTooltip(int index)

Parameters

index int

Returns

string

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

IsItemCheckable(int)

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.

public bool IsItemCheckable(int index)

Parameters

index int

Returns

bool

IsItemChecked(int)

Returns true if the item at the given index is checked.

public bool IsItemChecked(int index)

Parameters

index int

Returns

bool

IsItemDisabled(int)

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 SetItemDisabled(int, bool) for more info on how to disable an item.

public bool IsItemDisabled(int index)

Parameters

index int

Returns

bool

IsItemRadioCheckable(int)

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.

public bool IsItemRadioCheckable(int index)

Parameters

index int

Returns

bool

IsItemSeparator(int)

Returns true if the item is a separator. If it is, it will be displayed as a line. See AddSeparator(string, int) for more info on how to add a separator.

public bool IsItemSeparator(int index)

Parameters

index int

Returns

bool

IsItemShortcutDisabled(int)

Returns true if the specified item's shortcut is disabled.

public bool IsItemShortcutDisabled(int index)

Parameters

index int

Returns

bool

RemoveItem(int)

Removes the item at the given index from the menu.

Note: The indices of items after the removed item will be shifted by one.

public void RemoveItem(int index)

Parameters

index int

ScrollToItem(int)

Moves the scroll view to make the item at the given index visible.

public void ScrollToItem(int index)

Parameters

index int

SetFocusedItem(int)

Sets the currently focused item as the given index.

Passing -1 as the index makes so that no item is focused.

public void SetFocusedItem(int index)

Parameters

index int

SetItemAccelerator(int, Key)

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).

public void SetItemAccelerator(int index, Key accel)

Parameters

index int
accel Key

SetItemAsCheckable(int, bool)

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.

public void SetItemAsCheckable(int index, bool enable)

Parameters

index int
enable bool

SetItemAsRadioCheckable(int, bool)

Sets the type of the item at the given index to radio button. If false, sets the type of the item to plain text.

public void SetItemAsRadioCheckable(int index, bool enable)

Parameters

index int
enable bool

SetItemAsSeparator(int, bool)

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.

public void SetItemAsSeparator(int index, bool enable)

Parameters

index int
enable bool

SetItemChecked(int, bool)

Sets the checkstate status of the item at the given index.

public void SetItemChecked(int index, bool @checked)

Parameters

index int
checked bool

SetItemDisabled(int, bool)

Enables/disables the item at the given index. When it is disabled, it can't be selected and its action can't be invoked.

public void SetItemDisabled(int index, bool disabled)

Parameters

index int
disabled bool

SetItemIcon(int, Texture2D)

Replaces the Texture2D icon of the item at the given index.

public void SetItemIcon(int index, Texture2D icon)

Parameters

index int
icon Texture2D

SetItemIconMaxWidth(int, int)

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.

public void SetItemIconMaxWidth(int index, int width)

Parameters

index int
width int

SetItemIconModulate(int, Color)

Sets a modulating Color of the item's icon at the given index.

public void SetItemIconModulate(int index, Color modulate)

Parameters

index int
modulate Color

SetItemId(int, int)

Sets the id of the item at the given index.

The id is used in IdPressed and IdFocused signals.

public void SetItemId(int index, int id)

Parameters

index int
id int

SetItemIndent(int, int)

Sets the horizontal offset of the item at the given index.

public void SetItemIndent(int index, int indent)

Parameters

index int
indent int

SetItemLanguage(int, string)

Sets language code of item's text used for line-breaking and text shaping algorithms, if left empty current locale is used instead.

public void SetItemLanguage(int index, string language)

Parameters

index int
language string

SetItemMetadata(int, Variant)

Sets the metadata of an item, which may be of any type. You can later get it with GetItemMetadata(int), which provides a simple way of assigning context data to items.

public void SetItemMetadata(int index, Variant metadata)

Parameters

index int
metadata Variant

SetItemMultistate(int, int)

Sets the state of a multistate item. See AddMultistateItem(string, int, int, int, Key) for details.

public void SetItemMultistate(int index, int state)

Parameters

index int
state int

SetItemShortcut(int, Shortcut, bool)

Sets a Shortcut for the item at the given index.

public void SetItemShortcut(int index, Shortcut shortcut, bool global = false)

Parameters

index int
shortcut Shortcut
global bool

SetItemShortcutDisabled(int, bool)

Disables the Shortcut of the item at the given index.

public void SetItemShortcutDisabled(int index, bool disabled)

Parameters

index int
disabled bool

SetItemSubmenu(int, string)

Sets the submenu of the item at the given index. The submenu is the name of a child PopupMenu node that would be shown when the item is clicked.

public void SetItemSubmenu(int index, string submenu)

Parameters

index int
submenu string

SetItemText(int, string)

Sets the text of the item at the given index.

public void SetItemText(int index, string text)

Parameters

index int
text string

SetItemTextDirection(int, TextDirection)

Sets item's text base writing direction.

public void SetItemTextDirection(int index, Control.TextDirection direction)

Parameters

index int
direction Control.TextDirection

SetItemTooltip(int, string)

Sets the string tooltip of the item at the given index.

public void SetItemTooltip(int index, string tooltip)

Parameters

index int
tooltip string

ToggleItemChecked(int)

Toggles the check state of the item at the given index.

public void ToggleItemChecked(int index)

Parameters

index int

ToggleItemMultistate(int)

Cycle to the next state of a multistate item. See AddMultistateItem(string, int, int, int, Key) for details.

public void ToggleItemMultistate(int index)

Parameters

index int

Events

IdFocused

Emitted when the user navigated to an item of some id using the ProjectSettings.input/ui_up or ProjectSettings.input/ui_down input action.

public event PopupMenu.IdFocusedEventHandler IdFocused

Event Type

PopupMenu.IdFocusedEventHandler

IdPressed

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.

public event PopupMenu.IdPressedEventHandler IdPressed

Event Type

PopupMenu.IdPressedEventHandler

IndexPressed

Emitted when an item of some index is pressed or its accelerator is activated.

public event PopupMenu.IndexPressedEventHandler IndexPressed

Event Type

PopupMenu.IndexPressedEventHandler

MenuChanged

Emitted when any item is added, modified or removed.

public event Action MenuChanged

Event Type

Action
Edit this page