Developing Win32 GUI Applications Using FOX

Introduction.

FOX provides a nice platform-independent alternative to the traditional GUI frameworks for Win32 (namely MFC). While most of the other FOX documentation applies to FOX programming in general, this document deals specifically with some of the logistical details of creating a FOX-based application for Windows. Many thanks to Daniel Gehriger, who provided a lot of the information you see here!

Compilers and Development Tools.

One goal is for FOX to work with as many different compilers and development environments as possible. We have used Microsoft Visual C++ versions 5.0 and 6.0, Borland C++ Builder 3.0 and gcc (or egcs) to build FOX applications for Windows. The standard FOX source code distribution includes project workspace files for Microsoft Visual C++ 6.0 as well as make files for Borland C++. You may also be able to use the Visual C++ project files with Visual C++ 5.0, but this is unconfirmed at present. For detailed information about how to build the library itself, please refer to the `INSTALL` file which is found in the top-level directory of the standard FOX distribution.

Using Microsoft Visual C++ 6.0.

This section, and the following two sections, deal specifically with FOX development under Microsoft Visual C++ 6.0. This discussion assumes that you are at least minimally familiar with how to use Visual C++ 6.0. In particular, you should know how to create a new project workspace, and then add new project(s) to that workspace. Most of this information should be useful for Visual C++ 5.0 as well, although some settings may appear in different places.

1. Create the project. All FOX applications are just standard Win32 applications, so when you create a new project select that option:

1. Open the Project Settings dialog for this project. You will want to make changes for both the compile-time options and link-time options of this project. Choose the Settings... option from the Project pulldown menu. Change to the "C/C++" tab and then select "Preprocessor" from the "Category" drop-down list:

1. Modify preprocessor definitions for linking against the FOX DLL. The FOX library can be built as either a static library or a dynamic link library (DLL). If you prefer to link your application against the DLL version of the library, you will need to add FOXDLL to the preprocessor definitions (not shown above).
2. Modify preprocessor definitions for OpenGL. If you plan to use FOX's OpenGL-related features you should also add HAVE_OPENGL to the preprocessor definitions (as shown).
3. Add FOX's include directory to the list of "Additional include directories". This setting is on the "Preprocessor" page too!
4. Add the FOX library to the list of input libraries for this application. Now change to the "Link" tab of the Project Settings dialog box, and select "Input" from the "Category" drop-down list (see below). Add the appropriate library name (`foxd.lib` or `foxdlld.lib` for Debug builds; or `fox.lib` or `foxdll.lib` for Release builds) to the list of libraries under "Object/library modules".

1. Add FOX's lib directory to the "Additional library path". This setting is also on the "Input" page.
2. Change the entry-point symbol. Now select "Output" from the drop-down list on the "Link" tab and type mainCRTStartup in the "Entry-point symbol" type-in field (see below). Note that this field is empty by default. This setting tells the linker to use your application's `main()` function as the entry point instead of the standard `WinMain()` function.

Common Problems.

This section lists some commonly encountered problems for building Win32 applications with FOX.

Unresolved symbols at link time. If you get one or more "error LNK2001" messages at link time, this usually means you've omitted required libraries from the list. Open the Project Settings dialog and change to the "Link" tab. On this tab, choose "Input" from the "Category" drop-down list. Finally, add the missing libraries to the list under "Object/library modules". Here is a list of commonly forgotten libraries:

If the error message is... | You need this library
`foxd.lib(FXPrintDialog.obj) : error LNK2001: unresolved external symbol _EnumPrintersA@28` | `winspool.lib`

`foxd.lib(FXRegistry.obj) : error LNK2001: unresolved external symbol __imp__RegCloseKey@4`
`foxd.lib(FXRegistry.obj) : error LNK2001: unresolved external symbol __imp__RegEnumKeyExA@32`
`foxd.lib(FXRegistry.obj) : error LNK2001: unresolved external symbol __imp__RegCreateKeyExA@36`
`foxd.lib(FXRegistry.obj) : error LNK2001: unresolved external symbol __imp__RegOpenKeyExA@20`
`foxd.lib(FXRegistry.obj) : error LNK2001: unresolved external symbol __imp__RegEnumValueA@32`
`foxd.lib(FXRegistry.obj) : error LNK2001: unresolved external symbol __imp__RegSetValueExA@24`
`foxd.lib(FXRegistry.obj) : error LNK2001: unresolved external symbol __imp__RegDeleteKeyA@8`

`advapi32.lib`

`foxd.lib(FXApp.obj) : error LNK2001: unresolved external symbol __imp___TrackMouseEvent@4` | `comctl32.lib`

On the other hand, if you get this error message:

