"Deep in the sea are riches beyond compare.
But if you seek safety, it is on the shore."

API (Application Program Interface)

What's API

API (Application Program Interface) is a set of predefined Windows functions used to control the appearance and behavior of every Windows element (from the outlook of the desktop window to the allocation of memory for a new process). Every user action causes the execution of several or more API function telling Windows what's happened.

It is something like the native code of Windows. Other languages just act as a shell to provide an automated and easier way to access APIs. VB has done a lot in this direction. It has completely hidden the APIs and provided a quite different approach for programming under Windows.

Here is the place to say that, every line of code you write in VB is being translated by VB into API function and sent to Windows. Thus calling something like Form1.Print ... causes VB to call TextOut API function with the needed parameters (either given by you in the code, or taken by some defaults).

Also, when the user click a button on your form, Windows sends a message to your windows procedure (that is eventually hidden for you), VB gets the call, analyses it and raises a given event (Command1_Click) for you.

The API functions reside in DLLs (like User32.dll, GDI32.dll, Shell32.dll...) in the Windows system directory.

API Declaration

As said in “What's API”, functions are declared in DLLs located in the Windows System directory. You can type in the declaration of an API just as you do with any other function exported from a DLL, but VB has provided an easier way to do it. It is called API Text Viewer.

To have some API declared in your project, just launch API Text Viewer, open Win32Api.txt (or .MDB if you have converted it into a database to speed it up), choose Declares, find the function, click Add and then Copy. Go to your project and paste it in. Do the same to have a predefined constant or type.

There are few problems you may face:

Suppose you want to declare a function in your form module. You paste the declaration and run the program. VB says Compile Error, ...and Declare statements not allowed as Public members of ... . Sounds bad, but it isn't, all you need to do is add Private in front of the declaration (like Private Declare Function ...). Do not forget, though, that the function will be visible only within this form module.

In some cases, you may get the message Ambiguous name detected by VB. It means you have two functions, constants or whatsoever sharing one name. As most of the functions (maybe all of them, I haven't checked that) are aliased, which means they are given different names, and not their original using Alias clause, you may simply change the name of the function and it will still work.

You may read the Declare statement help topic of Visual Basic’s for description of Alias.

Messages

OK, now you know what API function is, but you have definitely heard of messages (if you haven't you will soon do) and wonder what is this. Messages are the basic way Windows tells your program that some kind of input has occurred and you must process it. A message to your form is sent when the user clicks on a button, moves the mouse over it or types text in a textbox.

All messages are sent along with four parameters - a window handle, a message identifier and two 32-bit (Long) values. The window handle contains the handle of the window the message is going to. The identifier is actually the type of input occurred (click, mousemove) and the two value specify an additional information for the message (like where is the mouse cursor when the mouse is been moved).

But, when messages are sent to you, why don't you see them, looks like someone is stealing your mail. And before you get angry enough, let me tell you.

The theft is actually VB. But he does not steal your mail, but instead read it for you and give you just the most important in a better look (with some information hidden from time to time). This better look is the events you write code for.

So, when the user moves the mouse over your form, Windows sends WM_MOUSEMOVE to your window, VB get the message and its parameters and executes the code you've entered for Button_MouseMove event. Along the way, VB has transformed the second 32-bit value of the message (it contains the x and y position in pixels, 16-bit each) into two Single type value of twips.

Now, say you need the coordinates of the mouse in pixels. VB converted them into twips, and now you will convert them into pixels again. Apart from losing time, it is somehow irritating to know Windows give you what you need and VB "favorably" alters it so that you must re-alter it. Here you will ask - Can't I receive the messages myself. OK, there is a way called Subclassing, but you should use it only if really necessary as it goes a bit against the concepts of safe programming of VB.

Something else that need to be said: You can send massages to your own window or to another one yourself. You just call SendMessage or PostMessage (SendMessage will cause the window to process the message immediately and Post message will post it onto a queue, called message queue, after any other messages waiting to be processed (it will return after the message is processed, i.e. with some delay)). You must specify the window handle to send the message to, the message identifier (all message identifiers are available as constants in VB API Text Viewer) and the two 32-bit values.

Some Windows specifics

This topic is intended to give you a clue about some Windows specifics that are not the same under VB.

Windows identifies every form, control, menu, menu item or whatever you can think of by its handle. When your application is run, every control on it is assigned a handle which is used later to separate the button from the rest of the controls. If you want to perform any operation on the button through an API you must use this handle. Where to get it from? Well VB has provided a Hwnd property for all controls that have handles in Windows.

Windows works with pixels, not twips. So, it is a good idea to have the controls you'll use API functions over set their ScaleMode properties to Pixel(3) so that you can use ScaleXXX properties to get their metrics. But even though, you have this opportunity, you may still need to convert twips to pixels and vice versa. You do it using TwipsPerPixelX and TwipsPerPixelY ot the global Screen object. Here it is:

pixXValue = twipXValue \ Screen.TwipsPerPixelX

pixYValue = twipYValue \ Screen.TwipsPerPixelY

twipXValue = pixXValue * Screen.TwipsPerPixelX

twipYValue = pixYValue * Screen.TwipsPerPixelY

I haven't really seen the TwipsPerPixelX and TwipsPerPixelY value to be different, but its always better to make difference, at least for the good programing style. Also note that \ (for integer division) is used instead of / as pixels must always be whole numbers.

Another thing to mention is that Windows uses different coordinate systems for the functions. So, be careful.

And lastly, don't forget that VB is safe till the moment you begin to use APIs. A single syntax error in an API call may cause VB to crash (save often!). Also VB cannot debug APIs and if your program is crashing or behaving awkwardly, firstly check the API calls - for missed ByVal, for mistaken type or parameter, everything).

Where to get the functions description from

This topics won't tell how to change the button text through API or how to find a file quickly. It is not a API functions documentation.

To get the description of an API function, you need to have either SDK help file or the Microsoft SDK documentation (it's more that 40MB I think - how can I place it here?). Such SDK helps are shipped with Borland Delphi 3.0 package or MS Visual C++ 5.0 for example. Search the internet are ask your friends to get one. The newer it is the better.

Note that SDK help for Win 3.x won't help you as some functions are obsolete, though most of them still exist for compatibility in Win95.

-by Invincible (psycho@nepalimail.com)