The ABCs of APIs Lesson 10
Using Winstring with Pointers to Text

Table of Contents

In Lesson 5 we discussed the use of a string variable as a buffer sent to an API function. The function filled the buffer with text, which we were able to retrieve and use. Some API functions create the string in memory and return a pointer to the memory location. We retrieve the text from that location with Winstring()


Winstring() retrieves a string of text returned from an API function. It can be in the form of a pointer to a memory location or a handle to a data object.

In the following snippet, ptrText is a pointer to a memory location that contains a string of text.

t$ = winstring(ptrText)
print "Text is ";t$

In the following snippet, hText is a handle to a data object in memory that contains a string of text.

t$ = winstring(hText)
print "Text is ";t$

The following snippet demonstrates that winstring() can be used with struct members of type ptr. The type "PTR" is a pointer.

struct Test, var$ as ptr
Test.var$.struct="Hello, World!"
print winstring(Test.var$.struct)


The following small program opens the clipboard and checks for text data. If there is text data on the clipboard, it uses winstring() to retrieve the data from the handle to the text object that is returned by the function.

'A handle to the window to be associated with the open clipboard.
'If this parameter is NULL, the open clipboard is associated with the current task.
hTask = _NULL
calldll #user32, "OpenClipboard",_
    hTask as ulong,_    'handle to window or null for current task
    result as long      'nonzero=success
calldll #user32, "GetClipboardData",_
    _CF_TEXT as long,_    'clipboard format for text data
    hText as long         'handle to data object
if hText<>0 then
    print "Text on clipboard is:"
    'retrieve text at this address:
    t$ = winstring(hText)
    print t$
    print "No text data on clipboard."
end if
calldll #user32, "CloseClipboard", result as void

Written by Alyce Watson. For more on APIs, see:
APIs for Liberty BASIC