HB_FUNC Bridge Reference

The HB_FUNC bridge is the critical layer that connects Harbour's OOP runtime to native platform APIs. Every HarbourBuilder control operation — creating a window, setting a property, handling an event — flows through this bridge. This page documents the core HB_FUNC functions and explains how the architecture works.

Bridge Architecture

The bridge sits between Harbour's OOP layer and the native platform API. When you call oForm:Create() in Harbour, the OOP method internally calls UI_FormNew(), which is an HB_FUNC that invokes the platform's native window creation API:

Core HB_FUNC Functions

Form Management

Control Creation

Property Management

Event Management

Lifecycle and Utility

How the Bridge Works: A Complete Example

Here is the complete journey from Harbour source code to native API call:

=== Step 1: Your Harbour source code ===
DEFINE FORM oForm TITLE "Hello" SIZE 400, 300
ACTIVATE FORM oForm CENTERED

=== Step 2: Preprocessor expansion (hbbuilder.ch) ===
oForm := TForm():New( nil )
oForm:cTitle  := "Hello"
oForm:nWidth  := 400
oForm:nHeight := 300
oForm:lCentered := .T.
oForm:Activate()

=== Step 3: Harbour OOP layer (TForm class) ===
METHOD Activate CLASS TForm
   local nHandle
   nHandle := UI_FormNew( ::cTitle, ::nWidth, ::nHeight )
   ::nHandle := nHandle
   if ::lCentered
      UI_FormCenter( nHandle )
   endif
   UI_FormShow( nHandle )
   UI_MsgLoop()
RETURN nil

=== Step 4: HB_FUNC bridge (C/C++ backend) ===
// On Windows (win32_backend.cpp):
HB_FUNC( UI_FORMNEW )
{
   const char * cTitle = hb_parc( 1 );
   int nWidth  = hb_parni( 2 );
   int nHeight = hb_parni( 3 );

   HWND hWnd = CreateWindowEx(
      0,                              // dwExStyle
      "HBBUILDER_FORM",               // lpClassName
      cTitle,                          // lpWindowName
      WS_OVERLAPPEDWINDOW,             // dwStyle
      CW_USEDEFAULT, CW_USEDEFAULT,    // x, y
      nWidth, nHeight,                 // width, height
      NULL, NULL,                      // parent, menu
      hInstance,                       // hInstance
      NULL                             // lpParam
   );

   hb_retni( ( int ) ( intptr_t ) hWnd );
}

Platform-Specific Function Counts

Adding a New HB_FUNC

To extend HarbourBuilder with a new native capability, you need to:

1. Define the HB_FUNC in each platform's backend source file:

   // In win32_backend.cpp:
   HB_FUNC( UI_NEWWIDGET )
   {
      // ... Win32 implementation ...
      hb_retni( nResult );
   }

2. Register the function in the Harbour function table (usually automatic with HB_FUNC macro).
3. Add the Harbour-side wrapper in the OOP class:

   METHOD CreateNewWidget( nType ) CLASS TControl
      local nHandle := UI_NewWidget( nType, ::nParent )
      ::nHandle := nHandle
      return self

4. Add the xBase command (optional) in hbbuilder.ch:

   #xcommand DEFINE WIDGET <o> TYPE <nType> OF <oParent> ;
      => <o> := TControl():New( <oParent> );
         <o>:CreateNewWidget( <nType> )