TextOutA 函式 (wingdi.h)

發行項
03/13/2024

TextOut 函式會使用目前選取的字型、背景色彩和文字色彩，在指定的位置寫入字元字串。

語法

BOOL TextOutA(
  [in] HDC    hdc,
  [in] int    x,
  [in] int    y,
  [in] LPCSTR lpString,
  [in] int    c
);

參數

[in] hdc

裝置內容的句柄。

[in] x

系統用來對齊字串之參考點的 x 座標，以邏輯座標表示。

[in] y

系統用來對齊字串之參考點的 Y 座標，以邏輯座標表示。

[in] lpString

要繪製之字串的指標。字串不需要以零結束，因為 cchString 會指定字串的長度。

[in] c

以字元為單位的 lpString 所指向的字串長度。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。

備註

參考點的解譯取決於目前的文字對齊模式。應用程式可以藉由呼叫 GetTextAlign 函式來擷取此模式;應用程式可以藉由呼叫 SetTextAlign 函式來改變此模式。您可以使用下列值進行文字對齊。只有一個旗標可以從影響水準和垂直對齊的旗標中選擇。此外，只能選擇改變目前位置的兩個旗標之一。

詞彙	描述
TA_BASELINE	參考點會位於文字的底線上。
TA_BOTTOM	參考點會位於周框的下邊緣。
TA_TOP	參考點會位於周框的上邊緣。
TA_CENTER	參考點會水平對齊周框的中心。
TA_LEFT	參考點會位於周框的左邊緣。
TA_RIGHT	參考點會位於周框的右邊緣。
TA_NOUPDATECP	每次文字輸出呼叫之後，目前的位置都不會更新。參考點會傳遞至文字輸出函式。
TA_RTLREADING	Windows 的中東語言版本：文字會以從右至左閱讀順序配置，而不是預設的由左至右順序。只有在選取到裝置內容的字型為希伯來文或阿拉伯文時，才會適用。
TA_UPDATECP	每個文字輸出呼叫之後都會更新目前的位置。目前的位置會當做參考點使用。

根據預設，此函式不會使用或更新目前的位置。不過，應用程式可以呼叫 SetTextAlign 函式，並將 fMode 參數設定為 TA_UPDATECP，以允許系統在每次應用程式呼叫指定裝置內容的 TextOut 時，使用並更新目前的位置。設定此旗標時，系統會在後續的 TextOut 呼叫上忽略 nXStart 和 nYStart 參數。

當 TextOut 函式放在路徑括弧內時，系統會產生 TrueType 文字的路徑，其中包含每個字元及其字元方塊。產生的區域是字元方塊減去文字，而不是文字本身。您可以在將 TextOut 函式放在路徑括弧中之前，先將背景模式設定為透明，以取得 TrueType 文字外框所括的區域。以下是示範此程式的範例程序代碼。


// Obtain the window's client rectangle 
GetClientRect(hwnd, &r);

// THE FIX: by setting the background mode 
// to transparent, the region is the text itself 
// SetBkMode(hdc, TRANSPARENT); 

// Bracket begin a path 
BeginPath(hdc);

// Send some text out into the world 
TCHAR text[ ] = "Defenestration can be hazardous";
TextOut(hdc,r.left,r.top,text, ARRAYSIZE(text));

// Bracket end a path 
EndPath(hdc);

// Derive a region from that path 
SelectClipPath(hdc, RGN_AND);

// This generates the same result as SelectClipPath() 
// SelectClipRgn(hdc, PathToRegion(hdc)); 

// Fill the region with grayness 
FillRect(hdc, &r, GetStockObject(GRAY_BRUSH));

範例

如需範例，請參閱列舉已安裝的字型。

注意

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	wingdi.h (包含 Windows.h)
程式庫	Gdi32.lib
Dll	Gdi32.dll