GitHub FLTK Project   FLTK News RSS Feed  
  FLTK Apps      FLTK Library      Forums      Links     Login 
 Home  |  Articles & FAQs  |  Bugs & Features  |  Documentation  |  Download  ]

2 - FLTK Basics

This chapter teaches you the basics of compiling programs that use FLTK.

Writing Your First FLTK Program

All programs must include the file <FL/Fl.H>. In addition the program must include a header file for each FLTK class it uses. Listing 1 shows a simple "Hello, World!" program that uses FLTK to display the window.

After including the required header files, the program then creates a window. All following widgets will automatically be children of this window.

Then we create a box with the "Hello, World!" string in it. FLTK automatically adds the new box to window, the current grouping widget.

    Fl_Box *box = new Fl_Box(20,40,260,100,"Hello, World!");

Next, we set the type of box and the size, font, and style of the label:

We tell FLTK that we will not add any more widgets to window.


Finally, we show the window and enter the FLTK event loop:

The resulting program will display the window in Figure 2-1. You can quit the program by closing the window or pressing the ESCape key.

Hello, World! Window
Figure 2-1: The Hello, World! Window

Creating the Widgets

The widgets are created using the C++ new operator. For most widgets the arguments to the constructor are:

    Fl_Widget(x, y, width, height, label)

The x and y parameters determine where the widget or window is placed on the screen. In FLTK the top left corner of the window or screen is the origin (i.e. x = 0, y = 0) and the units are in pixels.

The width and height parameters determine the size of the widget or window in pixels. The maximum widget size is typically governed by the underlying window system or hardware.

label is a pointer to a character string to label the widget with or NULL. If not specified the label defaults to NULL. The label string must be in static storage such as a string constant because FLTK does not make a copy of it - it just uses the pointer.

Creating Widget hierarchies

Widgets are commonly ordered into functional groups, which in turn may be grouped again, creating a hierarchy of widgets. FLTK makes it easy to fill groups by automatically adding all widgets that are created between a myGroup->begin() and myGroup->end(). In this example, myGroup would be the current group.

Newly created groups and their derived widgets implicitly call begin() in the constructor, effectively adding all subsequently created widgets to itself until end() is called.

Setting the current group to NULL will stop automatic hierarchies. New widgets can now be added manually using Fl_Group::add(...) and Fl_Group::insert(...).

Get/Set Methods

box->box(FL_UP_BOX) sets the type of box the Fl_Box draws, changing it from the default of FL_NO_BOX, which means that no box is drawn. In our "Hello, World!" example we use FL_UP_BOX, which means that a raised button border will be drawn around the widget. You can learn more about boxtypes in Chapter 3.

You could examine the boxtype in by doing box->box(). FLTK uses method name overloading to make short names for get/set methods. A "set" method is always of the form "void name(type)", and a "get" method is always of the form "type name() const".

Redrawing After Changing Attributes

Almost all of the set/get pairs are very fast, short inline functions and thus very efficient. However, the "set" methods do not call redraw() - you have to call it yourself. This greatly reduces code size and execution time. The only common exceptions are value() which calls redraw() and label() which calls redraw_label() if necessary.


All widgets support labels. In the case of window widgets, the label is used for the label in the title bar. Our example program calls the labelfont, labelsize, and labeltype methods.

The labelfont method sets the typeface and style that is used for the label, which for this example we are using FL_BOLD and FL_ITALIC. You can also specify typefaces directly.

The labelsize method sets the height of the font in pixels.

The labeltype method sets the type of label. FLTK supports normal, embossed, and shadowed labels internally, and more types can be added as desired.

A complete list of all label options can be found in Chapter 3.

Showing the Window

The show() method shows the widget or window. For windows you can also provide the command-line arguments to allow users to customize the appearance, size, and position of your windows.

The Main Event Loop

All FLTK applications (and most GUI applications in general) are based on a simple event processing model. User actions such as mouse movement, button clicks, and keyboard activity generate events that are sent to an application. The application may then ignore the events or respond to the user, typically by redrawing a button in the "down" position, adding the text to an input field, and so forth.

FLTK also supports idle, timer, and file pseudo-events that cause a function to be called when they occur. Idle functions are called when no user input is present and no timers or files need to be handled - in short, when the application is not doing anything. Idle callbacks are often used to update a 3D display or do other background processing.

Timer functions are called after a specific amount of time has expired. They can be used to pop up a progress dialog after a certain amount of time or do other things that need to happen at more-or-less regular intervals. FLTK timers are not 100% accurate, so they should not be used to measure time intervals, for example.

File functions are called when data is ready to read or write, or when an error condition occurs on a file. They are most often used to monitor network connections (sockets) for data-driven displays.

FLTK applications must periodically check (Fl::check()) or wait (Fl::wait()) for events or use the Fl::run() method to enter a standard event processing loop. Calling Fl::run() is equivalent to the following code:

    while (Fl::wait());

Fl::run() does not return until all of the windows under FLTK control are closed by the user or your program.

Compiling Programs with Standard Compilers

Under UNIX (and under Microsoft Windows when using the GNU development tools) you will probably need to tell the compiler where to find the header files. This is usually done using the -I option:

    CC -I/usr/local/include ...
    gcc -I/usr/local/include ...

The fltk-config script included with FLTK can be used to get the options that are required by your compiler:

    CC `fltk-config --cxxflags` ...

Similarly, when linking your application you will need to tell the compiler to use the FLTK library:

    CC ... -L/usr/local/lib -lfltk -lXext -lX11 -lm
    gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm

Aside from the "fltk" library, there is also a "fltk_forms" library for the XForms compatibility classes, "fltk_gl" for the OpenGL and GLUT classes, and "fltk_images" for the image file classes, Fl_Help_Dialog widget, and system icon support.


The libraries are named "fltk.lib", "fltkgl.lib", "fltkforms.lib", and "fltkimages.lib", respectively under Windows.

As before, the fltk-config script included with FLTK can be used to get the options that are required by your linker:

    CC ... `fltk-config --ldflags`

The forms, GL, and images libraries are included with the "--use-foo" options, as follows:

    CC ... `fltk-config --use-forms --ldflags`
    CC ... `fltk-config --use-gl --ldflags`
    CC ... `fltk-config --use-images --ldflags`
    CC ... `fltk-config --use-forms --use-gl --use-images --ldflags`

Finally, you can use the fltk-config script to compile a single source file as a FLTK program:

    fltk-config --compile filename.cpp
    fltk-config --use-forms --compile filename.cpp
    fltk-config --use-gl --compile filename.cpp
    fltk-config --use-images --compile filename.cpp
    fltk-config --use-forms --use-gl --use-images --compile filename.cpp

Any of these will create an executable named filename.

Compiling Programs with Microsoft Visual C++

In Visual C++ you will need to tell the compiler where to find the FLTK header files. This can be done by selecting "Settings" from the "Project" menu and then changing the "Preprocessor" settings under the "C/C++" tab. You will also need to add the FLTK (FLTK.LIB or FLTKD.LIB), the Windows Common Controls (COMCTRL32.LIB), and WinSock (WSOCK32.LIB) libraries to the "Link" settings.

You can build your Microsoft Windows applications as Console or WIN32 applications. If you want to use the standard C main() function as the entry point, FLTK includes a WinMain() function that will call your main() function for you.

Note: The Visual C++ 5.0 optimizer is known to cause problems with many programs. We only recommend using the "Favor Small Code" optimization setting. The Visual C++ 6.0 optimizer seems to be much better and can be used with the "optimized for speed" setting.


All public symbols in FLTK start with the characters 'F' and 'L':

  • Functions are either Fl::foo() or fl_foo().
  • Class and type names are capitalized: Fl_Foo.
  • Constants and enumerations are uppercase: FL_FOO.
  • All header files start with <FL/...>.

Header Files

The proper way to include FLTK header files is:

    #include <FL/Fl_xyz.H>

Case is significant on many operating systems, and the C standard uses the forward slash (/) to separate directories. Do not use any of the following include lines:

    	#include <FL\Fl_xyz.H>
    	#include <fl/fl_xyz.h>
    	#include <Fl/fl_xyz.h>

User Comments [ Add Comment ]

From Anonymous, 13:31 Jul 18, 2005 (score=5)

CC `fltk-config --cxxflags`
CC ... `fltk-config --ldflags`

it is important to mention that in the second command line, your own compiled .o-Files (from .cpp) must be _before_ `fltk-config --ldflags`, otherwise you might get "linker unresolved symbols"

(this is because `fltk-config --ldflags` expands to "-lfltk -lole32 -luuid -lcomctl32 -lwsock32 -lsupc++" etc, order might be important, see man g++, option "-l")
Reply ]

From jsaacmk, 09:19 Sep 18, 2005 (score=4)

