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

> ▶ 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_bouton.is_text  = "&Guardar"              // & = letra sublinhada (mnemonica)
    uo_bouton.is_style = uo_bouton.STYLE_PRIMARY // botao de acao principal
    uo_bouton.is_image = "mono:img\save.svg"     // icone recolorido pelo tema
    uo_bouton.is_shortcut = "Ctrl+S"             // atalho apresentado e ativo
    uo_bouton.is_tooltip = "Guarda o processo em curso"

    // event ue_clicked de uo_bouton
    of_enregistrer()

## 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); `&&` apresenta um E comercial literal
`is_image` | string | `""` | Ícone apresentado antes da etiqueta (formas aceites: caminho, `mono:`, `tint:`, recurso de DLL)
`ii_image_size` | integer | `0` | Tamanho do ícone em píxeis (`0` = tamanho natural do componente)
`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
`ib_default` | boolean | `false` | Botão predefinido: a tecla Enter aciona-o; um filete de destaque assinala-o
`ib_cancel` | boolean | `false` | Botão de cancelamento: a tecla Esc aciona-o
`is_shortcut` | string | `""` | Atalho de teclado (`"Ctrl+S"`, `"F5"`, `"Ctrl+Shift+N"`), apresentado no tooltip e ativo quando o botão tem o focus
`ii_badge` | integer | `0` | Emblema de contador no canto superior direito (`0` = nenhum)
`il_badge_color` | long | `0` | Fundo do emblema, em RGB do PowerBuilder (`0` = a cor que vem do tema). 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
`ib_track_mouse` | boolean | `false` | Opt-in: ativa `ue_mouse_enter` / `ue_mouse_leave`
`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 respetiva predefinição
`of_set_redraw (boolean)` | Agrupa uma rajada de modificações num único desenho
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta a representação como imagem

## Eventos #

Evento | Acionado quando
--- | ---
`ue_clicked ( )` | O botão é clicado, ou acionado por Enter / Esc / pelo respetivo atalho
`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 #

    uo_ok.is_text     = "Confirmar"
    uo_ok.is_style    = uo_ok.STYLE_PRIMARY
    uo_ok.ib_default  = true          // tecla Enter

    uo_annuler.is_text   = "Cancelar"
    uo_annuler.is_style  = uo_annuler.STYLE_STANDARD
    uo_annuler.ib_cancel = true       // tecla Esc

    uo_aide.is_text  = "Ajuda"
    uo_aide.is_style = uo_aide.STYLE_FLAT   // discreto, sem contorno

### Ícone e emblema de notificação #

    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"

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

    // 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(200, 30, 30)

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

### Etiqueta enriquecida #

    uo_bouton.is_text = "[b]Exportar[/b] [size-=20]· CSV[/size-=20]"
    uo_bouton.is_text = "Estado [picture=mono:img\ok.svg,14,14]"

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

    uo_valider.of_set_redraw(false)

    uo_valider.is_text     = "&Confirmar a encomenda"
    uo_valider.is_style    = uo_valider.STYLE_PRIMARY
    uo_valider.is_shortcut = "Ctrl+Enter"
    uo_valider.ib_default  = true
    uo_valider.is_super_tooltip_title = "Confirmar"
    uo_valider.is_super_tooltip_text  = "Envia a encomenda ao fornecedor." &
                                        + "[br][br][size-=15]Ação irreversível.[/size-=15]"

    uo_valider.of_set_redraw(true)

### Reagir à passagem do rato #

    uo_bouton.ib_track_mouse = true

    // event ue_mouse_enter de uo_bouton
    uo_statut.of_item("main").is_text = "Guarda o processo em curso"

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

← Referência dos componentes · Índice do guia