PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC -
the scope of the language as well as it's specific capabilities.
All window classes, such as dialogs and common controls, must be written
in such a way that they can receive instructions or information from the
Windows operating system.
In particular, each window class must include a special procedure (Function)
called the "window procedure". The window procedure must contain exactly
four arguments, all of which are simply numbers of data type Long.
Then, when Windows wants to send instructions/information, called "messages",
to a window it simply calls the window procedure and passes it the four numbers.
Calling the window procedure and passing it the four standard arguments is referred
to as "sending a message".
Each of the numbers that Windows might send have been pre-defined as
having a particular meaning. A window procedure will contain the code to
recognize, and respond, to those numbers (messages) which are important
to the window class. There are thousands of pre-defined Windows messages,
but any one window class might recognize, and respond to, only 20-50 of the
A message may also originate from within an application, such as the main
window directing one of the application's secondary windows to minimize.
Applications can even send messages to other applications.
The bottom line is that all communication between a window and the Windows OS
is handled through the use of messages. Likewise, all window-to-window
communication is handled through messages.
Here's a list of a window procedure's four arguments and a description
of what they contain.
- Handle handle of the window
- MsgID message identifier (a named constant)
- wParam numeric data, varies with msgid value
- lParam numeric data, varies with msgid value
The handle is a unique number assigned to all windows dialogs
when they are created. As was discussed in an earlier tutorial,
this includes dialogs and common controls.
The MsgID is simply one of the pre-defined numbers, whose value
represents a specific message as defined by Windows.
For example, the number 15 is an instruction to a window to
redraw itself. The name of the message is WM_PAINT. All Windows
messages are documented at MSDN.
In this case the WM standard for "window message". Message
nomenclature is discussed further down this page.
Windows also allows an application to create custom messages -
messages which are unique to an application.
The two message parameters (wParam or lParam) specify data or the location
of data. Their meaning and value depend on the value of MsgID. While both
are Long data types, Windows plays a lot of tricks to compress multiple
values into the values - such as storing 2 integer values (2 bytes each)
in the Long data type (4 bytes), using individual bits as flags, or simply
using the value as a pointer to a structure containing additional data..
Not all message use the wParam or lParam parameters. When a message does not use
message parameters, they are typically set to $Nul.
Messages & PowerBASIC
One of the key reasons that PowerBASIC chose to use dialogs as application
windows (rather than emphasizing custom windows) is the special features
which the dialog window class has for receiving and handling messages.
The next tutorial section on callbacks
discusses how a PowerBASIC application can respond to messages.
In short, the code for a dialog can include a special "Callback" function
which receives, and responds to, messages. The callback function includes
the code to recognize which messages are sent to the dialog, and to respond
to those messages of interest (not all received messages require a response).
As noted above, the starting point for interpreting a message is to look at
the MsgID value (2nd of the four values in a Windows message). Allowed
MsgID values have been given names (named constants) by WIndows. For example
a MsgID of WM_SETTEXT refers to a message that instructs a window to set its
displayed text to a new value.
Named constants consist of two or three character prefix, followed by one
or more additional name parts. All are separated by an underscore.
Named constant for Windows messages are easy to recognize because they
begin with a prefix ending with the letter "M", such as WM_ , OCM_, or NM_.
There is no one single listing of all Windows messages, which are
defined and documented separately for each of the various objects
managed by the Windows OS. The MSDN
site provides documentation covering all windows messages.
At MSDN you'll find two types of messages listed - messages and notifications.
The terminology can be a bit confusing, but as listed at MSDN a message
is one that is sent to a window procedure requesting that an action be
taken by the receiving window - such as changing it's visual features or
returning information. A message is received by a window's window procedure
and is not available to a PowerBASIC application.
A notification is a message that is sent to a window, advising it that an
event has taken place (such as a mouse click). A response by the receiving
window is optional. Notification messages are especially important because
PowerBASIC applications can receive, and respond to, notifications.
Within MSDN, documentation is available for each of the various system objects
and pre-defined window classes that Windows supports. Here's a list of
MSDN sections of special interest to PowerBASIC programmers.
Each of these MSDN sections lists messages and notifications which may be sent to
windows, such as the dialogs and common controls in a PowerBASIC application.
The following tables list the messages and notifications for the items in
the table above. The first table covers items which are not common controls
(the first two columns). The second table covers only common controls (the
last two columns).
The reason the next list of common control messages and notifications is
broken out separately is to highlight another potentially confusing
problem with nomenclature used at MSDN.
The notifications listed at MSDN for common controls are not messages at all.
Instead, the notifications MSDN lists for common controls are actually values
contained within the wParam or lParam arguments of two special messages,
WM_COMMAND and WM_NOTIFY. These are notification codes, not notification
messages. This distinction is covered in the next section.
Here's the list of common control messages and notification codes (embedded values
within WM_COMMAND and WM_NOTIFY notification messages).
To look up message/notification code information for a PowerBASIC control,
you'll need to know that some of the PowerBASIC controls are derivations of
the Windows common controls.
The following table shows how the PowerBASIC controls map to Windows common
controls and the corresponding messages which the PowerBASIC controls can
process. If a PowerBASIC control is not listed here, then its name matches that of the common control.
MSDN Control Name--- PowerBASIC Control Name -------------
edit control textbox
static control graphic, image, imagex, label, line
button button, check3state, checkbox, frame,
imgbutton, imgbuttonx, option
For example, the PowerBASIC checkbox is a derivative of the Window
button common control. To look up the messages and notification codes supported
by a PowerBASIC checkbox, you have to go the MSDN section on buttons.
Messages of Importance to PowerBASIC Programmers
Two notification messages are of special interest to PowerBASIC programmers
because they contain information sent to the parent dialog from its
child controls (also from menu and accelerator key presses).
These cover a majority (but definitely not all) of the events a
PowerBASIC application might see.
Sent when the user selects a command item from a menu, when a control
sends a notification message to its parent window, or when an accelerator
keystroke is translated.
Sent by a common control to its parent window when an event has occurred
or the control requires some information.
At MSDN, under each common control, is a list called notifications. These
notifications are not messages, but rather are values contained within
the WM_COMMNAD and WM_NOTIFY messages as values within the wParam and lParam
message values. It is these embedded values which are listed at MSDN
as notifications under each common control.
In the MSDN common control notification listings, the message in which
a notification is delivered is typically identified. For examples, a
BN_CLICK common control notification is documented by MSDN as being provided by a
It can be confusing - there are messages, notifications (notification messages)
and common control notification codes (embedded values in notification messages).
Experienced programmers familiar with the concepts often use the terms
interchangeably, making it even harder to newer programmers to understand
Typically, older common control notifications (those that have been in the API
for a long time) are sent in the WM_COMMAND notification message.
Sending Messages from a PowerBASIC Application
Messages do not always originate from the Windows OS. An application,
including PowerBASIC applications, can generate messages of its own.
A PowerBASIC application may send messages to any dialog or control
in the application, as well as to windows in other applications.
Typically, applications use SendMessage or SendDlgItemMessage API to
generate messages. PowerBASIC not only allows the use of those API,
but it also provides the CONTROL SEND statement which simplifies sending
messages to any window (dialog or control) in the PowerBASIC application,
or to windows in other applications.
If you have any suggestions or corrections, please let me know.