Win32 組合語言教學：用戶區文字繪製（DrawText / BeginPaint / EndPaint / GetClientRect）

教學目標

示範在 WM_PAINT 中正確繪製文字：取得裝置環境（BeginPaint）、查詢用戶區大小（GetClientRect）、以 DrawText 置中單行顯示、釋放裝置環境（EndPaint）。對比低層 TextOut，DrawText 內建換行、置中、裁剪功能，更適合動態版面。

核心流程與關鍵結構

PAINTSTRUCT 與 RECT

LOCAL hdc:HDC
LOCAL ps:PAINTSTRUCT
LOCAL rect:RECT

; RECT 結構 (Windows.inc 定義)
RECT STRUCT
  left   LONG ?
  top    LONG ?
  right  LONG ?
  bottom LONG ?
RECT ENDS

GetClientRect(hWnd, &rect) 回傳用戶區座標：left=top=0，right=寬度，bottom=高度。

WM_PAINT 處理範例

.ELSEIF uMsg==WM_PAINT
  INVOKE BeginPaint, hWnd, ADDR ps
  MOV hdc, EAX
  INVOKE GetClientRect, hWnd, ADDR rect
  INVOKE DrawText, hdc, ADDR OurText, -1, ADDR rect, \
       DT_SINGLELINE OR DT_CENTER OR DT_VCENTER
  INVOKE EndPaint, hWnd, ADDR ps

DrawText 參數完整解析

DrawText PROTO hdc:HDC, lpString:DWORD, nCount:DWORD, lpRect:DWORD, uFormat:DWORD

常用 uFormat 旗標

• DT_SINGLELINE：單行模式，忽略換行字元，垂直置中需配合 DT_VCENTER
• DT_CENTER：水平置中
• DT_VCENTER：垂直置中 (僅單行有效)
• DT_WORDBREAK：單字換行
• DT_CALCRECT：不實際繪製，僅計算所需矩形大小 (輸出於 lpRect)
• DT_NOCLIP：不裁剪，略過邊界檢查略微加速
• DT_EXPANDTABS：展開 Tab 字元
• DT_RIGHT：靠右對齊

BeginPaint / EndPaint 必備規則

1. 成對呼叫：每個 WM_PAINT 必須且只能呼叫一次 BeginPaint / EndPaint
2. 自動驗證無效區：BeginPaint 內部會呼叫 ValidateRect，清除無效區旗標。若不處理 WM_PAINT 也不呼叫 DefWindowProc，會陷入無限 WM_PAINT 風暴。
3. 剪輯區自動設定：BeginPaint 依 PAINTSTRUCT.rcPaint 設定 DC 剪輯區，繪圖指令自動限制於需更新區域，提升效能。
4. 不可跨訊息持有 HDC：EndPaint 釋放 DC，下一個訊息必須重新 BeginPaint 或 GetDC。

DrawText vs TextOut

非 WM_PAINT 繪圖替代方案

• 方案 A：GetDC → 繪圖 → ReleaseDC (即時回饋，不持久)
• 方案 B：InvalidateRect(hWnd, NULL, TRUE) → UpdateWindow(hWnd) 強制同步發送 WM_PAINT (持久化，建議做法)

常見錯誤

• ❌ 忘記 EndPaint → DC 洩漏、後續 BeginPaint 失敗
• ❌ DrawText 的 lpRect 傳遞錯誤位址 → 存取違規
• ❌ nCount 傳正數但字串含 0 → 截斷顯示
• ❌ 用 DT_VCENTER 於多行文字 → 垂直置中失效