Windows API Guide: EM_LINEINDEX Message
Introduction
As I mentioned earlier, Visual Basic hides some of the more difficult (and therefore powerful) concepts in programming from you. Its rationale is noble -- to make Visual Basic a simpler language to use -- and it often pays off. However, this simplicity becomes a liability when using the Windows API. The most obvious case here is pointers. Because Visual Basic almost always hides the pointers it uses from the programmer, using them in API functions can at times be difficult.
This final page reveals some of what Visual Basic hides from you during API-based programming. You won't find very much of this in Visual Basic's documentation; I learned most of this from experience and frustration. Nevertheless, a firm understanding of the following material is crucial for mastering the most complex of API functions.
The Truth About ByVal and ByRef
Earlier in this series, the superficial meanings of ByVal and ByRef were defined. However, in reality something somewhat more sinister is happening. You already know that Windows is a 32-bit operating system. Well, it just so happens that every parameter passed to any API function is a 32-bit integer.
"Wait just a minute," I'm sure you're saying right now. "You can too pass other things as parameters to API functions. Why, some functions take strings as parameters; others take byte arrays and structures. What do you mean, only 32-bit integers?" Well, behind the scenes, only 32-bit integers are being passed to the API functions. Although it looks like something else in your Visual Basic code, it does that to make things easier for you, which does in fact help most of the time.
Once again, ByRef literally means "By Reference." That "reference" is in reality a 32-bit pointer. That's right, Visual Basic is actually passing a 32-bit pointer to the object passed by reference. That structure isn't being passed -- only a pointer to it is. The same thing happens with anything else passed ByRef; that's why API functions can only edit your program variables when they are passed ByRef (except for strings). By using the pointer, the API function is able to access the variable itself to read or change.
The ByVal keyword is pretty much what it appears to be. It does pass the actual value of the parameter to the function. Again, that's why ByVal-passed variables (except for strings) cannot be edited by the function; the API function has no way to access the variable itself. API functions require ByVal whenever they do not need to modify the value of a 32-bit integer.
The Truth About Strings
You probably noticed that, in the above section, I kept making an exception for strings. While strings are always passed ByVal, the API function is always able to modify them freely. On the surface, it looks like this is impossible: nothing passed ByVal can be modified, right? But remember that every "real" parameter passed to an API function is a 32-bit integer. Strings passed ByVal aren't 32-bit integers, right?
It turns out that strings are much more sinister than you can imagine. It all stems from the differences between Visual Basic and C++. In C++, there is no "string" data type. Instead, an array of byte-long elements (of the "char"acter data type) is used to represent a string, each element in the array storing a single letter. The final element in the array is equal to 0, the null character. Whenever these pseudostrings are used, especially in parameter passing, a pointer to the first element is used. This pointer effectively references the entire string: everything from the pointed-at element to the terminating null.
Why does any of this matter? Remember that the Windows API is written in C++ and therefore uses the C++ style of string. Visual Basic is forced to use the Windows API to execute virtually all of its string operations (implicitly through Visual Basic's intrinsic functions). This forces Visual Basic to internally use the C++ style strings all the time while providing the programmer with its own easier-to-use string data type.
In reality, the Visual Basic String data type is actually a special form of the Long data type! Throughout the entire Visual Basic command set, the programming language recognizes the difference between a String and a Long and acts accordingly. (For example, the Len function returns the number of bytes in the actual string, not the length of the "real" variable.) And what does this covert 32-bit integer hold? Naturally, it holds a pointer to the beginning of the actual string! This is why strings must always be passed ByVal: the string itself is not passed, but the pointer to it is. Similar reasoning explains why API functions can edit these strings despite having been passed ByVal.
Don't believe what I just said? I can prove it to you. Consider the following structure:
Public Type MYSTRUCT svar As String End TypeThis structure has a single data member: a variable-length string. Now ask yourself, what is the size of the structure? Does it depend on the content of the string? Or is it a constant value? Try running the following code and you'll discover the answer:
Dim st As MYSTRUCT st.svar = "This is a line of text." Debug.Print "Size of structure is"; Len(st) st.svar = "Hello, world!" Debug.Print "Size of structure is"; Len(st)Run this code and you'll notice that both times, the size of the structure is reported to be 4. This is in fact the size in bytes of a 32-bit integer! The structure does not actually store a string. Instead, it stores a 32-bit pointer to the string. When you think about it, there's no other way to implement a variable-length string inside a structure. If the string truly were embedded in the structure, its entire contents would have to be rearranged every time the length of the string changed.
But what about fixed-length strings? It turns out that they are what they claim to be; they are not pointers. Try changing the data member in MYSTRUCT to the data type "String * 40" and run the example. Both times, the reported size will be 40. For fixed-length strings in a structure, the contents of the string are in fact embedded in the structure. However, this holds only for structures. If you define a fixed-length string outside a structure, it will still actually be a pointer to a string and must be passed ByVal to any API function.
Has all of this been confusing? It probably has, since you learned the truth about one of the great deceptions Visual Basic makes. This information really doesn't apply to anything else besides API function programming. Nevertheless, this realization should explain the curious use of ByVal for strings. Besides, this advanced information will give you a better understanding about what you're typing into your program.
The ByVal Keyword and CLng() Function
The ByRef method of parameter passing is often used when a pointer to some object is needed. However, in some cases, you wish to specify no object at all. For example, with some API functions, if you do not use an optional feature which requires a certain structure, passing that structure anyway will cause the function to fail. You need to somehow pass "nothing" for a ByRef parameter.
The way to accomplish this is to make use of the ByVal keyword. Placing the ByVal keyword immediately before the desired parameter, that parameter will be passed by value regardless of what appears in the function's declaration. Then you are able to simply pass 0 as the parameter, effectively giving a null pointer to the function. But what if that parameter is not a Long data type? Change the declaration to make that parameter's data type Any! But then, when you pass a null pointer, you must use the expression ByVal CLng(0).
Why "ByVal CLng(0)"? As the previous paragraph stated, ByVal is necessary to pass 0 for the parameter, instead of a pointer to where that 0 is stored in memory (and that pointer would not be 0). CLng() is a data type conversion function which converts a number into the Long data type. If you did not include the call to CLng(), Visual Basic would not know which data type the 0 is. Since the function declaration, reading As Any for that parameter, would not offer any help, it would probably try to pass it as a regular Integer or some other non-32-bit integer. But since API functions only accept 32-bit integers for parameters, a fatal error would arise. Therefore, using "ByVal CLng(0)" assures that a fully 32-bit 0 is being passed to the function, and everything will work perfectly.
For an example of ByVal CLng(0) in action, look at the following example:
' Read both a Long (32-bit) number and a String from the file ' C:\Test\myfile.txt. Notice how the ByVal keyword must be used ' when reading a string variable. Dim longbuffer As Long ' receives long read from file Dim stringbuffer As String ' receives string read from file Dim numread As Long ' receives number of bytes read from file Dim hFile As Long ' handle of the open file Dim retval As Long ' return value ' Open the file for read-level access. hFile = CreateFile("C:\Test\myfile.txt", GENERAL_READ, FILE_SHARE_READ, ByVal CLng(0), OPEN_EXISTING, FILE_ATTRIBUTE_ARCHIVE, 0) If hfile = -1 Then ' the file could not be opened Debug.Print "Unable to open the file -- it probably does not exist." End ' abort the program End If ' Read a Long-type number from the file retval = ReadFile(hFile, longbuffer, Len(longbuffer), numread, ByVal CLng(0)) If numread < Len(longbuffer) Then ' EOF reached Debug.Print "End of file encountered -- could not read the data." Else Debug.Print "Number read from file:"; longbuffer End If ' Read a 10-character string from the file stringbuffer = Space(10) ' make room in the buffer retval = ReadFile(hFile, ByVal stringbuffer, 10, numread, ByVal CLng(0)) If numread = 0 Then ' EOF reached Debug.Print "End of file encountered -- could not read any data." ElseIf numread < 10 Then ' read between 0 and 10 bytes Debug.Print "Incomplete string read: "; Left(stringbuffer, numread) Else Debug.Print "String read from file: "; stringbuffer End If ' Close the file. retval = CloseHandle(hFile)Remember: if you ever have to pass a "null pointer" (i.e., a value of 0 for a ByRef) to a function, you must change that parameter's data type in the declaration to Any, in case it is something different. If that parameter is not ByVal according to the declaration, then the ByVal keyword must be used explicitly in the call to the function. Finally, you must make use of the CLng() conversion function to force the 0 to be fully 32 bits in length.
Getting Pointers to Other Objects
Sometimes, an API function will demand a pointer to some sort of object, in which case you must find a way to obtain the necessary pointer. Sadly, the AddressOf operator only works with application-defined functions, so it cannot provide a pointer to a structure or other object. So what can you do?
Actually, there is no way in Visual Basic to get a pointer to any object. Instead, you should create a memory block of the necessary length and copy the object (often a structure) into that block. By using the GlobalAlloc and GlobalLock functions, both a handle and a pointer to this memory block can be obtained. Then, when calling the necessary API function, you can simply use a pointer to the memory block instead of one to the original object. Since the memory block holds a copy of the data (generated via the lstrcpy function for strings, or the CopyMemory function for all other objects), there is effectively no difference between it and the original object. After using the block, it should be freed using the GlobalUnlock and GlobalFree functions as necessary.
The easiest way of learning how to create and manipulate these pure memory blocks is to examine an example of it in use. The following example opens the Choose Font common dialog box. The CHOOSEFONT_TYPE structure requires a pointer to a LOGFONT structure as one of its data members. This is done by using a memory block (referenced via hMem and pMem) to hold a copy of the structure. The structure's contents is initially copied into the memory block, and later the block is copied back to the structure in case any alterations were made to its contents.
' Display a Choose Font dialog box. Print out the typeface name, point size, ' and style of the selected font. More detail about topics in this example can be found in ' the pages for CHOOSEFONT_TYPE and LOGFONT. Dim cf As CHOOSEFONT_TYPE ' data structure needed for function Dim lfont As LOGFONT ' receives information about the chosen font Dim hMem As Long, pMem As Long ' handle and pointer to memory buffer Dim fontname As String ' receives name of font selected Dim retval As Long ' return value ' Initialize the default selected font: Times New Roman, regular, black, 12 point. ' (Note that some of that information is in the CHOOSEFONT_TYPE structure instead.) lfont.lfHeight = 0 ' determine default height lfont.lfWidth = 0 ' determine default width lfont.lfEscapement = 0 ' angle between baseline and escapement vector lfont.lfOrientation = 0 ' angle between baseline and orientation vector lfont.lfWeight = FW_NORMAL ' normal weight i.e. not bold lfont.lfItalic = 0 ' not italic lfont.lfUnderline = 0 ' not underline lfont.lfStrikeOut = 0 ' not strikeout lfont.lfCharSet = DEFAULT_CHARSET ' use default character set lfont.lfOutPrecision = OUT_DEFAULT_PRECIS ' default precision mapping lfont.lfClipPrecision = CLIP_DEFAULT_PRECIS ' default clipping precision lfont.lfQuality = DEFAULT_QUALITY ' default quality setting lfont.lfPitchAndFamily = DEFAULT_PITCH Or FF_ROMAN ' default pitch, proportional with serifs lfont.lfFaceName = "Times New Roman" & vbNullChar ' string must be null-terminated ' Create the memory block which will act as the LOGFONT structure buffer. hMem = GlobalAlloc(GMEM_MOVEABLE Or GMEM_ZEROINIT, Len(lfont)) pMem = GlobalLock(hMem) ' lock and get pointer CopyMemory ByVal pMem, lfont, Len(lfont) ' copy structure's contents into block ' Initialize dialog box: Screen and printer fonts, point size between 10 and 72. cf.lStructSize = Len(cf) ' size of structure cf.hwndOwner = Form1.hWnd ' window Form1 is opening this dialog box cf.hdc = Printer.hDC ' device context of default printer (using VB's mechanism) cf.lfLogFont = pMem ' pointer to LOGFONT memory block buffer cf.iPointSize = 120 ' 12 point font (in units of 1/10 point) cf.flags = CF_BOTH Or CF_EFFECTS Or CF_FORCEFONTEXIST Or CF_INITTOLOGFONTSTRUCT Or CF_LIMITSIZE cf.rgbColors = RGB(0, 0, 0) ' black cf.lCustData = 0 ' we don't use this here... cf.lpfnHook = 0 ' ...or this... cf.lpTemplateName = "" ' ...or this... cf.hInstance = 0 ' ...or this... cf.lpszStyle = "" ' ...or this cf.nFontType = REGULAR_FONTTYPE ' regular font type i.e. not bold or anything cf.nSizeMin = 10 ' minimum point size cf.nSizeMax = 72 ' maximum point size ' Now, call the function. If successful, copy the LOGFONT structure back into the structure ' and then print out the attributes we mentioned earlier that the user selected. retval = ChooseFont(cf) ' open the dialog box If retval <> 0 Then ' success CopyMemory lfont, ByVal pMem, Len(lfont) ' copy memory back ' Now make the fixed-length string holding the font name into a "normal" string. fontname = Left(lfont.lfFaceName, InStr(lfont.lfFaceName, vbNullChar) - 1) ' Display font name and a few attributes. Debug.Print "FONT NAME: "; fontname Debug.Print "FONT SIZE (points):"; cf.iPointSize / 10 ' in units of 1/10 point! Debug.Print "FONT STYLE(S): "; If lfont.lfWeight >= FW_BOLD Then Debug.Print "Bold "; If lfont.lfItalic <> 0 Then Debug.Print "Italic "; If lfont.lfUnderline <> 0 Then Debug.Print "Underline "; If lfont.lfStrikeOut <> 0 Then Debug.Print "Strikeout"; Debug.Print ' end the line End If ' Deallocate the memory block we created earlier. Note that this must ' be done whether the function succeeded or not. retval = GlobalUnlock(hMem) ' destroy pointer, unlock block retval = GlobalFree(hMem) ' free the allocated memory<< Back to Part 5 | Contents of Introduction | (no following page)
Go back to the Articles section index.
Go back to the Windows API Guide home page.
Last Modified: January 21, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vb-world.net/articles/intro/part06.html
EAN: N/A
Pages: 610