# 2. Primeros pasos #

← Instalación · Índice · Base común →

Objetivo: mostrar un primer componente en cinco minutos y comprender después el esquema idéntico para todos los componentes.

## 2.1 Abrir la aplicación de demostración #

La aplicación de demostración (`pbtoolboxai_demo`) y la biblioteca `pbtoolboxai.pbl` se entregan en formato PowerBuilder 10, el formato más antiguo que todas las versiones admitidas siguen sabiendo leer.

1. Abra el workspace `pbtoolboxai_demo.pbw` en su versión de PowerBuilder.
2. PowerBuilder propone migrar las bibliotecas: acepte. La migración convierte `pbtoolboxai_demo.pbl` y `pbtoolboxai.pbl` al formato de su versión.
3. Ejecute un Full Build del target y después láncelo: el escaparate se abre en los mosaicos de componentes.

Es esa migración la que le proporciona un `pbtoolboxai.pbl` en el formato de su PowerBuilder: es ese archivo migrado el que añadirá después a la library list de sus propias aplicaciones.

> ⚠️ La migración es de sentido único: una biblioteca migrada a PowerBuilder 2025 ya no se abre en PowerBuilder 10. Migre una copia de la carpeta entregada y conserve el original.

## 2.2 Colocar el componente #

1. Abra una ventana (nueva o existente).
2. Insert → Control → User Object → elija `u_pbt_statictext` en `pbtoolboxai.pbl`.
3. Llámelo `uo_texte` y dimensiónelo.

En el painter, el control muestra un marco gris «PBToolboxAI component (rendered at runtime)»: la representación real solo tiene lugar durante la ejecución.

> 💡 Para interceptar los eventos del componente, conviene crear un userobject heredado (`u_pbt_statictext` → `uo_mon_texte`) y escribir en él los scripts de los eventos. También puede escribirlos directamente en el control colocado en la ventana.

## 2.3 Gobernarlo #

En el evento `open` de la ventana:

    // Contenido (el texto acepta las etiquetas enriquecidas: [b], [color=...], [br]...)
    uo_texte.is_text = "¡Bienvenido a [b]PBToolboxAI[/b]!"

    // Formato: todo es una PROPIEDAD, no un setter
    uo_texte.is_align    = uo_texte.ALIGN_CENTER
    uo_texte.is_valign   = uo_texte.VALIGN_CENTER
    uo_texte.ii_font_size = 14
    uo_texte.il_text_color = RGB(0, 103, 192)

Eso es todo: el componente se representa, aplica el tema y reacciona a las interacciones.

### Las constantes en lugar de las cadenas #

Cada propiedad con valores predefinidos expone constantes en el componente. El IDE las autocompleta y le evitan las erratas:

    uo_texte.is_align = uo_texte.ALIGN_CENTER      // en lugar de "center"
    uo_texte.is_theme_style = uo_texte.THEME_STYLE_OFFICE2007
    uo_texte.is_theme_mode  = uo_texte.THEME_MODE_DARK

## 2.4 Recibir los eventos #

Los componentes devuelven eventos PB tipados. Escriba sus scripts en su control (o en su userobject heredado):

    // evento ue_clicked de uo_texte
    MessageBox("PBToolboxAI", "Texto pulsado")

    // evento ue_hyperlink de uo_texte -- activado por [hyperlink=...]
    // as_url = la direccion pulsada
    Run("explorer.exe " + as_url)

## 2.5 El esquema, idéntico para todos los componentes #

Paso | Usted hace | El componente hace
--- | --- | ---
Creación | Colocar el userobject | Se crea, pone sus comandos en cola
Configuración | Asignar propiedades / llamar a los `of_add_*` | Los aplica, incluso antes de estar listo
Listo | (nada) | Activa `ue_ready`
Interacción | (nada) | Activa eventos `ue_*` tipados
Redimensionamiento | (nada) | Sigue el tamaño del userobject
Puesta a cero | `of_reset()` | Vuelve al estado inicial
Cierre | Cerrar la ventana | Se destruye limpiamente

Usted nunca tiene que gestionar el HTML, el JSON ni el estado «listo / no listo».

## 2.6 Un ejemplo completo #

    // ---- evento open de la ventana ---------------------------------------
    // Agrupa las modificaciones en UN solo repaint (sin parpadeo)
    uo_texte.of_set_redraw(false)

    uo_texte.is_text        = "Facturación: [b][color=#2e7d32]1 240 500 €[/color][/b]" &
                              + "[br][size-=15]Actualizado el " + String(Today(), "dd/mm/yyyy") + "[/size-=15]"
    uo_texte.is_align       = uo_texte.ALIGN_CENTER
    uo_texte.is_valign      = uo_texte.VALIGN_CENTER
    uo_texte.ii_padding     = 12
    uo_texte.ii_corner_radius = 6
    uo_texte.is_tooltip     = "Acumulado desde el 1 de enero"

    uo_texte.of_set_redraw(true)

## 2.7 Códigos de retorno #

Todos los métodos `of_*` devuelven un `long`:

    long ll_rc

    ll_rc = uo_texte.of_reset()
    if ll_rc < 0 then
        // -2 = componente no creado (runtime ausente) ; -5 = argumento no valido
        f_log(uo_texte.of_get_last_error())
    end if

En la práctica, a menudo se ignora el valor devuelto (los errores de configuración son poco frecuentes) y se recurre a `ue_ready` / `ue_runtime_missing`.

La asignación de una propiedad no devuelve nada (es una asignación PowerScript): un valor no válido es ignorado por el componente, sin excepción.

## 2.8 Y a continuación #

- Base común: motor de propiedades, items, ciclo de vida detallado.
- Temas y apariencia: aplicar una identidad visual a toda la aplicación.
- Referencia de componentes: una página por cada componente de la v1.

← Instalación · Índice · Base común →