CButtonST 類完整 API 參考手冊：從靜態/動態建立到圖示/位圖/顏色/對齊/選單/聲音全功能解析

本文整理 CButtonST (v3.6+) 完整公開 API 介面與參數說明，作為開發時的速查手冊。涵蓋：**靜態/動態建立、圖示/位圖設定 (多載)、扁平風格、對齊模式、按下樣式、核取狀態、顏色體系、偏移色彩** 等核心功能。

工程整合準備

// 專案加入檔案
BtnST.h, BtnST.cpp
// v3.5+ 選單支援
#define BTNST_USE_BCMENU
#include "BCMenu.h"
BCMenu.h, BCMenu.cpp
// v3.6+ 聲音支援
#define BTNST_USE_SOUND

建立按鈕實例

靜態建立 (對話框資源中已有按鈕)

// 成員變數
CButtonST m_btnOk;

// OnInitDialog 或 DoDataExchange
m_btnOk.SubclassDlgItem(IDOK, this); // 或 DDX_Control(pDX, IDOK, m_btnOk);

動態建立 (程式碼建立)

CButtonST* m_pBtnOk = new CButtonST;
m_pBtnOk->Create(_T("確定"), WS_CHILD|WS_VISIBLE|WS_GROUP|WS_TABSTOP, CRect(10,10,100,40), this, IDOK);
m_pBtnOk->SetFont(GetFont());
// 銷毀時必須 delete m_pBtnOk 避免洩漏

核心 API 詳細參考

圖示設定 SetIcon (三種多載)

// 1. 使用資源 ID，支援指定尺寸 (多尺寸圖示資源)
DWORD SetIcon(int nIconIn, int nCxDesiredIn, int nCyDesiredIn, 
              int nIconOut = NULL, int nCxDesiredOut = 0, int nCyDesiredOut = 0);

// 2. 使用資源 ID，自動尺寸
DWORD SetIcon(int nIconIn, int nIconOut = NULL);
// nIconOut 特殊值：BTNST_AUTO_GRAY (自動生成灰階), BTNST_AUTO_DARKER (暗化 25%)

// 3. 使用圖示控制代碼
DWORD SetIcon(HICON hIconIn, HICON hIconOut = NULL);

返回值： BTNST_OK 成功, BTNST_INVALIDRESOURCE 資源載入失敗。

位圖設定 SetBitmaps (兩種多載)

// 1. 資源 ID + 透明色
DWORD SetBitmaps(int nBmpIn, COLORREF crTransIn, int nBmpOut = NULL, COLORREF crTransOut = 0);

// 2. 位圖控制代碼 + 透明色
DWORD SetBitmaps(HBITMAP hBmpIn, COLORREF crTransIn, HBITMAP hBmpOut = NULL, COLORREF crTransOut = 0);

返回值新增： BTNST_FAILEDMASK 遮罩建立失敗。

風格與對齊

DWORD SetFlat(BOOL bFlat = TRUE, BOOL bRepaint = TRUE); // 扁平/立體
DWORD SetAlign(BYTE byAlign, BOOL bRepaint = TRUE); // 圖示/文字相對位置
// byAlign: ST_ALIGN_HORIZ(預設,圖左文右), ST_ALIGN_VERT(圖上文下), ST_ALIGN_HORIZ_RIGHT(圖右文左), ST_ALIGN_OVERLAP(重疊)
DWORD SetTextAlign(BYTE byTextAlign, BOOL bRepaint = TRUE); // 文字區內部對齊
// byTextAlign: ST_TEXTALIGN_CENTER_VCENTER(預設), ST_TEXTALIGN_LEFT_VCENTER, ST_TEXTALIGN_RIGHT_VCENTER
DWORD SetPressedStyle(BYTE byStyle, BOOL bRepaint = TRUE); // 按下動畫
// byStyle: BTNST_PRESSED_LEFTRIGHT(預設,左移右移), BTNST_PRESSED_TOPBOTTOM(上移下移)

核取方塊模式

DWORD SetCheck(int nCheck, BOOL bRepaint = TRUE); // 1=勾選, 0=取消 (按鈕需為 BS_CHECKBOX/BS_AUTOCHECKBOX)
int GetCheck(); // 返回 1/0

完整色彩控制體系

DWORD SetDefaultColors(BOOL bRepaint = TRUE); // 重置為系統預設色

// 設定特定狀態顏色
DWORD SetColor(BYTE byColorIndex, COLORREF crColor, BOOL bRepaint = TRUE);
// byColorIndex 取值：
// BTNST_COLOR_BK_IN    滑鼠進入背景色
// BTNST_COLOR_FG_IN    滑鼠進入前景色 (文字)
// BTNST_COLOR_BK_OUT   一般背景色
// BTNST_COLOR_FG_OUT   一般前景色
// BTNST_COLOR_BK_FOCUS 焦點/按下背景色
// BTNST_COLOR_FG_FOCUS 焦點/按下前景色

DWORD GetColor(BYTE byColorIndex, COLORREF* pCrColor); // 取得顏色

// 相對偏移調整色彩 (HLS 空間)
DWORD OffsetColor(BYTE byColorIndex, short shOffset, BOOL bRepaint = TRUE);
// shOffset: -255 ~ +255 (正值亮化/飽和, 負值暗化/灰化)

返回值代碼速查

授權重申

作者 Davide Calabro：非商業免費，商業用途 $5 授權。請尊重開源協議。