PopupMenu

PopupMenu displays a list of options.

is a that displays a list of options. They are popular in toolbars or context menus.

Incremental search: Like ItemList and , 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

Theme Properties

• id_focused ( id )

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

• id_pressed ( int id )

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

• index_pressed ( index )

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

Property Descriptions

• allow_search

If true, allows navigating PopupMenu with letter keys.

• bool hide_on_checkable_item_selection

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

• hide_on_item_selection

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

• bool hide_on_state_item_selection

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

• submenu_popup_delay

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.

• void add_check_item ( label, int id=-1, 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 0 will be assigned to it. 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 for more info on how to control it.

• void add_check_shortcut ( ShortCut shortcut, id=-1, bool global=false )

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 for more info on how to control it.

• void add_icon_check_item ( Texture texture, label, int id=-1, 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 0 will be assigned to it. 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 for more info on how to control it.

• void add_icon_check_shortcut ( Texture texture, shortcut, int id=-1, 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 ‘s name.

An 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 ( texture, String label, id=-1, int 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 0 will be assigned to it. See for more info on accelerators.

• void add_icon_radio_check_item ( Texture texture, label, int id=-1, accel=0 )

Same as add_icon_check_item, but uses a radio check button.

• void add_icon_radio_check_shortcut ( texture, ShortCut shortcut, id=-1, bool global=false )

Same as , but uses a radio check button.

• void add_icon_shortcut ( Texture texture, shortcut, int id=-1, global=false )

Adds a new item and assigns the specified ShortCut and icon texture to it. Sets the label of the checkbox to the ‘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, id=-1, int 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 0 will be assigned to it. See for more info on accelerators.

• void add_multistate_item ( String label, max_states, int default_state=0, id=-1, int 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 0 will be assigned to it. See for more info on accelerators.

• void add_radio_check_item ( String label, id=-1, int 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 0 will be assigned to it. See 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, int id=-1, global=false )

Adds a new radio check button and assigns a ShortCut to it. Sets the label of the checkbox to the ‘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 ( 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.

Adds a .

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

• void add_submenu_item ( String label, 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.

• get_current_index ( ) const

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

• int get_item_accelerator ( idx ) const

Returns the accelerator of the item at index idx. Accelerators are special combinations of keys that activate the item, no matter which control is focused.

• int get_item_count ( ) const

Returns the number of items in the PopupMenu.

• get_item_icon ( int idx ) const

Returns the icon of the item at index idx.

• get_item_id ( int idx ) const

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

• 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. Index can not be set manually.

• get_item_metadata ( int idx ) const

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

• ShortCut get_item_shortcut ( idx ) const

Returns the ShortCut associated with the specified idx item.

• get_item_submenu ( int idx ) const

Returns the submenu name of the item at index idx. See for more info on how to add a submenu.

• String get_item_text ( idx ) const

Returns the text of the item at index idx.

• String get_item_tooltip ( idx ) const

Returns the tooltip associated with the specified index idx.

• bool is_hide_on_window_lose_focus ( ) const

Returns true if the popup will be hidden when the window loses focus or not.

• is_item_checkable ( int idx ) const

Returns true if the item at index idx 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.

• is_item_checked ( int idx ) const

Returns true if the item at index idx is checked.

• is_item_disabled ( int idx ) const

Returns true if the item at index idx is disabled. When it is disabled it can’t be selected, or its action invoked.

See for more info on how to disable an item.

• bool is_item_radio_checkable ( idx ) const

Returns true if the item at index idx has radio button-style checkability.

Note: This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups.

• bool is_item_separator ( idx ) const

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.

• is_item_shortcut_disabled ( int idx ) const

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

• void remove_item ( idx )

Removes the item at index idx from the menu.

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

• void set_current_index ( int index )

Sets the currently focused item as the given index.

• void set_hide_on_window_lose_focus ( enable )

Hides the PopupMenu when the window loses focus.

• void set_item_accelerator ( int idx, accel )

Sets the accelerator of the item at index idx. Accelerators are special combinations of keys that activate the item, no matter which control is focused.

• void set_item_as_checkable ( int idx, enable )

Sets whether the item at index idx 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.

• void set_item_as_radio_checkable ( int idx, enable )

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

• void set_item_as_separator ( int idx, enable )

Mark the item at index idx as a separator, which means that it would be displayed as a line. If false, sets the type of the item to plain text.

• void set_item_checked ( int idx, checked )

Sets the checkstate status of the item at index idx.

• void set_item_disabled ( int idx, disabled )

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

Replaces the Texture icon of the specified idx.

• void set_item_id ( idx, int id )

Sets the id of the item at index idx.

• void set_item_metadata ( idx, Variant metadata )

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

• void set_item_multistate ( int idx, state )

Sets the state of a multistate item. See add_multistate_item for details.

• void set_item_shortcut ( idx, ShortCut shortcut, global=false )

Sets a ShortCut for the specified item idx.

• void set_item_shortcut_disabled ( idx, bool disabled )

Disables the of the specified index idx.

• void set_item_submenu ( int idx, submenu )

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

• void set_item_text ( int idx, text )

Sets the text of the item at index idx.

• void set_item_tooltip ( int idx, tooltip )

Sets the String tooltip of the item at the specified index idx.

• void toggle_item_checked ( idx )

Toggles the check state of the item of the specified index idx.

• void toggle_item_multistate ( int idx )

Cycle to the next state of a multistate item. See for details.

Theme Property Descriptions

• font_color

The default text Color for menu items’ names.

• font_color_accel

The text Color used for shortcuts and accelerators that show next to the menu item name when defined. See for more info on accelerators.

• Color font_color_disabled

used for disabled menu items’ text.

• Color font_color_hover

used for the hovered text.

• Color font_color_separator

used for labeled separators’ text. See add_separator.

• hseparation

The horizontal space between the item’s name and the shortcut text/submenu arrow.

• int vseparation

The vertical space between each menu item.

• font

Font used for the menu items.

• font_separator

Font used for the labeled separator.

• checked

Texture icon for the checked checkbox items.

• radio_checked

Texture icon for the checked radio button items.

• radio_unchecked

Texture icon for the unchecked radio button items.

• submenu

Texture icon for the submenu arrow.

• unchecked

Texture icon for the unchecked checkbox items.

• hover

StyleBox displayed when the PopupMenu item is hovered.

• labeled_separator_left

StyleBox for the left side of labeled separator. See .

• StyleBox labeled_separator_right

for the right side of labeled separator. See add_separator.

• panel

Default StyleBox of the PopupMenu items.

• panel_disabled

StyleBox used when the PopupMenu item is disabled.