Share via

ScriptStringAnalyse (Windows Embedded CE 6.0)

  • Article

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.

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