Super Prev Next

Using the Win32 API

This chapter contains a short description of the Win32 API usage in your Modula-2/Oberon-2 programs.


Super Prev Next

Obtaining API documentation

Your XDS package includes the Win32 API definition modules and the import library, but no documentation on the API. You have to use third-party books or the on-line documentation from the Microsoft Win32 SDK, which is available on Microsoft Developer Network CD-ROMs and along with some C compilers, for instance, Microsoft Visual C++ or Watcom.

Unfortunately, we can not afford licensing the API reference from Microsoft for adapting it to Modula-2 and distributing with XDS. We regret the inconvenience.


Super Prev Next

Using the Win32 API in your programs

The base Win32 API is collected in about 20 definition modules residing in the DEF\WIN32 subdirectory of your XDS installation. There is also an utility which merges these modules, except the module CommCtrl, into the single module Windows during installation. The installation program also invokes the compiler to build the symbol files for all Win32 API modules. To rebuild all these files anytime later, change directory to xxx\DEF\WIN32, where xxx is your XDS installation directory, and issue the following commands:

    build\merge           to rebuild Windows.def
    xm =p =a windef.prj   to rebuild Win32 API symbol files

If you are just studying the Win32 API using SDK references or a third party book, use the Windows module. Otherwise, you may wish to use separate modules.


Super Prev Next

Windows.def: merged versus reexporting

In versions prior to 2.31, you had to use either the merged module Windows or the separate modules, but not both simultaneously, throughout all modules of your program, to avoid compatibility problems. Starting from version 2.31, it is possible to to build the Windows.def file as a set of "reexport" declarations, such as:

    TYPE ULONG = WinDef.ULONG;
    CONST GetFileType = WinBase.GetFileType;

This approach, proposed by Victor Sergeev, removes the restriction on simultaneous usage of Windows.def and other Win32 API definition modules that resulted from compatibility problems.

To rebuild the Windows.def file using this method, issue the following command instead of build\merge:

    build\reexport

Note: As the new Windows.sym file is about 10 percent larger, you may need to increase the COMPILERHEAP equation value in the compiler configuration file.

You may switch between the old "merge" and the new "reexport" approaches to Windows.def creation at any time, but note that the CommCtrl module imports from separate modules.


Super Prev Next

Reducing the size of Windows.def

If are using the module Windows, but do not need some parts of the Win32 API collected in it, you may build a reduced version by passing the name of the file containing the list of modules you need to one of the utilitites merge or reexport. One such list is in the DEF\WIN32\BUILD\MIN.LST file that does not include things like OLE and mulimedia. Its usage reduces the size of Windows.def file by about 30% and considerably speeds up compilation of modules importing the module ’Windows’.


Super Prev Next

Building GUI applications

If your program is a GUI application, toggle the GUI option ON in the project file:

    +GUI


Super Prev Next

Declaring callbacks

If you have to pass a procedure as a parameter to an API call (a window procedure, for example), declare it as "StdCall" (see Direct language specification):

    PROCEDURE ["StdCall"] MainDlgProc
    ( hwnd   : Windows.HWND
    ; msg    : Windows.UINT
    ; wparam : Windows.WPARAM
    ; lparam : Windows.LPARAM
    )        : Windows.BOOL;


Super Prev Next

Using resources


Super Prev Next

Automatic resource binding

In early XDS versions, resources had to be bound to an executable "manually", i.e. by invoking a resource compiler, each time after linking. Starting from version 2.20, it is possible to specify any file in the !module project file directive and iterate files by extensions in makefile templates.

Thus, if your application uses resources, you may specify binary resource files as modules in your project to have them been automaticlly bound to the executable, provided that the used ???xc:template has adequate support:

    !module myapp.res


Super Prev Next

Header files

XDS package contains a resource compiler (XRC). Its current version is compatible with traditional resource compilers found in C compiler packages. Those compiles, however, have no idea about what Modula-2 is and work only with C header files. So does XRC. Therefore, constants which identify resources have to be defined in both C headers and Modula-2 definition modules, which may easily go out of sync.

To solve this problem, we suggest you to define resource identifiers in header files and then use the H2D utility to convert these files to definition modules before compilation.


Super Prev Next

Generic GUI application

The SAMPLES\GENERIC subdirectory of your XDS installation contains a generic GUI application, which you can use as a base for your own applications. The sample program uses the standard menus and dialogs that most applications would use. The source is designed to serve as a base for any GUI application and was written in such a way that it can be easily modified to handle any application specific commands.