button — `u_pbt_button` #

← Referência dos componentes · Índice do guia

Botão com tema: texto e ícone, estilos, emblema de contador, atalho de teclado, botões predefinido e de cancelamento.

⚠️ Vários botões? Prefira buttonbar: uma fila num único componente, onde N button separados custam N vezes a memória (cada componente é uma vista do motor). button continua suportado para o código existente. O que cada propriedade passa a ser na barra — e o que só button sabe fazer — está em « De button para buttonbar », mais abaixo.

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

Em resumo #

Userobject	`u_pbt_button`
Classe de items	— (componente sem items)
Serve para	Substituir um `commandbutton` por um botão moderno, com tema, ícone e emblema
Opções opt-in	`ib_track_mouse`

Início rápido #

// event open da janela
uo_button.is_text  = "&Guardar"              // & = letra sublinhada : Alt+G aciona-o
uo_button.is_style = uo_button.STYLE_PRIMARY // botao de acao principal
uo_button.is_image = "mono:img\save.svg"     // icone recolorido pelo tema
uo_button.is_shortcut = "Ctrl+S"             // atalho apresentado e ativo
uo_button.is_tooltip = "Guarda o processo em curso"

// event ue_clicked de uo_button
of_save()

Constantes #

Constante	Valor	Para
`STYLE_STANDARD` · `STYLE_PRIMARY` · `STYLE_FLAT`	`"standard"` `"primary"` `"flat"`	`is_style`

Propriedades #

Propriedade	Tipo	Predefinição	Função
`is_text`	string	`""`	Etiqueta. Aceita a formatação com etiquetas e o mnemónico `&` (`&Guardar` sublinha o G, e Alt+G aciona-o onde quer que esteja o foco na janela, depois dos atalhos explícitos e nunca esbatido; uma barra de menus PB que usa a mesma letra perde-a); `&&` apresenta um E comercial literal. É permitida uma etiqueta feita só de uma imagem (`[picture=…]`). Qualquer letra ou algarismo pode ser a mnemónica, letras acentuadas incluídas (`&Édição`: Alt+É); só conta o primeiro `&`, um segundo é apresentado sem sublinhado. Sem nenhum texto apresentado, é o tooltip que dá o nome ao botão para os leitores de ecrã
`is_image`	string	`""`	Ícone apresentado antes da etiqueta (formas aceites: caminho, `mono:`, `tint:`, recurso de DLL). Sem etiqueta, o ícone fica centrado
`ii_image_size`	integer	`0`	Tamanho do ícone em píxeis (`0` = o tamanho do tema, 18 píxeis)
`is_style`	string	`"standard"`	Aspeto: `STYLE_STANDARD`, `STYLE_PRIMARY` (fundo de destaque, ação principal), `STYLE_FLAT` (sem contorno)
`ib_enabled`	boolean	`true`	Botão ativo ou esbatido. Esbatido, ignora o rato e o teclado, sai da ordem de tabulação e deixa à janela Enter, Esc, o seu atalho e a sua mnemónica — à sua janela: um botão predefinido ou de cancelamento esbatido, o mais próximo do focus, mantém a tecla longe do botão predefinido de outra folha. Esbatido, nunca toma o focus do teclado
`ib_default`	boolean	`false`	Botão predefinido: Enter aciona-o onde quer que esteja o focus na janela, enquanto estiver ativo; um filete de destaque assinala-o. Com dois botões predefinidos ganha o mais próximo do focus, e em empate nenhum. Ctrl, Alt ou Shift + Enter é uma combinação: nunca prime o botão predefinido
`ib_cancel`	boolean	`false`	Botão de cancelamento: Esc aciona-o onde quer que esteja o focus na janela, enquanto estiver ativo; Ctrl, Alt ou Shift + Esc é uma combinação, nunca o botão de cancelamento
`is_shortcut`	string	`""`	Atalho de teclado (`"Ctrl+S"`, `"F5"`, `"Ctrl+Shift+N"`), ativo onde quer que esteja o focus na janela e acrescentado ao tooltip ("Guardar (Ctrl+S)"). Os nomes das teclas escrevem-se em inglês (`Enter`, `Esc`, `Del`, `PageUp`…); um atalho que a janela não sabe acionar (modificador ou tecla desconhecidos) é recusado e relê-se `""`. Com Ctrl ou Alt, `+`, `-`, `,`, `.`, as setas, `Space`, `Tab` e `Backspace` também são aceites. Relê-se na sua forma canónica, em minúsculas: `"Ctrl+Del"` relê-se `"ctrl+delete"` — compare a releitura com essa forma, não com o que escreveu
`ii_badge`	integer	`0`	Emblema de contador no canto superior final (direito, esquerdo da direita para a esquerda); acima de 99 mostra `99+` (`0` = nenhum)
`il_badge_color`	long	`-1`	Fundo do emblema, em RGB do PowerBuilder (`-1` = não definido: a cor que vem do tema; `0` é o preto, como para qualquer outra cor). A cor do texto é escolhida automaticamente para que o contador continue legível
`ii_badge_size`	integer	`0`	Altura do emblema em píxeis (`0` = o tamanho que vem do tema). O tamanho da letra acompanha sozinho: o contador continua centrado seja qual for a dimensão. Um tamanho negativo relê-se `0`
`ib_track_mouse`	boolean	`false`	Opt-in: ativa `ue_mouse_enter` / `ue_mouse_leave`. Um botão esbatido não lança `ue_mouse_enter`; uma entrada lançada tem sempre o seu `ue_mouse_leave`, mesmo que o botão tenha sido esbatido entretanto
`is_theme_style`	string	`""`	Estilo visual do componente (constantes `THEME_STYLE_*`); vazio = o da aplicação, seguido a cada mudança
`is_theme_mode`	string	`""`	Variante clara ou escura (constantes `THEME_MODE_*`); vazio = a da aplicação, seguida a cada mudança
`il_theme_accent`	long	`-1`	Cor de destaque deste componente (`-1` = destaque da aplicação, ou o do tema)
`is_tooltip`	string	`""`	Tooltip simples apresentado ao passar sobre o componente. Num botão sem texto (só um ícone), é também o nome que um leitor de ecrã diz
`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 respetiva predefinição. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_set_redraw (boolean)`	Agrupa uma rajada de modificaçõ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

