# 2. Primeiros passos #

← Instalação · Índice · Base comum →

Objetivo: apresentar um primeiro componente em cinco minutos e, depois, compreender o esquema idêntico para todos os componentes.

## 2.1 Abrir a aplicação de demonstração #

A aplicação de demonstração (`pbtoolboxai_demo`) e a biblioteca `pbtoolboxai.pbl` são fornecidas no formato PowerBuilder 10, o formato mais antigo que todas as versões suportadas ainda conseguem ler.

1. Abrir o workspace `pbtoolboxai_demo.pbw` na sua versão do PowerBuilder.
2. O PowerBuilder propõe migrar as bibliotecas: aceitar. A migração converte `pbtoolboxai_demo.pbl` e `pbtoolboxai.pbl` para o formato da sua versão.
3. Executar um Full Build do target e depois lançá-lo: a montra abre nos mosaicos de componentes.

É esta migração que lhe dá um `pbtoolboxai.pbl` no formato do seu PowerBuilder: é esse ficheiro migrado que irá depois acrescentar à library list das suas próprias aplicações.

> ⚠️ A migração é de sentido único: uma biblioteca migrada para o PowerBuilder 2025 já não abre no PowerBuilder 10. Migrar uma cópia da pasta fornecida e conservar o original.

## 2.2 Colocar o componente #

1. Abrir uma window (nova ou existente).
2. Insert → Control → User Object → escolher `u_pbt_statictext` em `pbtoolboxai.pbl`.
3. Atribuir-lhe o nome `uo_texte` e dimensioná-lo.

No painter, o controlo apresenta uma moldura cinzenta « PBToolboxAI component (rendered at runtime) »: a apresentação real só ocorre em execução.

> 💡 Para intercetar os eventos do componente, é preferível criar um userobject herdado (`u_pbt_statictext` → `uo_mon_texte`) e escrever os eventos nesse objeto. Também é possível escrevê-los diretamente no controlo colocado na window.

## 2.3 Controlá-lo #

No event `open` da window:

    // Conteudo (o texto aceita a formatacao com etiquetas: [b], [color=...], [br]...)
    uo_texte.is_text = "Bem-vindo ao [b]PBToolboxAI[/b]!"

    // Formatacao: tudo e uma PROPRIEDADE, nao um 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)

É tudo: o componente apresenta-se, aplica o tema e reage às interações.

### As constantes em vez das cadeias de carateres #

Cada propriedade com valores predefinidos expõe constantes no componente. São completadas automaticamente pelo IDE e evitam erros de escrita:

    uo_texte.is_align = uo_texte.ALIGN_CENTER      // em vez de "center"
    uo_texte.is_theme_style = uo_texte.THEME_STYLE_OFFICE2007
    uo_texte.is_theme_mode  = uo_texte.THEME_MODE_DARK

## 2.4 Receber os eventos #

Os componentes devolvem events PB tipados. Devem ser escritos no controlo (ou no userobject herdado):

    // event ue_clicked de uo_texte
    MessageBox("PBToolboxAI", "Texto clicado")

    // event ue_hyperlink de uo_texte -- desencadeado por [hyperlink=...]
    // as_url = o endereco clicado
    Run("explorer.exe " + as_url)

## 2.5 O esquema, idêntico para todos os componentes #

Etapa | O utilizador faz | O componente faz
--- | --- | ---
Criação | Colocar o userobject | Cria-se, coloca os comandos em fila
Configuração | Atribuir propriedades / chamar `of_add_*` | Aplica, mesmo antes de estar pronto
Pronto | (nada) | Levanta `ue_ready`
Interação | (nada) | Levanta eventos `ue_*` tipados
Redimensionamento | (nada) | Acompanha o tamanho do userobject
Reposição | `of_reset()` | Regressa ao estado inicial
Fecho | Fechar a window | Destrói-se corretamente

Nunca é necessário gerir o HTML, o JSON, nem o estado «pronto / não pronto».

## 2.6 Um exemplo completo #

    // ---- event open da window ---------------------------------------------
    // Agrupa as alteracoes num UNICO repaint (sem cintilacao)
    uo_texte.of_set_redraw(false)

    uo_texte.is_text        = "Volume de negócios: [b][color=#2e7d32]1 240 500 €[/color][/b]" &
                              + "[br][size-=15]Atualização " + 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 1 de janeiro"

    uo_texte.of_set_redraw(true)

## 2.7 Códigos de retorno #

Todos os métodos `of_*` devolvem um `long`:

    long ll_rc

    ll_rc = uo_texte.of_reset()
    if ll_rc < 0 then
        // -2 = componente nao criado (runtime ausente) ; -5 = argumento invalido
        f_log(uo_texte.of_get_last_error())
    end if

Na prática, o valor de retorno é muitas vezes ignorado (os erros de configuração são raros) e o funcionamento assenta em `ue_ready` / `ue_runtime_missing`.

A atribuição de uma propriedade não devolve nada (é uma atribuição PowerScript): um valor inválido é ignorado pelo componente, sem exceção.

## 2.8 E a seguir #

- Base comum: motor de propriedades, items, ciclo de vida detalhado.
- Temas e aspeto: aplicar uma identidade visual a toda a aplicação.
- Referência dos componentes: uma página por componente da v1.

← Instalação · Índice · Base comum →