ScriptStringAnalyse

The ScriptStringAnalyse function analyzes a plain text string.

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

Parameters

hdc

[in] Handle to the device context. If dwFlags is SSA_GLYPH, the hdc is required. If dwFlags is SSA_BREAK, the hdc is optional.

If the hdc is present, the current font in the hdc is inspected. If the current font is a symbolic font, the character string is treated as a single neutral SCRIPT_UNDEFINED item.

pString

[in] Pointer to the string to be analyzed. It must have at least one character.

cString

[in] Length of the string. This must be at least 1.

cGlyphs

[in] Glyph buffer size. This is required. The default size is cString * 3/2 + 1.

iCharset

[in] Character set descriptor. If this is an ANSI string, this is the charset. If it is a Unicode string, this is –1.

dwFlags

[in] Indicates the analysis required. This parameter can be one of the following values.

Value	Meaning
SSA_BREAK	Returns break flags, that is, character and word stops.
SSA_CLIP	Clips the string at iReqWidth.
SSA_DONTGLYPH	Used internally.
SSA_DZWG	Provides representation glyphs for control characters.
SSA_FALLBACK	Uses fallback fonts.
SSA_FIT	Justifies string to iReqWidth.
SSA_GLYPHS	Generates glyphs, positions, and attributes.
SSA_GCP	Returns missing glyphs and pwLogClust with GetCharacterPlacement conventions.
SSA_HIDEHOTKEY	Removes the first '&' from displayed string.
SSA_HOTKEY	Replaces '&' with underline on subsequent codepoint.
SSA_HOTKEYONLY	Displays underline only.
SSA_LAYOUTRTL	Used internally.
SSA_LINK	Applies East Asian font linking and association to noncomplex text.
SSA_METAFILE	Writes items with ExtTextOutW calls, not with glyphs.
SSA_PASSWORD	Inputs string contains a single character to be duplicated iLength times.
SSA_PIDX	Used internally.
SSA_RTL	Uses base embedding level 1.
SSA_TAB	Expands tabs.

iReqWidth

[in] Required width for fitting or clipping.

psControl

[in] Pointer to a SCRIPT_CONTROL structure.

psState

[in] Pointer to a SCRIPT_STATE structure. 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 hdc.

piDx

[in] Pointer to the requested logical dx array.

pTabdef

[in] Pointer to a SCRIPT_TABDEF structure.

pbInClass

[in] Pointer to a BYTE that indicates GetCharacterPlacement character classifications.

pssa

[out] Pointer to a SCRIPT_STRING_ANALYSIS structure.

Return Values

If the function is successful, it returns S_OK.

If there is an invalid argument, it returns E_INVALIDARG.

If SSA_FALLBACK was not specified, or if a standard fallback font is missing, it returns USP_E_SCRIPT_NOT_IN_FONT. It will also return any Win32 error (converted to an HRESULT by the HRESULT_FROM_WIN32 macro), such as those from lack of memory or GDI calls using the hdc.

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

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

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

Note that the uBidiLevel member in the initial SCRIPT_STATE value is ignored—the uBidiLevel that is used is derived from the SSA_RTL flag in combination with the layout of the hdc.

Requirements

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

See Also

Uniscribe Overview, Uniscribe Functions, ExtTextOut, GetCharacterPlacement, ScriptBreak, ScriptItemize, ScriptPlace, ScriptShape, SCRIPT_CONTROL, SCRIPT_STATE, SCRIPT_STRING_ANALYSIS, SCRIPT_TABDEF