Add placement parameter to menu open methods

Introduces a placement parameter to menu opening functions in C and C++ APIs, allowing context menus to be positioned relative to an anchor (e.g., top, bottom, left, right, and their variants). Updates platform-specific implementations (Linux, macOS, Windows) to handle placement logic, and modifies example code to demonstrate usage. This improves flexibility for UI positioning and enables more precise control over menu display.

Author: lijy91

examples/menu_c_example/main.c

@@ -179,8 +179,8 @@ int main() {
 
   native_point_t point = {100, 100};
   native_positioning_strategy_t strategy = native_positioning_strategy_absolute(&point);
-  if (native_menu_open(menu, strategy)) {
-    printf("Context menu opened successfully\n");
+  if (native_menu_open(menu, strategy, NATIVE_PLACEMENT_BOTTOM_START)) {
+    printf("Context menu opened successfully (BOTTOM_START placement)\n");
   } else {
     printf("Failed to open context menu (expected in console app)\n");
   }

examples/menu_example/main.cpp

@@ -105,13 +105,18 @@ int main() {
     std::cout << "\n=== Attempting to Open Context Menu ===" << std::endl;
     std::cout << "Note: Context menu display may not work in console applications" << std::endl;
 
-    // Try to show at screen coordinates (100, 100)
+    // Try to show at screen coordinates (100, 100) with default placement (BottomStart)
     if (menu->Open(PositioningStrategy::Absolute({100, 100}))) {
-      std::cout << "Context menu opened successfully" << std::endl;
+      std::cout << "Context menu opened successfully (BottomStart placement)" << std::endl;
     } else {
       std::cout << "Failed to open context menu (expected in console app)" << std::endl;
     }
 
+    // Demonstrate placement parameter - open menu above the point
+    if (menu->Open(PositioningStrategy::Absolute({100, 200}), Placement::Top)) {
+      std::cout << "Context menu opened successfully (Top placement)" << std::endl;
+    }
+
     // Demonstrate submenu
     std::cout << "\n=== Testing Submenu ===" << std::endl;
     auto submenu = std::make_shared<Menu>();

src/capi/geometry_c.h

@@ -25,3 +25,68 @@ typedef struct {
   double width;
   double height;
 } native_rectangle_t;
+
+/**
+ * Placement options for positioning UI elements relative to an anchor.
+ */
+typedef enum {
+  /**
+   * Position above the anchor, horizontally centered.
+   */
+  NATIVE_PLACEMENT_TOP,
+
+  /**
+   * Position above the anchor, aligned to the start (left).
+   */
+  NATIVE_PLACEMENT_TOP_START,
+
+  /**
+   * Position above the anchor, aligned to the end (right).
+   */
+  NATIVE_PLACEMENT_TOP_END,
+
+  /**
+   * Position to the right of the anchor, vertically centered.
+   */
+  NATIVE_PLACEMENT_RIGHT,
+
+  /**
+   * Position to the right of the anchor, aligned to the start (top).
+   */
+  NATIVE_PLACEMENT_RIGHT_START,
+
+  /**
+   * Position to the right of the anchor, aligned to the end (bottom).
+   */
+  NATIVE_PLACEMENT_RIGHT_END,
+
+  /**
+   * Position below the anchor, horizontally centered.
+   */
+  NATIVE_PLACEMENT_BOTTOM,
+
+  /**
+   * Position below the anchor, aligned to the start (left).
+   */
+  NATIVE_PLACEMENT_BOTTOM_START,
+
+  /**
+   * Position below the anchor, aligned to the end (right).
+   */
+  NATIVE_PLACEMENT_BOTTOM_END,
+
+  /**
+   * Position to the left of the anchor, vertically centered.
+   */
+  NATIVE_PLACEMENT_LEFT,
+
+  /**
+   * Position to the left of the anchor, aligned to the start (top).
+   */
+  NATIVE_PLACEMENT_LEFT_START,
+
+  /**
+   * Position to the left of the anchor, aligned to the end (bottom).
+   */
+  NATIVE_PLACEMENT_LEFT_END
+} native_placement_t;

src/capi/menu_c.cpp

@@ -838,14 +838,59 @@ native_menu_item_list_t native_menu_get_all_items(native_menu_t menu) {
   }
 }
 
-bool native_menu_open(native_menu_t menu, native_positioning_strategy_t strategy) {
+bool native_menu_open(native_menu_t menu, native_positioning_strategy_t strategy, native_placement_t placement) {
   if (!menu || !strategy)
     return false;
 
   try {
     auto menu_ptr = static_cast<Menu*>(menu);
     auto strategy_ptr = static_cast<PositioningStrategy*>(strategy);
-    return menu_ptr->Open(*strategy_ptr);
+    
+    // Convert C placement enum to C++ placement enum
+    Placement cpp_placement;
+    switch (placement) {
+      case NATIVE_PLACEMENT_TOP:
+        cpp_placement = Placement::Top;
+        break;
+      case NATIVE_PLACEMENT_TOP_START:
+        cpp_placement = Placement::TopStart;
+        break;
+      case NATIVE_PLACEMENT_TOP_END:
+        cpp_placement = Placement::TopEnd;
+        break;
+      case NATIVE_PLACEMENT_RIGHT:
+        cpp_placement = Placement::Right;
+        break;
+      case NATIVE_PLACEMENT_RIGHT_START:
+        cpp_placement = Placement::RightStart;
+        break;
+      case NATIVE_PLACEMENT_RIGHT_END:
+        cpp_placement = Placement::RightEnd;
+        break;
+      case NATIVE_PLACEMENT_BOTTOM:
+        cpp_placement = Placement::Bottom;
+        break;
+      case NATIVE_PLACEMENT_BOTTOM_START:
+        cpp_placement = Placement::BottomStart;
+        break;
+      case NATIVE_PLACEMENT_BOTTOM_END:
+        cpp_placement = Placement::BottomEnd;
+        break;
+      case NATIVE_PLACEMENT_LEFT:
+        cpp_placement = Placement::Left;
+        break;
+      case NATIVE_PLACEMENT_LEFT_START:
+        cpp_placement = Placement::LeftStart;
+        break;
+      case NATIVE_PLACEMENT_LEFT_END:
+        cpp_placement = Placement::LeftEnd;
+        break;
+      default:
+        cpp_placement = Placement::BottomStart;
+        break;
+    }
+    
+    return menu_ptr->Open(*strategy_ptr, cpp_placement);
   } catch (...) {
     return false;
   }

src/capi/menu_c.h

@@ -3,6 +3,7 @@
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
+#include "geometry_c.h"
 
 #if _WIN32
 #define FFI_PLUGIN_EXPORT __declspec(dllexport)
@@ -477,10 +478,12 @@ native_menu_item_list_t native_menu_get_all_items(native_menu_t menu);
  * Open the menu as a context menu using the specified positioning strategy
  * @param menu The menu
  * @param strategy The positioning strategy determining where to display the menu
+ * @param placement The placement option determining how the menu is positioned
+ *                  relative to the reference point (default: NATIVE_PLACEMENT_BOTTOM_START)
  * @return true if menu was opened successfully, false otherwise
  */
 FFI_PLUGIN_EXPORT
-bool native_menu_open(native_menu_t menu, native_positioning_strategy_t strategy);
+bool native_menu_open(native_menu_t menu, native_positioning_strategy_t strategy, native_placement_t placement);
 
 /**
  * Close the menu if it's currently showing

src/menu.h

@@ -650,22 +650,27 @@ class Menu : public EventEmitter<MenuEvent>, public NativeObjectProvider {
    * selects an item.
    *
    * @param strategy The positioning strategy determining where to display the menu
+   * @param placement The placement option determining how the menu is positioned
+   *                  relative to the reference point (default: BottomStart)
    * @return true if the menu was successfully opened, false otherwise
    *
    * @example
    * ```cpp
-   * // Open context menu at cursor position
-   * menu->Open(PositioningStrategy::CursorPosition());
+   * // Open context menu at cursor position, below the cursor
+   * menu->Open(PositioningStrategy::CursorPosition(), Placement::BottomStart);
    *
-   * // Open context menu at specific coordinates
-   * menu->Open(PositioningStrategy::Absolute({100, 200}));
+   * // Open context menu at specific coordinates, above and centered
+   * menu->Open(PositioningStrategy::Absolute({100, 200}), Placement::Top);
    *
-   * // Open context menu relative to a button with offset
+   * // Open context menu relative to a button with offset, to the right
    * Rectangle buttonRect = button->GetBounds();
-   * menu->Open(PositioningStrategy::Relative(buttonRect, {0, 10}));
+   * menu->Open(PositioningStrategy::Relative(buttonRect, {0, 10}), Placement::Right);
+   *
+   * // Use default placement (BottomStart)
+   * menu->Open(PositioningStrategy::CursorPosition());
    * ```
    */
-  bool Open(const PositioningStrategy& strategy);
+  bool Open(const PositioningStrategy& strategy, Placement placement = Placement::BottomStart);
 
   /**
    * @brief Programmatically close the menu if it's currently showing.

src/platform/linux/menu_linux.cpp

@@ -395,7 +395,7 @@ std::vector<std::shared_ptr<MenuItem>> Menu::GetAllItems() const {
   return pimpl_->items_;
 }
 
-bool Menu::Open(const PositioningStrategy& strategy) {
+bool Menu::Open(const PositioningStrategy& strategy, Placement placement) {
   if (pimpl_->gtk_menu_) {
     gtk_widget_show_all(pimpl_->gtk_menu_);
 
@@ -426,6 +426,61 @@ bool Menu::Open(const PositioningStrategy& strategy) {
       }
     }
 
+    // Map placement to GDK gravity values
+    GdkGravity anchor_gravity = GDK_GRAVITY_NORTH_WEST;
+    GdkGravity menu_gravity = GDK_GRAVITY_NORTH_WEST;
+
+    switch (placement) {
+      case Placement::Top:
+        anchor_gravity = GDK_GRAVITY_SOUTH;
+        menu_gravity = GDK_GRAVITY_NORTH;
+        break;
+      case Placement::TopStart:
+        anchor_gravity = GDK_GRAVITY_SOUTH_WEST;
+        menu_gravity = GDK_GRAVITY_NORTH_WEST;
+        break;
+      case Placement::TopEnd:
+        anchor_gravity = GDK_GRAVITY_SOUTH_EAST;
+        menu_gravity = GDK_GRAVITY_NORTH_EAST;
+        break;
+      case Placement::Right:
+        anchor_gravity = GDK_GRAVITY_WEST;
+        menu_gravity = GDK_GRAVITY_EAST;
+        break;
+      case Placement::RightStart:
+        anchor_gravity = GDK_GRAVITY_NORTH_WEST;
+        menu_gravity = GDK_GRAVITY_NORTH_EAST;
+        break;
+      case Placement::RightEnd:
+        anchor_gravity = GDK_GRAVITY_SOUTH_WEST;
+        menu_gravity = GDK_GRAVITY_SOUTH_EAST;
+        break;
+      case Placement::Bottom:
+        anchor_gravity = GDK_GRAVITY_NORTH;
+        menu_gravity = GDK_GRAVITY_SOUTH;
+        break;
+      case Placement::BottomStart:
+        anchor_gravity = GDK_GRAVITY_NORTH_WEST;
+        menu_gravity = GDK_GRAVITY_SOUTH_WEST;
+        break;
+      case Placement::BottomEnd:
+        anchor_gravity = GDK_GRAVITY_NORTH_EAST;
+        menu_gravity = GDK_GRAVITY_SOUTH_EAST;
+        break;
+      case Placement::Left:
+        anchor_gravity = GDK_GRAVITY_EAST;
+        menu_gravity = GDK_GRAVITY_WEST;
+        break;
+      case Placement::LeftStart:
+        anchor_gravity = GDK_GRAVITY_NORTH_EAST;
+        menu_gravity = GDK_GRAVITY_NORTH_WEST;
+        break;
+      case Placement::LeftEnd:
+        anchor_gravity = GDK_GRAVITY_SOUTH_EAST;
+        menu_gravity = GDK_GRAVITY_SOUTH_WEST;
+        break;
+    }
+
     // Try to position at explicit coordinates if available
     if (use_explicit_position) {
       GdkWindow* root_window = gdk_get_default_root_window();
@@ -436,7 +491,7 @@ bool Menu::Open(const PositioningStrategy& strategy) {
         rect.width = 1;
         rect.height = 1;
         gtk_menu_popup_at_rect(GTK_MENU(pimpl_->gtk_menu_), root_window, &rect,
-                               GDK_GRAVITY_NORTH_WEST, GDK_GRAVITY_NORTH_WEST, nullptr);
+                               anchor_gravity, menu_gravity, nullptr);
       } else {
         // Fallback to pointer if root window not available
         gtk_menu_popup_at_pointer(GTK_MENU(pimpl_->gtk_menu_), nullptr);

src/platform/macos/menu_macos.mm

@@ -670,7 +670,7 @@ - (void)menuDidClose:(NSMenu*)menu {
   return pimpl_->items_;
 }
 
-bool Menu::Open(const PositioningStrategy& strategy) {
+bool Menu::Open(const PositioningStrategy& strategy, Placement placement) {
   double x = 0, y = 0;
 
   // Determine position based on strategy type
@@ -697,6 +697,70 @@ - (void)menuDidClose:(NSMenu*)menu {
     }
   }
 
+  // Get menu size for placement adjustments
+  NSSize menu_size = [pimpl_->ns_menu_ size];
+  double menu_width = menu_size.width;
+  double menu_height = menu_size.height;
+
+  // Adjust position based on placement
+  switch (placement) {
+    case Placement::TopStart:  // topLeft
+      x -= menu_width;
+      y += menu_height;
+      break;
+    
+    case Placement::Top:  // top center
+      x -= menu_width / 2.0;
+      y += menu_height;
+      break;
+    
+    case Placement::TopEnd:  // topRight
+      y += menu_height;
+      break;
+    
+    case Placement::RightStart:  // right top
+      x += menu_width;
+      y += menu_height;
+      break;
+    
+    case Placement::Right:  // right center
+      x += menu_width;
+      y -= menu_height / 2.0;
+      break;
+    
+    case Placement::RightEnd:  // right bottom
+      x += menu_width;
+      y -= menu_height;
+      break;
+    
+    case Placement::BottomStart:  // bottomLeft
+      x -= menu_width;
+      break;
+    
+    case Placement::Bottom:  // bottom center
+      x -= menu_width / 2.0;
+      break;
+    
+    case Placement::BottomEnd:  // bottomRight
+      // No adjustment needed
+      break;
+    
+    case Placement::LeftStart:  // left top
+      x -= menu_width;
+      y += menu_height;
+      break;
+    
+    case Placement::Left:  // left center
+      x -= menu_width;
+      y -= menu_height / 2.0;
+      break;
+    
+    case Placement::LeftEnd:  // left bottom
+      x -= menu_width;
+      y -= menu_height;
+      break;
+  }
+
   // Get the main window
   NSWindow* main_window = [[NSApplication sharedApplication] mainWindow];
   if (!main_window) {