ScriptStringAnalyse function (usp10.h)
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 |
|---|---|
|
Retrieve break flags, that is, character and word stops. |
|
Clip the string at iReqWidth. |
|
Provide representation glyphs for control characters. |
|
Use fallback fonts. |
|
Justify the string to iReqWidth. |
|
Retrieve missing glyphs and pwLogClust with GetCharacterPlacement conventions. |
|
Generate glyphs, positions, and attributes. |
|
Remove the first "&" from displayed string. |
|
Replace "&" with underline on subsequent code point. |
|
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. |
|
Apply East Asian font linking and association to noncomplex text. |
|
Write items with ExtTextOutW calls, not with glyphs. |
|
Duplicate input string containing a single character cString times. |
|
Use base embedding level 1. |
|
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.
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 |