toaster — n_pbt_toaster #

← Referência dos componentes · Índice do guia

Notificações «toast» no canto do ecrã: uma mensagem que aparece, informa e desaparece sem bloquear o utilizador nem interromper a sua introdução de dados.

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

Em resumo #

O toast é uma window destacada: flutua por cima da aplicação (ou de todo o ecrã) e fecha-se sozinho.

// Variaveis locais
n_pbt_toaster lnv_toast

// Criar o notificador
lnv_toast = create n_pbt_toaster

// ... configuracao ...

// Destrui-lo no fim
destroy lnv_toast

Início rápido #

// Variaveis locais
n_pbt_toaster lnv_toast

// Criar o notificador
lnv_toast = create n_pbt_toaster

// Configurar e depois mostrar
lnv_toast.ipo_owner = this                       // window a qual o toast se fixa
lnv_toast.is_kind   = lnv_toast.KIND_SUCCESS     // icone verde + friso de sucesso
lnv_toast.is_text   = "As suas alterações foram [b]guardadas[/b]."
lnv_toast.of_show()

// Destrui-lo no fim
destroy lnv_toast

Tudo se configura por propriedades e, em seguida, of_show() — que não recebe qualquer argumento — faz aparecer a notificação.

Propriedades #

A definir antes de of_show.

Constantes #

Porquê LEFT/RIGHT aqui e START/END noutros locais? O toast é uma window de sistema posicionada em pixels do ecrã, não um conteúdo que siga um sentido de leitura: um canto do ecrã não tem «início». Estas constantes permanecem, portanto, deliberadamente físicas, e não mudam de lado quando a aplicação passa a escrita da direita para a esquerda. Ver Idioma e RTL.

Métodos #

Vários toasts apresentados no mesmo canto empilham-se automaticamente. Cada um tem uma cruz de fecho; o identificador devolvido por of_show permite distingui-los nos eventos e fechá-los a partir do código.

A contagem decrescente é suspensa enquanto o ponteiro estiver sobre o toast: uma notificação não deve desvanecer-se sob os olhos de quem a lê. Uma barra fina em baixo mostra o tempo restante — e explica assim o seu desaparecimento. Um clique no corpo responde e fecha, em ambos os modos de alojamento.

Uma notificação criada com il_timeout = 0 permanece no ecrã enquanto ninguém a fechar: convém guardar o respetivo identificador para a poder retirar quando a tarefa que anuncia estiver concluída.

// Variaveis locais
long ll_toast

// Notificacao persistente : ficara visivel ate of_close.
inv_toaster.is_text = "Exportação em curso..."
inv_toaster.il_timeout = /*ms, 0 = sem fecho automatico*/ 0
ll_toast = inv_toaster.of_show()

// ... processamento demorado ...

// Fechar o toast no fim do trabalho
inv_toaster.of_close(/*id*/ ll_toast)

Eventos — o toast responde #

Uma notificação não é um simples «apresentar e esquecer»: pode indicar que foi clicada, que um botão de ação foi escolhido, ou que se fechou.

Não tem de ligar nada: defina ipo_owner (a window à qual o toast está ancorado) e trate os eventos. O componente recolhe-os enquanto um toast está no ecrã e dispara-os no objeto — sem recetor, sem temporizador.

1. Definir ipo_owner na window à qual o toast está ancorado:

// Ancorar os toasts a esta janela
inv_toaster.ipo_owner = this      // a window a qual o toast esta ancorado

2. Tratar os eventos desencadeados no toaster:

Se não espera qualquer retorno — nem botão de ação, nem clique no corpo — não tem nenhum destes eventos para tratar: a notificação aparece e desaparece sozinha. É o modo mais simples, perfeito para uma simples confirmação.

Exemplos #

Os quatro níveis #

// Info : uma mensagem neutra
inv_toaster.of_reset()
inv_toaster.is_kind = inv_toaster.KIND_INFO
inv_toaster.is_text = "Operação concluída."
inv_toaster.of_show()

// Sucesso : esta feito
inv_toaster.of_reset()
inv_toaster.is_kind = inv_toaster.KIND_SUCCESS
inv_toaster.is_text = "As suas alterações foram [b]guardadas[/b]."
inv_toaster.of_show()

// Aviso : merece atencao
inv_toaster.of_reset()
inv_toaster.is_kind    = inv_toaster.KIND_WARNING
inv_toaster.il_timeout = 5000                        // um pouco mais longo
inv_toaster.is_text    = "Espaço em disco reduzido na unidade C:."
inv_toaster.of_show()

