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.