Liberty BASIC Programmer's Encyc - ABCs of APIs 10

The ABCs of APIs Lesson 10 
Using Winstring with Pointers to Text 
<img id="wikitext@@toc@@normal" class="WikiMedia WikiMediaToc" title="Table of Contents" src="/site/embedthumbnail/toc/normal?w=225&h=100"/> 
In <a class="wiki_link" href="/ABCs%20of%20APIs%205">Lesson 5 </a> 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() 
 
<h2>Winstring()</h2>
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.

<pre class="lb">t$ = winstring(ptrText) print &quot;Text is &quot;;t$</pre>
 
In the following snippet, hText is a handle to a data object in memory that contains a string of text.

<pre class="lb">t$ = winstring(hText) print &quot;Text is &quot;;t$</pre>
 
The following snippet demonstrates that winstring() can be used with struct members of type ptr. The type &quot;PTR&quot; is a pointer.

<pre class="lb">struct Test, var$ as ptr Test.var$.struct=&quot;Hello, World!&quot; print winstring(Test.var$.struct)</pre>
 
<h2>Demo</h2>
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.

<pre class="lb">'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, &quot;OpenClipboard&quot;,_ hTask as ulong,_ 'handle to window or null for current task result as long 'nonzero=success calldll #user32, &quot;GetClipboardData&quot;,_ _CF_TEXT as long,_ 'clipboard format for text data hText as long 'handle to data object if hText&lt;&gt;0 then print &quot;Text on clipboard is:&quot; 'retrieve text at this address: t$ = winstring(hText) print t$ else print &quot;No text data on clipboard.&quot; end if calldll #user32, &quot;CloseClipboard&quot;, result as void</pre>
 
 
 
Written by Alyce Watson. For more on APIs, see: 
<a class="wiki_link_ext" href="http://www.lulu.com/content/611431" rel="nofollow">APIs for Liberty BASIC</a>