# UI 視圖與介面呈現模組 (UI View) 深度分析

在 `CB_IMGPSScanImp.pas.bk` 中，「UI 與介面呈現模組」主要負責與使用者的視覺互動，這是作為 ActiveX 控制項的核心表現形式。它管理了表單的佈局、多國語言切換、快捷鍵操作以及各種滑鼠拖拉 (Drag and Drop) 與捲動行為。

以下是針對 UI View 模組的深度組成與分類分析：

---

## 1. 核心版面與容器管理 (Layout & Container Management)

**職責**：定義整個 ActiveX 控制項的視覺區塊，並透過階層式的 Panel 進行排版管理，確保在不同解析度下能正確顯示。
**核心實作特性**：
*   **ActiveX 窗體繼承**：`TCB_IMGPSScanX` 繼承自 `TActiveForm`，並實作 `ICB_IMGPSScanX` 介面，是所有 UI 元件的根容器。
*   **Panel 排版系統**：使用大量的 `TPanel` (如 `Panel1`, `Panel2`, `Panel9` 等) 與 `TSplitter` (如 `Splitter1`, `Splitter2`) 來分割畫面：
    *   **頂部/底部工具列**：放置各種操作按鈕 (`TBitBtn`, `TButton`)。
    *   **左側樹狀區**：放置文件結構清單 (`TreeView1`)。
    *   **右側工作區**：通常包含影像預覽或細節設定面板 (`Panel9`, `ScrollBox1`)。
*   **動態模式切換**：透過 `DisplayMode` 與 `GoViewMode` 根據不同的視圖模式 (VMode) 動態調整右側影像預覽區塊的排列方式 (如 1x1, 1x2, 2x2 等)，並控制各 `imgp` (Panel) 的顯示與隱藏。

## 2. 影像預覽與互動視窗 (Image Viewer & Interaction)

**職責**：提供高效能的影像顯示功能，支援大圖縮放、拖曳平移、局部放大以及多頁縮圖並排顯示。
**核心實作特性**：
*   **Envision 影像元件**：深度依賴 `EnImgScr` (TImageScrollBox) 來處理大型 TIFF/JPEG 影像的渲染與捲動。
*   **多圖預覽管理**：
    *   主影像 (`ISB1`) 與縮圖陣列 (`ISB2` ~ `ISB8`)。
    *   背景生成黑白影像 (`ISB_BW`) 供內部條碼辨識或影像處理使用，而不影響前端彩色顯示。
    *   動態建立/釋放：`CreatePreViewISB` 與 `FreePreViewISB` 負責根據案件頁數動態產生縮圖物件。
*   **滑鼠行為模式 (Mouse Mode)**：
    *   透過 `ViewMouseMode` 函式切換 `TImageScrollBox` 的狀態，例如：放大鏡 (`mmAmplifier`)、框選縮放 (`mmZoom`)、手形拖曳 (`mmDrag`)、旋轉 (`mmR90`, `mmR180`, `mmR270`) 或刪除 (`mmDelete`)。
    *   對應工具列按鈕 (`FC0` ~ `FC6`) 的點擊事件 (`FC0Click` ~ `FC6Click`) 來切換這些游標模式。
*   **滑鼠與滾輪事件**：
    *   處理自定義的滾輪捲動 (`WMMOUSEWHEEL`)，同步捲動 `ScrollBox1` 或放大縮小影像 (`ZoomPercent`)。
    *   處理影像上的點擊 (`ISBClick`) 與拖拉排序 (`ISBDragDrop`, `ISBDragOver`)。
    *   在影像上繪製選取框 (`PaintShape`, `FreeShapeobj`)。

## 3. 案件與文件樹狀檢視 (Case & Document TreeView)

**職責**：以階層式樹狀結構呈現當前掃描或下載的「案件 -> 文件 -> 頁面」，並提供豐富的右鍵選單功能以管理這些節點。
**核心實作特性**：
*   **TTreeView 結構維護**：
    *   `NewTreeNode`：頂層節點（如：新件、異動件）。
    *   `MyTreeNode1`：案件層級 (CaseID)。
    *   `MyTreeNode2`：文件層級 (DocNo/DocDir)。
    *   `MyTreeNode3`：表單/頁面層級 (FormID)。