When Fl::run() is completed, it does not delete the memory you allocated for your controls with new. So, you must delete them manually or else have a memory leak (which probably wouldn't be too serious on modern systems that can manage it, but do you want to write crappy code? I didn't think so).
Reply ]

From Aaron Michaux, 17:02 Jan 13, 2004 (score=4)

If you're using OS X, and you have touble selecting the window... In OS X you must attach a resource to an executable before the window manager will let you use the executable's windows. After compiling the tutorial, you must run /Developer/Tools/Rez -t APPL -o executable_name /usr/local/include/FL/mac.r
Reply ]

From Anonymous, 10:53 Oct 29, 2004 (score=4)

At least in fltk 1.1.5 (don't know about earlier versions), the MacOSX port's fltk-config has the option "--post" that attaches the resource fork to the executable: "fltk-config --post executable".

It would be nice if this was mentioned in the HTML documentation.
Reply ]

From Michael . Henry AT LPCorp . com, 21:36 Apr 08, 2004 (score=1)

In Dev-C++, I had to do two things to get the hello world to work.

1)  Click Tools, Compiler Options.  Remove the Check by "Use fast but imperfect dependency generation."

2)  Click the TAB "Libraries" and add the line "C:\Dev-Cpp\include\FL" and then click add.  Click OK.  Now it compiles!
Reply ]

From mrgibson, 08:28 Jan 21, 2003 (score=4)

For cygwin, use the sourcecode in the standart tar.gz source file and do a simple ./configure && make && make install

Its work very well (tested with 1.1.x)
Reply ]

From jcongote, 18:50 Sep 07, 2006 (score=3)

Under Code::Blocks you need to add this libs to compile:

libfltk_images.a libfltk.a libfltk_forms.a libfltk_gl.a libwsock32.a libgdi32.a libuuid.a libole32.a

Maybe for a bigger program than the example is possible to need more libs, but with that I compile the example.

Reply ]

From gregd, 15:26 Mar 11, 2006 (score=3)

It would be nice if fltk-config got installed by `make install`.  It doesn't under fltk 1.1.7 on Mac OS/X, and running it in the fltk directory is kind of useless (I want the paths to the installed include / libs / etc, not just to be told that '.' i one of the include paths).
Reply ]

From mike, 16:25 Mar 11, 2006 (score=3)

fltk-config *does* get installed by the top-level Makefile:

        -mkdir -p $(DESTDIR)$(bindir)
        $(RM) $(DESTDIR)$(bindir)/fltk-config
        -cp fltk-config $(DESTDIR)$(bindir)
        -chmod 755 $(DESTDIR)$(bindir)/fltk-config
Reply ]

From gregd, 17:33 Mar 12, 2006 (score=3)

You're right.  It turns out that the problem is that /usr/local/bin isn't in my PATH. :-(
Reply ]

From Iain Duncan, 19:23 Jul 31, 2004 (score=3)

When using FLTK under mingw I found that the only trip up is that the fltk-config script doesn't find the right directories for include files and library files. ( it still says /usr/local/include ) The best way for me was to make fltk, ( which worked fine ), copy the fltk include files and libfiles to my msys include and lib directories, run fltk-config to show me the flags I needed, and then use my own make file replacing the directories reported by fltk-config with the actual directories necessary. On my install these were from the root msys directory: /mingw/include and /mingw/lib

Other than that it was pretty easy and I'm a newbie to gcc and mingw, well done!
Reply ]

From InfiniteJobu, 11:35 Jun 08, 2004 (score=3)

When developing for Windows while using Cygwin, you must be careful to who you distribute the program to.  If you use the gcc compiler under cygwin, to run that program on another windows box you will need the Cygwin DLL.  There is a flag that allows you to link directly to the Win32 libraries "-mno-cygwin", but I had trouble with this flag.  I opted to use the MinGW Unix emulation environment.  When you use the GCC  compiler in MinGW it does not rely on the Cygwin DLL and should be portable to other windows boxes.
Reply ]

From sparky, 06:04 Sep 01, 2005 (score=3)

To use Cygwin with the "-mno-cygwin" option (and you are are making use of image libraries) make sure local versions of the jpeg, zlib, and png libraries are being used.

to do so add the following linking options to compile:
  -L../lib -lfltk_png -lfltk_z -lfltk_jpeg

as well as the following include options:
  -I -I../png -I../jpeg -I../zlib

I have also seen instances where you must force MS VC++ 6.0 to use the local versions of the zlib, png, and jpeg libs (or remove all refereces to these libs) to compile correctly
Reply ]

