Docs / Referencia / Puente HB_FUNC

Referencia del Puente HB_FUNC

El puente HB_FUNC es la capa critica que conecta el runtime OOP de Harbour con las APIs nativas de la plataforma. Cada operacion de control de HarbourBuilder — crear una ventana, establecer una propiedad, manejar un evento — fluye a traves de este puente. Esta pagina documenta las funciones HB_FUNC principales y explica como funciona la arquitectura.

¿Que es un HB_FUNC?

HB_FUNC es una macro de la API C de Harbour usada para definir funciones C/C++ que pueden ser llamadas desde codigo Harbour. Cada HB_FUNC recibe parametros de la pila de Harbour mediante funciones hb_par* y retorna valores mediante funciones hb_ret*. HarbourBuilder usa aproximadamente 130-160 funciones HB_FUNC dependiendo del backend de la plataforma.

Arquitectura del Puente

El puente se sienta entre la capa OOP de Harbour y la API nativa de la plataforma. Cuando llamas oForm:Create() en Harbour, el metodo OOP internamente llama a UI_FormNew(), que es un HB_FUNC que invoca la API de creacion de ventanas nativa de la plataforma:

graph TB A["Harbour OOP oForm:Create()"] --> B["Metodo de Clase Harbour TForm:Create()"] B --> C["Llamada HB_FUNC UI_FormNew( cTitle, nW, nH )"] C --> D1["Backend Win32 CreateWindowEx()"] C --> D2["Backend Cocoa [NSWindow alloc]"] C --> D3["Backend GTK3 gtk_window_new()"] D1 --> E["Ventana Nativa"] D2 --> E D3 --> E

Un puente, tres backends

El codigo OOP de Harbour y los nombres HB_FUNC son identicos en todas las plataformas. Solo la implementacion C/C++/Obj-C detras de cada HB_FUNC cambia. Esto significa que tu codigo .prg es 100% portable — no necesita saber si se ejecuta en Windows, macOS o Linux.

Funciones HB_FUNC Principales

Gestion de Formularios

Funcion	Parametros	Retorna	Descripcion
`UI_FormNew`	`cTitle, nWidth, nHeight`	`nFormHandle`	Crea una nueva ventana de nivel superior con el titulo y dimensiones especificados. Retorna un manejador numerico que identifica el formulario en todas las llamadas posteriores.
`UI_FormShow`	`nFormHandle`	vacio	Hace visible el formulario en pantalla.
`UI_FormClose`	`nFormHandle`	vacio	Cierra y destruye el formulario. Dispara la limpieza de todos los controles hijos y recursos nativos.
`UI_FormCenter`	`nFormHandle`	vacio	Centra el formulario en la pantalla. Calcula las dimensiones de la pantalla y posiciona la ventana.
`UI_SetTitle`	`nHandle, cTitle`	vacio	Establece el texto de la barra de titulo de un formulario.

Creacion de Controles

Funcion	Parametros	Retorna	Descripcion
`UI_ControlCreate`	`nType, nParentHandle, nLeft, nTop, nWidth, nHeight`	`nControlHandle`	Crea un widget nativo del tipo especificado (CT_BUTTON, CT_EDIT, etc.) dentro de un contenedor padre. La constante de tipo determina que widget nativo se instancia.
`UI_ButtonCreate`	`nParentHandle, nLeft, nTop, nWidth, nHeight, cCaption`	`nHandle`	Funcion de conveniencia que crea un boton con titulo en una llamada.
`UI_EditCreate`	`nParentHandle, nLeft, nTop, nWidth, nHeight`	`nHandle`	Crea un campo de entrada de texto de una sola linea.
`UI_LabelCreate`	`nParentHandle, nLeft, nTop, nWidth, nHeight, cText`	`nHandle`	Crea una etiqueta de texto estatico.

Gestion de Propiedades

