Implement `MenuBar` control to wrap `PopupMenu`s or native menu, use native menu for editor.

4 files changed, 246 insertions, 34 deletions

diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml
index cb2474384a..989d0cdb55 100644
--- a/doc/classes/DisplayServer.xml
+++ b/doc/classes/DisplayServer.xml
@@ -144,7 +144,7 @@
 			</description>
 		</method>
 		<method name="global_menu_add_check_item">
-			<return type="void" />
+			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
 			<param index="1" name="label" type="String" />
 			<param index="2" name="callback" type="Callable" />
@@ -153,16 +153,17 @@
 			<param index="5" name="index" type="int" default="-1" />
 			<description>
 				Adds a new checkable item with text [param label] to the global menu with ID [param menu_root].
+				Returns index of the inserted item, it's not guaranteed to be the same as [param index] value.
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
 		</method>
 		<method name="global_menu_add_icon_check_item">
-			<return type="void" />
+			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
 			<param index="1" name="icon" type="Texture2D" />
 			<param index="2" name="label" type="String" />
@@ -172,16 +173,17 @@
 			<param index="6" name="index" type="int" default="-1" />
 			<description>
 				Adds a new checkable item with text [param label] and icon [param icon] to the global menu with ID [param menu_root].
+				Returns index of the inserted item, it's not guaranteed to be the same as [param index] value.
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
 		</method>
 		<method name="global_menu_add_icon_item">
-			<return type="void" />
+			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
 			<param index="1" name="icon" type="Texture2D" />
 			<param index="2" name="label" type="String" />
@@ -191,16 +193,17 @@
 			<param index="6" name="index" type="int" default="-1" />
 			<description>
 				Adds a new item with text [param label] and icon [param icon] to the global menu with ID [param menu_root].
+				Returns index of the inserted item, it's not guaranteed to be the same as [param index] value.
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
 		</method>
 		<method name="global_menu_add_icon_radio_check_item">
-			<return type="void" />
+			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
 			<param index="1" name="icon" type="Texture2D" />
 			<param index="2" name="label" type="String" />
@@ -210,17 +213,18 @@
 			<param index="6" name="index" type="int" default="-1" />
 			<description>
 				Adds a new radio-checkable item with text [param label] and icon [param icon] to the global menu with ID [param menu_root].
+				Returns index of the inserted item, it's not guaranteed to be the same as [param index] value.
 				[b]Note:[/b] Radio-checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See [method global_menu_set_item_checked] for more info on how to control it.
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
 		</method>
 		<method name="global_menu_add_item">
-			<return type="void" />
+			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
 			<param index="1" name="label" type="String" />
 			<param index="2" name="callback" type="Callable" />
@@ -229,16 +233,17 @@
 			<param index="5" name="index" type="int" default="-1" />
 			<description>
 				Adds a new item with text [param label] to the global menu with ID [param menu_root].
+				Returns index of the inserted item, it's not guaranteed to be the same as [param index] value.
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
 		</method>
 		<method name="global_menu_add_multistate_item">
-			<return type="void" />
+			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
 			<param index="1" name="labe" type="String" />
 			<param index="2" name="max_states" type="int" />
@@ -250,16 +255,18 @@
 			<description>
 				Adds a new item with text [param labe] to the global menu with ID [param menu_root].
 				Contrarily to normal binary items, multistate items can have more than two states, as defined by [param max_states]. Each press or activate of the item will increase the state by one. The default value is defined by [param default_state].
+				Returns index of the inserted item, it's not guaranteed to be the same as [param index] value.
+				[b]Note:[/b] By default, there's no indication of the current item state, it should be changed manually.
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
 		</method>
 		<method name="global_menu_add_radio_check_item">
-			<return type="void" />
+			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
 			<param index="1" name="label" type="String" />
 			<param index="2" name="callback" type="Callable" />
@@ -268,41 +275,44 @@
 			<param index="5" name="index" type="int" default="-1" />
 			<description>
 				Adds a new radio-checkable item with text [param label] to the global menu with ID [param menu_root].
+				Returns index of the inserted item, it's not guaranteed to be the same as [param index] value.
 				[b]Note:[/b] Radio-checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See [method global_menu_set_item_checked] for more info on how to control it.
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
 		</method>
 		<method name="global_menu_add_separator">
-			<return type="void" />
+			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
 			<param index="1" name="index" type="int" default="-1" />
 			<description>
 				Adds a separator between items to the global menu with ID [param menu_root]. Separators also occupy an index.
+				Returns index of the inserted item, it's not guaranteed to be the same as [param index] value.
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
 		</method>
 		<method name="global_menu_add_submenu_item">
