API 參考：Widget 與 Canvas 詞彙
本頁內容與 PDK 內的
docs\NEXUS_TUI_PLUGIN_API_REFERENCE.md相同（依章節分頁，連結已改成站內連結）。
4.1 NxWidgetEvent 與 NxPropVal
ABI 4.0 的 widget 詞彙整批換成「型別／屬性／事件編號＋值容器」：宣告用 .nxlay 檔，狀態用屬性，兩者都不再有逐欄位的結構。編號與值容器在 sdk/nexus_widget_ids.h（由 nx_widget 套件產生，不要手改），nexus 專屬的幾個常數在 sdk/nexus_plugin_api.h。本節說明 Plugin 會碰到的幾個型別；NxPropVal 由套件產生，以整個結構為單位說明；NxWidgetEvent 是手寫結構，逐成員條目接在本節之後。
NxPropVal（屬性值，恆為 24 位元組，x86／x64 相同）
| 欄位 | 說明 |
|---|---|
SizeOfStruct | 呼叫端的 sizeof(NxPropVal)；SetWidgetProp()／GetWidgetProp() 都要先填 |
kind | NX_WKIND_*：NONE（取值結果：未設）、I64（含布林與列舉）、U64、F64、STR（UTF-8，len 為位元組數，不含 NUL）、BLOB、COLOR、NODE、ICON_NAME、RES_NAME |
flags | NX_WPV_F_*：TOKEN（COLOR 是主題權杖而非 RGB）、BORROWED（指標只在本幀有效）、UNKNOWN（值未知，不得當 0） |
u | 依 kind 選用的內容（i64／u64／f64／str.ptr+len／blob.ptr+len+elem_kind／color／node） |
不含 enum 與 #pragma pack；結尾新增欄位只 bump minor，欄位是否存在用 NX_ABI_HAS_FIELD(val->SizeOfStruct, NxPropVal, 欄位名)。
NxWidgetEvent（傳給 on_widget_event，48 位元組，x86／x64 相同）
| 欄位（偏移） | 說明 |
|---|---|
SizeOfStruct（0） | Core 寫入端的 sizeof(NxWidgetEvent) |
kind（4） | NX_WEVT_CHANGED 或 NX_WEVT_ACTIVATED；其他編號保留，Plugin 必須忽略不認得的 |
prop（6） | NX_WEVT_CHANGED 時為變動的 NX_WP_*（目前只有 NX_WP_VALUE），否則 0 |
modifiers（8） | NX_WMOD_* 位元或（Shift／Ctrl／Alt／Win）；Host 不回報時為 0（主控台 Host 的滑鼠事件沒有 Alt） |
token（12） | 保留給對話框／選單結果，目前恆為 0 |
user_data（16） | 該 widget 的 NX_WP_USER_DATA（未設為 0），為排入佇列當下的值 |
val（24） | 新值或位置；kind 為 NX_WKIND_NONE 表示沒有值 |
事件語意（非同步、尾端合併、作廢規則）見 IcPlugin::on_widget_event。
widget 型別與屬性編號：NX_WTYPE_*（LABEL、VALUE、TEXTBOX、CHECKBOX、DROPDOWN、BUTTON、TABLE、SEPARATOR、METER、SPIN、CHOICE、GROUPBOX、CHART、IMAGE、FILEPICK…，編號 0 ~ 44）與屬性 NX_WP_*、blob 記錄頭（NxItemHead、NxRowHead、NxGuideHead／NxGuideRec、NxSeriesHead）都定義在 sdk/nexus_widget_ids.h；3.x 的 NX_WIDGET_* 與 NX_WF_* 旗標已移除，旗標改為同名的 I64 屬性（NX_WP_OPTIONAL、NX_WP_PASSWORD、NX_WP_ENABLED…）。型別名稱 VALUE_LIST／PROGRESS／RADIO 在 4.0 的編號 6／8／10 分別更名為 TABLE／METER／CHOICE，數值不變。Host 不支援的型別（例如尚未實作者）在版面檔中以 ERR_NOT_SUPPORTED 拒絕。
nexus 專屬常數（sdk/nexus_plugin_api.h）
| 常數 | 值 | 說明 |
|---|---|---|
NX_WIDGET_ROOT | 0xFFFF | 面板根的 widget_id（一個 GROUPBOX；面板級屬性設在它上面；CreateWidget() 的 parent_id） |
NX_LAYOUT_F_FILE | 0x1 | LoadLayout() 的 flags：name 是相對於 Plugin DLL 目錄的檔案路徑 |
NX_LAYOUT_MAX_BYTES | 131072 | 一份 .nxlay 的位元組上限（資源、檔案、記憶體三種來源共用） |
NX_WLABEL_MAX_BYTES | 31 | LABEL／AUX 每段上限（不含 NUL） |
NX_WDROPDOWN_ITEM_TEXT_MAX／NX_WTABLE_ROW_TEXT_MAX | 255 | ITEMS 每項文字／ROWS 每列名稱與值的上限（不含 NUL） |
NX_MAX_WIDGETS_PER_PANEL | 256 | 每面板 widget 數上限 |
NX_WPOS_KEYBOARD | 0x80008000 | 鍵盤觸發 NX_WEVT_ACTIVATED 的位置封裝 |
NxWidgetEvent::SizeOfStruct
型別：NxDword
意義：Core 寫入端的 sizeof(NxWidgetEvent)（48 位元組），供 Plugin 在結尾新增欄位後判斷欄位是否存在。
合法值／哨兵：Core 填入，Plugin 只讀；判斷後續欄位是否存在用 NX_ABI_HAS_FIELD(evt->SizeOfStruct, NxWidgetEvent, 欄位名)，不比較 abi_minor。
何時填：每次 Core 呼叫 IcPlugin::on_widget_event 前。
NxWidgetEvent::kind
型別：NxWord
意義：事件種類，NX_WEVT_*。
合法值／哨兵：NX_WEVT_CHANGED（使用者改了值）或 NX_WEVT_ACTIVATED（widget 被觸發）；其他編號保留，Plugin 必須忽略不認得的種類。
何時填：Core 在排入事件佇列時填入。
NxWidgetEvent::prop
型別：NxWord
意義：NX_WEVT_CHANGED 時為變動的屬性編號 NX_WP_*。
合法值／哨兵：目前 NX_WEVT_CHANGED 只會是 NX_WP_VALUE；NX_WEVT_ACTIVATED 一律為 0。
何時填：Core 在排入事件佇列時填入。
NxWidgetEvent::modifiers
型別：NxDword
意義：事件發生當下的修飾鍵。
合法值／哨兵：NX_WMOD_* 的位元或（Shift／Ctrl／Alt／Win）；Host 不回報時為 0（主控台 Host 的滑鼠事件沒有 Alt）。
何時填：Core 在排入事件佇列時填入。
NxWidgetEvent::token
型別：NxDword
意義：保留給對話框、選單結果的關聯值。
合法值／哨兵：目前恆為 0，Plugin 不得依賴其他值。
何時填：Core 在排入事件佇列時填入。
NxWidgetEvent::user_data
型別：NxU64
意義：該 widget 的 NX_WP_USER_DATA，為事件排入佇列當下的值（之後 Plugin 再改，這一筆不變）。
合法值／哨兵：未設為 0。
何時填：Core 在排入事件佇列時填入。
NxWidgetEvent::val
型別：NxPropVal
意義：新值或位置。NX_WEVT_CHANGED 為新值；NX_WEVT_ACTIVATED 一律是 NX_WKIND_U64 的位置封裝 (v << 16) | h。
合法值／哨兵：kind 為 NX_WKIND_NONE 表示沒有值；字串值（u.str.ptr）指向 Core 的緩衝，只在 callback 期間有效，要保留請自行複製。
何時填：Core 在排入事件佇列時填入。
4.2 NxCanvasCell
NxCanvasCell::ch
型別：char
意義：該格的字元。
合法值／哨兵：任意字元；'\0' 視為空白。
何時填：呼叫 NxHostApi::DrawRegion 前，依 w * h（逐列排列）逐格填入。
NxCanvasCell::fg
型別：NxByte
意義：前景語意色。
合法值／哨兵：NX_COLOR_* 值域內的合法值。
何時填：同 NxCanvasCell::ch，呼叫 NxHostApi::DrawRegion 前填入。
NxCanvasCell::bg
型別：NxByte
意義：背景語意色。
合法值／哨兵：NX_COLOR_* 值域內的合法值。
何時填：同 NxCanvasCell::ch，呼叫 NxHostApi::DrawRegion 前填入。
NxCanvasCell::reserved
型別：reserved0：NxByte（結構結尾）。
意義：保留給日後在結構結尾追加欄位使用。
合法值／哨兵：一律填 0。
何時填：建構本結構時；Core 不讀取這個欄位的內容。