Add cross-platform Image API and update icon handling

Introduces a new Image class for unified image management across platforms, with C API bindings in image_c.h/cpp. Refactors menu and tray icon APIs to use Image objects instead of file paths or base64 strings, updating related headers and documentation for type safety and improved resource management.

Author: lijy91

src/capi/image_c.cpp

@@ -0,0 +1,150 @@
+#include "image_c.h"
+
+#include <cstring>
+#include "../image.h"
+#include "string_utils_c.h"
+
+using namespace nativeapi;
+
+// Create an image from a file path
+native_image_t native_image_from_file(const char* file_path) {
+  if (!file_path) {
+    return nullptr;
+  }
+
+  try {
+    auto image = Image::FromFile(file_path);
+    if (image) {
+      auto size = image->GetSize();
+      if (size.width > 0 && size.height > 0) {
+        return new std::shared_ptr<Image>(image);
+      }
+    }
+  } catch (...) {
+    // Handle exceptions
+  }
+
+  return nullptr;
+}
+
+// Create an image from base64-encoded data
+native_image_t native_image_from_base64(const char* base64_data) {
+  if (!base64_data) {
+    return nullptr;
+  }
+
+  try {
+    auto image = Image::FromBase64(base64_data);
+    if (image) {
+      auto size = image->GetSize();
+      if (size.width > 0 && size.height > 0) {
+        return new std::shared_ptr<Image>(image);
+      }
+    }
+  } catch (...) {
+    // Handle exceptions
+  }
+
+  return nullptr;
+}
+
+// Create an image from a platform-specific system icon
+native_image_t native_image_from_system_icon(const char* icon_name) {
+  if (!icon_name) {
+    return nullptr;
+  }
+
+  try {
+    auto image = Image::FromSystemIcon(icon_name);
+    if (image) {
+      auto size = image->GetSize();
+      if (size.width > 0 && size.height > 0) {
+        return new std::shared_ptr<Image>(image);
+      }
+    }
+  } catch (...) {
+    // Handle exceptions
+  }
+
+  return nullptr;
+}
+
+// Destroy an image and release its resources
+void native_image_destroy(native_image_t image) {
+  if (image) {
+    delete static_cast<std::shared_ptr<Image>*>(image);
+  }
+}
+
+// Get the size of an image in pixels
+void native_image_get_size(native_image_t image,
+                           double* width,
+                           double* height) {
+  if (!image || !width || !height) {
+    if (width)
+      *width = 0.0;
+    if (height)
+      *height = 0.0;
+    return;
+  }
+
+  try {
+    auto img = static_cast<std::shared_ptr<Image>*>(image);
+    auto size = (*img)->GetSize();
+    *width = size.width;
+    *height = size.height;
+  } catch (...) {
+    *width = 0.0;
+    *height = 0.0;
+  }
+}
+
+// Get the image format string for debugging purposes
+char* native_image_get_format(native_image_t image) {
+  if (!image) {
+    return nullptr;
+  }
+
+  try {
+    auto img = static_cast<std::shared_ptr<Image>*>(image);
+    std::string format = (*img)->GetFormat();
+
+    return to_c_str(format);
+  } catch (...) {
+    // Handle exceptions
+  }
+
+  return nullptr;
+}
+
+// Convert an image to base64-encoded PNG data
+char* native_image_to_base64(native_image_t image) {
+  if (!image) {
+    return nullptr;
+  }
+
+  try {
+    auto img = static_cast<std::shared_ptr<Image>*>(image);
+    std::string base64 = (*img)->ToBase64();
+
+    return to_c_str(base64);
+  } catch (...) {
+    // Handle exceptions
+  }
+
+  return nullptr;
+}
+
+// Save an image to a file
+bool native_image_save_to_file(native_image_t image, const char* file_path) {
+  if (!image || !file_path) {
+    return false;
+  }
+
+  try {
+    auto img = static_cast<std::shared_ptr<Image>*>(image);
+    return (*img)->SaveToFile(file_path);
+  } catch (...) {
+    return false;
+  }
+}

src/capi/image_c.h

@@ -0,0 +1,95 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#if _WIN32
+#define FFI_PLUGIN_EXPORT __declspec(dllexport)
+#else
+#define FFI_PLUGIN_EXPORT
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Opaque handle for image objects
+ */
+typedef void* native_image_t;
+
+/**
+ * Image operations
+ */
+
+/**
+ * Create an image from a file path
+ * @param file_path Path to the image file
+ * @return Image handle, or NULL if loading failed
+ */
+FFI_PLUGIN_EXPORT
+native_image_t native_image_from_file(const char* file_path);
+
+/**
+ * Create an image from base64-encoded data
+ * @param base64_data Base64-encoded image data, with or without data URI prefix
+ * @return Image handle, or NULL if decoding failed
+ */
+FFI_PLUGIN_EXPORT
+native_image_t native_image_from_base64(const char* base64_data);
+
+/**
+ * Create an image from a platform-specific system icon
+ * @param icon_name Platform-specific system icon name/identifier
+ * @return Image handle, or NULL if icon not found
+ */
+FFI_PLUGIN_EXPORT
+native_image_t native_image_from_system_icon(const char* icon_name);
+
+/**
+ * Destroy an image and release its resources
+ * @param image The image to destroy
+ */
+FFI_PLUGIN_EXPORT
+void native_image_destroy(native_image_t image);
+
+/**
+ * Get the size of an image in pixels
+ * @param image The image
+ * @param width Pointer to store the width (will be set to 0 if invalid)
+ * @param height Pointer to store the height (will be set to 0 if invalid)
+ */
+FFI_PLUGIN_EXPORT
+void native_image_get_size(native_image_t image, double* width, double* height);
+
+/**
+ * Get the image format string for debugging purposes
+ * @param image The image
+ * @return The image format (e.g., "PNG", "JPEG", "GIF"), or NULL if unknown
+ * (caller must free)
+ */
+FFI_PLUGIN_EXPORT
+char* native_image_get_format(native_image_t image);
+
+/**
+ * Convert an image to base64-encoded PNG data
+ * @param image The image
+ * @return Base64-encoded PNG data with data URI prefix (caller must free), or
+ * NULL on error
+ */
+FFI_PLUGIN_EXPORT
+char* native_image_to_base64(native_image_t image);
+
+/**
+ * Save an image to a file
+ * @param image The image
+ * @param file_path Path where the image should be saved
+ * @return true if saved successfully, false otherwise
+ */
+FFI_PLUGIN_EXPORT
+bool native_image_save_to_file(native_image_t image, const char* file_path);
+
+#ifdef __cplusplus
+}
+#endif

