PBToolboxAI v5 ← Site

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 #

Userobjectu_pbt_statictext
Classe de items— (componente sem items)
Serve paraSubstituir 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-inib_auto_height, ib_auto_width, ib_follow_end, ib_track_mouse, ib_track_cycle, ib_allow_drop, ib_selectable, ib_hover_effect, ib_ellipsis_tooltip, ib_marquee_overflow_only, ib_marquee_pause_on_hover, ib_mnemonic, ib_veto_links

Início rápido #

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

O texto aceita o texto formatado com etiquetas: é este componente que dele tira o melhor partido — as suas zonas [action=…] levantam ue_action e também se alcançam pelo teclado (a caixa de mensagem também as torna clicáveis; um [hyperlink=…] abre-se em qualquer lado).


Constantes #

ConstanteValorPara
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 #

PropriedadeTipoPredefiniçãoFunção
is_textstring""O texto apresentado, com o texto formatado com etiquetas: [b], [i], [u], cores, [picture=…], [hyperlink=…], [action=…]
is_alignstring"start"Alinhamento horizontal: ALIGN_START, ALIGN_CENTER, ALIGN_END, ALIGN_JUSTIFY
is_valignstring"top"Alinhamento vertical dentro do controlo: VALIGN_TOP, VALIGN_CENTER, VALIGN_BOTTOM
ib_wrapbooleantrueMudança de linha automática na margem. false já não dobra as linhas longas: transbordam, e só as quebras do texto ([br], uma mudança de linha) começam uma nova linha
ib_ellipsisbooleanfalseCom ib_wrap = false, trunca o excesso com reticências em vez de o cortar a direito
ib_ellipsis_tooltipbooleanfalseOpt-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_familystring""Tipo de letra predefinido do bloco (vazio = tipo de letra do tema)
ii_font_sizeinteger0Tamanho predefinido em pontos, de 6 a 200 como a etiqueta [size] (0 = tamanho do tema, ou o de PBT_SetDefaultFont). Um valor fora desse intervalo é trazido para o limite mais próximo, e relido tal como aplicado
il_text_colorlong-1Cor do texto RGB() (-1 = cor do tema). As etiquetas [color] mantêm a prioridade na respetiva porção. Uma cor de SISTEMA do PowerBuilder (WindowText, ButtonFace…) vale a cor do tema, e relê-se -1
ii_line_spacinginteger0Entrelinha em percentagem, de 50 a 400 (150 = 1,5 linha; 0 = predefinição). Um valor fora desses limites é levado ao mais próximo, e relê-se tal como foi aplicado
ib_enabledbooleantrueBloco ativo ou desativado. Desativado, hiperligações, ações e cabeçalhos dobráveis ficam inertes e saem da ordem de Tab; na superfície do tema o texto toma o cinzento do tema, sobre um fundo próprio (il_back_color, uma porção [bk]) as suas cores são mantidas e atenuadas: continua legível
ib_selectablebooleanfalseOpt-in: permite ao utilizador selecionar o texto e copiá-lo com Ctrl+C (desativado por predefinição, como uma etiqueta). Soltar o rato depois de uma seleção não gera ue_clicked
ii_max_linesinteger0No máximo N linhas mostradas (0 = sem limite): a última termina em «…», o texto conta como cortado para ue_text_overflow e ib_ellipsis_tooltip, e ib_auto_height mede as linhas mostradas. Sem efeito num letreiro deslizante
ib_mnemonicbooleanfalseOpt-in: o & do texto marca a letra de um atalho, como num StaticText do PowerBuilder — «&Nome:» mostra o N sublinhado, && escreve um &. Como no PowerBuilder, o atalho em si pertence ao controlo que a etiqueta designa (o seu Accelerator). Desativado por omissão: «R&D» fica tal como escrito; is_text relê-se com os seus &

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

