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