Skip to content

Latest commit

 

History

History
396 lines (234 loc) · 17.9 KB

class_menubutton.rst

File metadata and controls

396 lines (234 loc) · 17.9 KB
github_url:hide

MenuButton

Inherits: :ref:`Button<class_Button>` < :ref:`BaseButton<class_BaseButton>` < :ref:`Control<class_Control>` < :ref:`CanvasItem<class_CanvasItem>` < :ref:`Node<class_Node>` < :ref:`Object<class_Object>`

A button that brings up a :ref:`PopupMenu<class_PopupMenu>` when clicked.

.. rst-class:: classref-introduction-group

Description

A button that brings up a :ref:`PopupMenu<class_PopupMenu>` when clicked. To create new items inside this :ref:`PopupMenu<class_PopupMenu>`, use get_popup().add_item("My Item Name"). You can also create them directly from Godot editor's inspector.

See also :ref:`BaseButton<class_BaseButton>` which contains common properties and methods associated with this node.

.. rst-class:: classref-reftable-group

Properties

:ref:`ActionMode<enum_BaseButton_ActionMode>` action_mode 0 (overrides :ref:`BaseButton<class_BaseButton_property_action_mode>`)
:ref:`bool<class_bool>` flat true (overrides :ref:`Button<class_Button_property_flat>`)
:ref:`FocusMode<enum_Control_FocusMode>` focus_mode 0 (overrides :ref:`Control<class_Control_property_focus_mode>`)
:ref:`int<class_int>` :ref:`item_count<class_MenuButton_property_item_count>` 0
:ref:`bool<class_bool>` :ref:`switch_on_hover<class_MenuButton_property_switch_on_hover>` false
:ref:`bool<class_bool>` toggle_mode true (overrides :ref:`BaseButton<class_BaseButton_property_toggle_mode>`) 
.. rst-class:: classref-reftable-group

Methods

:ref:`PopupMenu<class_PopupMenu>` :ref:`get_popup<class_MenuButton_method_get_popup>` ( ) |const|
void :ref:`set_disable_shortcuts<class_MenuButton_method_set_disable_shortcuts>` ( :ref:`bool<class_bool>` disabled )
void :ref:`show_popup<class_MenuButton_method_show_popup>` ( ) 
.. rst-class:: classref-reftable-group

Theme Properties

:ref:`Color<class_Color>` :ref:`font_color<class_MenuButton_theme_color_font_color>` Color(0.875, 0.875, 0.875, 1)
:ref:`Color<class_Color>` :ref:`font_disabled_color<class_MenuButton_theme_color_font_disabled_color>` Color(1, 1, 1, 0.3)
:ref:`Color<class_Color>` :ref:`font_focus_color<class_MenuButton_theme_color_font_focus_color>` Color(0.95, 0.95, 0.95, 1)
:ref:`Color<class_Color>` :ref:`font_hover_color<class_MenuButton_theme_color_font_hover_color>` Color(0.95, 0.95, 0.95, 1)
:ref:`Color<class_Color>` :ref:`font_outline_color<class_MenuButton_theme_color_font_outline_color>` Color(1, 1, 1, 1)
:ref:`Color<class_Color>` :ref:`font_pressed_color<class_MenuButton_theme_color_font_pressed_color>` Color(1, 1, 1, 1)
:ref:`int<class_int>` :ref:`h_separation<class_MenuButton_theme_constant_h_separation>` 4
:ref:`int<class_int>` :ref:`outline_size<class_MenuButton_theme_constant_outline_size>` 0
:ref:`Font<class_Font>` :ref:`font<class_MenuButton_theme_font_font>`  
:ref:`int<class_int>` :ref:`font_size<class_MenuButton_theme_font_size_font_size>`  
:ref:`StyleBox<class_StyleBox>` :ref:`disabled<class_MenuButton_theme_style_disabled>`  
:ref:`StyleBox<class_StyleBox>` :ref:`focus<class_MenuButton_theme_style_focus>`  
:ref:`StyleBox<class_StyleBox>` :ref:`hover<class_MenuButton_theme_style_hover>`  
:ref:`StyleBox<class_StyleBox>` :ref:`normal<class_MenuButton_theme_style_normal>`  
:ref:`StyleBox<class_StyleBox>` :ref:`pressed<class_MenuButton_theme_style_pressed>`   
.. rst-class:: classref-section-separator


