Quick start

Build your first FLTK application in under 5 minutes

Quick start

Get up and running with FLTK in under 5 minutes. This guide walks you through creating a complete working application from scratch.

This guide assumes you have already installed FLTK. If not, follow the installation guide first.

Your first FLTK application

We’ll create a simple application with a button that responds to clicks - a perfect introduction to FLTK’s event-driven architecture.

1. Create the source file

   Create a new file called hello.cxx:

   hello.cxx

   #include <FL/Fl.H>
   #include <FL/Fl_Window.H>
   #include <FL/Fl_Box.H>
   
   int main(int argc, char **argv) {
     Fl_Window *window = new Fl_Window(340, 180);
     Fl_Box *box = new Fl_Box(20, 40, 300, 100, "Hello, World!");
     box->box(FL_UP_BOX);
     box->labelfont(FL_BOLD + FL_ITALIC);
     box->labelsize(36);
     box->labeltype(FL_SHADOW_LABEL);
     window->end();
     window->show(argc, argv);
     return Fl::run();
   }
   

   This creates a window with a styled text label.

2. Compile the application

   Using CMake

   Create CMakeLists.txt in the same directory:

   CMakeLists.txt

   cmake_minimum_required(VERSION 3.15)
   project(hello)
   
   # Point to your FLTK installation or build directory
   set(FLTK_DIR "/usr/local" CACHE FILEPATH "FLTK directory")
   
   find_package(FLTK CONFIG REQUIRED)
   
   add_executable(hello WIN32 MACOSX_BUNDLE hello.cxx)
   target_link_libraries(hello PRIVATE fltk::fltk)
   

   Build the application:

   cmake -B build
   cmake --build build
   

   If FLTK isn’t installed system-wide, set FLTK_DIR to your build directory:

   cmake -B build -D FLTK_DIR=/path/to/fltk/build
   

   Using fltk-config

   If you installed FLTK system-wide, use fltk-config:

   Linux/macOS:

   fltk-config --compile hello.cxx
   

   Or manually:

   g++ hello.cxx $(fltk-config --cxxflags --ldflags) -o hello
   

   Windows (MinGW):

   g++ hello.cxx -I/path/to/fltk -L/path/to/fltk/lib \
       -lfltk -lole32 -luuid -lcomctl32 -o hello.exe
   

   Manual compilation

   Linux:

   g++ hello.cxx \
     -I/path/to/fltk \
     -I/path/to/fltk/build \
     -L/path/to/fltk/build/lib \
     -lfltk -lX11 -lXext -lXft -lfontconfig -lpthread -ldl \
     -o hello
   

   macOS:

   clang++ hello.cxx \
     -I/path/to/fltk \
     -I/path/to/fltk/build \
     -L/path/to/fltk/build/lib \
     -lfltk \
     -framework Cocoa \
     -o hello
   

   Windows (Visual Studio):

   cl hello.cxx /I C:\path\to\fltk /I C:\path\to\fltk\build \
      /link /LIBPATH:C:\path\to\fltk\build\lib fltk.lib
   
3. Run the application

   # Linux/macOS
   ./build/hello
   
   # Windows
   .\build\Release\hello.exe
   

   You should see a window with “Hello, World!” displayed in a 3D box with shadow text.

   

Add interactivity

Let’s enhance the application with a button that responds to clicks:

button-demo.cxx

#include <FL/Fl.H>
#include <FL/Fl_Window.H>
#include <FL/Fl_Button.H>
#include <FL/Fl_Box.H>
#include <FL/fl_ask.H>

// Callback function executed when button is clicked
void button_callback(Fl_Widget *widget, void *data) {
  fl_message("Button clicked!");
}

int main(int argc, char **argv) {
  Fl_Window *window = new Fl_Window(320, 180, "Button Demo");
  
  // Create a button
  Fl_Button *button = new Fl_Button(110, 70, 100, 40, "Click Me");
  button->callback(button_callback);
  
  window->end();
  window->show(argc, argv);
  return Fl::run();
}

The callback function is called whenever the button is clicked. You can pass custom data through the second parameter.

Compile and run the same way:

cmake -B build
cmake --build build
./build/button-demo

Understanding the code

Let’s break down the key components:

Headers

#include <FL/Fl.H>           // Main FLTK header
#include <FL/Fl_Window.H>    // Window class
#include <FL/Fl_Button.H>    // Button widget

Common patterns

Layout management

FLTK uses absolute positioning by default, but you can make layouts responsive:

Fl_Window *window = new Fl_Window(400, 300, "Resizable");
Fl_Box *box = new Fl_Box(20, 20, 360, 260, "Content");
box->box(FL_DOWN_BOX);

