# statictext — `u_pbt_statictext` #

← Referência dos componentes · Índice do guia

> Bloco de texto formatado: etiquetas, alinhamentos, hiperligações e ações clicáveis, aspeto de cabeçalho, modo deslizante (marquee) e zona para largar ficheiros.

> ▶ Ver ao vivo — Aplicação de demonstração, mosaico Statictext: a pré-visualização, o código que o produz e esta página, lado a lado.

## Em resumo #

Userobject | `u_pbt_statictext`
Classe de items | — (componente sem items)
Serve para | Substituir um `statictext` do PowerBuilder por um bloco de texto formatado e clicável, capaz de servir de cabeçalho, de faixa deslizante ou de zona para largar ficheiros
Opções opt-in | `ib_auto_height`, `ib_track_mouse`, `ib_allow_drop`, `ib_selectable`, `ib_hover_effect`

## Início rápido #

    // event open da window
    uo_texte.is_text = "Bem-vindo ao [b][accent]PBToolboxAI[/accent][/b][br]" &
                       + "Consulte a [hyperlink=https://pbtoolboxai.net]documentação[/hyperlink]."
    uo_texte.is_align = uo_texte.ALIGN_CENTER
    uo_texte.is_valign = uo_texte.VALIGN_CENTER

O texto aceita o texto formatado com etiquetas: é este componente que dele tira o melhor partido, pois é o único que torna as zonas `[hyperlink=…]` e `[action=…]` realmente clicáveis.

## Constantes #

Constante | Valor | Para
--- | --- | ---
`ALIGN_START` · `ALIGN_CENTER` · `ALIGN_END` · `ALIGN_JUSTIFY` | `"start"` `"center"` `"end"` `"justify"` | `is_align`
`VALIGN_TOP` · `VALIGN_CENTER` · `VALIGN_BOTTOM` | `"top"` `"center"` `"bottom"` | `is_valign`

`start` e `end` são lógicos: seguem o sentido de escrita (Idioma e RTL). Os valores físicos `left` e `right` continuam a ser aceites como alias.

## Propriedades #

### Texto e formatação #

Propriedade | Tipo | Predefinição | Função
--- | --- | --- | ---
`is_text` | string | `""` | O texto apresentado, com o texto formatado com etiquetas: `[b]`, `[i]`, `[u]`, cores, `[picture=…]`, `[hyperlink=…]`, `[action=…]`
`is_align` | string | `"start"` | Alinhamento horizontal: `ALIGN_START`, `ALIGN_CENTER`, `ALIGN_END`, `ALIGN_JUSTIFY`
`is_valign` | string | `"top"` | Alinhamento vertical dentro do controlo: `VALIGN_TOP`, `VALIGN_CENTER`, `VALIGN_BOTTOM`
`ib_wrap` | boolean | `true` | Mudança de linha automática. `false` força uma linha única
`ib_ellipsis` | boolean | `false` | Com `ib_wrap = false`, trunca o excesso com reticências em vez de o cortar a direito
`ib_ellipsis_tooltip` | boolean | `false` | Opt-in: quando o texto não cabe na caixa, apresentá-lo por inteiro numa sugestão (marcação incluída). Nunca substitui uma sugestão que tenha definido com `is_tooltip` ou `is_super_tooltip_*`: a sua ganha
`is_font_family` | string | `""` | Tipo de letra predefinido do bloco (vazio = tipo de letra do tema)
`ii_font_size` | integer | `0` | Tamanho predefinido em pontos (`0` = tamanho do tema)
`il_text_color` | long | `-1` | Cor do texto `RGB()` (`-1` = cor do tema). As etiquetas `[color]` mantêm a prioridade na respetiva porção
`ii_line_spacing` | integer | `0` | Entrelinha em percentagem (`150` = 1,5 linha; `0` = predefinição)
`ib_enabled` | boolean | `true` | Bloco ativo ou desativado (hiperligações e ações ficam inertes quando está desativado)
`ib_selectable` | boolean | `false` | Opt-in: permite ao utilizador selecionar e copiar o texto (desativado por predefinição, como uma etiqueta)

