ScriptStringAnalyse function (usp10.h)

Article
10/13/2021

Analyzes a plain text string.

Syntax

HRESULT ScriptStringAnalyse(
  [in]           HDC                    hdc,
  [in]           const void             *pString,
  [in]           int                    cString,
  [in]           int                    cGlyphs,
  [in]           int                    iCharset,
  [in]           DWORD                  dwFlags,
  [in]           int                    iReqWidth,
  [in, optional] SCRIPT_CONTROL         *psControl,
  [in, optional] SCRIPT_STATE           *psState,
  [in, optional] const int              *piDx,
  [in, optional] SCRIPT_TABDEF          *pTabdef,
  [in]           const BYTE             *pbInClass,
  [out]          SCRIPT_STRING_ANALYSIS *pssa
);

Parameters

[in] hdc

Handle to the device context. If dwFlags is set to SSA_GLYPHS, the device context handle is required. If dwFlags is set to SSA_BREAK, the device context handle is optional. If the device context handle is provided, the function inspects the current font in the device context. If the current font is a symbolic font, the function treats the character string as a single neutral SCRIPT_UNDEFINED item.

[in] pString

Pointer to the string to analyze. The string must have at least one character. It can be a Unicode string or use the character set from a Windows ANSI code page, as specified by the iCharset parameter.

[in] cString

Length of the string to analyze. The length is measured in characters for an ANSI string or in wide characters for a Unicode string. The length must be at least 1.

[in] cGlyphs

Size of the glyph buffer, in WORD values. This size is required. The recommended size is (1.5 * cString + 16).

[in] iCharset

Character set descriptor. If the input string is an ANSI string, this descriptor is set to the character set identifier. If the string is a Unicode string, this descriptor is set to -1.

The following character set identifiers are defined:

[in] dwFlags

Flags indicating the analysis that is required. This parameter can have one of the values listed in the following table.

Value	Meaning
SSA_BREAK	Retrieve break flags, that is, character and word stops.
SSA_CLIP	Clip the string at iReqWidth.
SSA_DZWG	Provide representation glyphs for control characters.
SSA_FALLBACK	Use fallback fonts.
SSA_FIT	Justify the string to iReqWidth.
SSA_GCP	Retrieve missing glyphs and pwLogClust with GetCharacterPlacement conventions.
SSA_GLYPHS	Generate glyphs, positions, and attributes.
SSA_HIDEHOTKEY	Remove the first "&" from displayed string.
SSA_HOTKEY	Replace "&" with underline on subsequent code point.
SSA_HOTKEYONLY	Display underline only. The resulting bit pattern might be displayed, using an XOR mask, to toggle the visibility of the hotkey underline without disturbing the text.
SSA_LINK	Apply East Asian font linking and association to noncomplex text.
SSA_METAFILE	Write items with ExtTextOutW calls, not with glyphs.
SSA_PASSWORD	Duplicate input string containing a single character cString times.
SSA_RTL	Use base embedding level 1.
SSA_TAB	Expand tabs.

[in] iReqWidth

Width required for fitting or clipping.

[in, optional] psControl

Pointer to a SCRIPT_CONTROL structure. The application can set this parameter to NULL to indicate that all SCRIPT_CONTROL members are set to 0.

[in, optional] psState

Pointer to a SCRIPT_STATE structure. The application can set this parameter to NULL to indicate that all SCRIPT_STATE members are set to 0. The uBidiLevel member of SCRIPT_STATE is ignored. The value used is derived from the SSA_RTL flag in combination with the layout of the device context.

[in, optional] piDx

Pointer to the requested logical dx array.

[in, optional] pTabdef

Pointer to a SCRIPT_TABDEF structure. This value is only required if dwFlags is set to SSA_TAB.

[in] pbInClass

Pointer to a BYTE value that indicates GetCharacterPlacement character classifications.

[out] pssa

Pointer to a buffer in which this function retrieves a SCRIPT_STRING_ANALYSIS structure. This structure is dynamically allocated on successful return from the function.

Return value

Returns S_OK if successful. The function returns a nonzero HRESULT value if it does not succeed.

Error returns include:

E_INVALIDARG. An invalid parameter is found.
USP_E_SCRIPT_NOT_IN_FONT. SSA_FALLBACK has not been specified, or a standard fallback font is missing.

The function can also return a system error converted to an HRESULT type. An example is an error returned due to lack of memory or a GDI call using the device context.

Remarks

Use of this function is the first step in handling plain text strings. Such a string has only one font, one style, one size, one color, and so forth. ScriptStringAnalyse allocates temporary buffers for item analyses, glyphs, advance widths, and the like. Then it automatically runs ScriptItemize, ScriptShape, ScriptPlace, and ScriptBreak. The results are available through all the other ScriptString* functions.

On successful return from this function, pssa indicates a dynamically allocated structure that the application can pass successively to the other ScriptString* functions. The application must ultimately free the structure by calling ScriptStringFree.

Although the functionality of ScriptStringAnalyse can be implemented by direct calls to other functions, use of the function itself drastically reduces the amount of code required in the application for plain text handling.

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