Docs / Getting Started / Architecture

Architecture

HarbourBuilder uses a layered architecture that cleanly separates application logic from platform-specific native code. This design enables a single .prg codebase to produce native applications on Windows macOS Linux.

5-Layer Architecture

Every HarbourBuilder application flows through five layers, from high-level xBase syntax down to platform-native API calls:

graph TB A["1. Application Code
.prg source files"] --> B["2. xBase Commands
#xcommand / #translate (compile-time)"] B --> C["3. Harbour OOP Layer
TForm, TControl, TToolBar, ..."] C --> D["4. HB_FUNC Bridge
UI_FormNew, UI_SetProp, UI_OnEvent"] D --> E1["5a. Win32 API
C++ · CreateWindowEx"] D --> E2["5b. Cocoa / AppKit
Objective-C · NSView"] D --> E3["5c. GTK3
C · GtkWidget"] D --> E4["5d. Android
JNI · android.widget.*"] D --> E5["5e. iOS / UIKit
Objective-C · UIView"] style A fill:#58a6ff,stroke:#388bfd,color:#0d1117 style B fill:#8b5cf6,stroke:#7c3aed,color:#fff style C fill:#f59e0b,stroke:#d97706,color:#0d1117 style D fill:#3fb950,stroke:#2ea043,color:#0d1117 style E1 fill:#0078d4,stroke:#005a9e,color:#fff style E2 fill:#555,stroke:#333,color:#fff style E3 fill:#e95420,stroke:#c34113,color:#fff style E4 fill:#34c759,stroke:#1a8d4d,color:#0d1117 style E5 fill:#007aff,stroke:#005ec4,color:#fff

Why five layers? The xBase command layer lets developers write familiar Clipper-style syntax. The OOP layer provides a consistent object model. The HB_FUNC bridge is the single point where Harbour meets C/C++/Obj-C, making it straightforward to add new backends without touching application code.

Platform Backends

Each layer maps to a different native technology depending on the target platform:

Layer	Windows	macOS	Linux	Android	iOS
Application Code	Harbour .prg	Harbour .prg	Harbour .prg	Harbour .prg	Harbour .prg
xBase Commands	hbbuilder.ch	hbbuilder.ch	hbbuilder.ch	UI_* direct (re-emitted by IDE)	UI_* direct (re-emitted by IDE)
OOP Layer	TForm, TControl	TForm, TControl	TForm, TControl	flat UI_* (iter 1, TForm next)	flat UI_* (iter 1, TForm next)
HB_FUNC Bridge	C++ (MSVC/MinGW)	Objective-C (Clang)	C (GCC)	C + JNI (NDK Clang)	Objective-C (Xcode Clang)
Native Backend	Win32 API / GDI+	Cocoa / AppKit	GTK3 / Cairo	android.widget.*	UIKit / UIView
Window Creation	CreateWindowEx()	[NSWindow alloc]	gtk_window_new()	FrameLayout in MainActivity	UIView in UIViewController
Event Loop	GetMessage / WndProc	[NSApp run]	gtk_main()	Activity lifecycle (OS-owned)	UIApplicationMain (OS-owned)
Drawing	GDI / GDI+	Core Graphics	Cairo / Pango	Canvas / Skia (Android)	Core Graphics (iOS)

Android and iOS are cross-compile targets, not hosts. The IDE itself still runs on Windows/macOS/Linux; it produces an APK or .app that runs on the device or simulator. See the Android platform guide and the iOS platform guide for the full build pipelines and Setup Wizards that install the toolchains automatically.

Control Type System

Every visual component in HarbourBuilder is identified by a numeric CT_ constant defined in hbide.h. These constants (ranging from 0 to 86) determine how the IDE serializes controls, how the designer renders them, and which native widget the backend creates at runtime.

Why numeric IDs? A simple integer type makes it fast to dispatch control creation across the C bridge and keeps the binary form format compact. The same IDs are used by the designer, the code generator, and the runtime.

Palette Tab	CT_ Range	Controls
Standard	0 – 11	CT_FORM (0), CT_LABEL (1), CT_EDIT (2), CT_BUTTON (3), CT_CHECKBOX (4), CT_COMBOBOX (5), CT_GROUPBOX (6), CT_LISTBOX (7), CT_RADIO (8), CT_TOOLBAR (9), CT_TABCONTROL (10), CT_STATUSBAR (11)
Additional	12 – 32	CT_BITBTN (12), CT_SPEEDBTN (13), CT_IMAGE (14), CT_SHAPE (15), CT_BEVEL (16), CT_SCROLLBOX (17), CT_MASKEDIT (18), CT_STRINGGRID (19), CT_MEMO (24), CT_PANEL (25), CT_SCROLLBAR (26), CT_STATICTEXT (31), CT_LABELEDEDIT (32)
Native	20 – 37	CT_TREEVIEW (20), CT_LISTVIEW (21), CT_PROGRESSBAR (22), CT_RICHEDIT (23), CT_TRACKBAR (34), CT_UPDOWN (35), CT_DATETIMEPICKER (36), CT_MONTHCALENDAR (37)
System	38 – 39	CT_TIMER (38), CT_PAINTBOX (39)
Dialogs	40 – 45	CT_OPENDIALOG (40), CT_SAVEDIALOG (41), CT_FONTDIALOG (42), CT_COLORDIALOG (43), CT_FINDDIALOG (44), CT_REPLACEDIALOG (45)
AI	46 – 52	CT_OPENAI (46), CT_GEMINI (47), CT_CLAUDE (48), CT_DEEPSEEK (49), CT_GROK (50), CT_OLLAMA (51), CT_TRANSFORMER (52)
Data Access	53 – 61	CT_DBFTABLE (53), CT_MYSQL (54), CT_MARIADB (55), CT_POSTGRESQL (56), CT_SQLITE (57), CT_FIREBIRD (58), CT_SQLSERVER (59), CT_ORACLE (60), CT_MONGODB (61)
Internet	62, 71 – 78	CT_WEBVIEW (62), CT_WEBSERVER (71), CT_WEBSOCKET (72), CT_HTTPCLIENT (73), CT_FTPCLIENT (74), CT_SMTPCLIENT (75), CT_TCPSERVER (76), CT_TCPCLIENT (77), CT_UDPSOCKET (78)
Threading	63 – 70	CT_THREAD (63), CT_MUTEX (64), CT_SEMAPHORE (65), CT_CRITICALSECTION (66), CT_THREADPOOL (67), CT_ATOMICINT (68), CT_CONDVAR (69), CT_CHANNEL (70)
Data-Aware	79 – 86	CT_BROWSE (79), CT_DBGRID (80), CT_DBNAVIGATOR (81), CT_DBTEXT (82), CT_DBEDIT (83), CT_DBCOMBOBOX (84), CT_DBCHECKBOX (85), CT_DBIMAGE (86)

File Structure

The HarbourBuilder project is organized into clearly separated directories:

HarbourBuilder/
├── backends/
│   ├── cocoa/          // macOS Objective-C backend
│   ├── gtk3/           // Linux GTK3/C backend
│   ├── win32/          // Windows C++ backend
│   ├── android/        // Android JNI + Java backend
│   ├── ios/            // iOS UIKit + Objective-C backend
│   ├── console/        // TUI console backend
│   └── web/            // Web/HTML backend
├── core/               // Harbour OOP classes (TForm, TControl, ...)
├── cpp/
│   ├── include/        // C/C++ headers (hbide.h with CT_ defines)
│   └── src/            // IDE C++ source (designer, inspector, editor)
├── docs/
│   ├── assets/         // CSS, JS, images for documentation
│   ├── en/             // English documentation
│   ├── es/             // Spanish documentation
│   └── pt/             // Portuguese documentation
├── harbour/            // Harbour compiler and runtime
├── images/             // IDE icons and bitmaps
├── include/            // Harbour headers (hbide.ch)
├── resources/
│   └── icons/          // Component palette icons
└── samples/
    └── projects/       // Example projects

Event System

HarbourBuilder routes native OS events through a unified pipeline that ends in user-defined Harbour code blocks. The same event flow applies on all platforms — only the entry point differs (WndProc on Windows, NSResponder on macOS, g_signal on GTK3, JNI nativeOnClick on Android, UIEvent on iOS).

sequenceDiagram participant User participant OS as Native OS participant WndProc as WndProc / NSResponder / g_signal / UIResponder participant Fire as FireEvent() participant Block as Harbour Code Block participant Code as User Code User->>OS: Click button OS->>WndProc: WM_COMMAND / action / clicked / touchUpInside WndProc->>Fire: FireEvent( hWnd, nMsg, CT_BUTTON ) Fire->>Block: Eval( oBtn:OnClick ) Block->>Code: { || MsgInfo("Hello!") } Code-->>User: Message box displayed

Event binding Events are bound by assigning a code block to a control property: oBtn:OnClick := { || DoSomething() }. The code generator writes these assignments automatically when you double-click a control in the form designer.

Two-Way Tools

HarbourBuilder maintains perfect synchronization between the visual designer and the source code. Changes in either direction are reflected instantly, and user-written METHOD implementations are never overwritten during code regeneration.

flowchart LR A["Form Designer
(visual)"] -- "drop control /
move / resize" --> B["Code Generator"] B -- "writes .prg" --> C["Source Code
(.prg file)"] C -- "parse changes" --> D["Code Parser"] D -- "updates objects" --> A B -. "preserves METHOD
implementations" .-> C D -. "detects new controls
and properties" .-> A style A fill:#58a6ff,stroke:#388bfd,color:#0d1117 style C fill:#3fb950,stroke:#2ea043,color:#0d1117 style B fill:#f59e0b,stroke:#d97706,color:#0d1117 style D fill:#f59e0b,stroke:#d97706,color:#0d1117

Direction	Trigger	Action
Designer → Code	Drop, move, resize, or change a property in the inspector	Code generator rewrites DEFINE FORM / @ commands, preserving all METHOD blocks
Code → Designer	Edit .prg source in the code editor and save	Code parser detects new/changed controls and updates the designer canvas in real time

Build Pipeline

The build process compiles Harbour source into native executables through a multi-stage pipeline:

graph LR A[".prg
Harbour source"] --> B["Harbour Compiler
(harbour.exe)"] B --> C[".c
Generated C code"] C --> D["C Compiler
(MSVC / Clang / GCC)"] D --> E[".obj / .o
Object files"] E --> F["Linker
(link / ld)"] G["Native Backend
(Win32 / Cocoa / GTK3 / Android JNI / iOS UIKit)"] --> F H["Harbour Runtime
(libharbour)"] --> F F --> I[".exe / app / ELF / APK / .app
Native binary"] style A fill:#58a6ff,stroke:#388bfd,color:#0d1117 style B fill:#8b5cf6,stroke:#7c3aed,color:#fff style C fill:#f59e0b,stroke:#d97706,color:#0d1117 style D fill:#8b5cf6,stroke:#7c3aed,color:#fff style E fill:#f59e0b,stroke:#d97706,color:#0d1117 style F fill:#3fb950,stroke:#2ea043,color:#0d1117 style G fill:#e95420,stroke:#c34113,color:#fff style H fill:#555,stroke:#333,color:#fff style I fill:#3fb950,stroke:#2ea043,color:#0d1117

Stage	Windows	macOS	Linux	Android	iOS
Harbour Compiler	harbour.exe	harbour	harbour	harbour (NDK cross)	harbour (Xcode cross)
C Compiler	cl.exe (MSVC) / gcc (MinGW)	clang (Xcode)	gcc / g++	clang (NDK)	clang (Xcode)
Linker	link.exe / ld	ld (via clang)	ld (via gcc)	ld (NDK)	ld (via clang)
Extra Stages	—	—	—	aapt2 → javac → d8 → zipalign → apksigner	asset catalog → Info.plist → .app bundle
Output	.exe	.app bundle	ELF binary	.apk	.app bundle

One-click build Press F9 in the IDE to compile, link, and run your project. HarbourBuilder detects the current platform and selects the appropriate compiler toolchain automatically.

Getting Started

Component Palette

IDE Features

Tutorials

Reference

Platforms

Architecture

5-Layer Architecture

Platform Backends

Control Type System

File Structure

Event System

Two-Way Tools

Build Pipeline

On This Page