GrayStringA 函式 (winuser.h)

發行項
03/04/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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll