GrayStringA 函式（winuser.h）

發行項
11/20/2024

GrayString 函式會在指定的位置繪製灰色文字。函式會藉由將文字複製到記憶體位圖、呈現點陣圖灰色，然後將點陣圖複製到畫面來繪製文字。不論選取的筆刷和背景為何，函式都會讓文字呈現灰色。 GrayString 會使用目前為指定裝置內容選取的字型。

如果lpOutputFuncparameter NULL，GDI 會使用 TextOut 函式，而且假設lpDataparameter 是要輸出之字元字元串的指標。如果 TextOut 無法處理要輸出的字元（例如，字串會儲存為位圖），應用程式必須提供自己的輸出函式。

語法

BOOL GrayStringA(
  [in] HDC            hDC,
  [in] HBRUSH         hBrush,
  [in] GRAYSTRINGPROC lpOutputFunc,
  [in] LPARAM         lpData,
  [in] int            nCount,
  [in] int            X,
  [in] int            Y,
  [in] int            nWidth,
  [in] int            nHeight
);

參數

[in] hDC

裝置內容的句柄。

[in] hBrush

要用於呈現灰色之筆刷的句柄。如果此參數 NULL，則文字會以用來繪製視窗文字的相同筆刷呈現灰色。

[in] lpOutputFunc

應用程式定義函式的指標，將繪製字串，或者，如果 TextOut 用來繪製字串，則它是 NULL 指標。如需詳細資訊，請參閱 OutputProc 回呼函式。

[in] lpData

要傳遞至輸出函式之數據的指標。如果 lpOutputFunc 參數 NULL，lpData 必須是要輸出之字元串的指標。

[in] nCount

要輸出的字元數。如果 nCount 參數為零，GrayString 計算字串長度（假設 lpData 是字符串的指標）。如果 nCount 為 1，且 lpOutputFunc 所指向的函式 會傳回 FALSE，則會顯示影像，但不會呈現灰色。

[in] X

包含字串之矩形起始位置的裝置 x 座標。

[in] Y

包含字串之矩形起始位置的裝置 Y 座標。

[in] nWidth

以裝置單位表示的矩形寬度，以括住字串。如果此參數為零，GrayString 計算區域的寬度，假設 lpData 是字元串的指標。

[in] nHeight

以裝置單位表示的矩形高度，以括住字串。如果此參數為零，GrayString 計算區域的高度，假設 lpData 是字串的指標。

傳回值

如果繪製字串，則傳回值為非零值。

如果 TextOut 函式或應用程式定義的輸出函式傳回零，或記憶體不足而無法建立記憶體位圖呈現灰色，則傳回值為零。

言論

若未呼叫 GrayString，應用程式可以在支援純灰色色彩的裝置上繪製灰色字串。系統色彩COLOR_GRAYTEXT是用來繪製停用文字的純灰色系統色彩。應用程式可以呼叫 GetSysColor 函式，以擷取COLOR_GRAYTEXT的色彩值。如果色彩不是零（黑色），應用程式可以呼叫 SetTextColor 函式，將文字色彩設定為色彩值，然後直接繪製字元串。如果擷取的色彩為黑色，應用程式必須呼叫 GrayString 為文字灰色。

注意

winuser.h 標頭會將 GrayString 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winuser.h （包括 Windows.h）
連結庫	User32.lib
DLL	User32.dll