window->resizable(box);  // Make box resize with window
window->end();
window->show();

Multiple widgets

Widgets are automatically added to the current window:

window->begin();  // Start adding widgets to window
  Fl_Button *btn1 = new Fl_Button(20, 20, 80, 25, "Button 1");
  Fl_Button *btn2 = new Fl_Button(20, 50, 80, 25, "Button 2");
  Fl_Button *btn3 = new Fl_Button(20, 80, 80, 25, "Button 3");
window->end();    // Stop adding widgets

Passing data to callbacks

struct AppData {
  int counter;
  Fl_Box *display;
};

void increment_callback(Fl_Widget *w, void *data) {
  AppData *app = (AppData*)data;
  app->counter++;
  char buf[32];
  sprintf(buf, "Count: %d", app->counter);
  app->display->label(buf);
}

int main() {
  AppData app = {0, nullptr};
  
  Fl_Window *win = new Fl_Window(200, 100);
  app.display = new Fl_Box(20, 20, 160, 25, "Count: 0");
  Fl_Button *btn = new Fl_Button(20, 50, 160, 30, "Increment");
  btn->callback(increment_callback, &app);
  
  win->end();
  win->show();
  return Fl::run();
}

Example programs

FLTK includes dozens of example programs. After building FLTK with FLTK_BUILD_EXAMPLES=ON:

# View all examples
ls build/bin/examples/

# Try some examples
./build/bin/examples/browser-simple
./build/bin/examples/table-simple
./build/bin/examples/menubar-add

Example source code is in /path/to/fltk/examples/.

Using FLUID designer

FLUID is FLTK’s visual interface designer. It generates C++ code from a visual layout:

1. Launch FLUID

   ./build/bin/fluid
   
2. Create interface

   1. File → New
   2. Add widgets from the menu (e.g., New → Window)
   3. Double-click widgets to set properties
   4. Drag to position and resize
3. Generate code

   1. Save as myapp.fl
   2. FLUID generates myapp.cxx and myapp.h
   3. Include in your project:

   #include "myapp.h"
   
   int main() {
     make_window()->show();
     return Fl::run();
   }
   

Project templates

CMake template

A complete CMake project structure:

myapp/
├── CMakeLists.txt
├── src/
│   └── main.cxx
└── include/
    └── myapp.h

CMakeLists.txt

cmake_minimum_required(VERSION 3.15)
project(MyApp VERSION 1.0)

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Find FLTK
find_package(FLTK CONFIG REQUIRED)

# Add executable
add_executable(myapp WIN32 MACOSX_BUNDLE
  src/main.cxx
)

target_include_directories(myapp PRIVATE include)
target_link_libraries(myapp PRIVATE fltk::fltk)

# For images/OpenGL support:
# target_link_libraries(myapp PRIVATE fltk::images fltk::gl)

Makefile template

For simple projects without CMake:

Makefile

CXX = g++
CXXFLAGS = $(shell fltk-config --cxxflags)
LDFLAGS = $(shell fltk-config --ldflags)

TARGET = myapp
SOURCES = main.cxx window.cxx
OBJECTS = $(SOURCES:.cxx=.o)

all: $(TARGET)

$(TARGET): $(OBJECTS)
	$(CXX) -o $@ $^ $(LDFLAGS)

%.o: %.cxx
	$(CXX) $(CXXFLAGS) -c $<

clean:
	rm -f $(OBJECTS) $(TARGET)

.PHONY: all clean

Next steps

Hello world deep dive

Detailed explanation of FLTK program structure

API reference

Complete documentation for all FLTK classes

Widget gallery

Explore all available widgets with examples

Examples

Browse real-world FLTK example programs

Troubleshooting

Linker errors about missing symbols

Make sure you’re linking all required libraries:

# For basic apps
target_link_libraries(myapp PRIVATE fltk::fltk)

# If using images
target_link_libraries(myapp PRIVATE fltk::images)

# If using OpenGL
target_link_libraries(myapp PRIVATE fltk::gl)

Cannot find FL/Fl.H

Ensure your include paths are correct:

# With CMake, fltk::fltk target handles this automatically

# Manual compilation - include both source and build dirs
g++ -I/path/to/fltk -I/path/to/fltk/build ...

Window doesn't appear

Always call these in order:

window->end();        // First
window->show();       // Second
return Fl::run();     // Third - enter event loop

Callback not called

Make sure you:

1. Assigned the callback: widget->callback(my_callback);
2. Entered event loop: Fl::run();
3. Widget is visible and not disabled