Funcion	Parametros	Retorna	Descripcion
`UI_SetProp`	`nHandle, nPropId, xValue`	vacio	Establecedor de propiedades generico. `nPropId` es una constante que identifica que propiedad establecer (p. ej., PROP_TEXT, PROP_VISIBLE, PROP_COLOR).
`UI_GetProp`	`nHandle, nPropId`	`xValue`	Obtenedor de propiedades generico. Retorna el valor actual de la propiedad especificada.
`UI_SetText`	`nHandle, cText`	vacio	Establece el contenido de texto de un control. Envoltorio conveniente alrededor de UI_SetProp(PROP_TEXT, cText).
`UI_GetText`	`nHandle`	`cText`	Obtiene el contenido de texto de un control.
`UI_SetColor`	`nHandle, nForeColor, nBackColor`	vacio	Establece los colores de primer plano y fondo de un control.
`UI_SetFont`	`nHandle, cFontName, nSize, lBold, lItalic`	vacio	Establece la fuente de un control con especificacion completa de estilo.
`UI_SetBounds`	`nHandle, nLeft, nTop, nWidth, nHeight`	vacio	Establece posicion y tamano en una sola llamada para eficiencia.
`UI_SetVisible`	`nHandle, lVisible`	vacio	Muestra u oculta un control.
`UI_SetEnabled`	`nHandle, lEnabled`	vacio	Habilita o deshabilita un control (atenuado cuando esta deshabilitado).

Gestion de Eventos

Funcion	Parametros	Retorna	Descripcion
`UI_OnEvent`	`nHandle, nEventId, bCodeBlock`	vacio	Registra un bloque de codigo Harbour para ejecutar cuando se dispare el evento especificado en el control. El bloque de codigo se almacena en una tabla de eventos del lado de Harbour.
`FireEvent`	`nHandle, nEventId, [params...]`	Resultado del bloque de codigo	Funcion interna llamada por el manejador de eventos nativo del backend. Busca el bloque de codigo registrado y lo evalua.
`UI_RemoveEvent`	`nHandle, nEventId`	vacio	Elimina un manejador de eventos registrado previamente.

Ciclo de Vida y Utilidades

Funcion	Parametros	Retorna	Descripcion
`UI_Destroy`	`nHandle`	vacio	Destruye un control y libera todos los recursos nativos asociados.
`UI_Refresh`	`nHandle`	vacio	Fuerza un redibujado inmediato del control.
`UI_SetFocus`	`nHandle`	vacio	Da foco de entrada al control especificado.
`UI_AppInit`	`cAppName`	vacio	Inicializa los recursos a nivel de aplicacion. Se llama una vez al inicio.
`UI_MsgLoop`	ninguno	vacio (bloquea)	Entra en el bucle de eventos de la plataforma. Esta funcion bloquea hasta que la aplicacion sale.
`UI_Quit`	ninguno	vacio	Sale del bucle de eventos y termina la aplicacion.
`UI_MsgInfo`	`cMessage, [cTitle]`	vacio	Muestra un cuadro de mensaje de informacion simple.

Cantidad de Funciones por Plataforma

Backend	Lenguaje	Cantidad HB_FUNC	Lineas de codigo
Windows Win32	C++	~135	~7,100
macOS Cocoa	Objective-C++	~158	~3,800
Linux GTK3	C	~132	~7,300

¿Por que cantidades diferentes?

Cada plataforma tiene capacidades ligeramente diferentes. El backend macOS Cocoa tiene mas funciones HB_FUNC porque el estilo de mensajeria de Objective-C a veces requiere funciones de puente separadas para operaciones que otras plataformas pueden combinar. El backend GTK3 tiene mas lineas porque C requiere mas codigo repetitivo para funcionalidad equivalente.

Agregar un Nuevo HB_FUNC

Para extender HarbourBuilder con una nueva capacidad nativa, necesitas:

Definir el HB_FUNC en el archivo de fuente del backend de cada plataforma.
Registrar la funcion en la tabla de funciones de Harbour (usualmente automatico con la macro HB_FUNC).
Agregar el envoltorio del lado de Harbour en la clase OOP.
Agregar el comando xBase (opcional) en hbbuilder.ch.

En Esta Página

Primeros pasos Paleta de componentes Funciones del IDE Tutoriales Referencia Plataformas Arquitectura del Puente Funciones HB_FUNC Principales Gestion de Formularios Creacion de Controles Gestion de Propiedades Gestion de Eventos Ciclo de Vida y Utilidades Cantidad de Funciones por Plataforma Agregar un Nuevo HB_FUNC