### Aspeto de bloco (aspeto «cabeçalho») #

Propriedade | Tipo | Predefinição | Função
--- | --- | --- | ---
`il_back_color` | long | `-1` | Fundo do bloco `RGB()` (`-1` = fundo do tema)
`il_border_color` | long | `-1` | Cor do contorno (`-1` = sem contorno)
`ii_border_width` | integer | `0` | Espessura do contorno em pixels (`0` = sem contorno)
`ii_corner_radius` | integer | `0` | Raio de arredondamento dos cantos, em pixels
`ii_padding` | integer | `0` | Margem interior em pixels (`0` = valor do tema)
`ib_hover_effect` | boolean | `false` | Opt-in: ligeiro escurecimento ao passar o rato, para uma etiqueta-botão

### Modo deslizante (marquee) #

Propriedade | Tipo | Predefinição | Função
--- | --- | --- | ---
`ib_marquee` | boolean | `false` | Transforma o bloco numa faixa deslizante na horizontal
`ii_marquee_speed` | integer | `60` | Velocidade de deslocamento, em pixels por segundo
`is_marquee_direction` | string | `MARQUEE_START` | Sentido do deslocamento: `MARQUEE_START` (para o início de leitura) ou `MARQUEE_END`. Aceitam-se os alias físicos `"left"` / `"right"`
`ib_marquee_overflow_only` | boolean | `false` | Opt-in: deslocar apenas se o texto for demasiado largo para a caixa. Um letreiro que desloca um texto já legível não passa de ruído visual. Desativado por predefinição, para que `ib_marquee = true` continue a querer dizer desloca-se
`ib_marquee_pause_on_hover` | boolean | `false` | Opt-in: para o deslocamento enquanto o ponteiro estiver sobre o bloco, para que um texto longo se possa ler. A posição do ciclo é conservada: nada salta quando o ponteiro sai

### Interações opcionais #

