From b3b7c37e1b669e4add73a5d4d65c0a15d65a384b Mon Sep 17 00:00:00 2001
From: Olivier Goffart <olivier.goffart@slint.dev>
Date: Thu, 30 Jan 2025 17:42:27 +0100
Subject: [PATCH] Documentation for the MenuBar and the ContextMenu

---
 .../docs/reference/window/contextmenu.mdx     | 62 +++++++++++++++++++
 .../content/docs/reference/window/window.mdx  | 41 ++++++++++++
 internal/core-macros/link-data.json           |  6 ++
 3 files changed, 109 insertions(+)
 create mode 100644 docs/astro/src/content/docs/reference/window/contextmenu.mdx

diff --git a/docs/astro/src/content/docs/reference/window/contextmenu.mdx b/docs/astro/src/content/docs/reference/window/contextmenu.mdx
new file mode 100644
index 00000000000..269b6d4441b
--- /dev/null
+++ b/docs/astro/src/content/docs/reference/window/contextmenu.mdx
@@ -0,0 +1,62 @@
+---
+<!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT -->
+title: Window
+description: Window element api.
+---
+import SlintProperty from '/src/components/SlintProperty.astro';
+import Link from '/src/components/Link.astro';
+
+`ContextMenu` is an invisible element that is used to show a context menu.
+
+The context menu is shown if the user right-clicks on the area covered by the `ContextMenu` element,
+or if the user presses the "Menu" key on their keyboard while a `FocusScope` within the `ContextMenu` is focused.
+It is also possible to show the context menu by calling the `show` function on the `ContextMenu` element.
+
+In addition to normal sub elements, the `ContextMenu` element can contain `MenuItem` elements.
+The MenuItem elements are defining the actual menu.
+
+## Function
+
+### show(Point)
+
+Call this function to programmatically show the context menu at the given position relative to the `ContextMenu` element.
+
+## `MenuItem`
+
+A `MenuItem` represents a single menu entry. It can be placed as a child of a `ContextMenu`,
+<Link type="MenuBar" />, or another `MenuItem`.
+
+### Properties of `MenuItem`
+
+#### title
+<SlintProperty propName="title" typeName="string" defaultValue='""'>
+The label of the entry within the menu.
+</SlintProperty>
+
+### Callbacks of `MenuItem`
+
+#### activated()
+
+Invoked when the menu entry is activated.
+This is only called if the menu entry doesn't have submenus
+
+## Example
+
+```slint
+export component Example {
+    ContextMenu {
+        MenuItem {
+            title: "Copy";
+            activated => { debug("Copy"); }
+        }
+        MenuItem {
+            title: "Paste";
+            activated => { debug("Paste"); }
+        }
+        MenuItem {
+            title: "Cut";
+            activated => { debug("Cut"); }
+        }
+    }
+}
+```
diff --git a/docs/astro/src/content/docs/reference/window/window.mdx b/docs/astro/src/content/docs/reference/window/window.mdx
index 72cf704836e..ad994d06f17 100644
--- a/docs/astro/src/content/docs/reference/window/window.mdx
+++ b/docs/astro/src/content/docs/reference/window/window.mdx
@@ -4,6 +4,7 @@ title: Window
 description: Window element api.
 ---
 import SlintProperty  from '/src/components/SlintProperty.astro';
+import Link from '/src/components/Link.astro';
 
 `Window` is the root of the tree of elements that are visible on the screen.
 
@@ -57,3 +58,43 @@ Whether the window should be borderless/frameless or not.
 <SlintProperty propName="title" typeName="string">
 The window title that is shown in the title bar.
 </SlintProperty>
+
+## `MenuBar` element
+
+A `Window` can contain one `MenuBar` element. This special element is used to create a menu bar for that window.
+There can only be one `MenuBar` element in a `Window` and it must not be in a `for` or a `if`.
+The `MenuBar` doesn't have properties, but it should contain <Link type="MenuItem" /> as children that represent top level entries in the menu bar.
+Each `MenuItem` can contain further `MenuItem` as children that represent sub-menu
+
+Depending on the platform, the menu bar might be native or rendered by Slint.
+This means that for example, on MacOs, the menu bar be in top bar on the desktop where application usually have their top bar.
+The `width` and `height` property of the `Window` are the one of the client area, without counting the menu bar.
+The `x` and `y` properties of `Window` children are also relative to the client area.
+
+### Example
+
+```slint
+export component Example inherits Window {
+    MenuBar {
+        MenuItem {
+            title: "File";
+            MenuItem {
+                title: "New";
+            }
+            MenuItem {
+                title: "Open";
+            }
+        }
+        MenuItem {
+            title: "Edit";
+            MenuItem {
+                title: "Copy";
+            }
+            MenuItem {
+                title: "Paste";
+            }
+        }
+    }
+    // ... actual window content goes here
+}
+```
diff --git a/internal/core-macros/link-data.json b/internal/core-macros/link-data.json
index bfbe1c46a60..4b4a86d8cd5 100644
--- a/internal/core-macros/link-data.json
+++ b/internal/core-macros/link-data.json
@@ -92,6 +92,12 @@
     "LinuxkmsBackend": {
         "href": "guide/backends-and-renderers/backend_linuxkms/"
     },
+    "MenuBar": {
+        "href": "reference/window/window/#menubar"
+    },
+    "MenuItem": {
+        "href": "reference/window/contextmenu/#menuitem"
+    },
     "Modules": {
         "href": "guide/language/coding/file/#modules"
     },