FLTK Tutorial

CS 559 Introduction to Computer Graphics
Instructor: Dr. Gleicher
TA: Elizabeth Osten

1 Introduction

To do your programming assignments and projects for CS559, you will need some way to put windows on the screen, get input from the user, display information, .... While doing this kind of "engineering" isn't graphics per se, it is a necessary evil in an introductory course: it's of little use to make pictures if you can't show them to the user.

In practice, it doesn't matter what tools you use to create your programs. However, we have to pick something to give to you and support. We have chosen the FlTk interface toolkit. FlTk (pronounced fulltick) is an open source user interface toolkit that runs on many platforms, including Windows and Linux. FlTk was designed by graphics programmers (originally by some people at a special effects studio) to help them build graphics programs.

The advantage of FlTk is that it is simple to get simple things done. If FlTk seems complicated to you, you should see what the alternatives look like.

The first problem that you will face in using FlTk is simply compiling a program using it. This is more a statement about the complexities of the Microsoft Visual Studio tools in the CSL computing environment, than of FlTk.

This tutorial shows how to construct GUI (Graphical User Interface) applications using FLTK with Microsoft Visual Studios .NET. Note: This is neither a detailed nor a complete documentation for the FLTK library or Microsoft Visual Studios .NET.  Instead, it walks you through the process of building a program with fltk in the UW CSL software environment.

For complete documentation, please check http://www.fltk.org/, or locally at S:\fltk\i386_win2k\documentation\.  Since this documentation is intended for the students in the Graphics class only, we assume that you are using the instructional Windows 2000 stations in the CSL labs.

2 FLTK libraries

Before you even create your project, you should set up an environment variable that points to the fltk libraries. When you create your project, you will use this to link your project to the fltk libraries. Each computer in B240 has fltk installed on it. The fltk directories are in c:\Program Files\fltk-1.1.4.2\vs7.  Use explorer to examine the vs7 folder and see all of the stuff available to you. The lib folder in the vs7 directory contains the fltk libraries.

Set the environment variable and then close the my computer windows before starting visual studios, otherwise visual studios won't know about FLTKHOME!

In order to run an FLTK program, the FLTK binaries directory must be in your path. (FlTK is configured to link to your program dynamically). To do this, add the FlTk binaries directory "c:\Program Files\fltk-1.1.4.2\vs7\bin" to your PATH environment variable. Use the method described above to set the environment variable under Windows 2000.

Note: there is both a "system" PATH environment variable (that you cannot change), and a "user" environment variable (that you can change).

3 Creating A New FLTK Project

Older versions of Microsoft Visual Studios would have called this creating a workspace. Thanks to Microsoft's consistent naming scheme, the latest Visual Studios version, called .NET (also know as 7.1) has solutions. A solution contains any number of projects. Projects contain classes in source (.cpp) and header (.h) files.

1. Open the Microsoft Visual Studios .NET application by selecting Start->Programs->Microsoft Visual Studios .NET 2003 [or Microsoft Visual Studio .NET 2003]->Microsoft Visual Studios .NET 2003.
2. Choose File->New -> Blank Solution .
3. A "New Project" dialog box appears
4. Under "Project Types" select Visual C++ Projects -> Win32
5. Under "Templates" select "Win32 Console Project"
6. Choose a location and name for the new project.
7. Click "Ok"
8. "Win32 Application Wizard" dialog box pops up
9. Click on "Application Settings"
10. "Application Type" is "Console Application"
11. Under "Additional Options" choose "Empty Project"
12. Click "Finish".

This process should create a new directory with "name" at your specified location containing the project files, and open the project up in the Microsoft Visual Studios .NET program.

Note: One big advantage of FlTk over some of the other UI toolkits is that it can be built into a console application. That means that all of the C++ standard I/O stuff you used under Unix (like printf or cout) can be used in your programs.

4 Add a blank file to your project

To start this homework assignment, add an empty C++ source file to your project.

1.      In the main menu, choose View -> Solution Explorer

2.      Right click on the project you just created.

3.      Choose Add -> Add New Item

4.      Under categories, choose Visual C++ -> Code

5.      Choose "C++ file (.cpp)"

6.      Give the file a name, the default location is probably correct

7.      Click "Open"

5 Configure your project to be a FLTK project