From Lars R., 23:03 Aug 29, 2002 (score=3)

It would be nice if here was added some tips about FLTK under the Cygwin envidonment because it is a mixture between Windows and Un*x "features" and using FLTK on this platform is a little bit tricky...
Reply ]

From Wee Jin Goh, 07:42 Feb 07, 2003 (score=4)

I've found using fltk under Cygwin to be just the same as on Unix. Run ./configure and make and you're set.
Reply ]

From josh2112, 08:08 Jan 19, 2007 (score=2)

Are you getting the following message:

"This application has failed to start because the application configuration is incorrect. Reinstalling application may fix this problem."

while trying to run a FLTK app compiled with Visual Studio 2005 (VS8) on another machine? Me too... see this post:
Reply ]

From Misha, 09:57 Oct 20, 2004 (score=2)

To use fltk with VC .NET (ver. 7), I had to ignore "LIBC.lib" and "LIBCD.lib", note the case! Typing these names in lowercase wouldn't work.. strange.

To fix the unresolved dependency FL::wait(), had to include wsock32.lib. Here's the full list of additional libs: fltk.lib comctl32.lib fltkgl.lib opengl32.lib glu32.lib wsock32.lib
Reply ]

From BJS, 14:48 Oct 26, 2004 (score=3)

Try setting "Ignore Specific Library" to "libc" with no ".lib". This seems to work without needing upper case.
Reply ]

From happyslinky happyslinkySPAM_BAD, 23:20 Jan 17, 2003 (score=2)

if you're compiling in visual studio 6 and get this error: fltkd.lib(Fl_x.obj) : error LNK2001: unresolved external symbol __imp___TrackMouseEvent@4

you need to include comctl32.lib (project->settings->link->object/library modules to add it)
Reply ]

From Anonymous, 08:59 Jun 30, 2004 (score=1)

I'm having trouble getting FLTK to work with the Dev-C++ program. I've installed the packages and included what I think are the right files. Anything else I need to do to get this working?
Reply ]

From JKL, 16:16 May 15, 2004 (score=1)

I downloaded FLTK and used the .NET solution provided.  When I compiled it, I got errors saying:

resize fatal error C1083: Cannot open source file: '\fltk-1.1.5rc1\test\resize.cxx': No such file or directory

There is no test\resize.cxx; however, there is a test\resize.fl.  This happened for all the files in the test directory with .fl extensions.

I also got many unresolved external errors, but I believe that is due to not being able to open these files

How do I correct this?

Reply ]

From Anonymous, 14:45 Oct 26, 2004 (score=3)

If you are using MSVC .NET, be sure to use the fltk.sln in the vcnet directory and NOT the visualc directory. This will avoid the errors reported by JKL.
Reply ]

From Matthias, 23:35 Jun 18, 2004 (score=1)

The VisualC6 project file (we do not provide a .Net project) compiles 'fluid' first, which in turn should convert all .fl files int .cxx and .h files. This may be broken on your version of .NET . You can manually run fluid to generate the needed files. A contribution of a working .NET project file would help.
Reply ]

From Gregory Alan Hildstrom, 08:56 May 21, 2003 (score=1)

I got fltk 1.1.3 to work with Microsoft Visual C++ 6.0 and Windows 2000. Here are the guidelines I picked up to get it to work.

Everything you build and link together must be the same: either release or debug and either single or multithreaded. Fltk needs multithreading to work and it is enabled by default for fltk; which can be found under Project->Settings->C++ drop-down to Code Generation. This means that your project probably needs multithreading enabled to link properly to fltk.

I built fltkd.lib with no problems.

I ran into a bunch of unresolved externals while trying to link my program, HVDASGUI, to fltk. I added two libraries to link to under Project->Settings->Link: ws2_32.lib and comctl32.lib, which eliminated the unresolved externals. I also had to ignore libcd.lib, which can be set in the Link drop-down category Input.

After fixing the linked libraries, libraries to skip, and multithreading, HVDASGUI built and ran just fine.
Reply ]

From Melvin Quintos, 01:26 Oct 23, 2002 (score=1)

For visual studio 6.0: If you use any functions to output to the console (stdio.h or iostream.h), you may need to ignore libcd,libcmtd and also make sure you use the "Debug or Release Multithreaded DLL" run-time library under Project Settings -> C/C++.  In my experience, single-threaded crashes.
Reply ]


Comments are owned by the poster. All other content is copyright 1998-2021 by Bill Spitzak and others. This project is hosted by The FLTK Team. Please report site problems to ''.