An API Primer
What is API ?
As msdn defines it :
An acronym for Application Program Interface, the set of commands that an application uses to request and carry out lower-level services performed by a computer's operating system. The Windows API contains a huge number of procedures capable of performing just about any task you can imagine (or even cannot !!) and that can be called by any program running under Windows. In fact, the API is behind a great deal of what every Windows program offers. Displaying screen windows, using the printer, displaying text, using menus etc etc — these all are handled by the API.
When you write a routine visual Dialogscript program you are using API indirectly. When your program runs the code is translated into calls to the appropriate API procedures, which perform much of the actual job of the program.
Calling API procedures Directly from Visual Dialogscript
Why call the API directly when visual Dialogscript is already doing that for you ?
Although Visual Dialogscript (VDS) is powerful it doesn't give you all the capabilities provided by API. If you know what is available in windows API and how to access it you will have many more tools in your armamentarium when creating your VDS program making it more powerful and useful.
The API procedures are located in files called dynamic link libraries, or DLLs. These come with your operating system itself. There is only a single copy of each API procedure in a particular dll, which is shared by all programs that need it. (hence dynamic link library).
Now that you can call any non VDS dll from Visual Dialogscript and get access to API you can get about any task you want using API like window management, printer control, menus and dialogs, file manipulation, memory management, graphics drawing, multimedia, user interface, string manipulation, network management .. and so on.
API references go into thousands of pages . You can get several references over the internet.
You can get the W32HLP file for your reference - find it in the resources section or get it from microsoft.com.
How to use API in my VDS application and when ?
Well if you find that you do not have command/function in VDS to accomplish your task then probably it is time to use API if not a custom dll. I am not going here into the details as to how to use API. There are several examples in the main site (most likely you came from there)
as well as in the forum :
I also invite you to visit my homepage:
which contains more than 30 source code examples/Dialog Script units and a few non VDS dll's interfaced in VDS 5.x and some tools and utilities.I hope these examples help you in better understanding of these concepts.
Do i need to take precautions while using API ?
Well, While sharper knife cuts butter better you should take care of your fingers too!. Same holds true with API. While your using native VDS commands the IDE does a lot of error handling for you. Even if you do something wrong you are warned and made to have a chance to save your work. But once you are directly into the windows environment with API things are a bit different. If a serious error occurs your IDE may crash without warning , A blue screen may appear or in an extreme case windows may just crash and reboot without warning.
While these are extremely rare when your API is doing something within your dialog they may not be so uncommon if you are dealing with core window functions.
Here a few wise precautions you should take before you run or debug any of these scripts:
1. Always save your work. (e.g.. Don't run it into your unsaved 3 hour coding/typing session etc. while you have <2h left for an important assignment ;)
2. Again save your code before you debug/test run it as this will save a lot of time as API programming is already a little time consuming.
3. Use common sense e.g. Don't start testing these scripts (unless you are already satisfied that it works properly) on a Sever or PC which you don't have permissions to reboot if at all a need should arise.
4.Due the power, nature and complexity of API :
I or anybody for that matter refuse to take any responsibility for any consequence arising out of the use of these Scripts. From a legal perspective you are using them at your own risk. You cannot hold me responsible for some damage (if at all) that occurred and not even ask me to fix it or even to provide any help in that regard
5. Do not be unduly afraid to do something wrong - Unlike real life you will almost always have a second or even third chance :) Whatever you type in the IDE its unlikely that your will monitor will blow or your computer will get permanently damaged etc. Be bold, Just take precautions that's all.
6. It may be relieving to know that I check all my scripts twice before posting them although I do not legally accept any responsibility for their safety.
Happy API programming