Gary Peek

Some general comments

• Learning to program in PowerBasic for Windows is not "easy" if you have never done any Windows programming, and don't let anyone tell you that it is. Just because it has the general syntax of the BASIC language, don't think that it will be all that familiar.

• Writing programs for Windows is completely different than writing programs for DOS.
  • The Windows API (Application Programming Interface) consists of a large number of very useful and necessary functions that you can call from your programs, however, since there are so many of them, it will take a while to learn about them.
  • Windows is a multitasking environment, which means that the programs you write must coexist with other programs that are running. Windows does things that insure this, like not giving you complete control. It also means that calling API functions is sometimes complicated because multiple programs running under Windows might be calling these API functions, and Windows needs to keep track of them all.
  • There are many Windows "messages" being sent and received while your Windows programs are running. Some of them you will use in your program and for which you will write code to handle, and some of them Windows will take care of and never tell you about. (There are some utility programs available that can give you a "window" into what is going on with these messages so that you can better understand them.)
  • Windows programs are said to be "event driven", and Windows handles events in specific ways within a particlar type of window. Devices like the keyboard and mouse cause messages, and your program must act on these messages. Doing things like reading a key at the keyboard are not straightforward and easy.

• Writing programs in PowerBasic for Windows is a lot more like programming in the "C" language than it is GWBasic or QuickBasic.
  • You will need to get used to the way subroutines, functions, and APIs are called, which is just like in C, but with a slightly different syntax.
  • You will need to get used to the shortcuts in syntax that Windows programmers use, some of them very confusing and non-intuitive.

• Using PowerBasic requires that you learn and understand the Windows API to a much greater extent than those who use other programming languages and development tools, especially Microsoft products. Microsoft provides the programmer with a lot of functions (code) that take care of some of the most used tasks that a program might need, but at the expense of generating bloated and slow programs and requiring that many .DLL files accompany the main program file, (as well as the high cost of these software development packages).

• PowerBasic is "user supported". This means that support from PowerBasic, Inc. is minimal, and that the PowerBasic "community" provides most of the support. Fortunately this community is very helpful, and the PowerBasic support forums on their web site are very good. However, once you start using PowerBasic for complex applications and begin pushing the envelope of what PowerBasic has been used for, some of your questions may very well go unanswered, because possibly no one knows that much about how to do what you are trying to do. You might need to become the "expert".

Important Resources

• Win32 Help File (Programmers Reference), available in the file library of the PowerBasic web site. Unzipped file name is WIN32.HLP.

  This help file has not only the syntax of all of the APIs, but also has excellent explanations of some of the concepts of Windows programming. If you use it only to look up an API to see what it does, you are missing a lot of what it can do for you.

  For example, there are a number of sections with titles like "About Handles and Objects", "About Dialog Boxes", "About Menus", "About Bitmaps", etc. Read up on these in your spare time. All of the Windows messages are explained. Look up WM_ and take a look at the list of messages. Read up on these in your spare time. Some of the topics have sample code which is helpful. Of course, it will be in the "C" programming language, but will still be useful.

  There are some specific topics that you will want to read that will explain a number of things you will see in a lot of programs, e.g., System-Defined Messages, Application-Defined Messages, Painting and Drawing (and all about the WM_PAINT message).

• The PowerBasic Help File (called on-line help)

  This is the help file that is available when you use the Help function in the PowerBasic IDE (Integrated Development Environment) or the main development program. This includes not only the complete syntax of all of the language commands, but also a good bit of background information, and some source code examples as well.

• The PowerBasic Forums on the PowerBasic web site

  You will want to spend a lot of time here, because this is where all of the PowerBasic experts are to be found. Chances are that someone has already asked the question you have and chances are that it has been answered, quite possibly with a working example.

• POFFS by Borje Hagsten, a downloadable off-line archive of the PowerBasic forums.

• The web sites of various PowerBasic third-party software providers, where you will find their products, and sometimes free source code. Links to most of these are in the links area of the PowerBasic web site.

• Example code provided with PowerBasic, and also available in the file library area of the PowerBasic web site.

• Charles Petzold's book "Programming Windows" or "Programming Windows 95", an older (and probably cheaper) version.

• The example code from the Petzold book has been converted to PowerBasic and is available in the file library area of the PowerBasic web site.

Programming Style (SDK versus DDT)

1. SDK (Software Development Kit) style programming (in any language) means separating the source code file from the layout of the windows, dialog boxes, and other "resources" used by the program, like icons, bitmaps, etc. These resources are placed in a "resource file" which gets compiled separately. (Note: The "Resource Compiler" has its own Help File). Utility programs from Microsoft are available as part of the PowerBasic development software to create most of these resources.

2. DDT (Dynamic Dialog Tools) is a feature that PowerBasic includes that allows you to specify and create windows (dialog boxes) directly in the source code. Many of the example programs you will find in the PowerBasic forums will be DDT style programs, because it is quick to write an example program as a single file which the reader can copy, paste, and compile in PowerBasic.

3. Third party software is available for generating both SDK and DDT style code and resources, with most of it being very helpful and affordable.

Files included with PowerBasic

WIN32API.INC is the equates, types, and declarations for calling the Windows API from your PowerBASIC programs.

Helpful hint: Whenever you see an equate used as an option, (something that begins with the % sign), search for it in WIN32API.INC and find out all of the other options available for that API.

COMDLG32.INC is the Windows API Common Dialog declarations. Common Dialog boxes are things like a Printer dialog box that you get right before printing, or the FileOpen dialog box which lets you select from a list of files. You will want to look up the available options to the Common Dialogs too.

COMMCTRL.INC is the declarations for Common Controls, like scroll bars, progress bars, up-down controls, etc. A list of the Common Controls and details about them is in the Win32 Help File.

Things you will see in PowerBasic source code

Data types and naming variables-

Some programmers name variables according to a convention known as Hungarian notation. This type of naming indicates what data type the variable is just by looking at its name. For example lpszName would be a long pointer (lp) to a string (s) of the ASCIIZ type (z). This type of notation is helpful when trying to understand how someone's code works, however if not explained, this type of naming seems strange and unnecessary.

Since Windows programming involves the use of many "Handles", one of the most used naming conventions is naming variables that store handles with an "h" as the first character. For example, hWnd as a handle to a window, hDlg as the handle to a dialog box, etc.

In the PowerBasic on-line help file, examples are often given that show the result of a command using a variable ending with & character. This character is not really needed, but is there in the example to remind you that the command returns a long integer.

For example, s$ = LEFT$(string_expression, n&) means that the LEFT$ function returns a string ($) and requires a numeric value (&) as one of the arguments.

Equates-

Near the beginning of code and resource files you will often find equates that are named things like %ID_THIS or %IDM_THAT. Since each control in a window or dialog box needs a unique identifier (number) most people use these equates to identify the control. The prefixes to these equates are sometimes used to further identify the equate, for example, IDM for an ID for a menu. Note that IDOK, IDCANCEL, IDRETRY, IDYES, IDNO, IDCLOSE, IDHELP and others are predefined in WIN32API.INC.

Note: The first equate should normally be %WM_USER, which is a constant that Windows specifies as the first in a group of numbers to be used to define private messages (or your controls). Subsequent equates should be %WM_USER + (plus some number assigned by you.)

%NULL, %TRUE, and %FALSE-

In WIN32API.INC they are defined as: %TRUE = 1 %FALSE = 0 %NULL = 0 You will want to look up the ISTRUE, ISFALSE, and NOT operators in the PowerBasic on-line help file to see why using these equates is not very obvious and straightforward.

Code shortcuts and non-intuative construction-

If you have never programmed in the "C" programming language or are new to Windows programming, some of the conditional statements you see in PowerBasic will seem strange. One of the favorite things that programmers experienced in this type of programming like to do is to write shortcuts.

One of the most confusing shortcuts is calling a function which returns a True or False result within a conditional statement, which obscures its meaning to less experienced programmers. The following is a typical example.

"If the result (returned value) of the function is anything but zero then condition is True."

IF FunctionName() THEN
 ... do something
END IF

This construction is possible because an IF statement is True if the condition is anything but zero.

The following is the equivalent code but much more obvious, however, you will see this type of code much less often because the variable "result" must be defined.

result = FunctionName()
IF result <> 0 THEN
 ... do something
END IF