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

A modal window used to display a list of options.

Description¶

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

Properties¶

bool	allow_search	`true`
bool	hide_on_checkable_item_selection	`true`
bool	hide_on_item_selection	`true`
bool	hide_on_state_item_selection	`false`
int	item_count	`0`
float	submenu_popup_delay	`0.3`

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	add_item ( String label, int id=-1, Key accel=0 )
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 ( )
int	get_focused_item ( ) const
Key	get_item_accelerator ( int index ) const
Texture2D	get_item_icon ( int index ) const
int	get_item_id ( int index ) const
int	get_item_indent ( int index ) const
int	get_item_index ( int id ) const
String	get_item_language ( int index ) const
Variant	get_item_metadata ( int index ) const
Shortcut	get_item_shortcut ( int index ) const
String	get_item_submenu ( int index ) const
String	get_item_text ( int index ) const
TextDirection	get_item_text_direction ( int index ) const
String	get_item_tooltip ( int index ) const
bool	is_item_checkable ( int index ) const
bool	is_item_checked ( int index ) const
bool	is_item_disabled ( int index ) const
bool	is_item_radio_checkable ( int index ) const
bool	is_item_separator ( int index ) const
bool	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¶

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(1, 1, 1, 1)`
Color	font_separator_color	`Color(0.875, 0.875, 0.875, 1)`
Color	font_separator_outline_color	`Color(1, 1, 1, 1)`
int	h_separation	`4`
int	indent	`10`
int	item_end_padding	`2`
int	item_start_padding	`2`
int	outline_size	`0`
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	radio_checked
Texture2D	radio_checked_disabled
Texture2D	radio_unchecked
Texture2D	radio_unchecked_disabled
Texture2D	submenu
Texture2D	submenu_mirrored
Texture2D	unchecked
Texture2D	unchecked_disabled
StyleBox	hover
StyleBox	labeled_separator_left
StyleBox	labeled_separator_right
StyleBox	panel
StyleBox	panel_disabled
StyleBox	separator

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.

Emitted when any item is added, modified or removed.

Property Descriptions¶

bool allow_search = true

void set_allow_search ( bool value )
bool get_allow_search ( )

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

void set_hide_on_item_selection ( bool value )
bool is_hide_on_item_selection ( )

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

bool hide_on_state_item_selection = false

void set_hide_on_state_item_selection ( bool value )
bool is_hide_on_state_item_selection ( )

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

int item_count = 0

void set_item_count ( int value )
int get_item_count ( )

The number of items currently in the list.

float submenu_popup_delay = 0.3

void set_submenu_popup_delay ( float value )
float get_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.

Method Descriptions¶

void add_check_item ( String label, int id=-1,