UCHARPOS: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(One intermediate revision by the same user not shown)
Line 29: Line 29:
<gallery widths="48px" heights="48px" mode="nolines">
<gallery widths="48px" heights="48px" mode="nolines">
File:Qb64.png|'''none'''
File:Qb64.png|'''none'''
File:Qbpe.png|'''v3.7.1'''
File:Qbpe.png|'''v3.8.0'''
File:Apix.png
File:Apix.png
File:Win.png|'''yes'''
File:Win.png|'''yes'''
Line 68: Line 68:


{{PageSeeAlso}}
{{PageSeeAlso}}
* [https://qb64phoenix.com/forum/showthread.php?tid=2826 Featured in our "Keyword of the Day" series]
* [[_UFONTHEIGHT]], [[_ULINESPACING]], [[_UPRINTWIDTH]], [[_UPRINTSTRING]]
* [[_UFONTHEIGHT]], [[_ULINESPACING]], [[_UPRINTWIDTH]], [[_UPRINTSTRING]]
* [[_FONTWIDTH]], [[_FONTHEIGHT]], [[_PRINTWIDTH]]
* [[_FONTWIDTH]], [[_FONTHEIGHT]], [[_PRINTWIDTH]]

Latest revision as of 08:47, 26 June 2024

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&()][, utfEncoding&][, fontHandle&])


Parameters

  • text$ is any literal or variable STRING value. This can be a Unicode encoded text.
  • posArray&() is a long array that contains the pixel position information after a call to _UCHARPOS.
  • 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 simply 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 is required (e.g., when underling text or drawing a text cursor). This can be especially helpful when using variable width fonts.
  • When working with Unicode excoded 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


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



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