ScriptStringOut function (usp10.h)

Article
10/13/2021

Displays a string generated by a prior call to ScriptStringAnalyse and optionally adds highlighting.

Syntax

HRESULT ScriptStringOut(
  [in]           SCRIPT_STRING_ANALYSIS ssa,
  [in]           int                    iX,
  [in]           int                    iY,
  [in]           UINT                   uOptions,
  [in, optional] const RECT             *prc,
  [in]           int                    iMinSel,
  [in]           int                    iMaxSel,
  [in]           BOOL                   fDisabled
);

Parameters

[in] ssa

A SCRIPT_STRING_ANALYSIS structure for the string.

[in] iX

The x-coordinate of the reference point used to position the string.

[in] iY

The y-coordinate of the reference point used to position the string.

[in] uOptions

Options specifying the use of the application-defined rectangle. This parameter can be set to 0 or to any of the following values. The values can be combined with binary OR.

Value	Meaning
ETO_CLIPPED	Clip text to the rectangle.
ETO_OPAQUE	Use current background color to fill the rectangle.

[in, optional] prc

Pointer to a RECT structure that defines the rectangle to use. If uOptions is set to ETO_OPAQUE and NULL is provided for prc, the function succeeds and returns S_OK. However, if the application sets uOptions to ETO_CLIPPING and provides NULL for prc, the function returns E_INVALIDARG. The application can set this parameter to NULL to indicate that no option is needed.

[in] iMinSel

Zero-based index specifying the starting position in the string. For no selection, the application should set iMinSel >= iMaxSel.

[in] iMaxSel

Zero-based index specifying the ending position in the string.

[in] fDisabled

TRUE if the operating system applies disabled-text highlighting by setting the background color to COLOR_HIGHLIGHT behind all selected characters. The application can set this parameter to FALSE if the operating system applies enabled-text highlighting by setting the background color to COLOR_HIGHLIGHT and the text color to COLOR_HIGHLIGHTTEXT for each selected character.

Return value

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

Remarks

To use this function, the application needs to specify SSA_GLYPHS in its original call to ScriptStringAnalyse.

The application should not use SetTextAlign with TA_UPDATECP when using ScriptStringOut because selected text cannot be rendered correctly. If the application must use this flag, it can unset and reset the flag as necessary to avoid the problem.

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