PropriedadeTipoPredefiniçãoFunção
il_back_colorlong-1Fundo do bloco RGB() (-1 = fundo do tema). Com ii_corner_radius acompanha o arredondamento, e fora dos cantos o bloco mostra a cor do objeto sobre o qual está colocado. Continua anunciado ao PowerBuilder quando o tema muda. Uma cor de SISTEMA do PowerBuilder (ButtonFace…) vale o fundo do tema, e relê-se -1
il_border_colorlong-1Cor do contorno (-1 = sem contorno)
ii_border_widthinteger0Espessura do contorno em pixels (0 = sem contorno)
ii_corner_radiusinteger0Raio de arredondamento dos cantos, em pixels. O contorno E o fundo il_back_color acompanham-no
ii_paddinginteger-1Margem interior em pixels: -1 = a do tema (predefinição), 0 = nenhuma margem (o texto alinha-se com o bordo de um campo vizinho), acima = pixels
ib_hover_effectbooleanfalseOpt-in: ligeiro escurecimento ao passar o rato (clareamento num tema escuro), para uma etiqueta-botão

Modo deslizante (marquee) #

PropriedadeTipoPredefiniçãoFunção
ib_marqueebooleanfalseTransforma o bloco numa faixa deslizante na horizontal
ii_marquee_speedinteger60Velocidade de deslocamento, em pixels por segundo (0 = velocidade predefinida, 60)
is_marquee_directionstringMARQUEE_STARTSentido do deslocamento: MARQUEE_START (para o início de leitura) ou MARQUEE_END. Aceitam-se os alias físicos "left" / "right": continuam físicos, seja qual for o sentido de leitura. Qualquer outro valor vale, e relê-se, MARQUEE_START
ib_marquee_overflow_onlybooleanfalseOpt-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_hoverbooleanfalseOpt-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 #

PropriedadeTipoPredefiniçãoFunção
ib_allow_dropbooleanfalseOpt-in: aceita que se larguem ficheiros a partir do Explorador do Windows; os caminhos completos chegam por ue_drop_files. Um texto desativado (ib_enabled = false) recusa qualquer largada
ib_track_mousebooleanfalseOpt-in: ativa ue_mouse_enter / ue_mouse_leave
ib_track_cyclebooleanfalseOpt-in: ativa ue_cycle, lançado no fim de cada passagem do deslizamento; sem ele, o texto desliza em silêncio
ib_auto_heightbooleanfalseOpt-in: o bloco mede a sua altura ideal e redimensiona o userobject; ver Base comum
ib_auto_widthbooleanfalseOpt-in: o userobject assume a LARGURA do seu texto — a linha mais longa, sem quebra de linha (os [br] contam), mais a margem e o contorno; um texto novo, uma fonte ou uma margem redimensionam-no de novo, e ue_auto_width indica a largura adotada. Um texto deslizante (ib_marquee) não tem largura natural e não comunica nenhuma
ib_follow_endbooleanfalseOpt-in, para um registo escrito com of_append_text: a vista fica EM BAIXO à medida que as linhas chegam — exceto se o leitor subiu para ler uma linha mais antiga: nunca é afastado dela
il_max_log_lineslong0Para um registo escrito com of_append_text: o número de linhas mantidas (0 = todas). Para além disso, as mais antigas saem, do ecrã E de is_text; o texto posto por is_text conta como uma linha. Baixá-lo corta de imediato
ii_max_widthinteger0Com ib_auto_width: a largura máxima do userobject, em píxeis (0 = sem limite). Um texto mais longo muda de linha nessa largura, e ib_auto_height assume a altura
ib_veto_linksbooleanfalseOpt-in: antes de um [hyperlink] se abrir, é perguntado ue_hyperlink_opening; devolver FALSE mantém a hiperligação fechada e trata-a o senhor (o seu próprio navegador, uma confirmação). Desativado por omissão, como qualquer evento cancelável da biblioteca: a hiperligação abre-se de imediato
is_theme_stylestring""Estilo visual do componente (constantes THEME_STYLE_*); vazio = o da aplicação, seguido a cada mudança
is_theme_modestring""Variante clara ou escura (constantes THEME_MODE_*); vazio = a da aplicação, seguida a cada mudança
il_theme_accentlong-1Cor de destaque deste componente (-1 = destaque da aplicação, ou o do tema)
is_tooltipstring""Tooltip simples apresentado ao passar sobre o componente
is_super_tooltip_titlestring""Título do tooltip enriquecido (prevalece sobre is_tooltip)
is_super_tooltip_textstring""Texto do tooltip enriquecido (aceita marcação enriquecida)
is_super_tooltip_imagestring""Imagem do tooltip enriquecido

Métodos #

