ScriptTextOut 函式 (usp10.h)

發行項
08/26/2023

顯示指定之腳本圖形和放置資訊的文字。

語法

HRESULT ScriptTextOut(
  [in]           const HDC             hdc,
  [in, out]      SCRIPT_CACHE          *psc,
  [in]           int                   x,
  [in]           int                   y,
  [in]           UINT                  fuOptions,
  [in, optional] const RECT            *lprc,
  [in]           const SCRIPT_ANALYSIS *psa,
  [in]           const WCHAR           *pwcReserved,
  [in]           int                   iReserved,
  [in]           const WORD            *pwGlyphs,
  [in]           int                   cGlyphs,
  [in]           const int             *piAdvance,
  [in, optional] const int             *piJustify,
  [in]           const GOFFSET         *pGoffset
);

參數

[in] hdc

裝置內容的控制碼。如需詳細資訊，請參閱快取。請注意，不同于某些其他相關的 Uniscribe 函式，此函式會將控制碼定義為必要。

[in, out] psc

識別腳本快取之SCRIPT_CACHE 結構的指標。

[in] x

第一個圖像之 x 座標的值。

[in] y

第一個圖像的 Y 座標值。

[in] fuOptions

相當於ExtTextOut之 fuOptions參數的選項。這個參數可以設定為 ETO_CLIPPED 或 ETO_OPAQUE、兩個值或兩個值都不能設定為。

[in, optional] lprc

RECT結構的指標，其中包含用來裁剪顯示器的矩形。應用程式可以將此參數設定為 Null。

[in] psa

從先前呼叫ScriptItemize取得之SCRIPT_ANALYSIS結構的指標。

[in] pwcReserved

保留;必須設定為 Null。

[in] iReserved

保留;必須是 0。

[in] pwGlyphs

從先前呼叫 ScriptShape取得之字元陣列的指標。

[in] cGlyphs

由 pwGlyphs指示之陣列中的字元計數。字元的最大數目為 65，536。

[in] piAdvance

從先前呼叫 ScriptPlace取得之進階寬度陣列的指標。

[in, optional] piJustify

對齊進階寬度陣列的指標， (儲存格寬度) 。應用程式可以將此參數設定為 Null。

[in] pGoffset

GOFFSET結構的指標，其中包含合併圖像的 x 和 y 位移。

傳回值

若成功，即傳回 0。如果函式不成功，函式會傳回非零 HRESULT 值。應用程式可以使用 SUCCEEDED 和 FAILED 宏來測試傳回值。

備註

此函式會針對文字顯示呼叫作業系統 ExtTextOut 函式。如需詳細資訊，請參閱使用 Uniscribe 顯示文字。

除非fLogicalOrder成員設定在SCRIPT_ANALYSIS結構中，否則所有陣列都會以顯示順序顯示。

對於轉譯為由右至左並依邏輯順序產生的任何執行，強制執行 SCRIPT_ANALYSIS 的 fLogicalOrder 成員，應用程式必須呼叫 SetTextAlign (hdc，TA_RIGHT) 並提供右側座標，再呼叫 ScriptTextOut。

piJustify所指示的陣列會為每個字元提供儲存格寬度。當圖像的寬度與不合理的寬度不同時， piAdvance所指定的寬度會在其尾端邊緣的字元儲存格中新增或移除空格。圖像一律會與其儲存格的前置邊緣對齊。此規則會以視覺順序套用。

擴充圖像資料格時，額外空間通常是由空白字元的加法所組成。不過，若為阿拉伯文腳本，則額外空間是由一或多個 kashida 字元所組成，除非額外空間不足以使用字型中最短的 kashida 字元。呼叫 ScriptGetFontProperties即可取得最短 kashida 的寬度。

只有在ScriptTextOut必須對齊字串時，應用程式才應該傳遞piJustify的值。一般而言，應用程式應該傳遞 Null。

應用程式不應該使用 ScriptTextOut 來寫入中繼檔，除非會播放中繼檔，而不需要任何字型替代，例如，立即在相同的系統上進行可調整的頁面預覽。 ScriptTextOut 會記錄中繼檔中的字元數位。由於字元數位會從一個字型到另一個字型有很大的差異，所以當替換不同的字型時，檔案不太可能正確播放。例如，當中繼檔以不同的比例播放時，中繼檔中所記錄的 CreateFont 要求可以解析為點陣圖，而不是 TrueType 字型。同樣地，如果在不同的電腦上播放中繼檔，則可能不會安裝要求的字型。若要以與字型無關的方式以中繼檔撰寫複雜的腳本，應用程式應該使用 ExtTextOut 直接寫入邏輯字元，以便在播放文字之前不會發生字元產生和放置。

重要從 Windows 8 開始：若要維持在 Windows 7 上執行的能力，使用 Uniscribe 的模組必須指定 Usp10.lib，才能在其程式庫清單中指定 gdi32.lib。

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	usp10.h
程式庫	Usp10.lib
Dll	Usp10.dll
可轉散發套件	Windows Me/98/95 上的 Internet Explorer 5 或更新版本