General Information


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