Docs / Primeiros Passos / Arquitetura

Arquitetura

O HarbourBuilder usa uma arquitetura em camadas que separa de forma limpa a logica do aplicativo do codigo nativo especifico da plataforma. Este design permite que uma unica base de codigo .prg produza aplicacoes nativas em Windows macOS Linux.

Arquitetura de 5 Camadas

Cada aplicativo HarbourBuilder flui por cinco camadas, da sintaxe xBase de alto nivel ate chamadas de API nativas da plataforma:

graph TB A["1. Codigo do Aplicativo
arquivos fonte .prg"] --> B["2. Comandos xBase
#xcommand / #translate (tempo de compilacao)"] B --> C["3. Camada OOP Harbour
TForm, TControl, TToolBar, ..."] C --> D["4. Bridge HB_FUNC
UI_FormNew, UI_SetProp, UI_OnEvent"] D --> E1["5a. API Win32
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

Por que cinco camadas? A camada de comandos xBase permite que os desenvolvedores escrevam sintaxe familiar no estilo Clipper. A camada OOP fornece um modelo de objetos consistente. A bridge HB_FUNC e o ponto unico onde o Harbour encontra C/C++/Obj-C, tornando simples adicionar novos backends sem tocar no codigo do aplicativo.

Backends de Plataforma

Cada camada e mapeada para uma tecnologia nativa diferente dependendo da plataforma alvo:

Camada	Windows	macOS	Linux	Android	iOS
Codigo do Aplicativo	Harbour .prg	Harbour .prg	Harbour .prg	Harbour .prg	Harbour .prg
Comandos xBase	hbbuilder.ch	hbbuilder.ch	hbbuilder.ch	UI_* direto (reemitido pelo IDE)	UI_* direto (reemitido pelo IDE)
Camada OOP	TForm, TControl	TForm, TControl	TForm, TControl	UI_* plano (iter 1, TForm em breve)	UI_* plano (iter 1, TForm em breve)
Bridge HB_FUNC	C++ (MSVC/MinGW)	Objective-C (Clang)	C (GCC)	C + JNI (NDK Clang)	Objective-C (Xcode Clang)
Backend Nativo	API Win32 / GDI+	Cocoa / AppKit	GTK3 / Cairo	android.widget.*	UIKit / UIView
Criacao de Janela	CreateWindowEx()	[NSWindow alloc]	gtk_window_new()	FrameLayout em MainActivity	UIView em UIViewController
Loop de Eventos	GetMessage / WndProc	[NSApp run]	gtk_main()	Ciclo de vida da Activity	UIApplicationMain (controlado pelo SO)
Desenho	GDI / GDI+	Core Graphics	Cairo / Pango	Canvas / Skia	Core Graphics (iOS)

Android e iOS sao alvos de cross-compile, nao hosts. O IDE continua rodando em Windows/macOS/Linux; o que ele produz e um APK ou .app que roda no dispositivo ou simulador. Ver o guia da plataforma Android e o guia da plataforma iOS para os pipelines completos e os Setup Wizards que instalam os toolchains automaticamente.

Sistema de Tipos de Controle

Cada componente visual no HarbourBuilder e identificado por uma constante numerica CT_ definida em hbide.h. Essas constantes (variando de 0 a 86) determinam como o IDE serializa controles, como o designer os renderiza e qual widget nativo o backend cria em tempo de execucao.

Por que IDs numericos? Um tipo inteiro simples torna rapido o despacho de criacao de controles atraves da bridge C e mantem o formato binario do formulario compacto. Os mesmos IDs sao usados pelo designer, pelo gerador de codigo e pelo runtime.

Aba da Paleta	Intervalo CT_	Controles
Padrao	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)
Adicional	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)
Nativo	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)
Sistema	38 – 39	CT_TIMER (38), CT_PAINTBOX (39)
Dialogos	40 – 45	CT_OPENDIALOG (40), CT_SAVEDIALOG (41), CT_FONTDIALOG (42), CT_COLORDIALOG (43), CT_FINDDIALOG (44), CT_REPLACEDIALOG (45)
IA	46 – 52	CT_OPENAI (46), CT_GEMINI (47), CT_CLAUDE (48), CT_DEEPSEEK (49), CT_GROK (50), CT_OLLAMA (51), CT_TRANSFORMER (52)
Acesso a Dados	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)
Consciente de Dados	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)

Estrutura de Arquivos

O projeto HarbourBuilder e organizado em diretorios claramente separados:

