ScriptXtoCP (Windows Embedded CE 6.0)

  • Article

1/6/2010

This function converts an x offset from the left end (!fLogicalOrder) or leading edge (fLogicalOrder) of a run to a logical character position and a flag that indicates whether the x position fell in the leading or the trailing half of the character.

Syntax

HRESULT WINAPI ScriptXtoCP(
  int iX, 
  int cChars, 
  int cGlyphs, 
  const WORD* pwLogClust, 
  const SCRIPT_VISATTR* psva, 
  const int* piAdvance, 
  const SCRIPT_ANALYSIS* psa, 
  int* piCP, 
  int* piTrailing 
);

Parameters

  • iX
    [in] Offset, in logical units, from the end of the run specified by SCRIPT_ANALYSIS.fLogicalOrder.
  • cChars
    [in] Count of logical code points in the run.
  • cGlyphs
    [in] Count of glyphs in the run.
  • pwLogClust
    [in] Pointer to an array containing logical clusters.
  • psva
    [in] Pointer to an array of SCRIPT_VISATTR structures containing the glyph's visual attributes.
  • piAdvance
    [in] Pointer to an array of advance widths.
  • psa
    [in] Pointer to a SCRIPT_ANALYSIS structure. SCRIPT_ANALYSIS.fLogicalOrder specifies the end of the run: if it is set, the leading edge of the run is specified; otherwise, the left end of the run is specified.
  • piCP
    [out] Pointer to an integer to receive the character position.
  • piTrailing
    [out] Pointer to an integer that tells the distance, in code points, from the leading edge of the logical character to the iX position. If zero, the iX position is at the leading edge of the logical character. For more information, see the Remarks.

Return Value

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. If any other unrecoverable error is encountered, it is returned as an HRESULT.

Remarks

The leading and trailing edge of the logical character is determined by the direction of text in the run (LTR or RTL).

For scripts where the caret may conventionally be placed into the middle of clusters (for example, Arabic and Hebrew), the returned character position may be for any code point in the line, and piTrailing will be either zero or one.

For scripts in which the caret is conventionally snapped to the boundaries of a cluster, the returned character position is always the position of the first code point in a cluster (considered logically), and piTrailing is either zero or the number of code points in the cluster.

Thus the appropriate caret position for a mouse hit is always the returned character position plus the value of fTrailing.

When iX is a position outside of the run, ScriptXtoCP acts as if there is an extra infinitely large character beyond each end of the run. This results in the behavior shown in the following table.

iX position (outside of the run) Result

Before the run, that is: (if run is LTR) iX < 0, or (if run is RTL) iX >= sum of advances for the run

*piCP is returned as -1 and

*piTrailing is returned as TRUE

After the run, that is: (if run is LTR) iX >= sum of the advances of the run, or (if run is RTL), iX < 0

*piCP is returned as cChars, and

*piTrailing is returned as FALSE

Requirements

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

See Also

Reference

SCRIPT_STRING_ANALYSIS
SCRIPT_VISATTR

Other Resources

Uniscribe Functions