UCHARPOS: Difference between revisions
Jump to navigation
Jump to search
Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
(Clarify why posArray& is codepoints& + 1 in size.) |
No edit summary |
||
(3 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
{{DISPLAYTITLE:_UCHARPOS}} | {{DISPLAYTITLE:_UCHARPOS}} | ||
The '''_UCHARPOS''' function calculates the starting pixel positions of every character of the text [[STRING|string]] (0 being the starting pixel position of the first character). This information is returned in a [[LONG|long]] array. The function also returns the number of characters in the text [[STRING|string]]. The function supports Unicode encoded text. | The '''_UCHARPOS''' function calculates the starting pixel positions of every character of the text [[STRING|string]] (0 being the starting pixel position of the first character). This information is returned in a [[LONG|long]] array. The function also returns the number of characters in the text [[STRING|string]]. The function supports Unicode encoded text. | ||
{{PageSyntax}} | {{PageSyntax}} | ||
: {{Parameter|codepoints&}} = [[_UCHARPOS]]({{Parameter|text$}}[, {{Parameter|posArray&()}}][, {{Parameter|utfEncoding&}}][, {{Parameter|fontHandle&}}]) | : {{Parameter|codepoints&}} = [[_UCHARPOS]]({{Parameter|text$}}[, {{Parameter|posArray&()}}][, {{Parameter|utfEncoding&}}][, {{Parameter|fontHandle&}}]) | ||
{{PageParameters}} | {{PageParameters}} | ||
Line 10: | Line 12: | ||
* {{Parameter|utfEncoding&}} is an optional UTF encoding of {{Parameter|text$}}. This can be 0 for ASCII, 8 for UTF-8, 16 for UTF-16 or 32 for UTF-32. | * {{Parameter|utfEncoding&}} is an optional UTF encoding of {{Parameter|text$}}. This can be 0 for ASCII, 8 for UTF-8, 16 for UTF-16 or 32 for UTF-32. | ||
* {{Parameter|fontHandle&}} is an optional font handle. | * {{Parameter|fontHandle&}} is an optional font handle. | ||
{{PageDescription}} | {{PageDescription}} | ||
* If {{Parameter|posArray&()}} is omitted, then the function simply returns the number of characters in the text [[STRING|string]]. | * If {{Parameter|posArray&()}} is omitted, then the function simply returns the number of characters in the text [[STRING|string]]. | ||
* If {{Parameter|utfEncoding&}} is omitted, then it is assumed to be 0. | * If {{Parameter|utfEncoding&}} is omitted, then it is assumed to be 0 (ASCII). | ||
* If {{Parameter|fontHandle&}} is omitted, then the current write page font is used. | * If {{Parameter|fontHandle&}} is omitted, then the current write page font is used. | ||
* {{Parameter|posArray&(codepoints&)}} (assuming {{Parameter|posArray&()}} is 0 [[TO]] {{Parameter|codepoints&}} | * {{Parameter|posArray&(codepoints&)}} (assuming {{Parameter|posArray&()}} is declared (indexed) as 0 [[TO]] {{Parameter|codepoints&}}) will hold the (ending pixel position of the last character) + 1. | ||
* All multi-byte UTF encodings are expected in little-endian. | * 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. | * 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. | * 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]]({{Parameter|text$}})) and then resize the array (0 [[TO]] {{Parameter|codepoints&}}) using [[REDIM]] [[PRESERVE]]. | * 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]]({{Parameter|text$}})) and then resize the array (0 [[TO]] {{Parameter|codepoints&}}) using [[REDIM]] [[PRESERVE]]. | ||
{{PageAvailability}} | {{PageAvailability}} | ||
Line 25: | 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. | File:Qbpe.png|'''v3.8.0''' | ||
File:Apix.png | File:Apix.png | ||
File:Win.png|'''yes''' | File:Win.png|'''yes''' | ||
Line 31: | Line 35: | ||
File:Osx.png|'''yes''' | File:Osx.png|'''yes''' | ||
</gallery> | </gallery> | ||
<!-- additional availability notes go below here --> | |||
{{PageExamples}} | {{PageExamples}} | ||
Line 59: | Line 65: | ||
{{Cl|END}} | {{Cl|END}} | ||
{{CodeEnd}} | {{CodeEnd}} | ||
{{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]] | ||
Line 66: | Line 74: | ||
* [[_PRINTSTRING]], [[_FONT]] | * [[_PRINTSTRING]], [[_FONT]] | ||
* [[Text Using Graphics]] | * [[Text Using Graphics]] | ||
{{PageNavigation}} | {{PageNavigation}} |
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
- Featured in our "Keyword of the Day" series
- _UFONTHEIGHT, _ULINESPACING, _UPRINTWIDTH, _UPRINTSTRING
- _FONTWIDTH, _FONTHEIGHT, _PRINTWIDTH
- _NEWIMAGE, _LOADFONT
- _PRINTSTRING, _FONT
- Text Using Graphics