Linux Platform Guide

The Linux backend uses GTK3 (C) for all native widgets, with Cairo for custom drawing. It is written in pure C and compiled with GCC, providing a native Linux experience that integrates with GNOME, XFCE, KDE, and other GTK-compatible desktop environments.

Architecture Overview

Native Window Creation

Every HarbourBuilder form is a GtkWindow with a GtkFixed container for absolute-positioned child controls. The backend creates GTK widgets and stores their pointers in a handle table:

// gtk3_backend.c - Creating a form window
HB_FUNC( UI_FORMNEW )
{
   const char * cTitle = hb_parc( 1 );
   gint nWidth  = hb_parni( 2 );
   gint nHeight = hb_parni( 3 );

   GtkWidget * window = gtk_window_new( GTK_WINDOW_TOPLEVEL );
   gtk_window_set_title( GTK_WINDOW( window ), cTitle );
   gtk_window_set_default_size( GTK_WINDOW( window ), nWidth, nHeight );
   gtk_window_set_position( GTK_WINDOW( window ), GTK_WIN_POS_NONE );

   // Use GtkFixed for absolute positioning of child controls
   GtkWidget * fixed = gtk_fixed_new();
   gtk_container_add( GTK_CONTAINER( window ), fixed );

   // Store handle in Harbour-side object table
   hb_retnint( (gintptr) window );
}

Controls map to GTK3 widgets:

Event Handling (g_signal)

The GTK3 backend uses GObject's signal system (g_signal_connect()) to connect native widget events to Harbour event handlers:

// gtk3_backend.c - Signal-based event binding
HB_FUNC( UI_ONEVENT )
{
   gint nHandle = hb_parnint( 1 );
   gint nEventId = hb_parnint( 2 );
   PHB_ITEM pBlock = hb_param( 3, HB_IT_BLOCK );

   GtkWidget * widget = GTK_WIDGET( GetHandlePtr( nHandle ) );

   // Store the Harbour code block
   StoreEventBlock( nHandle, nEventId, pBlock );

   // Connect the GTK signal to our dispatch function
   switch( nEventId )
   {
      case EVENT_CLICK:
         g_signal_connect( widget, "clicked",
                           G_CALLBACK( on_clicked_signal ),
                           GINT_TO_POINTER( nHandle ) );
         break;

      case EVENT_CHANGE:
         g_signal_connect( widget, "changed",
                           G_CALLBACK( on_changed_signal ),
                           GINT_TO_POINTER( nHandle ) );
         break;

      case EVENT_KEYDOWN:
         g_signal_connect( widget, "key-press-event",
                           G_CALLBACK( on_key_signal ),
                           GINT_TO_POINTER( nHandle ) );
         break;

      case EVENT_MOUSEDOWN:
         g_signal_connect( widget, "button-press-event",
                           G_CALLBACK( on_mouse_signal ),
                           GINT_TO_POINTER( nHandle ) );
         break;

      // ... additional signal connections
   }
}

// Signal callback dispatches to Harbour
static void on_clicked_signal( GtkWidget * widget, gpointer user_data )
{
   gint nHandle = GPOINTER_TO_INT( user_data );
   FireEvent( nHandle, EVENT_CLICK );
}

Dark Mode

GTK3 dark mode is controlled via GTK settings:

• gtk-application-prefer-dark-theme — The backend sets this GTK property to TRUE when the system is in dark mode. GTK3 themes (like Adwaita-dark) respond by providing dark color schemes for all widgets.
• GTK settings daemon — On desktop environments that support it (GNOME, XFCE), GTK3 reads the system theme preference from the settings daemon automatically.
• Manual override — Users can force dark mode by setting the environment variable:

  export GTK_THEME=Adwaita:dark

• CSS styling — For fine-grained control, the backend can load a GTK CSS stylesheet that overrides widget colors for the dark theme.

// gtk3_backend.c - Dark theme setup
void SetupDarkTheme( void )
{
   GtkSettings * settings = gtk_settings_get_default();

   // Check system theme preference
   gboolean prefer_dark = IsSystemDarkMode();

   g_object_set( settings,
                 "gtk-application-prefer-dark-theme",
                 prefer_dark,
                 NULL );
}

Scintilla Integration

On Linux, Scintilla 5.6.1 is built as a shared library:

Scintilla is loaded with dlopen() and dlsym() at runtime. The GTK Scintilla widget (ScintillaObject) is embedded in the code editor tab:

// Loading Scintilla on Linux
void * hSci = dlopen( "libscintilla.so", RTLD_LAZY );
if( !hSci ) {
   fprintf( stderr, "Failed to load Scintilla: %s\n", dlerror() );
   return;
}

// Creating the Scintilla GTK widget
ScintillaObject * sci = scintilla_new();
gtk_container_add( GTK_CONTAINER( editor_scrolled ), GTK_WIDGET( sci ) );
scintilla_send_message( sci, SCI_SETLEXER, SCLEX_CPP, 0 );

Build Process

Prerequisites

1. GCC compiler:

   sudo apt install gcc g++

2. GTK3 development libraries:

   sudo apt install libgtk-3-dev

3. WebKit2GTK (optional, for TWebView):

   sudo apt install libwebkit2gtk-4.1-dev

   Without this package, TWebView controls display a placeholder. The build script auto-detects WebKit2GTK and enables it when available.

4. Harbour 3.2+ — Install from your distro's package manager or build from source:

   sudo apt install harbour

   Or clone from github.com/harbour/core.

Build Script (build_linux.sh)

The script performs these steps:

1. Check prerequisites — Verifies that GCC and GTK3 headers are available.
2. Build Scintilla — Compiles Scintilla and Lexilla shared libraries from source.
3. Compile Harbour source — Runs the Harbour compiler on the IDE source files.
4. Compile the backend — Compiles gtk3_backend.c with GCC.
5. Link — Links everything together with GTK3, Cairo, Pango, and the Harbour runtime.

# build_linux.sh - Typical build session on Ubuntu/Debian
# Install dependencies
sudo apt update
sudo apt install libgtk-3-dev gcc g++ harbour

# Build
cd HarbourBuilder/samples
./build_linux.sh

# Run
../bin/hbbuilder_linux

Compilation Details

# Manual compilation (what build_linux.sh does internally)
# 1. Compile Harbour source to C
harbour hbbuilder.prg -n -q -gc1

# 2. Compile C backend
gcc -O2 -c gtk3_backend.c \
    $(pkg-config --cflags gtk+-3.0) \
    -I$HBDIR/include \
    -I./include

# 3. Compile Harbour-generated C code
gcc -O2 -c hbbuilder.c \
    -I$HBDIR/include

# 4. Link
gcc -o hbbuilder_linux hbbuilder.o gtk3_backend.o \
    $(pkg-config --libs gtk+-3.0) \
    -lcairo -lpango-1.0 \
    -lscintilla -llexilla \
    -L$HBDIR/lib -lharbour \
    -ldl -lm

Platform-Specific Features

WebView Support (WebKit2GTK)

The TWebView control provides an embedded web browser using WebKit2GTK. The build script automatically detects the library and enables it at compile time.

Installation

# Ubuntu / Debian
sudo apt install libwebkit2gtk-4.1-dev

# Fedora
sudo dnf install webkit2gtk4.1-devel

# Arch Linux
sudo pacman -S webkit2gtk-4.1

Build Detection

The build_linux.sh script automatically detects WebKit2GTK:

• If pkg-config --exists webkit2gtk-4.1 succeeds: compiles with -DHAVE_WEBKIT2GTK and links against WebKit2GTK 4.1.
• Falls back to webkit2gtk-4.0 if 4.1 is not available.
• Without either package: TWebView shows a placeholder label instead of web content.

After installing the dev package, force a rebuild of the GTK3 backend:

rm -f source/gtk3_core.o
./build_linux.sh

You should see:

  WebKit2GTK 4.1 detected — WebView enabled

Supported Functions

Example

// WebView in a form
@ 44, 0 WEBVIEW ::oWebView1 OF Self SIZE 800, 500 URL "https://harbour.github.io"

// Navigate programmatically
::oWebView1:Navigate( "https://github.com" )

// Execute JavaScript
::oWebView1:EvaluateJS( "document.title" )

Known Limitations

• Desktop environment variance — GTK3 widgets look different on GNOME, XFCE, KDE, etc. The backend targets the default Adwaita theme. Other themes may produce slightly different appearances.
• GtkFixed layout &mdash> The backend uses GtkFixed for absolute positioning (matching the Windows/macOS model). This means controls do not automatically resize or reflow when the window size changes. Use the OnResize event for dynamic layout.
• Scintilla shared library &mdash> The libscintilla.so must be in the library search path (LD_LIBRARY_PATH or /usr/local/lib). Run sudo ldconfig after installing.
• Wayland &mdash> GTK3 supports Wayland, but some features (system tray, global menus) may not work under pure Wayland sessions. X11 is fully supported.

Dependencies