stepbar — u_pbt_stepbar #

← Referência dos componentes · Índice do guia

Sequência de etapas de um assistente: as etapas já concluídas, a etapa atual e as que estão por vir, na horizontal ou na vertical.

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

Em resumo #

Início rápido #

// event open da janela
uo_etapes.of_add_step(/*key*/ "compte",  /*etiqueta*/ "Conta")
uo_etapes.of_add_step(/*key*/ "profil",  /*etiqueta*/ "Perfil")
uo_etapes.of_add_step(/*key*/ "paiement", /*etiqueta*/ "Pagamento")
uo_etapes.of_add_step(/*key*/ "fin",     /*etiqueta*/ "Confirmação")

// Etapa atual (1 = a primeira)
uo_etapes.ii_current = 1

// Botao Seguinte do assistente
uo_etapes.ii_current = uo_etapes.ii_current + 1

O modelo: uma etapa, três estados automáticos #

Uma etapa não tem estado a gerir manualmente. Ele deduz-se da sua posição relativamente a ii_current:

Um quarto estado, error, nunca se obtém automaticamente: é forçado numa etapa que falhou (ver mais abaixo).

Propriedades #

Propriedades de uma etapa — n_pbt_stepbar_step #

Obtidas através de of_step(id):

Métodos #

O terceiro argumento é o ícone, como em todo o resto da biblioteca (of_add_item da listbar, of_add_panel da statusbar, of_add_tile da tilesbox). A segunda linha vem depois.

Eventos #

A barra NÃO navega sozinha. Um clique comunica (ue_step_clicked) e mais nada: a barra fica onde está. É o utilizador que a desloca, definindo ii_current ou chamando of_next / of_previous — e esses deslocamentos anunciam-se com ue_step_changed.

Esta divisão não é uma limitação, é o sentido do componente: uma barra de passos reflete um percurso que a sua aplicação conduz. Chegar ao passo 3 costuma significar que um formulário era válido e que um registo foi guardado; nenhum clique pode decidir isso por si.

ue_step_clicked transporta o passo visado, ue_step_changed transporta além disso o passo deixado — tanto pelo identificador de negócio como pela ordem. É esse par que permite escrever «recuar sim, saltar à frente não» numa linha.

is_navigation_mode continua a ser o filtro do clique: NAV_NONE deixa de lançar seja o que for, NAV_BACKWARD só deixa clicar as etapas já percorridas.

Com o teclado #

A barra é uma única paragem de tabulação: uma vez alcançada, percorre-se inteiramente com o teclado.

As setas não selecionam, ao contrário dos separadores de um dockcontainer. Alcançar uma etapa coloca uma pergunta à sua aplicação: percorrer uma barra de oito etapas enviaria oito, e uma recusa a meio caminho deixaria o foco e a etapa atual dessincronizados.

Cada etapa é um verdadeiro botão: leva a sua etiqueta e o seu estado no nome falado («Conta - concluída»), a etapa atual está marcada com aria-current="step", e uma etapa desativada é um botão desativado — não apenas um texto esbatido. O marcador numerado não é lido em voz alta: uma ordem não ensina nada.

Exemplos #

Avançar no assistente #

uo_etapes.of_add_step(/*key*/ "compte",   /*etiqueta*/ "Conta")
uo_etapes.of_add_step(/*key*/ "profil",   /*etiqueta*/ "Perfil")
uo_etapes.of_add_step(/*key*/ "paiement", /*etiqueta*/ "Pagamento")
uo_etapes.of_add_step(/*key*/ "fin",      /*etiqueta*/ "Confirmação")

// As etapas 1 e 2 passam automaticamente a "concluida" (assinalada)
uo_etapes.ii_current = 3

Assinalar uma etapa em erro #

// O estado de uma etapa forca-se atraves do seu handle
uo_etapes.of_step(/*key*/ "profil").is_state = n_pbt_stepbar_step.STATE_ERROR

// Uma vez corrigido o problema, devolve-se o controlo ao calculo automatico
uo_etapes.of_step(/*key*/ "profil").is_state = n_pbt_stepbar_step.STATE_AUTO

Sequência vertical #

// left / right : a sequencia desenha-se verticalmente, ideal a margem de um formulario
uo_etapes.is_position = uo_etapes.POSITION_START

// O TERCEIRO argumento e o icone : ocupa o lugar do numero da etapa
uo_etapes.of_add_step(/*key*/ "compte", /*etiqueta*/ "Conta", /*icone*/ "mono:img\packimages.dll:svg/samples/folder-open")

Etiquetas enriquecidas em duas linhas #

// A etiqueta de uma etapa aceita as etiquetas de texto rico
uo_etapes.of_add_step("compte",   "[b]Conta[/b][br][size=9](ligação)")
uo_etapes.of_add_step("profil",   "[b]Perfil[/b][br][size=9](os seus dados)")
uo_etapes.of_add_step("paiement", "[b]Pagamento[/b][br][size=9](cartão)")
uo_etapes.of_add_step("fin",      "[accent][b]Concluído[/b][/accent]")

uo_etapes.ii_current = 2

Navegação por clique #

// event ue_step_clicked de uo_etapes : (integer ai_index, string as_key)
// A barra NAO se moveu : e aqui que se decide.
if ai_index > uo_etapes.ii_current then
    MessageBox("Assistente", "Conclua o passo atual antes de prosseguir.")
    return
end if
uo_etapes.ii_current = ai_index

Etapa condicional #

// Um cliente ja conhecido nao tem etapa "Perfil" a preencher
uo_etapes.of_step("profil").ib_visible = false

Boas práticas #

• Dê a cada passo um identificador de negócio estável ("paiement"): é esse que recebe em ue_step_clicked e ue_step_changed, não um número que se desloca à menor inserção.
• Deixe o componente calcular os estados; force is_state apenas para o erro.
• O clique numa etapa é um simples sinal: cabe ao programador autorizar (ou não) o salto, em especial para uma etapa ainda não atingida.
• Enquadre a declaração das etapas com of_set_redraw(false) / of_set_redraw(true) quando são numerosas.
• Chame of_reset() antes de reutilizar a mesma sequência para outro assistente.

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.

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.

← Referência dos componentes · Índice do guia