// Erro : falhou
inv_toaster.of_reset()
inv_toaster.is_kind    = inv_toaster.KIND_ERROR
inv_toaster.il_timeout = 6000
inv_toaster.is_text    = "Não foi possível contactar o servidor."
inv_toaster.of_show()

Escolher o canto, na window ou no ecrã #

// Fixado ao canto superior direito da WINDOW (predefinicao : acompanha a aplicacao)
inv_toaster.is_position = inv_toaster.POSITION_TOP_RIGHT
inv_toaster.ib_screen   = false
inv_toaster.is_text     = "Fixado ao canto da window."
inv_toaster.of_show()

// Destacado : fixado ao canto do ECRA, visivel mesmo se a window estiver minimizada
inv_toaster.is_position = inv_toaster.POSITION_TOP_RIGHT
inv_toaster.ib_screen   = true
inv_toaster.is_text     = "Processamento noturno concluído."
inv_toaster.of_show()

Toast enriquecido: título, imagem e duração #

// Partir das definicoes por omissao
inv_toaster.of_reset()

// Um titulo, um texto e uma imagem
inv_toaster.is_title    = "Cópia de segurança concluída"
inv_toaster.is_text     = "1 240 ficheiros copiados para [b]\\servidor\backup[/b]."
inv_toaster.is_image    = "mono:img\backup.svg"
inv_toaster.il_timeout  = 8000                    // permanece 8 segundos
inv_toaster.of_show()

Notificação com botões de ação #

// event open : ancorar o toaster de uma vez por todas ; os retornos chegam sozinhos
inv_toaster.ipo_owner = this

// Propor duas acoes ; timeout 0 = o toast aguarda a decisao do utilizador
inv_toaster.of_reset()

// Titulo, texto e dois botoes, depois mostrar
inv_toaster.is_title   = "Atualização disponível"
inv_toaster.is_text    = "A versão 2.0 está pronta a ser instalada."
inv_toaster.il_timeout = 0
inv_toaster.of_add_button(/*key*/ "installer", /*label*/ "Instalar")
inv_toaster.of_add_button(/*key*/ "later", /*label*/ "Mais tarde")
inv_toaster.of_show()

// event ue_toast_action de inv_toaster : (long al_id, string as_key, string as_action)
choose case as_action
    case "installer" ; of_start_update()
    case "later" ; of_reporter(1)
end choose

Reagir ao clique na mensagem #

// event ue_toast_clicked de inv_toaster : (long al_id, string as_key)
// O utilizador clicou no corpo do toast : abrir o ecra correspondente
Open(w_journal_import)

Notificar a partir de um processamento demorado #

// Fim de uma importacao : informar sem bloquear o ecra de introducao de dados
inv_toaster.of_reset()

// O tipo e o texto seguem o resultado
if ll_errors = 0 then
    inv_toaster.is_kind = inv_toaster.KIND_SUCCESS
    inv_toaster.is_text = "Importação concluída: [b]" + String(ll_rows) + " linhas[/b] integradas."
else
    inv_toaster.is_kind    = inv_toaster.KIND_ERROR
    inv_toaster.il_timeout = 0                    // um erro tem de ser lido
    inv_toaster.is_text    = "Importação interrompida: " + String(ll_errors) + " erros."
end if

// Mostrar o toast
inv_toaster.of_show()

Boas práticas #

• Uma instância persistente por window (variável de instância criada na abertura) em vez de uma criação/destruição a cada mensagem: a ancoragem ipo_owner mantém-se e os retornos chegam. Um toaster destruído já não recebe nada: os seus toasts ficam no ecrã, mudos.
• Convém chamar of_reset() antes de cada notificação: sem isso, o título, a imagem ou os botões da anterior permanecem definidos.
• il_timeout = 0 deve reservar-se às mensagens que exigem uma decisão (erro bloqueante, ação proposta): um toast que não desaparece sozinho acaba por incomodar.
• ib_screen = true deve utilizar-se apenas para o que tem de permanecer visível quando a aplicação está em segundo plano (fim de processamento demorado, tarefa noturna).
• Um toast é uma mensagem transitória: se for absolutamente necessária uma resposta antes de continuar, deve utilizar-se a messagebox, que bloqueia e devolve a escolha.
• Para um estado permanente em vez de uma notificação, é preferível a statusbar.

← Referência dos componentes · Índice do guia