Introduction

Welcome to my Windows 95 API Guide! This guide is my attempt to help other programmers learn about how to use the Windows API to add a lot of functionality to their programs. Of course, although this guide specializes in Windows 95, almost everything here applies to Windows 98 and Windows NT, as well as Win32s. Likewise, although this guide uses examples and declarations written in Visual Basic, the API can be used by any Windows-based applications. See your own language's help for details on converting the code.

If you are completely new to the concept of the API, please take a few minutes and read the rest of this page. If you would just instead like to brush up on the vocabulary used throughout this guide, you can skip down to the vocabulary section. Or, if you think you know what you are doing, you should jump down to the example entry to learn how this guide is laid out.

And as always, if you have a question, clarification, correction, or want something added to this page or anything else in this guide, don't hesitate to e-mail me at Borg953@aol.com. If I can, I'll try to help you out.

Back to the index.

Introduction to the Windows API

What the heck's an "API" anyway?

So why should I need to worry about it?

The API saves the programmer incredible amounts of time and effort. Think about it. Say you want to create a window that lets the user select a file to open. You could create a window, add list boxes and combo boxes and buttons on it, fill them with the file and directory structure on the disk drive, add a pop-up window telling the user that the file doesn't exist, and so on. That could take days, even weeks! But have you noticed that the Open File dialog boxes in 99% of Windows programs are indentical? That's because the API provides a function, GetOpenFileName, that does all of this for you! You just tell it what kind of files you want, a little more information, and that's it! It saves time, not to mention program size!

Sounds good, but what do I need to do to use it?

Using the API is simple. Usually the most you need to do is to add a declaration of the function to your program. This just tells the programming language that you want to use that API function. You might also have to define any special data types or constants that it uses. (Your programming language may pre-declare these API functions for you automatically. See your documentation for details.) Then, you use the API function just like any other function in your program! It's incredibly easy.

So if it's so easy, why do I need this guide?

The Windows API consists of hundreds of functions ranging from almost every possible topic. No one could possibly remember everything! Also, you need to use the correct syntax when you use the functions so Windows knows what you're talking about. This guide explains many of these functions in plain English, shows you what the various pieces of information you have to tell it are, and even shows you an example of how it is used. Armed with this information, you should be able to utilize the API for your own programs.

Back to the index.

The following is a list of the terms that will be used throughout the API. Some sections honestly won't make sense if you don't know what the terms mean. I'm not just making these up. These terms are used whenever you talk about the API.

Common Dialog

One of the group of dialog boxes used throughout Windows programs. These are the Open File, Save File, Choose Color, Choose Font, Choose Printer, Find, and Find And Replace dialog boxes that look identical in almost every program.

Device

An object that peforms either input or output (or both). Devices range from peripherals (such as a printer, the screen, etc) to other objects such as windows. A device is identified by a device context.

Device Context

A value that references a device in Windows. If you know what a pointer is, think of device contexts as a kind of pointer.

Error Code

A value (usually returned from a function) that identifies the error (if any) that occured when an API function was called. Typically, 0 means failure and a non-zero value such as 1 indicates success. Sometimes error codes are more descriptive, identifying what kind of error occured.

File

A collection of data on a disk. This has the same meaning as the term file does throughout computing. Files can be referenced via handles.

Handle

A value that references an object in Windows. If you know what a pointer is, think of handles as a kind of pointer. Handles reference a diverse group of objects, including windows, files, and registry keys.

Rectangle

A box having all right angles (just like in Geometry). In Windows, rectangles are identified by two pairs of coordinates: the upper-left corner and the lower-right corner. Rectangle information is stored in the RECT data type.

Window

A rectangular box on the screen that makes up an object. Windows range from things such as main application windows to buttons and other objects inside other windows. Almost everything on the screen is some kind of window. Windows are referenced by both handles and device contexts.

Back to the index.

The following is an example of an entry in this guide. Superscript numbers refer to notes on the format that follow the example. Information about a function is shown here, but the entries for data types and constants are very similar.

-- begin example --

GetWindowRect Function¹

Declare Function GetWindowRect Lib "user32.dll" (ByVal hwnd As Long, lpRect As RECT3) As Long2

GetWindowRect reads the size and position of a window. This information is put into the variable passed as lpRect. The rectangle receives the coordinates of the upper-left and lower-right corners of the window. If the window is past one of the edges of the screen, the values will reflect that (for example, if the left edge of a window is off the screen, the rectangle's .Left property will be negative). The function returns 0 if an error occured, or a non-zero value if successful.⁴

hwnd⁵

The handle of the window to read the position and width of.

lpRect

Variable that receives the coordinates of the upper-left and lower-right corners of the window.

Example:⁶

' Find the width and height of Form1
Dim r As RECT
x = GetWindowRect(Form1.hWnd, r)
Debug.Print "Width ="; r.Right - r.Left
Debug.Print "Height ="; r.Bottom - r.Top

Related Call: SetWindowPos⁷
Category: Windows⁸
Back to the index.⁹

-- end example --

1. The heading identifies the name of the function.
2. The declaration of the function (in Visual Basic). Copy this to your program to use the function.
3. If any special data types are used (such as here), there will be a link to information about it.
4. This paragraph tells what the function does and how to use it. It also explains what the value returned by the function means.
5. A list of the parameters passed to the function and a brief explanation of what each one means.
6. A short example (in Visual Basic) of how the function might be used inside an actual program.
7. Links to any functions that perform related or complementary tasks.
8. A link to a list of other functions that deal with the same general topic.
9. A link back to the index list.

The sections on data types and constants have an almost identical format, except there is no example and the Related Calls and Category entries are replaced by Used by, which lists any functions and data types that use it.

Back to the index.