MétodoFunção
of_reset ( )Repõe todas as propriedades na predefinição e limpa o texto. Devolve 0 depois de aplicado, -2 se o componente não estiver criado
of_set_redraw (boolean)Agrupa uma rajada de alterações num único desenho. Devolve 0 depois de aplicado, -2 se o componente não estiver criado
of_save_as_png (string) · of_save_as_jpg (string)Exporta a representação como imagem. Devolve 0 depois de a imagem ser escrita, -4 se a escrita falhar, -2 se o componente não estiver criado
of_refresh_parent_color ( )Relê a cor do objeto sobre o qual o bloco está pousado. Com il_back_color e ii_corner_radius, os cantos arredondados mostram essa cor, lida quando estas duas propriedades são definidas: deve chamar-se depois de alterar o BackColor da janela, ou de mover o bloco para outro pai. Devolve 0 depois de enviado, -2 se o componente não estiver criado
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. Devolve 0 depois de enviado, -2 se o componente não estiver criado
of_append_text (string as_markup)Acrescenta UMA linha no fim do texto, para um registo: só essa linha segue para o componente e só ela é desenhada — reescrever is_text a cada linha reenviava e redesenhava todo o registo. as_markup aceita a mesma marcação que is_text; uma linha começa sem etiquetas abertas, e uma linha vazia mantém a altura de uma linha. Relido, is_text contém todas as linhas, unidas por [br], cada uma fechando as etiquetas que deixava abertas. Com ib_follow_end a vista fica em baixo, com il_max_log_lines as linhas mais antigas saem; um leitor de ecrã anuncia cada nova linha. Devolve 0 depois de enviado, -2 se o componente não estiver criado
of_clear ( )Esvazia o texto, incluindo todas as linhas de um registo, e mantém todas as outras definições (of_reset repõe-nas todas no seu valor por omissão). Devolve 0 depois de enviado, -2 se o componente não estiver criado

Eventos #

EventoAcionado quando
ue_clicked ( )Clique esquerdo no bloco — não é acionado numa zona [action] ou [hyperlink] (sem duplicação), no cabeçalho de um [foldarea] (dobrar não gera nada), nem depois de uma seleção de texto
ue_hyperlink (string as_url, boolean ab_opened)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. ab_opened diz se se abriu de facto: FALSE para um esquema diferente de http, https ou mailto (of_get_last_error() diz porquê), ou quando ue_hyperlink_opening o manteve fechado
ue_hyperlink_opening (string as_url) → booleanCancelável, perguntado antes de uma zona [hyperlink=url] se abrir, só quando ib_veto_links = true. Devolver FALSE mantém a hiperligação fechada e trata-a o senhor: ue_hyperlink chega então com ab_opened = FALSE. Por omissão: TRUE
ue_action (string as_key)Uma zona [action=id] foi clicada: cabe ao programador ligar aí o seu código. A zona também se alcança pelo teclado: Tab até ela, depois Enter ou Espaço
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_auto_width (long al_width)O bloco assumiu uma nova largura, em unidades PowerBuilder — requer ib_auto_width = 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 (uma animação DENTRO do texto nunca conta como passagem) — requer ib_track_cycle = true
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.

// Congelar a apresentacao enquanto tudo e definido
uo_header.of_set_redraw(/*on*/ false)

// O titulo, centrado
uo_header.is_text  = "[b]Painel de vendas"
uo_header.is_align = uo_header.ALIGN_CENTER

// Fundo preenchido e texto branco legivel
uo_header.il_back_color = RGB(/*red*/ 60, /*green*/ 110, /*blue*/ 190)
uo_header.il_text_color = RGB(/*red*/ 255, /*green*/ 255, /*blue*/ 255)
uo_header.ii_padding = 14

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

// Tudo e desenhado de uma so vez
uo_header.of_set_redraw(/*on*/ true)
// event ue_auto_height de uo_header
of_reposition_below_header(al_height)   // desloca o conteudo para baixo do cabecalho

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

// Uma ligacao para uma pagina web e uma acao tratada pela sua aplicacao (ue_action)
uo_text.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_text : (string as_key)
choose case as_key
    case "renew" ; of_open_renewal()
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 #

// Duas seccoes recolhiveis : a segunda comeca recolhida
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]"

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

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 #

// A mensagem da faixa
uo_banner.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_banner.ib_marquee = true
uo_banner.ii_marquee_speed = 90        // pixels por segundo
uo_banner.is_marquee_direction = uo_banner.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.

Uma vez definido ib_track_cycle = true, 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_banner.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