HarbourBuilder/
├── backends/
│   ├── cocoa/          // Backend Objective-C do macOS
│   ├── gtk3/           // Backend GTK3/C do Linux
│   ├── win32/          // Backend C++ do Windows
│   ├── android/        // Backend JNI + Java do Android
│   ├── ios/            // Backend UIKit + Objective-C do iOS
│   ├── console/        // Backend TUI console
│   └── web/            // Backend Web/HTML
├── core/               // Classes Harbour OOP (TForm, TControl, ...)
├── cpp/
│   ├── include/        // Headers C/C++ (hbide.h com definicoes CT_)
│   └── src/            // Fonte C++ do IDE (designer, inspetor, editor)
├── docs/
│   ├── assets/         // CSS, JS, imagens para documentacao
│   ├── en/             // Documentacao em ingles
│   ├── es/             // Documentacao em espanhol
│   └── pt/             // Documentacao em portugues
├── harbour/            // Compilador Harbour e runtime
├── images/             // Icones e bitmaps do IDE
├── include/            // Headers Harbour (hbide.ch)
├── resources/
│   └── icons/          // Icones da Paleta de Componentes
└── samples/
    └── projects/       // Projetos de exemplo

Sistema de Eventos

O HarbourBuilder roteia eventos nativos do sistema operacional atraves de um pipeline unificado que termina em blocos de codigo definidos pelo usuario. O mesmo fluxo de eventos se aplica em todas as plataformas — apenas o ponto de entrada difere (WndProc no Windows, NSResponder no macOS, g_signal no GTK3, UIEvent no iOS).

sequenceDiagram participant User participant OS as SO Nativo participant WndProc as WndProc / NSResponder / g_signal / UIResponder participant Fire as FireEvent() participant Block as Bloco de Codigo Harbour participant Code as Codigo do Usuario User->>OS: Clica no botao OS->>WndProc: WM_COMMAND / action / clicked / touchUpInside WndProc->>Fire: FireEvent( hWnd, nMsg, CT_BUTTON ) Fire->>Block: Eval( oBtn:OnClick ) Block->>Code: { || MsgInfo("Ola!") } Code-->>User: Caixa de mensagem exibida

Vinculacao de eventos Os eventos sao vinculados atribuindo um bloco de codigo a uma propriedade de controle: oBtn:OnClick := { || DoSomething() }. O gerador de codigo escreve essas atribuicoes automaticamente quando voce clica duas vezes em um controle no designer de formularios.

Ferramentas Bidirecionais

O HarbourBuilder mantem sincronizacao perfeita entre o designer visual e o codigo-fonte. Alteracoes em qualquer direcao sao refletidas instantaneamente, e implementacoes de METHOD escritas pelo usuario nunca sao sobrescritas durante a regeneracao de codigo.

flowchart LR A["Designer de Formularios
(visual)"] -- "solta controle /
move / redimensiona" --> B["Gerador de Codigo"] B -- "escreve .prg" --> C["Codigo-Fonte
(arquivo .prg)"] C -- "analisa alteracoes" --> D["Analisador de Codigo"] D -- "atualiza objetos" --> A B -. "preserva implementacoes
de METHOD" .-> C D -. "detecta novos controles
e propriedades" .-> 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

Direcao	Gatilho	Acao
Designer → Codigo	Soltar, mover, redimensionar ou alterar uma propriedade no inspetor	O gerador de codigo reescreve comandos DEFINE FORM / @, preservando todos os blocos METHOD
Codigo → Designer	Editar o fonte .prg no editor de codigo e salvar	O analisador de codigo detecta controles novos/alterados e atualiza o canvas do designer em tempo real

Pipeline de Compilacao

O processo de compilacao transforma o codigo-fonte Harbour em executaveis nativos atraves de um pipeline multi-estagio:

graph LR A[".prg
fonte Harbour"] --> B["Compilador Harbour
(harbour.exe)"] B --> C[".c
codigo C gerado"] C --> D["Compilador C
(MSVC / Clang / GCC)"] D --> E[".obj / .o
arquivos objeto"] E --> F["Linker
(link / ld)"] G["Backend Nativo
(Win32 / Cocoa / GTK3 / Android JNI / iOS UIKit)"] --> F H["Runtime Harbour
(libharbour)"] --> F F --> I[".exe / app / ELF / APK / .app
binario nativo"] 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

Estagio	Windows	macOS	Linux	Android	iOS
Compilador Harbour	harbour.exe	harbour	harbour	harbour (NDK cross)	harbour (Xcode cross)
Compilador C	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)
Estagios Extras	—	—	—	aapt2 → javac → d8 → zipalign → apksigner	asset catalog → Info.plist → .app bundle
Saida	.exe	pacote .app	binario ELF	.apk	pacote .app

Compilacao com um clique Pressione F9 no IDE para compilar, linkar e executar seu projeto. O HarbourBuilder detecta a plataforma atual e seleciona a toolchain de compilador apropriada automaticamente.

Nesta Página

Primeiros Passos Paleta de Componentes Recursos do IDE Tutoriais Referencia Plataformas Arquitetura de 5 Camadas Backends de Plataforma Sistema de Tipos de Controle Estrutura de Arquivos Sistema de Eventos Ferramentas Bidirecionais Pipeline de Compilacao