Export (0) Print
Expand All

ScriptStringAnalyse function

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_opt_  SCRIPT_CONTROL *psControl,
  _In_opt_  SCRIPT_STATE *psState,
  _In_opt_  const int *piDx,
  _In_opt_  SCRIPT_TABDEF *pTabdef,
  _In_      const BYTE *pbInClass,
  _Out_     SCRIPT_STRING_ANALYSIS *pssa
);

Parameters

hdc [in]

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.

pString [in]

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.

cString [in]

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.

cGlyphs [in]

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

iCharset [in]

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:

ANSI_CHARSET
ARABIC_CHARSET
BALTIC_CHARSET
CHINESEBIG5_CHARSET
DEFAULT_CHARSET
EASTEUROPE_CHARSET
GB2312_CHARSET
GREEK_CHARSET
HANGUL_CHARSET
HEBREW_CHARSET
JOHAB_CHARSET
MAC_CHARSET
OEM_CHARSET
RUSSIAN_CHARSET
SHIFTJIS_CHARSET
SYMBOL_CHARSET
THAI_CHARSET
TURKISH_CHARSET
VIETNAMESE_CHARSET
dwFlags [in]

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

ValueMeaning
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.

 

iReqWidth [in]

Width required for fitting or clipping.

psControl [in, optional]

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.

psState [in, optional]

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.

piDx [in, optional]

Pointer to the requested logical dx array.

pTabdef [in, optional]

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

pbInClass [in]

Pointer to a BYTE value that indicates GetCharacterPlacement character classifications.

pssa [out]

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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Redistributable

Internet Explorer 5 or later on Windows Me/98/95

Header

Usp10.h

Library

Usp10.lib

DLL

Usp10.dll

See also

Uniscribe
Uniscribe Functions
ScriptBreak
ScriptItemize
ScriptPlace
ScriptShape
SCRIPT_CONTROL
SCRIPT_STATE
SCRIPT_STRING_ANALYSIS
SCRIPT_TABDEF

 

 

Community Additions

ADD
Show:
© 2014 Microsoft