textOutW 函式 (wingdi.h)

發行項
03/04/2024

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

語法

BOOL TextOutW(
  [in] HDC     hdc,
  [in] int     x,
  [in] int     y,
  [in] LPCWSTR 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 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	wingdi.h (包含 Windows.h)
程式庫	Gdi32.lib
Dll	Gdi32.dll