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.

// Variaveis locais
n_pbt_messagebox lnv_mb

// Criar o objeto de dialogo
lnv_mb = create n_pbt_messagebox

// ... configuracao ...

// Libertar o objeto de dialogo
destroy lnv_mb

Início rápido #

// Variaveis locais
n_pbt_messagebox lnv_mb

// Criar o objeto de dialogo
lnv_mb = create n_pbt_messagebox

// Configurar a caixa
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."

// Adicionar os botoes
lnv_mb.of_add_button(/*text*/ "Eliminar", /*default*/ true,  /*cancel*/ false)   // -> 1
lnv_mb.of_add_button(/*text*/ "Cancelar", /*default*/ false, /*cancel*/ true)    // -> 2

// Mostrar em modal e agir sobre o primeiro botao
if lnv_mb.of_show(/*hwnd*/ Handle(this)) = 1 then
    of_delete()
end if

// Libertar o objeto de dialogo
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 #

// Variaveis locais
n_pbt_messagebox lnv_mb
long ll_answer

// Criar o objeto de dialogo
lnv_mb = create n_pbt_messagebox

// Configurar a caixa
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?"

// Adicionar os botoes
lnv_mb.of_add_button(/*text*/ "&Guardar",     /*default*/ true,  /*cancel*/ false)  // 1
lnv_mb.of_add_button(/*text*/ "&Não guardar", /*default*/ false, /*cancel*/ false) // 2
lnv_mb.of_add_button(/*text*/ "Cancelar",          /*default*/ false, /*cancel*/ true)   // 3

// Mostrar em modal e depois libertar o objeto de dialogo
ll_answer = lnv_mb.of_show(/*hwnd*/ Handle(this))
destroy lnv_mb

// Agir conforme o botao clicado (posicao a partir de 1)
choose case ll_answer
    case 1 ; of_save() ; Close(parent)
    case 2 ; Close(parent)
    case else ; // 3 ou 0: nao se fecha
end choose

Mensagem enriquecida e ícone #

// Configurar a caixa
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."

// Adicionar o botao e depois mostrar a caixa
lnv_mb.of_add_button(/*text*/ "OK", /*default*/ true, /*cancel*/ false)
lnv_mb.of_show(/*hwnd*/ Handle(this))

Um valor dos seus dados na mensagem #

A mensagem é texto formatado: um parêntese reto é uma etiqueta. O nome de um cliente, um texto escrito por um utilizador passam por of_escape_markup (de n_pbt_utils) antes de entrar — caso contrário «Silva [action=x]» fecharia a caixa como uma escolha.

// Local variables
n_pbt_utils lnv_utils

// The name comes from the database : escape it, it is shown as it is
lnv_mb.is_title   = "Delete customer"
lnv_mb.is_message = "Delete the customer [b]" + lnv_utils.of_escape_markup(/*text*/ ls_name) + "[/b] ?"

// Add the buttons, then show the box
lnv_mb.of_add_button(/*text*/ "Delete", /*default*/ false, /*cancel*/ false)
lnv_mb.of_add_button(/*text*/ "Cancel", /*default*/ true, /*cancel*/ true)
lnv_mb.of_show(/*hwnd*/ Handle(this))

Caixa «não voltar a perguntar» #

// Variaveis locais
n_pbt_messagebox lnv_mb

// Criar o objeto de dialogo
lnv_mb = create n_pbt_messagebox

// Configurar a caixa
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

// Adicionar os botoes
lnv_mb.of_add_button(/*text*/ "Eliminar", /*default*/ true,  /*cancel*/ false)
lnv_mb.of_add_button(/*text*/ "Cancelar", /*default*/ false, /*cancel*/ true)

// Mostrar em modal e agir sobre o primeiro botao
if lnv_mb.of_show(/*hwnd*/ Handle(this)) = 1 then
    of_delete()

    // Memorizar a escolha do utilizador
    ib_confirm_delete = not lnv_mb.of_checked()
end if

// Libertar o objeto de dialogo
destroy lnv_mb

Botão com contagem decrescente #

// Configurar a caixa
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(/*text*/ "Continuar", /*default*/ true, /*cancel*/ false, /*enable_secs*/ 3, /*click_secs*/ 0)

// "Mais tarde" clica-se sozinho ao fim de 10 segundos
lnv_mb.of_add_button_timed(/*text*/ "Mais tarde", /*default*/ false, /*cancel*/ true, /*enable_secs*/ 0, /*click_secs*/ 10)

// Mostrar em modal
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

// Adicionar o botao e depois mostrar a caixa
lnv_mb.of_add_button(/*text*/ "Fechar", /*default*/ true, /*cancel*/ 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

// Configurar a nova caixa e depois mostra-la
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(/*text*/ "OK", /*default*/ true, /*cancel*/ 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