-			<return type="void" />
+			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
 			<param index="1" name="label" type="String" />
 			<param index="2" name="submenu" type="String" />
 			<param index="3" name="index" type="int" default="-1" />
 			<description>
 				Adds an item that will act as a submenu of the global menu [param menu_root]. The [param submenu] argument is the ID of the global menu root that will be shown when the item is clicked.
+				Returns index of the inserted item, it's not guaranteed to be the same as [param index] value.
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
@@ -315,7 +325,7 @@
 				[b]Note:[/b] This method is implemented on macOS.
 				[b]Supported system menu IDs:[/b]
 				[codeblock]
-				"" - Main menu (macOS).
+				"_main" - Main menu (macOS).
 				"_dock" - Dock popup menu (macOS).
 				[/codeblock]
 			</description>
@@ -347,6 +357,15 @@
 				[b]Note:[/b] This method is implemented on macOS.
 			</description>
 		</method>
+		<method name="global_menu_get_item_indentation_level" qualifiers="const">
+			<return type="int" />
+			<param index="0" name="menu_root" type="String" />
+			<param index="1" name="idx" type="int" />
+			<description>
+				Returns the horizontal offset of the item at the given [param idx].
+				[b]Note:[/b] This method is implemented on macOS.
+			</description>
+		</method>
 		<method name="global_menu_get_item_index_from_tag" qualifiers="const">
 			<return type="int" />
 			<param index="0" name="menu_root" type="String" />
@@ -528,6 +547,16 @@
 				[b]Note:[/b] This method is not supported by macOS "_dock" menu items.
 			</description>
 		</method>
+		<method name="global_menu_set_item_indentation_level">
+			<return type="void" />
+			<param index="0" name="menu_root" type="String" />
+			<param index="1" name="idx" type="int" />
+			<param index="2" name="level" type="int" />
+			<description>
+				Sets the horizontal offset of the item at the given [param idx].
+				[b]Note:[/b] This method is implemented on macOS.
+			</description>
+		</method>
 		<method name="global_menu_set_item_max_states">
 			<return type="void" />
 			<param index="0" name="menu_root" type="String" />
diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml
index 6079cc48c8..64e9110145 100644
--- a/doc/classes/EditorSettings.xml
+++ b/doc/classes/EditorSettings.xml
@@ -553,6 +553,10 @@
 		<member name="interface/editor/unfocused_low_processor_mode_sleep_usec" type="float" setter="" getter="">
 			When the editor window is unfocused, the amount of sleeping between frames when the low-processor usage mode is enabled (in microseconds). Higher values will result in lower CPU/GPU usage, which can improve battery life on laptops (in addition to improving the running project's performance if the editor has to redraw continuously). However, higher values will result in a less responsive editor. The default value is set to limit the editor to 20 FPS when the editor window is unfocused. See also [member interface/editor/low_processor_mode_sleep_usec].
 		</member>
+		<member name="interface/editor/use_embedded_menu" type="bool" setter="" getter="">
+			If [code]true[/code], editor main menu is using embedded [MenuBar] instead of system global menu.
+			Specific to the macOS platform.
+		</member>
 		<member name="interface/inspector/max_array_dictionary_items_per_page" type="int" setter="" getter="">
 			The number of [Array] or [Dictionary] items to display on each "page" in the inspector. Higher values allow viewing more values per page, but take more time to load. This increased load time is noticeable when selecting nodes that have array or dictionary properties in the editor.
 		</member>
diff --git a/doc/classes/MenuBar.xml b/doc/classes/MenuBar.xml
new file mode 100644
index 0000000000..3ef0572e9f
--- /dev/null
+++ b/doc/classes/MenuBar.xml
@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="MenuBar" inherits="Control" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A horizontal menu bar, which displays [PopupMenu]s or system global menu.
+	</brief_description>
+	<description>
+		New items can be created by adding [PopupMenu] nodes to his node.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="get_menu_count" qualifiers="const">
+			<return type="int" />
+			<description>
+				Returns number of menu items.
+			</description>
+		</method>
+		<method name="get_menu_popup" qualifiers="const">
+			<return type="PopupMenu" />
+			<param index="0" name="menu" type="int" />
+			<description>
+				Returns [PopupMenu] associated with menu item.
+			</description>
+		</method>
+		<method name="get_menu_title" qualifiers="const">
+			<return type="String" />
+			<param index="0" name="menu" type="int" />
+			<description>
+				Returns menu item title.
+			</description>
+		</method>
+		<method name="get_menu_tooltip" qualifiers="const">
+			<return type="String" />
+			<param index="0" name="menu" type="int" />
+			<description>
+				Returns menu item tooltip.
+			</description>
+		</method>
+		<method name="is_menu_disabled" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="menu" type="int" />
+			<description>
+				Returns [code]true[/code], if menu item is disabled.
+			</description>
+		</method>
+		<method name="is_menu_hidden" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="menu" type="int" />
+			<description>
+				Returns [code]true[/code], if menu item is hidden.
+			</description>
+		</method>
+		<method name="is_native_menu" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code], if system global menu is supported and used by this [MenuBar].
+			</description>
+		</method>
+		<method name="set_disable_shortcuts">
+			<return type="void" />
+			<param index="0" name="disabled" type="bool" />
+			<description>
+				If [code]true[/code], shortcuts are disabled and cannot be used to trigger the button.
+			</description>
+		</method>
+		<method name="set_menu_disabled">
+			<return type="void" />
+			<param index="0" name="menu" type="int" />
+			<param index="1" name="disabled" type="bool" />
+			<description>
+				If [code]true[/code], menu item is disabled.
+			</description>
+		</method>
+		<method name="set_menu_hidden">
+			<return type="void" />
+			<param index="0" name="menu" type="int" />
+			<param index="1" name="hidden" type="bool" />
+			<description>
+				If [code]true[/code], menu item is hidden.
+			</description>
+		</method>
+		<method name="set_menu_title">
+			<return type="void" />
+			<param index="0" name="menu" type="int" />
+			<param index="1" name="title" type="String" />
+			<description>
+				Sets menu item title.
+			</description>
+		</method>
+		<method name="set_menu_tooltip">
+			<return type="void" />
+			<param index="0" name="menu" type="int" />
+			<param index="1" name="tooltip" type="String" />
+			<description>
+				Sets menu item tooltip.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="flat" type="bool" setter="set_flat" getter="is_flat" default="false">
+			Flat [MenuBar] don't display item decoration.
+		</member>
+		<member name="language" type="String" setter="set_language" getter="get_language" default="&quot;&quot;">
+			Language code used for line-breaking and text shaping algorithms, if left empty current locale is used instead.
+		</member>
+		<member name="prefer_global_menu" type="bool" setter="set_prefer_global_menu" getter="is_prefer_global_menu" default="true">
+			If [code]true[/code], [MenuBar] will use system global menu when supported.
+		</member>
+		<member name="shortcut_context" type="Node" setter="set_shortcut_context" getter="get_shortcut_context">
+			The [Node] which must be a parent of the focused GUI [Control] for the shortcut to be activated. If [code]null[/code], the shortcut can be activated when any control is focused (a global shortcut). This allows shortcuts to be accepted only when the user has a certain area of the GUI focused.
+		</member>
+		<member name="start_index" type="int" setter="set_start_index" getter="get_start_index" default="-1">
+			Position in the global menu to insert first [MenuBar] item at.
+		</member>
+		<member name="switch_on_hover" type="bool" setter="set_switch_on_hover" getter="is_switch_on_hover" default="true">
+			If [code]true[/code], when the cursor hovers above menu item, it will close the current [PopupMenu] and open the other one.
+		</member>
+		<member name="text_direction" type="int" setter="set_text_direction" getter="get_text_direction" enum="Control.TextDirection" default="0">
+			Base text writing direction.
+		</member>
+	</members>
+	<theme_items>
+		<theme_item name="font_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 1)">
+			Default text [Color] of the menu item.
+		</theme_item>
+		<theme_item name="font_disabled_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 0.5)">
+			Text [Color] used when the menu item is disabled.
+		</theme_item>
+		<theme_item name="font_focus_color" data_type="color" type="Color" default="Color(0.95, 0.95, 0.95, 1)">
+			Text [Color] used when the menu item is focused. Only replaces the normal text color of the menu item. Disabled, hovered, and pressed states take precedence over this color.
+		</theme_item>
+		<theme_item name="font_hover_color" data_type="color" type="Color" default="Color(0.95, 0.95, 0.95, 1)">
+			Text [Color] used when the menu item is being hovered.
+		</theme_item>
+		<theme_item name="font_hover_pressed_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)">
+			Text [Color] used when the menu item is being hovered and pressed.
+		</theme_item>
+		<theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)">
+			The tint of text outline of the menu item.
+		</theme_item>
+		<theme_item name="font_pressed_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)">
+			Text [Color] used when the menu item is being pressed.
+		</theme_item>
+		<theme_item name="h_separation" data_type="constant" type="int" default="4">
+			The horizontal space between menu items.
+		</theme_item>
+		<theme_item name="outline_size" data_type="constant" type="int" default="0">
+			The size of the text outline.
+		</theme_item>
+		<theme_item name="font" data_type="font" type="Font">
+			[Font] of the menu item's text.
+		</theme_item>
+		<theme_item name="font_size" data_type="font_size" type="int">
+			Font size of the menu item's text.
+		</theme_item>
+		<theme_item name="disabled" data_type="style" type="StyleBox">
+			[StyleBox] used when the menu item is disabled.
+		</theme_item>
+		<theme_item name="focus" data_type="style" type="StyleBox">
+			[StyleBox] used when the menu item is focused. The [code]focus[/code] [StyleBox] is displayed [i]over[/i] the base [StyleBox], so a partially transparent [StyleBox] should be used to ensure the base [StyleBox] remains visible. A [StyleBox] that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty] resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.
+		</theme_item>
+		<theme_item name="hover" data_type="style" type="StyleBox">
+			[StyleBox] used when the menu item is being hovered.
+		</theme_item>
+		<theme_item name="normal" data_type="style" type="StyleBox">
+			Default [StyleBox] for the menu item.
+		</theme_item>
+		<theme_item name="pressed" data_type="style" type="StyleBox">
+			[StyleBox] used when the menu item is being pressed.
+		</theme_item>
+	</theme_items>
+</class>
diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml
index 26bc765ef4..0f47bea5df 100644
--- a/doc/classes/PopupMenu.xml
+++ b/doc/classes/PopupMenu.xml
@@ -195,13 +195,6 @@
 				Returns the accelerator of the item at the given [param index]. Accelerators are special combinations of keys that activate the item, no matter which control is focused.
 			</description>
 		</method>
