ScriptJustify function (usp10.h)

Creates an advance widths table to allow text justification when passed to the ScriptTextOut function.

Syntax

HRESULT ScriptJustify(
  [in]  const SCRIPT_VISATTR *psva,
  [in]  const int            *piAdvance,
  [in]  int                  cGlyphs,
  [in]  int                  iDx,
  [in]  int                  iMinKashida,
  [out] int                  *piJustify
);

Parameters

[in] psva

Pointer to an array, of length indicated by cGlyphs, containing SCRIPT_VISATTR structures. Each structure contains visual attributes for a glyph in the line to process.

[in] piAdvance

Pointer to an advance widths array, of length indicated by cGlyphs, obtained from a previous call to ScriptPlace.

[in] cGlyphs

Count of glyphs for the arrays indicated by psva and piAdvance. This parameter also indicates the count of glyphs for the output parameter piJustify.

[in] iDx

Width, in pixels, of the desired change, either an increase of decrease.

[in] iMinKashida

Minimum width of a kashida glyph to generate.

[out] piJustify

Pointer to a buffer in which this function retrieves an array, of length indicated by cGlyphs, containing justified advance widths. The justified widths are sometimes called "cell widths" to distinguish them from unjustified advance widths.

Return value

Returns 0 if successful. The function returns a nonzero HRESULT value if it does not succeed. The application can test the return value with the SUCCEEDED and FAILED macros.

Remarks

See Displaying Text with Uniscribe for a discussion of the context in which this function is normally called.

This function provides a simple implementation of multilingual justification. It establishes the amount of adjustment to make at each glyph position on the line. It interprets the SCRIPT_VISATTR array generated by a call to ScriptShape, giving top priority to kashida. The function uses interword spacing if no kashida points are available. It uses intercharacter spacing if no interword points are available.

Note  Sophisticated text formatters might generate their own delta dx array by combining formatter-specific features with the information retrieved by ScriptShape in the SCRIPT_VISATTR array.

 

The application should pass the justified advance widths generated by ScriptJustify to ScriptTextOut in the piJustify parameter.

ScriptJustify creates a justified array containing updated advance widths for each glyph. When an advance width for a glyph is increased, the extra width is 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 to justify visually. Microsoft Word and Microsoft PowerPoint use this concept. Any change in the kashida placement algorithm should accompany a change in the corresponding ScriptTextOut handler for a particular script, for example, the Arabic TextOut justification handler.

 

Sometimes the application tries to handle glyphs that cannot be justified, in which case the uJustification member of SCRIPT_VISATTR is set to SCRIPT_JUSTIFY_NONE. In this case, ScriptJustify copies the input array indicated by piAdvance to the output array indicated by piJustify and returns S_FALSE to the application.

Important  Starting with Windows 8: To maintain the ability to run on Windows 7, a module that uses Uniscribe must specify Usp10.lib before gdi32.lib in its library list.

 

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	usp10.h
Library	Usp10.lib
DLL	Usp10.dll
Redistributable	Internet Explorer 5 or later on Windows Me/98/95

See also

Displaying Text with Uniscribe

SCRIPT_VISATTR

ScriptPlace

ScriptShape

ScriptTextOut

Uniscribe

Uniscribe Functions