src/capi/menu_c.cpp

@@ -1067,8 +1067,6 @@ bool native_menu_remove_listener(native_menu_t menu, int listener_id) {
   }
 }
 
-
-
 // Utility functions
 
 void native_menu_item_list_free(native_menu_item_list_t list) {

src/capi/menu_c.h

@@ -15,6 +15,7 @@ extern "C" {
 #endif
 
 #include "geometry_c.h"
+#include "image_c.h"
 
 /**
  * Opaque handles for menu objects
@@ -194,20 +195,21 @@ FFI_PLUGIN_EXPORT
 char* native_menu_item_get_label(native_menu_item_t item);
 
 /**
- * Set the icon of a menu item
+ * Set the icon of a menu item using an Image object
  * @param item The menu item
- * @param icon Path to icon file or base64 data
+ * @param image The Image object to set as the icon, or NULL to clear the icon
  */
 FFI_PLUGIN_EXPORT
-void native_menu_item_set_icon(native_menu_item_t item, const char* icon);
+void native_menu_item_set_icon(native_menu_item_t item, native_image_t image);
 
 /**
- * Get the icon of a menu item
+ * Get the current icon image of the menu item
  * @param item The menu item
- * @return The icon path/data string (caller must free), or NULL if item is invalid or no icon set
+ * @return The Image object, or NULL if no icon is set. Caller must call
+ *         native_image_destroy() when done.
  */
 FFI_PLUGIN_EXPORT
-char* native_menu_item_get_icon(native_menu_item_t item);
+native_image_t native_menu_item_get_icon(native_menu_item_t item);
 
 /**
  * Set the tooltip of a menu item
@@ -577,8 +579,6 @@ int native_menu_add_listener(native_menu_t menu,
 FFI_PLUGIN_EXPORT
 bool native_menu_remove_listener(native_menu_t menu, int listener_id);
 
-
-
 /**
  * Utility functions
  */
@@ -600,4 +600,4 @@ char* native_keyboard_accelerator_to_string(const native_keyboard_accelerator_t*
 
 #ifdef __cplusplus
 }
-#endif
+#endif

src/capi/tray_icon_c.h

@@ -15,6 +15,7 @@ extern "C" {
 #endif
 
 #include "geometry_c.h"
+#include "image_c.h"
 #include "menu_c.h"
 
 /**
@@ -98,12 +99,21 @@ FFI_PLUGIN_EXPORT
 native_tray_icon_id_t native_tray_icon_get_id(native_tray_icon_t tray_icon);
 
 /**
- * Set the icon image for the tray icon
+ * Set the icon image for the tray icon using an Image object
  * @param tray_icon The tray icon
- * @param icon Path to icon file or base64 encoded image data
+ * @param image The Image object to set as the icon, or NULL to clear the icon
  */
 FFI_PLUGIN_EXPORT
-void native_tray_icon_set_icon(native_tray_icon_t tray_icon, const char* icon);
+void native_tray_icon_set_icon(native_tray_icon_t tray_icon, native_image_t image);
+
+/**
+ * Get the current icon image of the tray icon
+ * @param tray_icon The tray icon
+ * @return The Image object, or NULL if no icon is set. Caller must call
+ *         native_image_destroy() when done.
+ */
+FFI_PLUGIN_EXPORT
+native_image_t native_tray_icon_get_icon(native_tray_icon_t tray_icon);
 
 /**
  * Set the title text for the tray icon
@@ -116,8 +126,8 @@ void native_tray_icon_set_title(native_tray_icon_t tray_icon, const char* title)
 /**
  * Get the title text of the tray icon
  * @param tray_icon The tray icon
- * @return The title text, or NULL if no title is set or error. Caller must free the returned
- * string.
+ * @return The title text, or NULL if no title is set or error. Caller must free
+ * the returned string.
  */
 FFI_PLUGIN_EXPORT
 char* native_tray_icon_get_title(native_tray_icon_t tray_icon);
@@ -133,8 +143,8 @@ void native_tray_icon_set_tooltip(native_tray_icon_t tray_icon, const char* tool
 /**
  * Get the tooltip text of the tray icon
  * @param tray_icon The tray icon
- * @return The tooltip text, or NULL if no tooltip is set or error. Caller must free the returned
- * string.
+ * @return The tooltip text, or NULL if no tooltip is set or error. Caller must
+ * free the returned string.
  */
 FFI_PLUGIN_EXPORT
 char* native_tray_icon_get_tooltip(native_tray_icon_t tray_icon);