Windows API Tutorial - Part One
As you might expect, there's an alternative for the message box available via the Windows API. And although Visual Basic has its own excellent MsgBox() statement, I'd like to introduce this wizzy call to you as it helps us demonstrate a few new API concepts.
- Start Visual Basic and create a new Standard Exe
- Draw a Command Button onto Form1
- Add a Module to the project
Now I'd like to introduce you to a tool called the API Viewer. It ships with all versions of Visual Basic and is available by selecting the Microsoft Visual Basic (or Visual Studio) folder on the Start menu, and dipping into the Visual Basic Tools folder. If you can't find it, have a scour around its filename is APILOAD.EXE
- Launch the API Viewer
The API Viewer is simply a program that lists virtually all of the available Windows API calls you can make in Visual Basic, along with their declaration format.
- Click File, Open
- Select the 'Win32api.txt' file and click Open
- If prompted to change to database format, accept the invitation
You've just loaded all the Windows API calls into the API Viewer program. Let's see whether it lists the GetTickCount() function we played around with just a few minutes ago:
- Select 'Declares' from the API Type combo box
- In the box just above the list of 'Available Items', type in GetTickCount
Do you see it in the list?
- Double-click on 'GetTickCount'
The format for declaring the GetTickCount() routine should appear exactly the same as we typed it. In fact, this is where I got the declaration myself.
For now, let's remove the GetTickCount() declaration from our screen:
- Click on the GetTickCount declaration in the 'Selected Items' box and click 'Remove'
Have a quick scroll up and down the 'Available Items' list. Now, you're probably wondering what all those other items do. Me too. Well, I think I can guess what 'GetTimeZoneInformation' does. And perhaps even 'AbortPrinter'. Erm, but 'WriteConsoleOutputAttribute'? Oh boy...
So don't concern yourself with knowing every single API call. Just be aware that the Windows API is available to help if things look impossible. When you need to do something and you think the API can lend a hand, you could try searching the Microsoft site and related API documentation (www.microsoft.com/api/), checking out the VB-World API section (www.vb-world.net/api/) or even the Complete and Categorised API Bible (www.vbapi.com/ref/). At the end of this tutorial, I'll also be recommending a couple o' books that list the most frequently used calls and how they can brighten your programming life.
Anyway, let's continue:
- Type 'MessageBox' in the box just above 'Available Items'
- Double-click on 'MessageBox' in the combo box
The following should appear in the 'Selected Items' box:
Public Declare Function MessageBox Lib "user32" Alias _"MessageBoxA" (ByVal hwnd As Long, ByVal lpText As String, _ByVal lpCaption As String, ByVal wType As Long) As Long
- Click the 'Copy' button
- Switch back to the copy of Visual Basic you have running
- Open your module and select Edit, Paste
The above code should appear in your module. Great!
Top Tip: You can also put your API declaration code behind a Form but be sure to replace the 'Declare' or 'Public' bit to 'Private' first. Also, bear in mind that only the current form will be able to 'see' it.
Now this declaration is a little different from the one we've seen so far. Let's take a peek.
This one is saying to Visual Basic I'm publicly declaring a function called MessageBox that uses the library called user32.dll (you don't always need to precede with the .DLL extension). Inside the user32.dll, the bit of code I want to run has an alias (name) of "MessageBoxA". Four different arguments are also required two strings, two longs. And as I'm a function, a value will be returned actually, a Long, as the last bit points out.
Phew! Sound complicated? It's a new way of coding and bound to be a little confusing at first, but please, bear with me.
Let's take a moment to analyse those four arguments the API call requires. The very first is devilishly difficult, so don't worry if you can't grasp the concept straight away:
- hwnd (Long) this is something you will see cropping up all over the place. Think of it as a number that points to a form or more geekishly, the 'handle' to a 'window'. You can access the 'handle' of a form, by using it's hWnd property (even seen that before? Go take a peek!). Why does the API call need this 'form handle'? Well, this is how it knows from which form the message box originated.
- lpText (String) this is the message you want to display in the box
- lpCaption (String) this is the message box title
- wType (Long) this is a number that represents what the message box should look like. Should it have an OK and Cancel button? Yes or No? What icons should it display? We'll cover this shortly.
Now if programming were real life, that last argument would be one of those weirdo punks with purple hair and a nose ring - so we'll be all civilised and ignore it for the moment. For now, let's just get a quick message box up and running!
- Open your Form
- Behind the Command Button, enter this code:
Call MessageBox(Form1.hwnd, "Did Video Kill the Radio Star?", _"Whodunnit?", 0)
You should understand pretty much everything here. The first argument is perhaps the most confusing really though, we're just passing the hWnd property of our form, a 'pointer' to it. That's how the API knows what program is displaying the message box.
As we've not discussed that last punk parameter yet wType I've just slotted a lonely '0' in its place.
- Press F5 and click the Command Button
<Me: Does it work?>
You should see a simple message box appear with an OK button. But what if you wanted Retry/Ignore? Or perhaps OK/Cancel? That's where our last parameter comes into play.
Hmm, I think it's time we explained it... sure, you may never use the API to display a message box, but what we'll learn here applies to virtually hundreds of other chocolate chip API calls.
Page 4 of 6