ScriptTextOut

The ScriptTextOut function takes the output of both ScriptShape and ScriptPlace calls and calls the operating system ExtTextOut function appropriately.

All arrays are in display order unless the fLogicalOrder member is set in the SCRIPT_ANALYSIS structure pointed to by psa.

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

Parameters

hdc

[in] Handle to a device context.

psc

[in/out] Pointer to a SCRIPT_CACHE structure.

x

[in] Value of the x-coordinate of the first glyph.

y

[in] Value of the y-coordinate of the first glyph.

fuOptions

[in] Options equivalent to the fuOptions parameter of ExtTextOut. It may contain ETO_CLIPPED or ETO_OPAQUE (or neither of them, or both of them).

lprc

[in] Pointer to a rectangle used to clip the display. This parameter is optional and can be NULL.

psa

[in] Pointer to a SCRIPT_ANALYSIS structure obtained from a previous call to ScriptItemize.

pwcReserved

Reserved, must be NULL.

iReserved

Reserved, must be zero.

pwGlyphs

[in] Pointer to an array of glyphs obtained from a previous call to ScriptShape.

cGlyphs

[in] Count of the glyphs in the pwGlyphs array.

piAdvance

[in] Pointer to an array of advance widths obtained from a previous call to ScriptPlace.

piJustify

[in] Pointer to an array of justified advance widths. This parameter is optional and can be NULL.

pGoffset

[in] Pointer to a GOFFSET structure containing the x and y offsets for the combining glyph.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. And if any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

For any run that is rendered right-to-left (fRTL) and was generated in logical order by forcing the fLogicalOrder flag, call SetTextAlign(hdc, TA_RIGHT) and give the right-side coordinate before calling ScriptTextOut.

The piJustify array provides requested cell widths for each glyph. When the piJustify width of a glyph differs from the unjustified width (in piAdvance), space is added to or removed from the glyph cell at its trailing edge. The glyph is always aligned with the leading edge of its cell. (This rule applies even in visual order.)

When a glyph cell is extended the extra space is usually made up by the addition of white space, however for Arabic scripts, the extra space is made up by one or more kashida glyphs, unless the extra space is insufficient for the shortest kashida glyph in the font. (The width of the shortest kashida is available by calling ScriptGetFontProperties.)

The piJustify parameter should be passed only if the string must be justified again. Normally, pass NULL to this parameter.

The pwcinChars and cChars parameters are required only if output is to a metafile DC. If hdc is not a metafile, these parameters may be passed as NULL and zero.

Do not use ScriptTextOut to write to a metafile unless you are sure that the metafile will be played back without any font substitution. ScriptTextOut records glyph numbers in the metafile, and since glyph numbers vary considerably from one font to another, such a metafile is unlikely to play back correctly when different fonts are substituted. For example, when a metafile is played back at a different scale, a CreateFont request that is recorded in the metafile may resolve to a bitmap instead of a TrueType font. Likewise, if the metafile is played back on a different machine, the requested fonts may not be installed. To write complex scripts in a metafile in a font-independent manner, use ExtTextOut to write the logical characters directly, so that glyph generation and placement do not occur until the text is played back.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Usp10.h.
  Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ExtTextOut, ScriptGetFontProperties, ScriptItemize, ScriptPlace, ScriptShape, SetTextAlign, GOFFSET, SCRIPT_ANALYSIS, SCRIPT_CACHE