Unify object identity/lifecycle model

Display becomes an identity object: managed via shared_ptr, non-copyable,
identified by an integer DisplayId from IdAllocator (GetName() keeps the
human-readable string). DisplayManager now caches one live instance per
connected display keyed by platform identity, so repeated enumeration
returns the same object with a stable id; the cache/diff/event logic is
shared code and platforms only implement EnumerateNativeDisplays().

GetAll()/GetPrimary() return shared_ptr; GetPrimary() returns nullptr
instead of throwing (the library's only throwing API). DisplayEvent
carries a shared_ptr<Display>; DisplayChangedEvent no longer carries
old/new snapshots - identity objects read state live. Shortcut is
non-copyable to match the identity-object rules.

The identity-object / value-object rules are specified in
specs/object-model.md.

Author: lijy91

examples/display_c_example/main.c

@@ -26,9 +26,8 @@ int main() {
       printf("  Name: %s\n", name ? name : "Unknown");
       free_c_str(name);
 
-      char* id = native_display_get_id(display);
-      printf("  ID: %s\n", id ? id : "Unknown");
-      free_c_str(id);
+      native_display_id_t id = native_display_get_id(display);
+      printf("  ID: %u\n", id);
 
       native_point_t position = native_display_get_position(display);
       printf("  Position: (%.0f, %.0f)\n", position.x, position.y);

examples/display_example/main.cpp

@@ -33,13 +33,13 @@ int main() {
     DisplayManager& displayManager = DisplayManager::GetInstance();
 
     // Test getting all displays
-    std::vector<Display> displays = displayManager.GetAll();
+    std::vector<std::shared_ptr<Display>> displays = displayManager.GetAll();
 
     if (!displays.empty()) {
       std::cout << "Found " << displays.size() << " display(s):" << std::endl << std::endl;
 
       for (size_t i = 0; i < displays.size(); i++) {
-        const Display& display = displays[i];
+        const Display& display = *displays[i];
 
         std::cout << "Display " << (i + 1) << ":" << std::endl;
 
@@ -88,11 +88,15 @@ int main() {
 
     // Test getting primary display
     std::cout << "=== Primary Display ===" << std::endl;
-    Display primary = displayManager.GetPrimary();
-    std::cout << "Primary display: " << primary.GetName() << std::endl;
+    std::shared_ptr<Display> primary = displayManager.GetPrimary();
+    if (primary) {
+      std::cout << "Primary display: " << primary->GetName() << std::endl;
 
-    Size size = primary.GetSize();
-    std::cout << "Size: " << (int)size.width << " x " << (int)size.height << std::endl;
+      Size size = primary->GetSize();
+      std::cout << "Size: " << (int)size.width << " x " << (int)size.height << std::endl;
+    } else {
+      std::cout << "No primary display available" << std::endl;
+    }
 
     // Test getting cursor position
     std::cout << std::endl << "=== Cursor Position ===" << std::endl;

examples/window_example/main.cpp

@@ -320,11 +320,11 @@ int main() {
 
   display_manager.AddListener<nativeapi::DisplayAddedEvent>(
       [](const nativeapi::DisplayAddedEvent& event) {
-        std::cout << "Display added: " << event.GetDisplay().GetId() << std::endl;
+        std::cout << "Display added: " << event.GetDisplay()->GetId() << std::endl;
       });
   display_manager.AddListener<nativeapi::DisplayRemovedEvent>(
       [](const nativeapi::DisplayRemovedEvent& event) {
-        std::cout << "Display removed: " << event.GetDisplay().GetId() << std::endl;
+        std::cout << "Display removed: " << event.GetDisplay()->GetId() << std::endl;
       });
 
   auto& app = Application::GetInstance();

specs/object-model.md

@@ -0,0 +1,112 @@
+# 对象模型规范：身份对象与值对象
+
+> 状态：已实施
+> 适用范围：`src/` 全部公共类型，以及 codegen 生成的 C ABI 与各语言绑定
+
+本规范回答一个问题：**库中的一个公共类型，应该以什么方式被创建、持有、
+传递和销毁。**每个公共类型必须归入下面两类之一；新增类型时先决定归属，
+再写代码。
+
+## 1. 分类总览
+
+| | 身份对象 | 值对象 |
+|---|---|---|
+| 代表什么 | 一个唯一的底层资源 | 一段纯数据 |
+| 拷贝 | 禁止（拷贝"身份"没有意义） | 自由拷贝 |
+| 持有方式 | `std::shared_ptr` | 按值 |
+| 标识 | 整数 ID（若被集合管理） | 无 |
+| 状态 | 从底层资源活读，不做快照 | 自身即状态 |
+| 跨 C ABI | handle（见 [handle-ownership.md](../docs/handle-ownership.md)） | 转换为对应的 C struct |
+
+## 2. 身份对象（identity object)
+
+代表一个唯一的底层资源：一个窗口、一个托盘图标、一个物理显示器、
+一次快捷键注册。
+
+### 规则
+
+1. **以 `std::shared_ptr` 管理和传递。**类内 `delete` 拷贝构造、拷贝赋值、
+   移动构造、移动赋值四件套，并在注释中说明"share the shared_ptr instead"。
+2. **被 manager/registry 以集合管理的类型持有一个整数 ID。**
+   - 类型别名在该类型自己的头文件中定义一次：
+     `typedef IdAllocator::IdType XxxId;`
+   - ID 在实例构造时从 `IdAllocator::Allocate<T>()` 分配，之后不变；
+     `GetId()` 返回它。
+   - 类型必须先在 `foundation/id_allocator.h` 的 `IdTypeTag<T>` 注册表中
+     登记 tag（**只可追加，不可改号**）；漏登记是编译错误。
+3. **同一底层资源的重复查询必须返回同一个实例。**manager 负责按底层
+   资源的平台身份做实例缓存与去重；实例存活期间 ID 因而稳定。
+4. **属性活读。**getter 每次从底层资源读取当前状态；持有的实例永远反映
+   现状，不保存快照。底层资源消失后 getter 返回类型默认值。
+5. **生命周期与底层资源解耦但单向感知。**资源消失（如显示器拔出）时
+   实例从 manager 缓存移除，已被外部持有的 `shared_ptr` 仍安全可用，
+   只是读到默认值；同一资源重新出现得到**新实例、新 ID**。
+
+### 成员
+
+`Window`、`TrayIcon`、`Menu`、`MenuItem`、`Shortcut`、`Display`、`Image`。
+
+### 无集合 ID 的身份对象
+
+`Preferences`、`SecureStorage`、`LaunchAtLogin`、`KeyboardMonitor`、
+`MessageDialog` 等实例类：同样禁拷贝、以 handle 跨 ABI，但不进入任何
+manager 集合，因此不定义 `XxxId` 别名、不调用 `IdAllocator::Allocate`。
+它们仍需要 `IdTypeTag` 登记——那只服务于 handle 表的类型校验。
+
+## 3. 值对象（value object）
+
+纯数据，没有底层资源身份。
+
+### 规则
+
+1. 可自由拷贝；需要相等性时按成员值比较。
+2. 不进 handle 表；跨 C ABI 时按值转换为对应的 C struct。
+3. 不持有 ID，不注册 `IdTypeTag`。
+
+### 成员
+
+- 几何与外观：`Point`、`Size`、`Rectangle`、`Color`
+- 输入描述：`KeyboardAccelerator`
+- options 类：`ShortcutOptions`、`WindowOptions` 等
+- 全部 Event 类（见第 5 节）
+
+## 4. 案例：Display 的归属
+
+`Display` 曾是可拷贝值类型（pimpl 深拷贝、平台字符串做 ID），是身份对象
+规则的最佳反例，现按本规范归入身份对象：
+
+- `DisplayId`（整数）在实例创建时分配；人类可读名称保留在 `GetName()`。
+- `DisplayManager` 按**平台身份 key**（macOS 的 `CGDirectDisplayID`、
+  Windows 的设备名等）缓存实例。key 是私有实现细节，不出现在公共 API。
+- 显示器保持连接期间，`GetAll()` / `GetPrimary()` 每次返回同一
+  `shared_ptr`，ID 稳定；断开后实例从缓存移除（`DisplayRemovedEvent`
+  携带最后一份引用），重新连接得到新实例、新 ID。
+- 平台层只实现原生枚举（`EnumerateNativeDisplays()`）；缓存、diff、
+  事件发射是共享代码（`display_manager.cpp`）。
+- `DisplayChangedEvent` 只携带发生变化的 display 本身，不携带 old/new
+  两份"快照"——身份对象属性活读，旧状态快照本就无法成立（规则 4 的
+  直接推论）。
+
+新类型拿不准归属时，对照这个案例：**"两个实例可能指同一个东西吗？"**
+可能——身份对象；不可能——值对象。
+
+## 5. 事件中的对象引用
+
+Event 类本身是值对象（按值构造、跨线程传递、进回调），但它可以引用
+身份对象。允许两种形态：
+
+- 携带 `std::shared_ptr<T>`（如 `DisplayEvent`）：事件让对象多活一程，
+  适合"资源即将消失、监听者还需要读它"的场景（如 removed 事件）。
+- 只携带整数 ID（如 `WindowEvent`）：监听者按需通过 manager 解析，
+  适合对象必然还活着的场景。
+
+事件**不得**按值内嵌身份对象（那要求身份对象可拷贝，与第 2 节矛盾）。
+
+## 6. 新增类型检查单
+
+- [ ] 决定归属：身份对象还是值对象？
+- [ ] 身份对象：删除四件套拷贝/移动；`IdTypeTag` 登记；
+      需要集合管理时定义 `XxxId` 并在构造时分配。
+- [ ] 身份对象：确定谁负责实例去重（哪个 manager、按什么平台 key）。
+- [ ] 值对象：确认无 ID、无 handle、C ABI 有对应 struct 映射。
+- [ ] 事件引用身份对象时，选 `shared_ptr` 或 ID，不按值内嵌。

src/capi/display_c.cpp

@@ -17,36 +17,26 @@
 #include "geometry_c.h"
 #include "../display.h"
 
-native_display_t native_display_create(void) {
-  try {
-    return nativeapi::HandleTable::GetInstance().Insert(
-        std::make_shared<nativeapi::Display>());
-  } catch (...) {
-    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_display_create");
-    return 0;
-  }
-}
-
-native_display_t native_display_create_with_display(void* display) {
+native_display_t native_display_create(void* display) {
   try {
     return nativeapi::HandleTable::GetInstance().Insert(
         std::make_shared<nativeapi::Display>(display));
   } catch (...) {
-    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_display_create_with_display");
+    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_display_create");
     return 0;
   }
 }
 
-char* native_display_get_id(native_display_t display) {
+native_display_id_t native_display_get_id(native_display_t display) {
   auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Display>(display);
   if (!self) {
-    return nullptr;
+    return 0;
   }
   try {
-    return to_c_str(self->GetId());
+    return self->GetId();
   } catch (...) {
     fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_display_get_id");
-    return nullptr;
+    return 0;
   }
 }
 
@@ -216,8 +206,7 @@ bool to_c_display_event(const nativeapi::DisplayEvent& event, native_display_eve
     return false;
   }
   *out = native_display_event_t{};
-  out->display = nativeapi::HandleTable::GetInstance().Insert(
-      std::make_shared<nativeapi::Display>(event.GetDisplay()));
+  out->display = nativeapi::HandleTable::GetInstance().Insert(event.GetDisplay());
   if (const auto* typed = dynamic_cast<const nativeapi::DisplayAddedEvent*>(&event)) {
     out->type = NATIVE_DISPLAY_EVENT_TYPE_ADDED;
     (void)typed;
@@ -230,10 +219,7 @@ bool to_c_display_event(const nativeapi::DisplayEvent& event, native_display_eve
   }
   if (const auto* typed = dynamic_cast<const nativeapi::DisplayChangedEvent*>(&event)) {
     out->type = NATIVE_DISPLAY_EVENT_TYPE_CHANGED;
-    out->data.changed.old_display = nativeapi::HandleTable::GetInstance().Insert(
-        std::make_shared<nativeapi::Display>(typed->GetOldDisplay()));
-    out->data.changed.new_display = nativeapi::HandleTable::GetInstance().Insert(
-        std::make_shared<nativeapi::Display>(typed->GetNewDisplay()));
+    (void)typed;
     return true;
   }
   return false;
@@ -245,11 +231,5 @@ void free_c_display_event(native_display_event_t* value) {
   }
   nativeapi::HandleTable::GetInstance().Release(value->display);
   value->display = 0;
-  if (value->type == NATIVE_DISPLAY_EVENT_TYPE_CHANGED) {
-    nativeapi::HandleTable::GetInstance().Release(value->data.changed.old_display);
-    value->data.changed.old_display = 0;
-    nativeapi::HandleTable::GetInstance().Release(value->data.changed.new_display);
-    value->data.changed.new_display = 0;
-  }
 }
 

src/capi/display_c.h

@@ -19,6 +19,8 @@
 extern "C" {
 #endif
 
+typedef unsigned int native_display_id_t;
+
 typedef enum {
   NATIVE_DISPLAY_ORIENTATION_PORTRAIT = 0,
   NATIVE_DISPLAY_ORIENTATION_LANDSCAPE = 90,
@@ -57,27 +59,16 @@ typedef enum {
 typedef struct {
   native_display_event_type_t type;
   native_display_t display;
-  union {
-    struct {
-      native_display_t old_display;
-      native_display_t new_display;
-    } changed;
-  } data;
 } native_display_event_t;
 
 typedef void (*native_display_event_callback_t)(const native_display_event_t* event, void* user_data);
 
 /// Creates a Display instance; release it with native_display_free().
 FFI_PLUGIN_EXPORT
-native_display_t native_display_create(void);
+native_display_t native_display_create(void* display);
 
-/// Creates a Display instance; release it with native_display_free().
-FFI_PLUGIN_EXPORT
-native_display_t native_display_create_with_display(void* display);
-
-/// Caller owns the returned string; free it with free_c_str().
 FFI_PLUGIN_EXPORT
-char* native_display_get_id(native_display_t display);
+native_display_id_t native_display_get_id(native_display_t display);
 
 /// Caller owns the returned string; free it with free_c_str().
 FFI_PLUGIN_EXPORT

src/capi/display_manager_c.cpp

@@ -31,8 +31,7 @@ native_display_list_t native_display_manager_get_all(void) {
       return list;
     }
     for (size_t i = 0; i < items.size(); ++i) {
-      list.displays[i] = nativeapi::HandleTable::GetInstance().Insert(
-          std::make_shared<nativeapi::Display>(items[i]));
+      list.displays[i] = nativeapi::HandleTable::GetInstance().Insert(items[i]);
     }
     list.count = static_cast<long>(items.size());
     return list;
@@ -45,8 +44,7 @@ native_display_list_t native_display_manager_get_all(void) {
 
 native_display_t native_display_manager_get_primary(void) {
   try {
-    return nativeapi::HandleTable::GetInstance().Insert(
-        std::make_shared<nativeapi::Display>(nativeapi::DisplayManager::GetInstance().GetPrimary()));
+    return nativeapi::HandleTable::GetInstance().Insert(nativeapi::DisplayManager::GetInstance().GetPrimary());
   } catch (...) {
     fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_display_manager_get_primary");
     return 0;