ScriptJustify

The ScriptJustify function creates an advance widths table to allow text justification when passed to the ScriptTextOut function.

HRESULT WINAPI ScriptJustify(
  const SCRIPT_VISATTR *psva, 
  const int *piAdvance, 
  int cGlyphs, 
  int iDx, 
  int iMinKashida, 
  int *piJustify 
);

Parameters

psva

[in] Pointer to an array of SCRIPT_VISATTR structures containing visual attributes for the entire line to be processed.

piAdvance

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

cGlyphs

[in] Count of the number of glyphs contained in all arrays.

iDx

[in] Length of the desired line in pixels.

iMinKashida

[in] Minimum length of a kashida glyph to generate.

piJustify

[out] Pointer to an updated advance widths array to pass to the ScriptTextOut function.

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

ScriptJustify provides a simple implementation of multilingual justification. The ScriptJustify function establishes how much adjustment to make at each glyph position on the line. It interprets the SCRIPT_VISATTR array generated by a call to ScriptShape, and gives top priority to kashida. It uses interword spacing if there are no kashida points, and then uses intercharacter spacing if there are no interword points.

Sophisticated text formatters may prefer to generate their own delta dx array by combining their own features with the information returned by ScriptShape in the SCRIPT_VISATTR array.

The justified advance widths generated in ScriptJustify should be passed to ScriptTextOut in the piJustify paramter.

ScriptJustify creates a justify array containing updated advance widths for each glyph. Where a glyph's advance width is increased, it is expected that the extra width will be rendered to the right of the glyph, with a white space or, for Arabic text, a kashida.

Note  Kashida insertion occurs to the right of the glyph, visually. Word and PPT use this concept. As a result, ScriptJustify now generates piJustify, which indicates kashida insertion to the right (visually) of the glyph to be justified. Any change in the algorithm of where to insert kashida should accompany a change in the corresponding ScriptTextOut handler for the particular script (for example, Arabic TextOut justification handler if kashida placement algorithm has changed).

If there are a series of glyphs that can't be justified (that is, SCRIPT_VISATTR.uJustification is SCRIPT_JUSTIFY_NONE for the glyphs), ScriptJustify copies the input piAdvance array to the output piJustify array and returns S_FALSE to the caller.

Requirements

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

See Also

Uniscribe Overview, Uniscribe Functions, ScriptPlace, ScriptShape, ScriptTextOut, SCRIPT_VISATTR