1. Select Project -> <project name> Properties...
2. Set "Configuration:" to  "All Configurations"
3. Under the "Configuration Properties" folder, select C/C++ -> General
4. In the "Additional Include Directories" space on the right, type "$(FLTKHOME)" (Without the quotation marks)
5. On the left, choose Linker -> General
6. On the right, by "Additional Libraries Directory", type "$(FLTKHOME)/lib"
7. Set "Configuration:" to debug
8. Click "Yes"  when the dialog box asks if you'd like to save the properties you just set.
9. On the left, select the "c++ -> Preprocessor" tab
10. Add the symbol "FL_DLL" to the "Preprocessor Definitions" list (its a list of symbols).
11. On the left, choose Linker -> Input
12. On the right, type "fltkdlld.lib" in the "Additional Dependencies" space.
13. Set "Configuration:" to release
14. Click "Yes"  when the dialog box asks if you'd like to save the properties you just set.
15. Add "FL_DLL" to the preprocessor definitions here too.
16. On the left, choose Linker -> Input
17. On the right, type "fltkdll.lib" in the "Additional Dependencies" space.
18. OK, your 're done with the linking stuff!

6 Get some Code

The most basic C++ code you can try to run is the following line:

void main( ) { }

Typing that line into your .cpp file should let you make a program that builds and runs. (It does nothing, but at least it works!)

One working example program source code file is here.  You can try this file to make sure that all the options for the project are setup correctly. Just copy and paste this code into your .cpp file.

If this works, go nuts:

Add header files and more .cpp files to your project.  Go crazy, make cool stuff happen.

Here are a few more files you can try out. EventBox is a class that has code to create a box that does stuff when events happen. The events are things like dragging the mouse over the box and clicking on it. Save these files somewhere, then add them to your project by right clicking on your project in the solution explorer and adding an existing file.

• eventBox.h - header file for EventBox class
• eventBox.cpp - code source file for EventBox class
• window.cpp - contains main(). calls EventBox

1. Select Build -> Build <project name>. (Or right click on the project in the solution explorer, and select build there.)
2. Select Debug -> Start, or Debug -> Start Without Debugging
3. This should compile and link this project, and launch the new executable.
4. If during the Build process, error messages are generated, then there may be some problem with either your code or some settings that we have done.  For more details please refer to Trouble Shooting.
   

• Error that indicates FLTK library include/header file (.h files) not found during compilation

You did not set the "Additional Include Directories" path correctly for the FLTK library. Check "C/C++ -> General" under project properties. Also check that your environment variable was set correctly.

• Other compile errors

Most likely caused by some problem in your code.

See if your program builds when the only two lines in your .cpp file are "#include <FL/FL_Window.H>" and "void main( ) { }"

• Error/Crash during the execution of your program

Most likely caused by some problem in your code.

• If you need to include "stdafx.h" in order to compile, then you probably didn't create the project as an empty project, and have the default visual studios stuff in your files. You don't need that stuff. See 3.11 above.
  
• Visual studios can't find fltkdll.lib or fltkdlld.lib!

And you 're sure you set your environment variable correctly and everything! You have to set the environment variable and close the window before starting visual studios. Just close and restart visual studios. Make sure that the my computer properties window is closed - open it again and shut it again, it's really obnoxious, but it will stay open and hide on you if you don't close it properly.

• Make sure you use Visual Studios 2003 .NET, version 7.1
• Make sure you didn't copy and paste my earlier typo. IT's fltkdlld.lib, not flktdlld.lib.
• If nothing else works, log off and try a different computer. Sometimes things just need to get cleaned out.

Appendix B FAQ

This will be updated as questions arise.

Send questions to osten@cs.wisc.edu

Q: I'm getting errors like: "c:\Program Files\fltk-1.1.4.2\vs7\FL\Fl_Widget.H(156) : warning C4312: 'type cast' : conversion from 'long' to 'void *' of greater size"

A: Those are just warnings, and I get them too. So far I've just ignored them, and haven't had any problems. Type cast warnings are usually harmless. Here it's warning that code on line 156 in Fl_Widget.H is converting data into a type that takes up more memory than it needs. That shouldn't hurt anything.

Q: I'm getting errors like:
LNK2001: unresolved external symbol "public: static int Fl::e_keysym" (?e_keysym@Fl@@2HA)

A: You have not defined the FL_DLL preprocessor symbol.