ScriptStringAnalyse (Windows Embedded CE 6.0)

1/6/2010

This function analyzes a plain text string.

Syntax

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	Description
  SSA_BREAK	Returns break flags, that is, character and word stops.
  SSA_CLIP	Clips the string at iReqWidth.
  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_HIDEHOTKEY	Removes the first '&' from displayed string.
  SSA_HOTKEY	Replaces '&' with underline on subsequent codepoint.
  SSA_HOTKEYONLY	Displays underline only.
  SSA_PASSWORD	Inputs string contains a single character to be duplicated iLength times.
  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. If NULL, all SCRIPT_CONTROL members are set to zero.

• psState
  [in] Pointer to a SCRIPT_STATE structure. If NULL, all SCRIPT_STATE members are set to zero. 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. This is only required if dwFlags is SSA_TAB.

• pbInClass
  [in] Must be set to NULL for Windows Embedded CE.

• pssa
  [out] Pointer to a SCRIPT_STRING_ANALYSIS structure.

Return Value

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 can also return a system error (converted to an HRESULT), such as those from lack of memory or GDI calls using the hdc.

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

Header	usp10.h
Library	Uspce.lib
Windows Embedded CE	Windows CE 5.0 and later

See Also

Reference

ScriptBreak
ScriptItemize
ScriptPlace
ScriptShape
SCRIPT_CONTROL
SCRIPT_STATE
SCRIPT_STRING_ANALYSIS
SCRIPT_TABDEF

Other Resources

Uniscribe Functions