// O que a zona mostra, centrado
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[])
// Local variables
integer li

// A largada terminou : a zona volta ao aspeto normal
uo_zone.ii_border_width = 0

// Cada ficheiro largado, um apos o outro
for li = 1 to UpperBound(as_files)
    of_import(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(/*red*/ 21, /*green*/ 101, /*blue*/ 192)
uo_zone.ii_border_width = 2
// event ue_drag_leave de uo_zone : o arrasto saiu, a zona volta ao aspeto normal
uo_zone.ii_border_width = 0

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 #

// Um texto que se comporta como um botao-ligacao
uo_link.is_text = "Selecionar tudo"
uo_link.il_text_color = RGB(/*red*/ 21, /*green*/ 101, /*blue*/ 192)
uo_link.ii_padding = 8
uo_link.ii_corner_radius = 6
uo_link.ib_hover_effect = true       // reage ao sobrevoo como um botao
// event ue_clicked de uo_link
of_select_all()

Um registo escrito linha a linha #

Cada chamada envia só a linha acrescentada; ib_follow_end mantém a última à vista enquanto o leitor não subir, e il_max_log_lines guarda só as mais recentes.

// Local variables
long ll_row

// Once, when the window opens : the view follows the end, the 500 newest lines are kept
uo_log.ib_follow_end = true
uo_log.il_max_log_lines = 500
uo_log.is_text = "[b]Import[/b]"

// For every row imported : one line, sent alone
for ll_row = 1 to 2000
    uo_log.of_append_text(/*markup*/ "Row " + String(ll_row) + " [color=#2e7d32]imported[/color]")
next

Uma etiqueta da largura do seu texto #

// A status chip : background, rounded corners, and the width of its text
uo_status.is_text = "[b]Status :[/b] connected"
uo_status.il_back_color = RGB(/*red*/ 232, /*green*/ 245, /*blue*/ 233)
uo_status.ii_corner_radius = 12
uo_status.ib_auto_width = true

Uma etiqueta de campo escrita à maneira do PowerBuilder #

Uma etiqueta retomada de um StaticText do PowerBuilder mantém o seu &: com ib_mnemonic a letra fica sublinhada e && escreve um &. Como no PowerBuilder, o atalho em si é o Accelerator do campo que a etiqueta designa.

// The & marks the shortcut letter : "Customer name:" with the C underlined
uo_label.ib_mnemonic = true
uo_label.is_text = "&Customer name:"

Decidir se uma hiperligação se abre #

Com ib_veto_links, ue_hyperlink_opening é perguntado antes de um [hyperlink] se abrir: devolver FALSE mantém-no fechado — abra-o à sua maneira, ou peça uma confirmação — e ue_hyperlink chega então com ab_opened = FALSE.

// Ask before a link opens
uo_text.ib_veto_links = true
uo_text.is_text = "See the [hyperlink=https://pbtoolboxai.net/doc/]documentation[/hyperlink]."
// ue_hyperlink_opening event of uo_text : (string as_url) returns boolean
// Only the pages of the company site open, every other link stays shut
return Left(as_url, 24) = "https://pbtoolboxai.net/"

Boas práticas #

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

MembrosFunçãoDetalhado em
of_resetRepor o componente a zero3.6 Repor um componente a zero: of_reset()
of_register_shortcut · of_clear_shortcutsAtalhos de teclado do componente3.5 Os atalhos de teclado
of_is_created · of_is_ready · of_get_last_errorSe nasceu, se está pronto, o que falhou3.7 Diagnóstico
of_save_as_png · of_save_as_jpgExportar a renderização como imagem3.8 Exportar a representação como imagem
of_set_redrawAgrupar as alterações num único repinte3.10 Boas práticas
of_preload_iconsÍcones mostrados sem atrasoApresentação instantânea: of_icon
of_set_translationTraduzir uma legenda do componente5.2 Adaptar uma etiqueta: of_set_translation
of_focus_webviewDar o foco ao componente6.4 Teclado e focus
of_print · of_print_to_pdfImprimir, ou escrever um PDF6.9 Imprimir
of_set_property · of_get_property · of_component_nameControlar uma propriedade pelo nome3.1 O motor de propriedades
is_accessible_name · is_accessible_descriptionO nome e a descrição que um leitor de ecrã diz3.4 Propriedades e eventos opcionais

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.


← Referência dos componentes · Índice do guia