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

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 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 ( int index )

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


  • menu_changed ( )

Property Descriptions

Default

true

Setter

set_allow_search(value)

Getter

get_allow_search()

If true, allows navigating PopupMenu with letter keys.


  • bool hide_on_checkable_item_selection

Default

true

Setter

set_hide_on_checkable_item_selection(value)

Getter

is_hide_on_checkable_item_selection()

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


  • bool hide_on_item_selection

Default

true

Setter

set_hide_on_item_selection(value)

Getter

is_hide_on_item_selection()

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


  • bool hide_on_state_item_selection

Default

false

Setter

set_hide_on_state_item_selection(value)

Getter

is_hide_on_state_item_selection()

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


  • int item_count

Default

0

Setter

set_item_count(value)

Getter

get_item_count()

The number of items currently in the list.


  • float submenu_popup_delay

Default

0.3

Setter

set_submenu_popup_delay(value)

Getter

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


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 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 0 will be assigned to it. 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 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.


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 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 0 will be assigned to it. 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 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 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.


Adds a Shortcut.

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


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. Accelerators are special combinations of keys that activate the item, no matter which control is focused.


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.


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.


  • String get_item_submenu ( int index ) const

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


Returns the text of the item at the given index.


Returns item's text base writing direction.


  • String get_item_tooltip ( int index ) const

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


  • bool is_item_checkable ( int index ) const

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.


  • bool is_item_checked ( int index ) const

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


  • bool is_item_disabled ( int index ) const

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.


  • bool is_item_radio_checkable ( int index ) const

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.


  • bool is_item_separator ( int index ) 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.


  • bool is_item_shortcut_disabled ( int index ) const

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


  • void remove_item ( int index )

Removes the item at the given index from the menu.

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


  • void scroll_to_item ( int index )

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


  • void set_focused_item ( int index )

Sets the currently focused item as the given index.

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


  • void set_item_accelerator ( int index, Key accel )

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


  • void set_item_as_checkable ( int index, bool enable )

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.


  • void set_item_as_radio_checkable ( int index, bool enable )

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


  • void set_item_as_separator ( int index, bool enable )

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.


  • void set_item_checked ( int index, bool checked )

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


  • void set_item_disabled ( int index, bool disabled )

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.


  • void set_item_id ( int index, int id )

Sets the id of the item at the given index.

The id is used in id_pressed and id_focused signals.


  • void set_item_indent ( int index, int indent )

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


  • void set_item_language ( int index, String language )

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


  • void set_item_metadata ( int index, Variant metadata )

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.


  • void set_item_multistate ( int index, int state )

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


  • void set_item_shortcut ( int index, Shortcut shortcut, bool global=false )

Sets a Shortcut for the item at the given index.


  • void set_item_shortcut_disabled ( int index, bool disabled )

Disables the Shortcut of the item at the given index.


  • void set_item_submenu ( int index, String submenu )

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.


  • void set_item_text ( int index, String text )

Sets the text of the item at the given index.


Sets item's text base writing direction.


  • void set_item_tooltip ( int index, String tooltip )

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


  • void toggle_item_checked ( int index )

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


  • void toggle_item_multistate ( int index )

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

Theme Property Descriptions

  • Color font_accelerator_color

Default

Color(0.7, 0.7, 0.7, 0.8)

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


Default

Color(0.875, 0.875, 0.875, 1)

The default text Color for menu items' names.


  • Color font_disabled_color

Default

Color(0.4, 0.4, 0.4, 0.8)

Color used for disabled menu items' text.


Default

Color(0.875, 0.875, 0.875, 1)

Color used for the hovered text.


  • Color font_outline_color

Default

Color(1, 1, 1, 1)

The tint of text outline of the menu item.


  • Color font_separator_color

Default

Color(0.875, 0.875, 0.875, 1)

Color used for labeled separators' text. See add_separator.


  • Color font_separator_outline_color

Default

Color(1, 1, 1, 1)

The tint of text outline of the labeled separator.


  • int h_separation

Default

4

The horizontal space between the item's elements.


Default

10

Width of the single indentation level.


  • int item_end_padding

Default

2


  • int item_start_padding

Default

2


  • int outline_size

Default

0

The size of the item text outline.


  • int separator_outline_size

Default

0

The size of the labeled separator text outline.


  • int v_separation

Default

4

The vertical space between each menu item.


Font used for the menu items.


  • Font font_separator

Font used for the labeled separator.


  • int font_separator_size

Font size of the labeled separator.


  • int font_size

Font size of the menu items.


Texture2D icon for the checked checkbox items.


Texture2D icon for the checked checkbox items when they are disabled.


Texture2D icon for the checked radio button items.


Texture2D icon for the checked radio button items when they are disabled.


Texture2D icon for the unchecked radio button items.


Texture2D icon for the unchecked radio button items when they are disabled.


Texture2D icon for the submenu arrow (for left-to-right layouts).


Texture2D icon for the submenu arrow (for right-to-left layouts).


Texture2D icon for the unchecked checkbox items.


Texture2D icon for the unchecked checkbox items when they are disabled.


StyleBox displayed when the PopupMenu item is hovered.


StyleBox for the left side of labeled separator. See add_separator.


StyleBox for the right side of labeled separator. See add_separator.


Default StyleBox of the PopupMenu items.


StyleBox used when the PopupMenu item is disabled.


StyleBox used for the separators. See add_separator.