@lynx-js/lynx-library-headers 0.0.1-alpha.4

package/include/lynx/platform/embedder/public/lynx_value.h

@@ -0,0 +1,270 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_VALUE_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_VALUE_H_
+
+#include <functional>
+#include <memory>
+#include <string>
+#include <utility>
+
+#include "base/include/value/lynx_value_api.h"
+namespace lynx {
+namespace pub {
+
+class LynxValue;
+using LynxValueIterator =
+    std::function<void(const LynxValue&, const LynxValue&)>;
+using LynxValueIteratorCallback =
+    std::function<void(lynx_api_env, const lynx_value&, const lynx_value&)>;
+
+class LynxValue {
+ public:
+  ~LynxValue() { lynx_value_remove_reference(env_, value_, nullptr); }
+
+  LynxValue(const LynxValue& val) {
+    if (this == &val) return;
+    lynx_value_add_reference(env_, val.value_, nullptr);
+    value_ = val.value_;
+  }
+
+  LynxValue(LynxValue&& val) noexcept {
+    value_ = val.value_;
+    val.value_.type = lynx_value_null;
+  }
+
+  LynxValue& operator=(const LynxValue& val) {
+    if (this != &val) {
+      lynx_value_add_reference(env_, val.value_, nullptr);
+      lynx_value_remove_reference(env_, value_, nullptr);
+      value_ = val.value_;
+    }
+    return *this;
+  }
+
+  LynxValue& operator=(LynxValue&& val) noexcept {
+    if (this != &val) {
+      this->~LynxValue();
+      new (this) LynxValue(std::move(val));
+    }
+    return *this;
+  }
+
+  explicit LynxValue(bool val) { lynx_value_create_bool(env_, val, &value_); }
+
+  explicit LynxValue(int32_t val) {
+    lynx_value_create_int32(env_, val, &value_);
+  }
+
+  explicit LynxValue(int64_t val) {
+    lynx_value_create_int64(env_, val, &value_);
+  }
+
+  explicit LynxValue(uint32_t val) {
+    lynx_value_create_uint32(env_, val, &value_);
+  }
+
+  explicit LynxValue(uint64_t val) {
+    lynx_value_create_uint64(env_, val, &value_);
+  }
+
+  explicit LynxValue(double val) {
+    lynx_value_create_double(env_, val, &value_);
+  }
+
+  explicit LynxValue(const char* str) {
+    lynx_value_create_string_utf8(
+        env_, str, str == nullptr ? 0 : std::strlen(str), &value_);
+  }
+
+  explicit LynxValue(const std::string& str) {
+    lynx_value_create_string_utf8(env_, str.c_str(), str.size(), &value_);
+  }
+
+  enum CreateAsNullTag {
+    kCreateAsNullTag,
+  };
+  explicit LynxValue(CreateAsNullTag) { lynx_value_create_null(env_, &value_); }
+
+  enum CreateAsArrayTag {
+    kCreateAsArrayTag,
+  };
+  explicit LynxValue(CreateAsArrayTag) {
+    lynx_value_create_array(env_, &value_);
+  }
+
+  enum CreateAsMapTag {
+    kCreateAsMapTag,
+  };
+  explicit LynxValue(CreateAsMapTag) { lynx_value_create_map(env_, &value_); }
+
+  explicit LynxValue(const lynx_value& val) : value_(val) {
+    lynx_value_add_reference(env_, value_, nullptr);
+  }
+
+  explicit LynxValue(lynx_value&& val) : value_(std::move(val)) {}
+
+  lynx_value_type Type() const {
+    lynx_value_type type;
+    lynx_value_typeof(env_, value_, &type);
+    return type;
+  }
+
+  lynx_value Value() const { return value_; }
+
+  bool Bool() const {
+    bool ret;
+    lynx_api_status status = lynx_value_get_bool(env_, value_, &ret);
+    if (status != lynx_api_ok) return false;
+    return ret;
+  }
+
+  double Number() const {
+    double ret;
+    lynx_api_status status = lynx_value_get_number(env_, value_, &ret);
+    if (status != lynx_api_ok) return 0.f;
+    return ret;
+  }
+
+  double Double() const {
+    double ret;
+    lynx_api_status status = lynx_value_get_double(env_, value_, &ret);
+    if (status != lynx_api_ok) return 0.f;
+    return ret;
+  }
+
+  int32_t Int32() const {
+    int32_t ret;
+    lynx_api_status status = lynx_value_get_int32(env_, value_, &ret);
+    if (status != lynx_api_ok) return 0;
+    return ret;
+  }
+
+  uint32_t UInt32() const {
+    uint32_t ret;
+    lynx_api_status status = lynx_value_get_uint32(env_, value_, &ret);
+    if (status != lynx_api_ok) return 0;
+    return ret;
+  }
+
+  int64_t Int64() const {
+    int64_t ret;
+    lynx_api_status status = lynx_value_get_int64(env_, value_, &ret);
+    if (status != lynx_api_ok) return 0;
+    return ret;
+  }
+
+  uint64_t UInt64() const {
+    uint64_t ret;
+    lynx_api_status status = lynx_value_get_uint64(env_, value_, &ret);
+    if (status != lynx_api_ok) return 0;
+    return ret;
+  }
+
+  std::string StdString() const {
+    size_t str_size;
+    lynx_api_status status =
+        lynx_value_get_string_utf8(env_, value_, nullptr, 0, &str_size);
+    if (status != lynx_api_ok) return "";
+    auto buf = std::make_unique<char[]>(str_size + 1);
+    status = lynx_value_get_string_utf8(env_, value_, buf.get(), str_size + 1,
+                                        &str_size);
+    if (status != lynx_api_ok) return "";
+    return std::string(buf.get(), str_size);
+  }
+
+  uint32_t ArrayLength() const {
+    uint32_t ret;
+    lynx_value_get_array_length(env_, value_, &ret);
+    return ret;
+  }
+
+  bool InsertValue(uint32_t idx, const LynxValue& val) {
+    lynx_api_status status =
+        lynx_value_set_element(env_, value_, idx, val.value_);
+    if (status != lynx_api_ok) return false;
+    return true;
+  }
+
+  LynxValue GetValueAt(uint32_t idx) const {
+    lynx_value ret;
+    lynx_api_status status = lynx_value_get_element(env_, value_, idx, &ret);
+    if (status != lynx_api_ok) return LynxValue(kCreateAsNullTag);
+    return LynxValue(std::move(ret));
+  }
+
+  bool HasProperty(const char* key) const {
+    bool ret;
+    lynx_api_status status = lynx_value_has_property(env_, value_, key, &ret);
+    if (status != lynx_api_ok) return false;
+    return ret;
+  }
+
+  bool SetProperty(const char* key, const LynxValue& val) {
+    lynx_api_status status =
+        lynx_value_set_named_property(env_, value_, key, val.value_);
+    if (status != lynx_api_ok) return false;
+    return true;
+  }
+
+  LynxValue GetProperty(const char* key) const {
+    lynx_value ret;
+    lynx_api_status status =
+        lynx_value_get_named_property(env_, value_, key, &ret);
+    if (status != lynx_api_ok) return LynxValue(kCreateAsNullTag);
+    return LynxValue(std::move(ret));
+  }
+
+  void IteratorValue(const LynxValueIterator& callback) const {
+    LynxValueIteratorCallback callback_wrap =
+        [&callback](lynx_api_env env, const lynx_value& key,
+                    const lynx_value& value) {
+          LynxValue keyWrap(key);
+          lynx_value v = value;
+          LynxValue valueWrap(std::move(v));
+          callback(keyWrap, valueWrap);
+        };
+    lynx_value_iterate_value(env_, value_, InternalLynxValueIteratorCallback,
+                             reinterpret_cast<void*>(&callback_wrap), nullptr);
+  }
+
+  static void ForEachLynxValue(const LynxValue& val, LynxValueIterator func) {
+    lynx_api_env env = val.env_;
+    lynx_value property_names;
+    lynx_api_status status =
+        lynx_value_get_property_names(env, val.value_, &property_names);
+    if (status != lynx_api_ok) return;
+    uint32_t len;
+    lynx_value_get_array_length(env, property_names, &len);
+    for (uint32_t i = 0; i < len; i++) {
+      lynx_value element;
+      lynx_value_get_element(env, property_names, i, &element);
+      auto key = LynxValue(std::move(element));
+      lynx_value property;
+      lynx_value_get_named_property(env, val.value_, key.StdString().c_str(),
+                                    &property);
+      auto value = LynxValue(std::move(property));
+      func(key, value);
+    }
+    lynx_value_remove_reference(env, property_names, nullptr);
+  }
+
+ private:
+  static inline void InternalLynxValueIteratorCallback(lynx_api_env env,
+                                                       lynx_value key,
+                                                       lynx_value value,
+                                                       void* pfunc,
+                                                       void* raw_data) {
+    reinterpret_cast<LynxValueIteratorCallback*>(pfunc)->operator()(env, key,
+                                                                    value);
+  }
+
+  lynx_value value_;
+  lynx_api_env env_ = nullptr;
+};
+
+}  // namespace pub
+}  // namespace lynx
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_VALUE_H_