Eventos #

Evento	Acionado quando
`ue_clicked ( )`	O botão é clicado; ou acionado por Enter ou Espaço (sozinhos) quando tem o focus, por Enter / Esc conforme o seu papel, pelo seu atalho ou por Alt + a sua letra, onde quer que esteja o focus na janela. Ctrl, Alt ou Shift + Enter ou Espaço no botão com o focus são combinações da janela: não o clicam
`ue_rclicked ( )`	Clique com o botão direito no botão
`ue_mouse_enter ( )`	O rato entra — exige `ib_track_mouse = true`
`ue_mouse_leave ( )`	O rato sai — exige `ib_track_mouse = 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 #

Os três estilos #

// O botao principal : responde a tecla Enter
uo_ok.is_text     = "Confirmar"
uo_ok.is_style    = uo_ok.STYLE_PRIMARY
uo_ok.ib_default  = true          // tecla Enter

// O botao de cancelar : responde a tecla Esc
uo_cancel.is_text   = "Cancelar"
uo_cancel.is_style  = uo_cancel.STYLE_STANDARD
uo_cancel.ib_cancel = true       // tecla Esc

// Um botao de ajuda discreto
uo_help.is_text  = "Ajuda"
uo_help.is_style = uo_help.STYLE_FLAT   // discreto, sem contorno

Ícone e emblema de notificação #

// Um icone maior e um selo de contador
uo_messages.is_text  = "Mensagens"
uo_messages.is_image = "mono:img\mail.svg"
uo_messages.ii_image_size = 20
uo_messages.ii_badge = 12             // emblema "12"

// Local variables
long ll_unread

// Atualizar o contador: o emblema desaparece a 0
ll_unread = 12
uo_messages.ii_badge = ll_unread

// Um emblema vermelho para um alerta, em vez da cor do tema.
// A cor do texto e escolhida sozinha para continuar legivel.
uo_messages.il_badge_color = RGB(/*red*/ 200, /*green*/ 30, /*blue*/ 30)

// Voltar a cor que vem do tema
uo_messages.il_badge_color = -1

Etiqueta enriquecida #

// Texto rico : negrito e tamanho reduzido, ou uma imagem no texto
uo_button.is_text = "[b]Exportar[/b] [size-=20]· CSV[/size-=20]"
uo_button.is_text = "Estado [picture=mono:img\ok.svg,14,14]"

Botão de ação principal com atalho e ajuda #

// Congelar o desenho durante as definicoes
uo_submit.of_set_redraw(/*on*/ false)

// Texto, estilo, atalho, botao predefinido e dica rica
uo_submit.is_text     = "&Confirmar a encomenda"
uo_submit.is_style    = uo_submit.STYLE_PRIMARY
uo_submit.is_shortcut = "Ctrl+Enter"
uo_submit.ib_default  = true
uo_submit.is_super_tooltip_title = "Confirmar"
uo_submit.is_super_tooltip_text  = "Envia a encomenda ao fornecedor." &
                                    + "[br][br][size-=15]Ação irreversível.[/size-=15]"

// Um unico redesenho, com tudo
uo_submit.of_set_redraw(/*on*/ true)

Reagir à passagem do rato #

// Raise ue_mouse_enter and ue_mouse_leave when the pointer comes and goes
uo_button.ib_track_mouse = true

// event ue_mouse_enter de uo_button
uo_status.of_panel(/*key*/ "main").is_text = "Guarda o processo em curso"

De button para buttonbar #

Uma fila de botões vive melhor numa única buttonbar. Eis o que cada membro de button passa a ser na barra — e o que só button sabe fazer:

`button`	`buttonbar`
`uo_button.is_text = "&Save"`	`uo_bar.of_add_button("save", "&Save")`, `uo_bar.of_button("save").is_text`
`uo_button.is_image`	`uo_bar.of_button("save").is_image`
`uo_button.ii_image_size`	`uo_bar.ii_image_size` (um tamanho para todos os botões da barra)
`uo_button.is_style`	`uo_bar.of_button("save").is_style`
`uo_button.ib_enabled`	`uo_bar.of_button("save").ib_enabled`; toda a barra: `uo_bar.ib_enabled`
`uo_button.ib_default` · `uo_button.ib_cancel`	`uo_bar.is_default = "save"` · `uo_bar.is_cancel = "close"`: a chave do botão
`uo_button.is_shortcut`	`uo_bar.of_button("save").is_shortcut`
`uo_button.ii_badge`	`uo_bar.of_button("save").is_badge` (um texto)
`uo_button.il_badge_color`	`uo_bar.of_button("save").il_badge_color`
`uo_button.ii_badge_size`	`uo_bar.ii_badge_size` (um tamanho para todos os botões da barra)
`uo_button.ue_clicked` · `uo_button.ue_rclicked`	`uo_bar.ue_clicked` · `uo_bar.ue_button_rclicked`, que trazem a chave do botão
`uo_button.ib_track_mouse` · `uo_button.ue_mouse_enter` · `uo_button.ue_mouse_leave`	— a barra não tem eventos de entrada e saída do rato: mantenha `button` para isso

Boas práticas #

Um único botão primary por ecrã: é a ação esperada.
ib_default e ib_cancel substituem a gestão manual de Enter / Esc na janela.
Deve utilizar-se mono: para os ícones monocromáticos: acompanharão o tema claro tal como o escuro.
Deve chamar-se of_reset() antes de reutilizar um botão para outra ação.

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.

Membros	Função	Detalhado em
`of_reset`	Repor o componente a zero	3.6 Repor um componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Atalhos de teclado do componente	3.5 Os atalhos de teclado
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se nasceu, se está pronto, o que falhou	3.7 Diagnóstico
`of_save_as_png` · `of_save_as_jpg`	Exportar a renderização como imagem	3.8 Exportar a representação como imagem
`of_set_redraw`	Agrupar as alterações num único repinte	3.10 Boas práticas
`of_preload_icons`	Ícones mostrados sem atraso	Apresentação instantânea: `of_icon`
`of_set_translation`	Traduzir uma legenda do componente	5.2 Adaptar uma etiqueta: `of_set_translation`
`of_focus_webview`	Dar o foco ao componente	6.4 Teclado e focus
`of_print` · `of_print_to_pdf`	Imprimir, ou escrever um PDF	6.9 Imprimir
`of_set_property` · `of_get_property` · `of_component_name`	Controlar uma propriedade pelo nome	3.1 O motor de propriedades
`is_accessible_name` · `is_accessible_description`	O nome e a descrição que um leitor de ecrã diz	3.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.