Propriedade | Tipo | Predefinição | Função
--- | --- | --- | ---
`ib_allow_drop` | boolean | `false` | Opt-in: aceita que se larguem ficheiros a partir do Explorador do Windows; os caminhos completos chegam por `ue_drop_files`
`ib_track_mouse` | boolean | `false` | Opt-in: ativa `ue_mouse_enter` / `ue_mouse_leave`
`ib_auto_height` | boolean | `false` | Opt-in: o bloco mede a sua altura ideal e redimensiona o userobject; ver Base comum
`is_theme_style` | string | `fluent` | Estilo visual do componente (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante clara ou escura (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Cor de destaque deste componente (`-1` = destaque do tema)
`is_tooltip` | string | `""` | Tooltip simples apresentado ao passar sobre o componente
`is_super_tooltip_title` | string | `""` | Título do tooltip enriquecido (prevalece sobre `is_tooltip`)
`is_super_tooltip_text` | string | `""` | Texto do tooltip enriquecido (aceita marcação enriquecida)
`is_super_tooltip_image` | string | `""` | Imagem do tooltip enriquecido

## Métodos #

Método | Função
--- | ---
`of_reset ( )` | Repõe todas as propriedades na predefinição e limpa o texto
`of_set_redraw (boolean)` | Agrupa uma rajada de alterações num único desenho
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta a representação como imagem
`of_scroll_to_end ( )` | Desce até ao fim do texto. Para um registo, cuja linha mais recente fica no fim: sem isto ela passa abaixo da linha de água assim que o texto ultrapassa a altura visível

## Eventos #

Evento | Acionado quando
--- | ---
`ue_clicked ( )` | Clique esquerdo no bloco — não é acionado numa zona `[action]` ou `[hyperlink]` (sem duplicação)
`ue_hyperlink (string as_url)` | Uma zona `[hyperlink=url]` foi clicada. O navegador abre-se sozinho: o evento chega-lhe além disso, para registar o clique ou fazer mais com ele
`ue_action (string as_id)` | Uma zona `[action=id]` foi clicada: cabe ao programador ligar aí o seu código
`ue_drop_files (string as_files[])` | Foram largados ficheiros a partir do Windows: caminhos completos, uma entrada por ficheiro. Requer `ib_allow_drop = true`
`ue_drag_enter ( )` | Um arrastamento de ficheiros entra no componente (`ib_allow_drop`)
`ue_drag_leave ( )` | O arrastamento de ficheiros sai do componente
`ue_auto_height (long al_height)` | O bloco calculou a sua altura ideal — requer `ib_auto_height = true`
`ue_rclicked ( )` | Clique direito no bloco
`ue_double_clicked ( )` | Duplo clique no bloco, tal como o `StaticText` nativo do PowerBuilder. Os cliques simples que o precedem também são emitidos, pela mesma ordem. Não numa zona `[action]` ou `[hyperlink]`, que têm canal próprio
`ue_text_overflow (boolean ab_truncated)` | O texto deixou de caber na caixa — ou volta a caber. Emitido apenas na mudança, nunca em rajada: um bloco com mudança de linha conta como cortado quando fica aparado em baixo, e um de uma só linha quando é cortado de lado. Trate-o para alargar uma coluna, oferecer um botão ver mais, ou simplesmente ativar `ib_ellipsis_tooltip`
`ue_mouse_enter ( )` | O rato entra — requer `ib_track_mouse = true`
`ue_mouse_leave ( )` | O rato sai — requer `ib_track_mouse = true`
`ue_cycle ( )` | Apenas no modo deslizante: o texto acabou de concluir uma passagem completa
`ue_ready ( )` | O componente terminou o carregamento; tudo o que foi enviado antes foi reproduzido
`ue_runtime_missing ( )` | O runtime WebView2 está ausente: o componente permanece vazio
`ue_bg_color (long al_color)` | O componente calculou a cor de fundo do respetivo tema; o userobject já a adotou (`backcolor`)

## Exemplos #

### Um cabeçalho de secção #

Fundo preenchido, texto branco centrado e altura ajustada ao conteúdo: o bloco lê-se como uma verdadeira barra de título.

    uo_entete.of_set_redraw(false)

    uo_entete.is_text  = "[b]Painel de vendas"
    uo_entete.is_align = uo_entete.ALIGN_CENTER

    // Fundo preenchido e texto branco legivel
    uo_entete.il_back_color = RGB(/*vermelho*/ 60, /*verde*/ 110, /*azul*/ 190)
    uo_entete.il_text_color = RGB(/*vermelho*/ 255, /*verde*/ 255, /*azul*/ 255)
    uo_entete.ii_padding = 14

    // O bloco cola-se ao seu conteudo : le-se como uma barra de titulo
    uo_entete.ib_auto_height = true

    uo_entete.of_set_redraw(true)

    // event ue_auto_height de uo_entete
    of_repositionner_sous_entete(al_height)   // desloca o conteudo para baixo do cabecalho

### Texto formatado com hiperligação e ação #

    uo_texte.is_text = "A sua licença expira a [b]31/12[/b]. " &
                       + "[hyperlink=https://pbtoolboxai.net]Saber mais[/hyperlink] " &
                       + "ou [action=renew]renová-la agora[/action]."

    // event ue_action de uo_texte : (string as_id)
    choose case as_id
        case "renew" ; of_ouvrir_renouvellement()
    end choose

`ue_hyperlink` está reservado aos URL (o navegador abre-se sozinho); `[action=id]` é a escolha certa quando o clique deve permanecer dentro da aplicação. A variante `[invisibleaction=id]` aciona o mesmo `ue_action` sem o aspeto de uma hiperligação.

### Um bloco recolhível #

    uo_recap.is_text = "[b]Encomenda 2026-0148[/b][br]" &
                       + "[foldarea:[b]Entrega[/b]]Enviado a 12/07, em 48 horas.[/foldarea]" &
                       + "[foldarea-closed:[i]Aviso legal[/i]]Devolucao aceite em 14 dias.[/foldarea]"

    uo_recap.ib_auto_height = true   // o bloco encolhe quando uma seccao e recolhida

Um `[foldarea:Título]` acrescenta um cabeçalho clicável por cima do seu conteúdo: o leitor recolhe a secção com um clique e o marcador passa de `−` para `+`. `[foldarea-closed:Título]` produz o mesmo bloco, recolhido logo à partida. Os blocos aninham-se e o recolhimento não emite qualquer evento: é uma questão de leitura, não de código. Se `ib_auto_height` estiver ativo, a altura é notificada de novo a cada recolha. O título é texto com etiquetas: `[foldarea:[b][accent]Encomenda 2026-0148[/accent][/b]]` coloca o seu a negrito e com a cor de destaque.

### Uma faixa deslizante #

    uo_bandeau.is_text = "[b]Informação[/b] -- encerramento excecional do serviço na sexta-feira, dia 12."

    // Modo deslizante, a maneira de um fio de noticias
    uo_bandeau.ib_marquee = true
    uo_bandeau.ii_marquee_speed = 90        // pixels por segundo
    uo_bandeau.is_marquee_direction = uo_bandeau.MARQUEE_START

O deslocamento repete-se sem tempos mortos. Para o parar, basta repor `ib_marquee` a `false`: o texto retoma a sua disposição normal.

A cada passagem completa do texto, o evento `ue_cycle` é acionado — prático para fazer rodar várias mensagens:

    // Em ue_cycle da faixa : passar a mensagem seguinte
    ii_message = Mod(ii_message, UpperBound(is_messages)) + 1
    uo_bandeau.is_text = is_messages[ii_message]

### Uma zona para largar ficheiros #

    // Aceitar os ficheiros arrastados a partir do Explorador do Windows
    uo_zone.ib_allow_drop = true

    uo_zone.is_text = "[size=32][accent][b]Largue aqui os seus ficheiros[/b][/accent][/size][br][br]" &
                      + "Arraste um ou vários ficheiros a partir do Explorador do Windows."
    uo_zone.is_align  = uo_zone.ALIGN_CENTER
    uo_zone.is_valign = uo_zone.VALIGN_CENTER

    // event ue_drop_files de uo_zone : (string as_files[])
    integer li

    for li = 1 to UpperBound(as_files)
        of_importer(as_files[li])       // as_files[li] = caminho COMPLETO do ficheiro
    next

    // event ue_drag_enter de uo_zone : assinalar o destino durante o sobrevoo
    uo_zone.il_border_color = RGB(/*vermelho*/ 21, /*verde*/ 101, /*azul*/ 192)
    uo_zone.ii_border_width = 2

Os caminhos recebidos são completos: podem ser passados diretamente a `FileOpen` ou à rotina de importação.

### Uma etiqueta que se comporta como um botão #

    uo_lien.is_text = "Selecionar tudo"
    uo_lien.il_text_color = RGB(/*vermelho*/ 21, /*verde*/ 101, /*azul*/ 192)
    uo_lien.ii_padding = 8
    uo_lien.ii_corner_radius = 6
    uo_lien.ib_hover_effect = true       // reage ao sobrevoo como um botao

    // event ue_clicked de uo_lien
    of_tout_selectionner()

## Boas práticas #

- Um texto sem etiquetas não tem qualquer custo adicional: pode substituir-se sistematicamente os `statictext` do PowerBuilder, mesmo para texto simples.
- É preferível `is_align = uo.ALIGN_START` a `"left"`: o ecrã continuará correto se a aplicação passar a escrita da direita para a esquerda.
- `ib_selectable` permanece desativado por predefinição, como uma etiqueta. Deve ativar-se apenas onde a cópia faça sentido (número de processo, mensagem de erro técnica).
- Para um cabeçalho, deve combinar-se `il_back_color` + `ii_padding` + `ib_auto_height`: o bloco dimensiona-se sozinho quando o texto muda de comprimento.
- Só se deve ativar `ib_track_mouse` se `ue_mouse_enter` / `ue_mouse_leave` forem realmente programados.
- Convém chamar `of_reset()` antes de reutilizar um bloco para outro conteúdo: sem isso, um fundo, um contorno ou o modo deslizante anteriores permanecem em vigor.

← Referência dos componentes · Índice do guia