MFC 樹狀控制項 (CTreeCtrl) 設定狀態圖示：CImageList 與 TVSIL_STATE 完整指南

樹狀控制項的狀態圖示（State Image）顯示在項目圖示左側，常用於核取方塊、選項按鈕、自訂狀態標記。本文說明如何建立包含多個狀態圖示的影像清單、關聯至樹狀控制項、並在插入/更新項目時指定狀態索引（需使用 `INDEXTOSTATEIMAGEMASK` 宏）。

四步驟完成

1. 準備位圖資源

• 建立單一 BMP，橫向排列所有狀態圖示（如 13x13 像素每個）
• 匯入資源，設定 ID 為 `IDB_STATE`
• 背景色設為不會出現在圖示中的顏色（如純白 `RGB(255,255,255)`），做為透明色

2. 宣告影像清單成員

class CTreeCtrlX : public CTreeCtrl {
public:
    CImageList m_imgState;  // 狀態圖示清單
    // ...
};

3. 初始化並關聯

在 `OnInitDialog` 或 `OnInitialUpdate` 中：

// 建立影像清單：資源 ID、單張寬度、成長步長、透明色
m_imgState.Create(IDB_STATE, 13, 1, RGB(255,255,255));

// 關聯至樹狀控制項，TVSIL_STATE 表示狀態圖示清單
SetImageList(&m_imgState, TVSIL_STATE);

4. 為項目指定狀態圖示

狀態圖示索引從 1 開始（0 表示無狀態圖示），必須用 `INDEXTOSTATEIMAGEMASK(n)` 宏轉換為狀態遮罩值。

// 方法一：插入時指定 (TV_INSERTSTRUCT)
TV_INSERTSTRUCT tv = {0};
tv.hParent = TVI_ROOT;
tv.hInsertAfter = TVI_LAST;
tv.item.mask = TVIF_TEXT | TVIF_STATE;
tv.item.stateMask = TVIS_STATEIMAGEMASK;
tv.item.state = INDEXTOSTATEIMAGEMASK(1);  // 使用第 1 個狀態圖示
tv.item.pszText = _T("項目文字");
HTREEITEM hItem = InsertItem(&tv);

// 方法二：事後設定
SetItemState(hItem, INDEXTOSTATEIMAGEMASK(2), TVIS_STATEIMAGEMASK); // 切換為第 2 個

關鍵點總結

• `Create` 參數：`cx` 為單張寬度，高度自動取自位圖高度
• `TVSIL_STATE` 專門用於狀態圖示；一般項目圖示用 `TVSIL_NORMAL`
• 狀態圖示索引 1-based，`INDEXTOSTATEIMAGEMASK(0)` 會清除狀態圖示
• 影像清單物件 `m_imgState` 需隨控制項生命週期存在，勿過早銷毀
• 若需動態改變狀態（如核取/取消），在 `OnLButtonDown` 擊測 `TVHT_ONITEMSTATEICON` 後呼叫 `SetItemState` 切換索引

常見應用場景

• 核取方塊：索引 1=未勾選、2=勾選、3=不確定
• 資料夾狀態：展開/折疊/載入中
• 自訂標記：優先級、標旗、同步狀態等