UCHARPOS

The _UCHARPOS function calculates the starting pixel positions of every character of the text string (0 being the starting pixel position of the first character). This information is returned in a long array. The function also returns the number of characters in the text string. The function supports Unicode encoded text.

Syntax

codepoints& = _UCHARPOS(text$[, posArray&([index&])][, utfEncoding&][, fontHandle&])

Parameters

• text$ is any literal or variable STRING value. This can be a Unicode encoded text.
• posArray&([index&]) is a long array that contains the pixel position information after a call to _UCHARPOS. An optional index can be used to specify the starting point in the array.
• utfEncoding& is an optional UTF encoding of text$. This can be 0 for ASCII, 8 for UTF-8, 16 for UTF-16 or 32 for UTF-32.
• fontHandle& is an optional font handle.

Description

• If posArray&() is omitted, then the function returns the number of characters in the text string.
• If utfEncoding& is omitted, then it is assumed to be 0 (ASCII).
• If fontHandle& is omitted, then the current write page font is used.
• posArray&(codepoints&) (assuming posArray&() is declared (indexed) as 0 TO codepoints&) will hold the (ending pixel position of the last character) + 1.
• All multi-byte UTF encodings are expected in little-endian.
• Unicode byte order mark (BOM) is not processed and must be handled by user code.
• This can be useful when the positions of every character in a string are required (e.g., when underlying text or drawing a text cursor). This can be especially helpful when using variable width fonts.
• When working with Unicode encoded text, instead of calling the function twice (first time to get the array size and then a second time to get the pixel positions), call it once with a large enough array (0 TO LEN(text$)) and then resize the array (0 TO codepoints&) using REDIM PRESERVE.

Availability

• 

  none

• 

  v3.8.0

• 
• 

  yes

• 

  yes

• 

  yes

Examples

Example

Underlines every character of a text printed using a variable width font.

OPTION _EXPLICIT SCREEN 12 CONST TEXT = "Hello, world!" CONST TEXT_X = 220 CONST TEXT_Y = 220 DIM fh AS LONG: fh = _LOADFONT("arial.ttf", 32) _FONT fh DIM arr(0 TO LEN(TEXT)) AS LONG, i AS LONG PRINT "Len of "; TEXT; " ="; _UCHARPOS(TEXT, arr()) _UPRINTSTRING (TEXT_X, TEXT_Y), TEXT FOR i = LBOUND(arr) TO UBOUND(arr) - 1 PRINT arr(i + 1); LINE (TEXT_X + arr(i), TEXT_Y + _UFONTHEIGHT)-(TEXT_X + arr(i + 1) - 1, TEXT_Y + _UFONTHEIGHT), 9 + i MOD 7 NEXT END

See also

• Featured in our "Keyword of the Day" series
• _UFONTHEIGHT, _ULINESPACING, _UPRINTWIDTH, _UPRINTSTRING
• _FONTWIDTH, _FONTHEIGHT, _PRINTWIDTH
• _NEWIMAGE, _LOADFONT
• _PRINTSTRING, _FONT
• Text Using Graphics

---

Navigation: Main Page with Articles and Tutorials Keyword Reference - Alphabetical Keyword Reference - By usage Report a broken link