> `MSVCRTD.lib(crtexew.obj) : error LNK2001: unresolved external symbol _WinMain@16`

this indicates that you forgot to change the application's entry-point symbol to mainCRTStartup. See this section for the details.

Missing support for JPEG or PNG images. If you're trying to use the FXJPEGIcon, FXJPEGImage, FXPNGIcon or FXPNGImage classes and it doesn't seem to be working, it's possible that the FOX library was not compiled correctly to include support for these image formats. Load the FOX library project into Developer Studio and then launch the Project Settings dialog box. On the C/C++ tab of this dialog box, look at the list of preprocessor definitions and confirm that HAVE_JPEGLIB_H (for JPEG support) and/or HAVE_PNG_H (for PNG support) are defined. You will also want to be sure that the compiler can find its way to the JPEG and PNG header files, so make sure the include paths are correct as well. Note that these settings are only relevant for building the FOX library itself; you don't need to have HAVE_JPEGLIB_H or HAVE_PNG_H defined when compiling your FOX-based application code, nor do you need access to the JPEG or PNG header files. You will need to link your applications to the JPEG or PNG libraries, however.

Other Tips...

1. If you find yourself using FOX on a regular basis (as we hope) you might want to add its installation directory to the lists of standard directories searched by Visual C++ for include files and libraries. To do this, open the Options dialog by selecting the Options... command from the Tools pulldown menu, and switch to the "Directories" tab:

> Select "Include files" from the "Show directories for:" drop-down list and the list of directories should show the default include path (in order). Add your FOX installation's include directory to the end of the list. Then select "Library files" from the drop-down list and add your FOX installation's lib directory that list.

1. If you do link your executables against the FOX DLL, the executable needs to find it in the path when it runs. You can copy this DLL by hand to some directory in the path, but you may want to instead make the following modifications to automatically copy the DLL into your application's build directory (requires Windows NT). Start by opening the Project Settings dialog box and change to the "Post-Build Step" tab (it's on the far right, you'll need to scroll over to see it!)

> Add a description such as "Updating DLL..." to indicate what's going on; this message gets printed to the Build output window in Developer Studio when these commands are executed. Then, add the following two commands to the "Post-build command(s)" list:

> `REPLACE C:\src\fox\lib\foxdlld.dll /U Debug`
> `IF NOT EXIST Debug\foxdlld.dll COPY C:\src\fox\lib\foxdlld.dll Debug`

You should, of course, use the correct path to the DLL for your FOX installation. You should also be sure to copy the release build of the DLL (named `foxdll.dll`) to your project's `Release` subdirectory, if that's the configuration you're configuring.
1. You may want to add the fox or foxdll project (`fox.DSP` or `foxdll.DSP`) to your own workspace, and configure a dependency from your application's project to the appropriate library's project. You can do this by selecting the Dependencies... option from the Project pulldown menu, to open the Project Dependencies dialog box. That way you can simply unpack a new FOX drop over the existing tree and your project will first re-compile the new files before compiling your project.

Using the MinGW Compilers.

The FOX library, and FOX-based applications, can now be built using the MinGW compilers and related Unix-like tools. If you are not familiar with this development option, but would like to know more, I recommend starting with the MinGW FAQ list.

Disclaimer. The process described here has been tested using the most recent release of the Cygwin tools (i.e. the 1.1.x series) and the MinGW tools, under Windows 2000.

To get started, you will need to download and install the following packages:

- The Cygwin tools, or some reasonable substitute. You will at least need a bash-compatible shell and GNU make version 3.76.1 or earlier;
- The latest MinGW distribution; and,
- The latest FOX distribution;

If you want to use OpenGL, you'll also need to download the OpenGL header files MinGW; they are not a standard part of the packages listed above. Check the MinGW FAQ list for more information about how to develop OpenGL applications using MinGW.

Now, because of some problems with the version of make distributed with MinGW (currently, make-3.77) you'll need to use an earlier version of make, such as the one distributed with the Cygwin tools (make-3.76.1). Ensure that the correct version of make is picked up by either renaming or deleting the version of make distributed with MinGW.

Next, unpack the FOX distribution somewhere by typing, e.g.,

> `tar xzf fox-0.99.149.tar.gz`

and then go to the top-level directory of the FOX distribution and type:

> `./configure`

If `configure` stops rather quickly, right after it prints the message about "checking whether make sets ${MAKE}", it's picking up the wrong version of make (see the notes a few paragraphs earlier).

Once `configure` is finished doing its thing, and assuming there were no errors, build the library and supporting executables by typing:

> `make`

and then sit back and wait ;)

Copyright © 1997,2001 Jeroen van der Zijp, All Rights Reserved.