Ansi and Wide Function

Requires: gfawinx.lg32

Purpose

Allows conversion between UNICODE and ANSI formatted strings.

Syntax

str = Ansi(widestr)
widestr = Wide(str [,fNullTerm = True])

fNullTerm	: Boolean expression
str	: ANSI formatted string expression
widestr	: UNICODE formatted string expression

Description

Ansi can convert a string with UNICODE characters to ANSI characters. In most of the cases a wide string is obtained from a Windows API. More and more APIs require wide strings, either as input or for output. GFA-BASIC's string functions expect ANSI (1 byte – 1 character) strings. If the UNICODE string argument includes two null-bytes at the end of the wide string the Ansi function will remove – after conversion – the last null byte that is part of the converted string.

Conversely, the Wide function converts an ANSI string to UNICODE or wide char format. The wide char format expects two bytes for each character, a format used by more and more Windows APIs. Because Wide strings are most often used with Windows APIs, the function includes two null bytes at the end of the string by default. After conversion the length of the wide string will be Len(ansi) * 2 + 2. Setting the second parameter fNullTerm to False prevents the inclusion of the two null bytes and the converted string will be exactly twice as long as the input string.

Example

This example shows how the same string is stored in both ANSI and UNICODE formats:

$Library "gfawinx"

Local String a, w

a = "Hello GFABASIC32"

w = Wide(a)

Debug HexDump(V:w, Len(w))

a = Ansi(w)

Debug HexDump(V:a, Len(a))

The next example shows how to invoke a Windows API function, declared in commctrl.inc, which expects wide char strings. The Wide function takes its parameter as a Variant and consequently accepts any datatype. Wide tries to convert the datatype to a string before conversion. If the datatype cannot be converted to a string an error is raised.

$Library "commctrl.inc"

$Library "gfawinx"

OpenW 1

Print DlgTask(Me.hWnd, "Prompt", "Content", , , -3)

Sleep

Until Me Is Nothing

Function DlgTask(hOwner As Handle, sMainText$, sContent$, _

Optional sTitle$, Optional iButtons% = TDCBF_OK_BUTTON, _

Optional Icon& = 0) As Long

Local Long RetVal, lIcon

Local String Title

sMainText$ = Wide(sMainText$)

sContent$ = Wide(sContent$)

Title = Wide(Iif(IsMissing(sTitle$), App.Name, sTitle$))

lIcon = MakeLongHiLo(0, Icon&)

If TaskDialog(hOwner, 0, V:Title, V:sMainText$, V:sContent$, iButtons%, lIcon, RetVal) == S_OK

Return RetVal

EndIf

EndFunc

Remarks

The Ansi function uses the variant-to-string function from GFA-BASIC. To remove the termination null-byte from the string, the length part of the string descriptor is decremented, so the string itself remains untouched (to improve the execution speed). This is possible because all GB’s string functions use the length stored in the descriptor, they ignore the actual length of a string.