MessagesIn 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 possible messages.
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.
Message Content
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).
Message Identifiers
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.
Message Types
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.
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 WM_COMMAND message.
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 the terminology!
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.