messagebox — n_pbt_messagebox #

← Referência dos componentes · Índice do guia

Caixa de diálogo modal com tema, de retorno síncrono: o substituto direto do MessageBox() do PowerBuilder, com texto formatado, botões livres, ícones e caixa de verificação.

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

Em resumo #

Ao contrário dos componentes visuais, este objeto não se insere numa janela: cria-se, configura-se, apresenta-se, destrói-se.

n_pbt_messagebox lnv_mb

lnv_mb = create n_pbt_messagebox
// ... configuracao ...
destroy lnv_mb

Início rápido #

n_pbt_messagebox lnv_mb

lnv_mb = create n_pbt_messagebox

lnv_mb.is_title   = "Eliminação"
lnv_mb.is_icon    = lnv_mb.ICON_WARNING
lnv_mb.is_message = "Eliminar definitivamente [b]12 processos[/b]?[br][br]Esta ação é irreversível."

lnv_mb.of_add_button(/*texto*/ "Eliminar", /*predefinido*/ true,  /*cancelamento*/ false)   // -> 1
lnv_mb.of_add_button(/*texto*/ "Cancelar", /*predefinido*/ false, /*cancelamento*/ true)    // -> 2

if lnv_mb.of_show(/*hwnd*/ Handle(this)) = 1 then
    of_supprimer()
end if

destroy lnv_mb

of_show aguarda a resposta do utilizador: a linha seguinte só é executada após o clique, exatamente como acontece com MessageBox().

Propriedades #

A definir antes de of_show.

Constantes #

Métodos #

A etiqueta de um botão aceita o texto formatado com etiquetas e o mnemónico & ("&Guardar" sublinha o G e ativa-o com Alt+G); && apresenta um E comercial literal.

O teclado #

Na abertura, nenhum botão tem contorno de foco: é intencional e corresponde ao comportamento das caixas de diálogo modernas do Windows. O contorno só aparece após uma primeira pressão em Tab, ou seja, quando o utilizador passa explicitamente para o teclado. Enter e Esc permanecem ativos desde o primeiro segundo, mesmo sem foco visível.

Exemplos #

Questão fechada com botão predefinido #

n_pbt_messagebox lnv_mb
long ll_reponse

lnv_mb = create n_pbt_messagebox

lnv_mb.is_title   = "Guardar as alterações"
lnv_mb.is_icon    = lnv_mb.ICON_QUESTION
lnv_mb.is_message = "O processo foi modificado. Pretende guardar antes de fechar?"

lnv_mb.of_add_button(/*texto*/ "&Guardar",     /*predefinido*/ true,  /*cancelamento*/ false)  // 1
lnv_mb.of_add_button(/*texto*/ "&Não guardar", /*predefinido*/ false, /*cancelamento*/ false) // 2
lnv_mb.of_add_button(/*texto*/ "Cancelar",          /*predefinido*/ false, /*cancelamento*/ true)   // 3

ll_reponse = lnv_mb.of_show(/*hwnd*/ Handle(this))
destroy lnv_mb

choose case ll_reponse
    case 1 ; of_enregistrer() ; Close(parent)
    case 2 ; Close(parent)
    case else ; // 3 ou 0: nao se fecha
end choose

Mensagem enriquecida e ícone #

lnv_mb.is_title   = "Importação concluída"
lnv_mb.is_icon    = lnv_mb.ICON_SUCCESS
lnv_mb.is_message = "[b]1 240 linhas[/b] integradas.[br][br]" &
                  + "[accent]18 duplicados[/accent] foram ignorados."

lnv_mb.of_add_button(/*texto*/ "OK", /*predefinido*/ true, /*cancelamento*/ false)
lnv_mb.of_show(/*hwnd*/ Handle(this))

Caixa «não voltar a perguntar» #

n_pbt_messagebox lnv_mb

lnv_mb = create n_pbt_messagebox

lnv_mb.is_title    = "Eliminação"
lnv_mb.is_icon     = lnv_mb.ICON_WARNING
lnv_mb.is_message  = "Eliminar as linhas selecionadas? Esta ação é irreversível."
lnv_mb.is_checkbox = "Não voltar a perguntar"
lnv_mb.ib_checked  = false

lnv_mb.of_add_button(/*texto*/ "Eliminar", /*predefinido*/ true,  /*cancelamento*/ false)
lnv_mb.of_add_button(/*texto*/ "Cancelar", /*predefinido*/ false, /*cancelamento*/ true)

if lnv_mb.of_show(/*hwnd*/ Handle(this)) = 1 then
    of_supprimer()
    // Memorizar a escolha do utilizador
    ib_confirmer_suppression = not lnv_mb.of_checked()
end if

destroy lnv_mb

Botão com contagem decrescente #

lnv_mb.is_title   = "Reinício"
lnv_mb.is_icon    = lnv_mb.ICON_INFORMATION
lnv_mb.is_message = "A aplicação vai reiniciar para aplicar a atualização."

// "Continuar" permanece esbatido durante 3 segundos (e apresentado um contador)
lnv_mb.of_add_button_timed(/*texto*/ "Continuar", /*predefinido*/ true, /*cancelamento*/ false, &
                           /*segundos_ativo*/ 3, /*segundos_clique*/ 0)

// "Mais tarde" clica-se sozinho ao fim de 10 segundos
lnv_mb.of_add_button_timed(/*texto*/ "Mais tarde", /*predefinido*/ false, /*cancelamento*/ true, &
                           /*segundos_ativo*/ 0, /*segundos_clique*/ 10)

lnv_mb.of_show(/*hwnd*/ Handle(this))

Mensagem longa: limitar o tamanho #

// Um texto volumoso: a caixa e limitada e o corpo desloca-se
lnv_mb.is_title      = "Notas de versão"
lnv_mb.is_message    = ls_notes
lnv_mb.il_max_width  = 480
lnv_mb.il_max_height = 320

lnv_mb.of_add_button(/*texto*/ "Fechar", /*predefinido*/ true, /*cancelamento*/ true)
lnv_mb.of_show(/*hwnd*/ Handle(this))

Reutilizar uma instância #

// Uma instancia de janela, varios dialogos: of_reset entre cada chamada
inv_mb.of_reset()      // limpa as propriedades E os botoes anteriores

inv_mb.is_title   = "Segundo diálogo"
inv_mb.is_message = "Cada of_reset recomeça a partir de uma caixa vazia."
inv_mb.of_add_button(/*texto*/ "OK", /*predefinido*/ true, /*cancelamento*/ false)
inv_mb.of_show(/*hwnd*/ Handle(this))

Boas práticas #

• Chamar sempre of_reset() antes de reconfigurar uma instância reutilizada: sem isso, os botões do diálogo anterior somam-se aos novos.
• Marque sistematicamente um botão predefinido e um botão de cancelamento: o utilizador que trabalha com o teclado espera Enter e Esc.
• Teste o valor de retorno 0: significa que a caixa foi fechada sem escolha (cruz ou Esc). Trate-o como o cancelamento.
• Passe Handle(this) (ou Handle(parent)) como janela chamadora: a caixa centra-se sobre ela e a modalidade aplica-se à janela correta.
• Reserve o vermelho e ICON_ERROR para os erros verdadeiros; uma confirmação banal merece ICON_QUESTION.
• Para uma informação que não exige qualquer resposta, é preferível uma notificação não bloqueante: ver toaster.

← Referência dos componentes · Índice do guia