package/include/lynx/platform/embedder/public/lynx_view.h

@@ -0,0 +1,364 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_VIEW_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_VIEW_H_
+
+#include <algorithm>
+#include <memory>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "capi/lynx_view_builder_capi.h"
+#include "capi/lynx_view_capi.h"
+#include "lynx_event_simulation_proxy.h"
+#include "lynx_generic_resource_fetcher.h"
+#include "lynx_group.h"
+#include "lynx_load_meta.h"
+#include "lynx_native_module.h"
+#include "lynx_runtime_lifecycle_observer.h"
+#include "lynx_update_meta.h"
+#include "lynx_view_client.h"
+#include "lynx_windowless_renderer.h"
+
+// Forward declaration of internal struct
+struct lynx_view_t;
+
+namespace lynx {
+namespace pub {
+
+/**
+ * @apidoc
+ * @brief LynxView is the main entry point for rendering and interacting with
+ * Lynx. It provides methods for loading and rendering templates, updating data,
+ * and sending events.
+ */
+class LynxView {
+ public:
+  class Builder {
+   public:
+    Builder() : builder_(lynx_view_builder_create()) {}
+    ~Builder() { lynx_view_builder_release(builder_); }
+
+    Builder& SetScreenSize(float width, float height, float pixel_ratio) {
+      lynx_view_builder_set_screen_size(builder_, width, height, pixel_ratio);
+      return *this;
+    }
+
+    Builder& SetFrame(float x, float y, float width, float height) {
+      lynx_view_builder_set_frame(builder_, x, y, width, height);
+      return *this;
+    }
+
+    Builder& SetFontScale(float scale) {
+      lynx_view_builder_set_font_scale(builder_, scale);
+      return *this;
+    }
+
+    Builder& SetICUDataPath(const std::string& icu_data_path) {
+      lynx_view_builder_set_icu_data_path(builder_, icu_data_path.c_str());
+      return *this;
+    }
+
+    Builder& SetWebView2FixedRuntimePath(
+        const std::string& webview2_fixed_runtime_path) {
+      lynx_view_builder_set_webview2_fixed_runtime_path(
+          builder_, webview2_fixed_runtime_path.c_str());
+      return *this;
+    }
+
+    Builder& SetLynxGroup(std::shared_ptr<LynxGroup> group) {
+      group_ = std::move(group);
+      lynx_view_builder_set_lynx_group(builder_, group_->Impl());
+      return *this;
+    }
+
+    Builder& SetParent(NativeWindow parent) {
+      lynx_view_builder_set_parent(builder_, parent);
+      return *this;
+    }
+    Builder& SetWindowlessRenderer(
+        std::shared_ptr<LynxWindowlessRenderer> renderer) {
+      renderer->InitIfNeeded();
+      lynx_view_builder_set_windowless_renderer(builder_, renderer->Impl());
+      windowless_renderer_ = renderer;
+      return *this;
+    }
+    Builder& SetGenericResourceFetcher(
+        std::shared_ptr<LynxGenericResourceFetcher> fetcher) {
+      fetcher->InitIfNeeded();
+      lynx_view_builder_set_generic_resource_fetcher(builder_, fetcher->Impl());
+      generic_fetcher_ = fetcher;
+      return *this;
+    }
+
+    Builder& RegisterNativeModule(const std::string& module_name,
+                                  napi_module_creator creator, void* opaque) {
+      lynx_view_builder_register_native_module(builder_, module_name.c_str(),
+                                               creator, opaque);
+      return *this;
+    }
+
+    template <typename T>
+    Builder& RegisterNativeView(const std::string& tag_name,
+                                void* opaque = nullptr) {
+      lynx_view_builder_register_native_view(
+          builder_, tag_name.c_str(),
+          [](void* opaque) -> lynx_native_view_t* {
+            return (new T(opaque))->native_view();
+          },
+          opaque);
+      return *this;
+    }
+
+    lynx_view_builder_t* Impl() { return builder_; }
+
+    std::unique_ptr<LynxView> Build() {
+      std::unique_ptr<LynxView> view = std::make_unique<LynxView>(this);
+      view->generic_fetcher_ = std::move(generic_fetcher_);
+      view->windowless_renderer_ = std::move(windowless_renderer_);
+      return view;
+    }
+
+    Builder(const Builder&) = delete;
+    Builder& operator=(const Builder&) = delete;
+
+   private:
+    lynx_view_builder_t* builder_;
+    std::shared_ptr<LynxGroup> group_;
+    std::shared_ptr<LynxWindowlessRenderer> windowless_renderer_;
+    std::shared_ptr<LynxGenericResourceFetcher> generic_fetcher_;
+    friend class LynxView;
+  };
+
+  static LynxView* Unwrap(lynx_view_t* view) {
+    if (view == nullptr) {
+      return nullptr;
+    }
+    return static_cast<LynxView*>(lynx_view_get_user_data(view));
+  }
+
+  explicit LynxView(Builder* builder)
+      : lynx_view_(lynx_view_create(builder->builder_, this)) {}
+
+  virtual ~LynxView() { lynx_view_release(lynx_view_); }
+
+  /**
+   * @apidoc
+   * @brief Register a native view for the `LynxView`.
+   * @param tag_name The tag name of element, specifying exists tag name will
+   * override corresponding builtin element.
+   * @param opaque An opaque pointer to user-specific data.
+   */
+  template <typename T>
+  LynxView& RegisterNativeView(const std::string& tag_name,
+                               void* opaque = nullptr) {
+    lynx_view_register_native_view(
+        lynx_view_, tag_name.c_str(),
+        [](void* opaque) -> lynx_native_view_t* {
+          return (new T(opaque))->native_view();
+        },
+        opaque);
+    return *this;
+  }
+
+  /**
+   * @apidoc
+   * @brief Register lifecycle event observer `LynxViewClient` for the
+   * `LynxView`.
+   * @param client The structure implemented by the client and registered to
+   * the `LynxView` instance is used to obtain the callbacks of each process
+   * in the `LynxView` lifecycle.
+   */
+  void AddClient(std::shared_ptr<LynxViewClient> client) {
+    if (std::find(lynx_view_clients_.begin(), lynx_view_clients_.end(),
+                  client) == lynx_view_clients_.end()) {
+      lynx_view_add_client(lynx_view_, client->Impl());
+      lynx_view_clients_.emplace_back(client);
+    }
+  }
+
+  /**
+   * @apidoc
+   * @brief Remove `LynxView` lifecycle event monitoring.
+   * @param client The structure implemented by the client and registered to the
+   * `LynxView` instance is used to obtain the callbacks of each process in the
+   * LynxView life cycle.
+   */
+  void RemoveClient(std::shared_ptr<LynxViewClient> client) {
+    lynx_view_remove_client(lynx_view_, client->Impl());
+    lynx_view_clients_.erase(std::remove(lynx_view_clients_.begin(),
+                                         lynx_view_clients_.end(), client),
+                             lynx_view_clients_.end());
+  }
+
+  void RegisterRuntimeLifecycleObserver(
+      std::shared_ptr<LynxRuntimeLifecycleObserver> observer) {
+    observer->InitIfNeeded();
+    lynx_view_register_runtime_lifecycle_observer(lynx_view_, observer->Impl());
+    runtime_lifecycle_observer_ = observer;
+  }
+
+  /**
+   * @apidoc
+   * @brief Using `LynxLoadMeta` to render `LynxView`, it is the main entrance
+   * for the client to load `Lynx` templates.
+   * @param load_meta Lynx template loads metadata, and developers use this data
+   * structure to specify optional data loaded by the template.
+   */
+  void LoadTemplate(std::shared_ptr<LynxLoadMeta> load_meta) {
+    lynx_view_load_template(lynx_view_, load_meta->Impl());
+  }
+
+  /**
+   * @apidoc
+   * @brief Using `LynxUpdateMeta` to update `LynxView`, it is the main entrance
+   * for the client to update template data.
+   * @param meta Lynx template update metadata, developers use this data
+   * structure to specify the optional data content of the update template.
+   */
+  void UpdateData(std::shared_ptr<LynxUpdateMeta> update_meta) {
+    lynx_view_update_data(lynx_view_, update_meta->Impl());
+  }
+
+  /**
+   * @apidoc
+   * @brief Reload the `LynxView` template with new data.
+   * @param data The template data to be loaded.
+   * @param global_props The global properties of the template.
+   */
+  void ReloadTemplate(std::shared_ptr<LynxTemplateData> data,
+                      std::shared_ptr<LynxTemplateData> global_props) {
+    lynx_view_reload_template(lynx_view_, data->Impl(),
+                              global_props ? global_props->Impl() : nullptr);
+  }
+
+  /**
+   * @apidoc
+   * @brief Send global events to the front end through the client, and the
+   * front end can listen to the event through `GlobalEventEmitter`.
+   * @param name Global event name.
+   * @param params Parameters carried by global events.
+   */
+  void SendGlobalEvent(const std::string& name, const std::string& json) {
+    lynx_view_send_global_event(lynx_view_, name.c_str(), json.c_str());
+  }
+
+  void SendTouchEvent(const std::string& name, int32_t id, float x, float y,
+                      float client_x, float client_y, float page_x,
+                      float page_y) {
+    lynx_view_send_touch_event(lynx_view_, name.c_str(), id, x, y, client_x,
+                               client_y, page_x, page_y);
+  }
+
+  int GetNodeForLocation(int x, int y) {
+    return lynx_view_get_node_for_location(lynx_view_, x, y);
+  }
+
+  void EmulateMouseEvent(const std::string& event_name, float x, float y,
+                         float delta_x = 0.f, float delta_y = 0.f) {
+    lynx_view_emulate_mouse_event(lynx_view_, event_name.c_str(), x, y, delta_x,
+                                  delta_y);
+  }
+
+  /**
+   * @apidoc
+   * @brief Update the screen metrics of the `LynxView`.
+   * @param width The width of the screen.
+   * @param height The height of the screen.
+   * @param pixel_ratio The pixel ratio of the screen.
+   */
+  void UpdateScreenMetrics(float width, float height, float pixel_ratio) {
+    lynx_view_update_screen_metrics(lynx_view_, width, height, pixel_ratio);
+  }
+
+  /**
+   * @apidoc
+   * @brief Set the position and size of the `LynxView` in the window.
+   * @param x The x coordinate of the `LynxView` position.
+   * @param y The y coordinate of the `LynxView` position.
+   * @param width The width of the `LynxView`.
+   * @param height The height of the `LynxView`.
+   */
+  void SetFrame(float x, float y, float width, float height) {
+    lynx_view_set_frame(lynx_view_, x, y, width, height);
+  }
+
+  /**
+   * @apidoc
+   * @brief Changing the font scaling ratio in client settings will
+   * automatically change the text size.
+   * @param scale The new font scaling ratio.
+   */
+  void SetFontScale(float scale) {
+    lynx_view_set_font_scale(lynx_view_, scale);
+  }
+
+  /**
+   * @apidoc
+   * @brief Set the parent window of the `LynxView`.
+   * @param parent The parent window of the `LynxView`.
+   */
+  void SetParent(NativeWindow parent) {
+    lynx_view_set_parent(lynx_view_, parent);
+  }
+
+  NativeWindow GetNativeWindow() {
+    return lynx_view_get_native_window(lynx_view_);
+  }
+
+  /**
+   * @apidoc
+   * @brief Notify the `LynxView` that it has entered the foreground.
+   */
+  void OnEnterForeground() { lynx_view_enter_foreground(lynx_view_); }
+
+  /**
+   * @apidoc
+   * @brief Notify the `LynxView` that it has entered the background.
+   */
+  void OnEnterBackground() { lynx_view_enter_background(lynx_view_); }
+
+  void InjectBubbleEvent(const std::string& params) {
+    lynx_view_inject_bubble_event(lynx_view_, params.c_str());
+  }
+
+  void SetEventSimulationProxy(
+      std::shared_ptr<LynxEventSimulationProxy> proxy) {
+    event_proxy_ = std::move(proxy);
+    if (event_proxy_) {
+      lynx_view_set_event_simulation_proxy(
+          lynx_view_,
+          [](void* ctx, const char* event_type, int x, int y,
+             const char* button, float delta_x, float delta_y, int modifiers,
+             int click_count) {
+            static_cast<LynxEventSimulationProxy*>(ctx)->EmulateTouch(
+                event_type, x, y, button, delta_x, delta_y, modifiers,
+                click_count);
+          },
+          event_proxy_.get());
+    } else {
+      lynx_view_set_event_simulation_proxy(lynx_view_, nullptr, nullptr);
+    }
+  }
+
+  lynx_view_t* Impl() { return lynx_view_; }
+
+  LynxView(const LynxView&) = delete;
+  LynxView& operator=(const LynxView&) = delete;
+
+ private:
+  lynx_view_t* lynx_view_;
+  std::shared_ptr<LynxGenericResourceFetcher> generic_fetcher_;
+  std::vector<std::shared_ptr<LynxViewClient>> lynx_view_clients_;
+  std::shared_ptr<LynxWindowlessRenderer> windowless_renderer_;
+  std::shared_ptr<LynxRuntimeLifecycleObserver> runtime_lifecycle_observer_;
+  std::shared_ptr<LynxEventSimulationProxy> event_proxy_;
+};
+
+}  // namespace pub
+}  // namespace lynx
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_VIEW_H_