.. rst-class:: classref-descriptions-group

Signals

.. rst-class:: classref-signal

about_to_popup ( )

Emitted when the :ref:`PopupMenu<class_PopupMenu>` of this MenuButton is about to show.

.. rst-class:: classref-section-separator


.. rst-class:: classref-descriptions-group

Property Descriptions

.. rst-class:: classref-property

:ref:`int<class_int>` item_count = 0

.. rst-class:: classref-property-setget

The number of items currently in the list.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

:ref:`bool<class_bool>` switch_on_hover = false

.. rst-class:: classref-property-setget

If true, when the cursor hovers above another MenuButton within the same parent which also has switch_on_hover enabled, it will close the current MenuButton and open the other one.

.. rst-class:: classref-section-separator


.. rst-class:: classref-descriptions-group

Method Descriptions

.. rst-class:: classref-method

:ref:`PopupMenu<class_PopupMenu>` get_popup ( ) |const|

Returns the :ref:`PopupMenu<class_PopupMenu>` contained in this button.

Warning: This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their :ref:`Window.visible<class_Window_property_visible>` property.

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

void set_disable_shortcuts ( :ref:`bool<class_bool>` disabled )

If true, shortcuts are disabled and cannot be used to trigger the button.

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

void show_popup ( )

Adjusts popup position and sizing for the MenuButton, then shows the :ref:`PopupMenu<class_PopupMenu>`. Prefer this over using get_popup().popup().

.. rst-class:: classref-section-separator


.. rst-class:: classref-descriptions-group

Theme Property Descriptions

.. rst-class:: classref-themeproperty

:ref:`Color<class_Color>` font_color = Color(0.875, 0.875, 0.875, 1)

Default text :ref:`Color<class_Color>` of the MenuButton.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`Color<class_Color>` font_disabled_color = Color(1, 1, 1, 0.3)

Text :ref:`Color<class_Color>` used when the MenuButton is disabled.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`Color<class_Color>` font_focus_color = Color(0.95, 0.95, 0.95, 1)

Text :ref:`Color<class_Color>` used when the MenuButton is focused. Only replaces the normal text color of the button. Disabled, hovered, and pressed states take precedence over this color.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`Color<class_Color>` font_hover_color = Color(0.95, 0.95, 0.95, 1)

Text :ref:`Color<class_Color>` used when the MenuButton is being hovered.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`Color<class_Color>` font_outline_color = Color(1, 1, 1, 1)

The tint of text outline of the MenuButton.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`Color<class_Color>` font_pressed_color = Color(1, 1, 1, 1)

Text :ref:`Color<class_Color>` used when the MenuButton is being pressed.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`int<class_int>` h_separation = 4

The horizontal space between MenuButton's icon and text. Negative values will be treated as 0 when used.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`int<class_int>` outline_size = 0

The size of the text outline.

Note: If using a font with :ref:`FontFile.multichannel_signed_distance_field<class_FontFile_property_multichannel_signed_distance_field>` enabled, its :ref:`FontFile.msdf_pixel_range<class_FontFile_property_msdf_pixel_range>` must be set to at least twice the value of :ref:`outline_size<class_MenuButton_theme_constant_outline_size>` for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`Font<class_Font>` font

:ref:`Font<class_Font>` of the MenuButton's text.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`int<class_int>` font_size

Font size of the MenuButton's text.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` disabled

:ref:`StyleBox<class_StyleBox>` used when the MenuButton is disabled.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` focus

:ref:`StyleBox<class_StyleBox>` used when the MenuButton is focused. The focus :ref:`StyleBox<class_StyleBox>` is displayed over the base :ref:`StyleBox<class_StyleBox>`, so a partially transparent :ref:`StyleBox<class_StyleBox>` should be used to ensure the base :ref:`StyleBox<class_StyleBox>` remains visible. A :ref:`StyleBox<class_StyleBox>` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty<class_StyleBoxEmpty>` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` hover

:ref:`StyleBox<class_StyleBox>` used when the MenuButton is being hovered.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` normal

Default :ref:`StyleBox<class_StyleBox>` for the MenuButton.

.. rst-class:: classref-item-separator


.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` pressed

:ref:`StyleBox<class_StyleBox>` used when the MenuButton is being pressed.