-		<method name="get_item_horizontal_offset" qualifiers="const">
-			<return type="int" />
-			<param index="0" name="index" type="int" />
-			<description>
-				Returns the horizontal offset of the item at the given [param index].
-			</description>
-		</method>
 		<method name="get_item_icon" qualifiers="const">
 			<return type="Texture2D" />
 			<param index="0" name="index" type="int" />
@@ -216,6 +209,13 @@
 				Returns the id of the item at the given [param index]. [code]id[/code] can be manually assigned, while index can not.
 			</description>
 		</method>
+		<method name="get_item_indent" qualifiers="const">
+			<return type="int" />
+			<param index="0" name="index" type="int" />
+			<description>
+				Returns the horizontal offset of the item at the given [param index].
+			</description>
+		</method>
 		<method name="get_item_index" qualifiers="const">
 			<return type="int" />
 			<param index="0" name="id" type="int" />
@@ -388,14 +388,6 @@
 				Enables/disables the item at the given [param index]. When it is disabled, it can't be selected and its action can't be invoked.
 			</description>
 		</method>
-		<method name="set_item_horizontal_offset">
-			<return type="void" />
-			<param index="0" name="index" type="int" />
-			<param index="1" name="offset" type="int" />
-			<description>
-				Sets the horizontal offset of the item at the given [param index].
-			</description>
-		</method>
 		<method name="set_item_icon">
 			<return type="void" />
 			<param index="0" name="index" type="int" />
@@ -413,6 +405,14 @@
 				The [param id] is used in [signal id_pressed] and [signal id_focused] signals.
 			</description>
 		</method>
+		<method name="set_item_indent">
+			<return type="void" />
+			<param index="0" name="index" type="int" />
+			<param index="1" name="indent" type="int" />
+			<description>
+				Sets the horizontal offset of the item at the given [param index].
+			</description>
+		</method>
 		<method name="set_item_language">
 			<return type="void" />
 			<param index="0" name="index" type="int" />
@@ -540,6 +540,10 @@
 				Emitted when an item of some [param index] is pressed or its accelerator is activated.
 			</description>
 		</signal>
+		<signal name="menu_changed">
+			<description>
+			</description>
+		</signal>
 	</signals>
 	<theme_items>
 		<theme_item name="font_accelerator_color" data_type="color" type="Color" default="Color(0.7, 0.7, 0.7, 0.8)">
@@ -566,6 +570,9 @@
 		<theme_item name="h_separation" data_type="constant" type="int" default="4">
 			The horizontal space between the item's elements.
 		</theme_item>
+		<theme_item name="indent" data_type="constant" type="int" default="10">
+			Width of the single indentation level.
+		</theme_item>
 		<theme_item name="item_end_padding" data_type="constant" type="int" default="2">
 		</theme_item>
 		<theme_item name="item_start_padding" data_type="constant" type="int" default="2">