*   **視覺狀態回饋**：依據節點的狀態改變圖示 (`ImageIndex`)，例如：未配號、檢核失敗、完成檢核、或標記為被引用 (`GetUseCase`) 的文件。
*   **節點資料綁定與更新**：
    *   利用 `DrawDocItem2` 根據實體的 `.dat` 設定檔重新長出整棵樹。
    *   利用 `NewTreeNodeRefresh`, `MyTreeNode1Refresh` 等更新節點後方的筆數或頁數統計。
*   **右鍵選單與節點操作**：
    *   根據選中的節點層級，動態顯示/隱藏 `PopupMenu1` 的選項 (`PopupMenu1Popup`)。
    *   支援在樹狀圖上的拖拉移動 (`TreeView1DragDrop`) 以改變影像歸屬。

## 4. 多國語言與本地化引擎 (I18N & Localization)

**職責**：將 UI 介面上的所有寫死字串抽離，透過外部設定檔實現多國語言的動態切換。
**核心實作特性**：
*   **語言檔載入**：在初始化時透過 HTTP/FTP 下載最新的語言包 (`Language.Lng` 至 `LngPath`)。
*   **動態介面翻譯**：`InitialLanguage` 函式。
    *   利用 `TMemIniFile` 讀取語言檔。
    *   遍歷表單上的所有元件 (`Components`)，判斷其類型 (`TButton`, `TBitBtn`, `TMenuItem`, `TLabel`, `TListView`, `TRadioGroup` 等)。
    *   將元件的 `Name` 作為 Key 去 Ini 檔中尋找對應的翻譯字串，並替換其 `Caption` 或 `Hint`。

## 5. 系統狀態與進度回饋 (Status & Progress Feedback)

**職責**：在進行耗時的網路傳輸、影像處理或資料庫比對時，鎖定 UI 並給予使用者明確的等待提示，避免重複操作。
**核心實作特性**：
*   **全域 UI 鎖定 (`DataLoading`)**：
    *   當執行耗時任務時，將滑鼠游標改為漏斗 (`crHourGlass`)。
    *   停用主要的控制面板 (`Panel1.Enabled := False`, `Panel2.Enabled := False`)。
    *   顯示中央的進度提示面板 (`Panel22` 或 `Panel8`)。
*   **動態文字更新**：透過 `Timer2` 定期在進度提示文字 (`ShowText`) 後方加上點號 (`...`)，營造系統正在運作的視覺效果。
*   **狀態列 (`StatusBar1`)**：顯示當前版本號 (`GetCurrentVersionNo`)、登入使用者名稱、引用狀態，以及浮動授權 (License) 的剩餘額度。

---

## 💡 未來重構與微服務化建議

若要將此「UI View 模組」進行現代化重構 (例如轉向 Web 介面或更清晰的架構)，建議考量以下方向：

1.  **MVC / MVVM 架構解耦**：目前的程式碼將按鈕點擊事件 (Controller)、資料讀取 (Model) 與畫面更新 (View) 混雜在同一個 Pas 檔中。應將邏輯抽離，讓 UI 只負責「顯示資料」與「轉發命令」。
2.  **TreeView 虛擬化 (Virtualization)**：若案件內包含極多頁面，頻繁的 `DrawDocItem2` 清空並重建樹狀節點會導致效能低落。建議改用 Virtual TreeView 或資料綁定 (Data Binding) 的方式，只渲染可見節點。
3.  **分離多國語言引擎**：將 `InitialLanguage` 的邏輯獨立為一個全局的 `Translator` 服務，避免每個 Form 或 Frame 都需要自己實作載入邏輯。
4.  **Web 相容性評估**：
    *   由於深切依賴 `TImageScrollBox` 的 Windows GDI 渲染與特定的滑鼠狀態 (`TMouseMode`)，若要轉為 Web (HTML5/Canvas)，需尋找或實作對應的 Web Image Viewer 套件。
    *   ActiveX 特有的 COM 介面 (`TActiveForm`, `safecall`) 將被淘汰，改以 WebSocket 或 REST API 提供狀態更新，前端由 React/Vue 等框架接手渲染。