WDL
“USE” Files
These files are to be used by any program that wishes to perform any Windows API (Application Program Interface) function call. Take note that those “USE” files described as containing declarative information must be “USE’d” at or near the beginning of your program before any executable statements. All others should be “USE’d” some place after the first executable statements, typically after the last statement in your program. Although there are many other USE files contained in the WDL, for the purposes of this document and unless otherwise stated, WDL implies the following three files:
COSWIN.IBS Driver Library. This file contains IB functions and support code necessary to perform various Windows functions. This module actually serves two purposes: The first is to translate and package IB data into a form that is more compatible with the COSW API, sending the data to the appropriate support function in COSW. The second is to provide a simple mechanism for invoking high level features like Modal and Modeless dialogs, Menus, and Window Controls without the user having to juggle the myriad of messages flying around the Windows environment.
COSWIND.INC Contains declaratives for constants, variables and formats that are used by the code contained in COSWIN.IBS.
WINDOWS.INC Contains most of the constants required to perform various functions using the Windows API. The constants have been derived from the C/C++ include file “windows.h” which is supplied as part of the C/C++ development platform.
Symbolic Constant Names
Many of the symbols used to describe constants in windows.h contain one or more embedded underscore characters “_” so that the function purpose stands out. In an IB program, the underscore character is reserved as a line continuation character, and therefore, cannot be used as previously described. Instead, we have chosen to use the decimal point character “.” as a direct replacement. The results of this substitution is that with few exceptions, for any Windows symbolic constant you see referenced in the windows.h file, you can expect to find the same constant in the #windows file.
For example:
The windows.h constant BN_CLICKED (a button control was pressed), would become BN.CLICKED in #windows.
Feature Controls
Because the WDL API must contain code for all types of Windows functions whether or not they are used in a program, it became necessary to find a way to limit the inclusion of this unneeded source code from user programs. This has been accomplished through the use of conditional compilation, a technique that enables blocks of source code to be conditionally included or excluded during a compile by way of testing symbolic constants. These constants, as used by #coswin, are refered to as feature controls.
The following feature control constants can be used to enable or disable pre-defined sections of #coswin code. The section granularity is somewhat arbitrary and may require adjustment. If program size becomes a problem then it may become necessary to modify the driver code or to create a separate library of functions specific to an application. A word of CAUTION: As new compiler and system features become available, further changes will be made to the driver library rendering custom libraries incompatible or in need of merging.
CF.PICFRAME.CODE Enables .BMP Picture Control functions
CF.PICBUTTON.CODE Enables Picture Pushbutton Control functions
CF.LISTBOX.CODE Enables ListBox Control functions
CF.COMBOBOX.CODE Enables ComboBox Control functions
CF.MODELESS.CODE Enables Modeless Dialog functions
CF.MODAL.CODE Enables Modal Dialog functions
CF.METAFILE Enables Meta-File functions
TRACE.CALLS Enables tracing of all calls to #coswin (required for any tracing)
TRACE.LPARAM Enables the inclusion of lParam data (up to 254 bytes) during tracing
TRACE.SEND Enables tracing of data sent to COSW
TRACE.RECEIVE Enables tracing of data received from COSW
TRACE.LUN Specifies the lun to use for tracing
TRACE.DEVICE$ Specifies the trace file/device
Callback
Control
To simplify the use of dialogs and controls in an IB program, we have defined a set of functions that can be included in the user’s code. These functions will be called as needed by the driver library. Calls to these functions in the user program are enabled by defining constants on an as-needed basis as follows:
CF.USR.IDLE Enables USR.Idle callback
CF.USR.COMMANDHANDLER Enables USR.CommandHandler callback
CF.USR.COMMANDFILTERINIT Enables USR.CommandFilterInit callback
CF.USR.MESSAGEHANDLER Enables USR.MessageHandler callback
CF.USR.MESSAGEFILTERINIT Enables USR.MessageFilterInit callback
CF.USR.ERRORHANDLER Enables USR.ErrorHandler callback
CF.USR.DIALOGINIT Enables USR.DialogInit callback
User
Supplied Functions (CallBacks)
A CallBack is the term used to describe a subroutine in your program that will be "gosub'ed" by Windows when certain events occur. An example of a callback would be USR.CommandHandler which is called by Windows whenever a command event occurs.
The following callback functions are used by the driver library to inform the application of an event occurrence or to retrieve initialization information from the application. Each function must be enabled by setting the appropriate constant as outlined in the “Callback Control” section of this document.
USR.MessageFilterInit: Gets WM message filter information
USR.MessageHandler: Handles WM messages
USR.CommandFilterInit: Gets WM.COMMAND filter information
USR.CommandHandler: Handles WM.COMMAND messages
USR.DialogInit: Called when a dialog has been constructed
USR.Idle: Called during idle time from Modal dialog or Modal loop
USR.ErrorHandler: Called when a system error occurs