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 #

Userobject	`u_pbt_stepbar`
Classe de items	`n_pbt_stepbar_step` (uma etapa)
Serve para	Situar o utilizador num assistente, num formulário de várias páginas, num processo de validação
Princípio	Declaram-se as etapas e depois desloca-se `ii_current`: os estados calculam-se automaticamente

Início rápido #

// event open da janela
uo_steps.of_add_step(/*key*/ "account",  /*label*/ "Conta")
uo_steps.of_add_step(/*key*/ "profile",  /*label*/ "Perfil")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Pagamento")
uo_steps.of_add_step(/*key*/ "done",     /*label*/ "Confirmação")

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

// Botao Seguinte do assistente : a etapa seguinte, saltando as ocultas e as desativadas
uo_steps.of_next()

// Botao Anterior
uo_steps.of_previous()

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:

Posição	Estado	Representação
Antes da etapa atual	`done` — concluída	Marcador assinalado
A etapa atual	`current` — em curso	Marcador realçado
Depois da etapa atual	`todo` — por vir	Marcador numerado, tonalidade discreta

Outros três estados nunca se obtêm automaticamente: são forçados numa etapa — error quando falhou, warning quando foi percorrida mas resta algo a rever, skipped quando foi ignorada (ver mais abaixo).

Propriedades #

Propriedade	Tipo	Predefinição	Função
`ii_current`	integer	`1`	Etapa atual, numerada a partir de 1 (número de etapas + 1 = tudo concluído). Defini-la lança `ue_step_changed` quando a barra se move. A etapa atual é seguida pela sua identidade: acrescentar, retirar ou deslocar uma etapa antes dela não muda a etapa atual. Definida antes das etapas, o valor é guardado e aplicado assim que a etapa existe. Uma etapa atual oculta não deixa nenhuma etapa «em curso» no ecrã. «Tudo concluído» fica ancorado na última etapa desse momento: uma etapa adicionada depois dela torna-se a etapa atual (e lança `ue_step_changed`); uma inserida antes não muda nada
`is_position`	string	`"top"`	Orientação: `top` / `bottom` (sequência horizontal) ou `start` / `end` (sequência vertical) — constantes `POSITION_TOP`, `POSITION_BOTTOM`, `POSITION_START`, `POSITION_END`. `START`/`END` são lógicas e acompanham o sentido de escrita
`is_navigation_mode`	string	`"free"`	Aquilo que um clique pode alcançar: `NAV_FREE` (qualquer etapa, a predefinição), `NAV_BACKWARD` (apenas as etapas já percorridas — voltar atrás, nunca saltar em frente), `NAV_VISITED` (qualquer etapa já alcançada, exceto a atual — depois de voltar atrás, as etapas alcançadas mais à frente continuam a um clique) ou `NAV_NONE` (nada: um simples indicador de progresso, conduzido apenas pelo seu código). O que continua clicável lança `ue_step_clicked`; a barra, essa, nunca se move num clique
`is_overflow_mode`	string	`"auto"`	Demasiadas etapas para a largura: `OVERFLOW_AUTO` compacta a barra abaixo de um mínimo legível por etapa (cada etapa passa a um ponto, apenas a atual conserva a etiqueta, e todas continuam clicáveis), `OVERFLOW_SCROLL` conserva as etiquetas e desloca, mantendo a etapa atual à vista, `OVERFLOW_SHRINK` comprime-as até às reticências. Uma sequência vertical nunca compacta
`is_theme_style`	string	`""`	Estilo visual do componente (constantes `THEME_STYLE_*`); vazio = o da aplicação, seguido a cada mudança
`is_theme_mode`	string	`""`	Variante clara ou escura (constantes `THEME_MODE_*`); vazio = a da aplicação, seguida a cada mudança
`il_theme_accent`	long	`-1`	Cor de destaque deste componente (`-1` = destaque da aplicação, ou o 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

Propriedades de uma etapa — `n_pbt_stepbar_step` #

Obtidas através de of_step(id):

Propriedade	Tipo	Predefinição	Função
`is_state`	string	`STATE_TODO`	Força o estado da etapa: `STATE_TODO`, `STATE_CURRENT`, `STATE_DONE`, `STATE_ERROR`, `STATE_WARNING` (percorrida, mas com algo a rever: marcador âmbar com um «!», etiqueta âmbar), `STATE_SKIPPED` (ignorada, nem feita nem por fazer: marcador oco com anel tracejado e um «–», etiqueta em itálico). Os leitores de ecrã anunciam-nas «com um aviso» e «ignorado»; depois de uma ou de outra, a linha fica percorrida, como depois de uma etapa feita. `STATE_AUTO` = regresso ao cálculo automático; a releitura devolve o estado efetivo da etapa, não o forçado. Definido numa chave que não designa nenhuma etapa, é ignorado
`is_text`	string	—	Altera a etiqueta da etapa, etiquetas de texto rico aceites
`is_description`	string	`""`	Segunda linha da etapa — «Facultativo», uma data, um montante. Etiquetas de texto rico aceites. Anunciada a um leitor de ecrã como a descrição da etapa, depois do seu nome. Uma cadeia vazia retira-a; uma barra compactada abandona-a para caber numa linha
`is_image`	string	`""`	Ícone apresentado no lugar do número da etapa (formas aceites)
`ib_enabled`	boolean	`true`	Etapa ativa; uma etapa desativada deixa de reagir ao clique
`ib_visible`	boolean	`true`	Oculta a etapa sem a retirar do modelo

Métodos #

Método	Função
`of_add_step (string as_key, string as_label)`	Acrescenta uma etapa no fim da sequência. Devolve `0` depois de aplicado, `-5` perante uma chave vazia, que contém `/` ou `	`, ou já presente na barra,` -2` se o componente não estiver criado
`of_add_step (string as_key, string as_label, string as_icon_file)`	O mesmo, com o ícone no lugar do número da etapa. Devolve `0` depois de aplicado, `-5` perante uma chave vazia, que contém `/` ou `	`, ou já presente na barra,` -2` se o componente não estiver criado
`of_add_step (string as_key, string as_label, string as_icon_file, string as_desc)`	O mesmo, com o ícone e a segunda linha. Devolve `0` depois de aplicado, `-5` perante uma chave vazia, que contém `/` ou `	`, ou já presente na barra,` -2` se o componente não estiver criado
`of_insert_step (string as_key, string as_label, integer ai_index)`	Insere uma etapa na posição indicada (contada a partir de 1; `0` ou menos = no início, para além do fim = no fim). Devolve `0` depois de aplicado, `-5` perante uma chave vazia, que contém `/` ou `	`, ou já presente na barra,` -2` se o componente não estiver criado
`of_insert_step (string as_key, string as_label, string as_icon_file, integer ai_index)`	O mesmo, com o ícone. Devolve `0` depois de aplicado, `-5` perante uma chave vazia, que contém `/` ou `	`, ou já presente na barra,` -2` se o componente não estiver criado
`of_insert_step (string as_key, string as_label, string as_icon_file, string as_desc, integer ai_index)`	O mesmo, com o ícone e a segunda linha. Devolve `0` depois de aplicado, `-5` perante uma chave vazia, que contém `/` ou `	`, ou já presente na barra,` -2` se o componente não estiver criado
`of_move_step (string as_key, integer ai_index)`	Desloca uma etapa existente; a etapa atual continua a sê-lo. Devolve `0` depois de aplicado, `-5` perante uma chave vazia ou que não designa nenhuma etapa, `-2` se o componente não estiver criado
`of_next ( )`	Passa à etapa seguinte, saltando as ocultas e as desativadas — aquelas em que `ii_current + 1` aterraria. Para na última alcançável. O modo de navegação não é consultado: limita o utilizador, não o seu código. Nenhuma pergunta é colocada, mas `ue_step_changed` é lançado. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_previous ( )`	Regressa à etapa anterior, as mesmas regras. A partir da posição «tudo terminado» regressa à última etapa. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_remove_step (string as_key)`	Retira uma etapa; as restantes conservam o seu estado. Retirar a etapa atual passa à seguinte alcançável (ou a «tudo concluído») e lança `ue_step_changed`. Devolve `0` depois de aplicado, `-5` perante uma chave vazia ou que não designa nenhuma etapa, `-2` se o componente não estiver criado
`of_clear_steps ( )`	Esvazia a sequência. A barra recomeça na sua primeira etapa: as etapas acrescentadas depois formam um novo percurso. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_step (string as_key)` → `n_pbt_stepbar_step`	Handle de uma etapa, para definir as suas propriedades
`of_reset ( )`	Esvazia as etapas e repõe todas as propriedades nos seus valores predefinidos. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_set_redraw (boolean)`	Agrupa uma sequência de alterações numa única representação. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exporta a representação como imagem. Devolve `0` depois de a imagem ser escrita, `-4` se a escrita falhar, `-2` se o componente não estiver criado

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 #

Evento	Acionado quando
`ue_step_clicked (integer ai_index, string as_key)`	O utilizador clicou num passo. A barra não se move: programe este evento, faça as suas verificações e depois defina `ii_current` se aceitar
`ue_step_changed (integer ai_from_index, string as_from_key, integer ai_index, string as_key)`	A barra deslocou-se: `ii_current` foi definido para outro passo, `of_next` / `of_previous` chamado, o passo atual retirado, ou um passo adicionado depois de «tudo concluído». Um clique nunca chega aqui
`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`)

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 serve para registar ou guardar o passo que se deixa; a regra «recuar sim, saltar à frente não» escreve-se com NAV_BACKWARD.

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. NAV_VISITED vai mais longe: qualquer etapa já alcançada continua clicável, mesmo à frente da atual — o utilizador que voltou para corrigir a etapa 2 regressa com um clique à etapa 4 que tinha alcançado, o que NAV_BACKWARD nunca permite. Uma nova lista de etapas esquece o que foi alcançado, e uma etapa inserida nunca foi alcançada.

Com o teclado #

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

Tecla	Efeito
Setas	Deslocam o foco de uma etapa para outra, em ciclo; as etapas ocultas, desativadas ou fora de alcance (ver `is_navigation_mode`) são saltadas
Home / End	Primeira / última etapa alcançável
Enter ou Espaço	Comunica um clique na etapa com o foco (`ue_step_clicked`) — a barra não se move por isso

As setas não selecionam, ao contrário dos separadores de um dockcontainer: movem o foco. Enter ou Espaço numa etapa comunica o clique (ue_step_clicked), como o rato; é a sua aplicação que desloca a barra. Percorrer uma barra de oito etapas com o teclado não deve enviar oito cliques.

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 #

// Os quatro passos do assistente, por ordem
uo_steps.of_add_step(/*key*/ "account",   /*label*/ "Conta")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "Perfil")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Pagamento")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "Confirmação")

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

Assinalar uma etapa em erro #

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

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

Etapa ignorada, etapa a rever, voltar para a frente #

// Os quatro passos da encomenda
uo_steps.of_add_step(/*key*/ "cart",    /*label*/ "Carrinho")
uo_steps.of_add_step(/*key*/ "coupon",    /*label*/ "Desconto")
uo_steps.of_add_step(/*key*/ "delivery", /*label*/ "Entrega")
uo_steps.of_add_step(/*key*/ "payment",  /*label*/ "Pagamento")

// O cliente nao tem codigo promocional : a etapa e ignorada, nem feita nem por fazer
uo_steps.of_step(/*key*/ "coupon").is_state = n_pbt_stepbar_step.STATE_SKIPPED

// Morada nao verificada : a etapa foi percorrida, mas deve ser revista
uo_steps.of_step(/*key*/ "delivery").is_state = n_pbt_stepbar_step.STATE_WARNING

// Qualquer etapa ja alcancada continua clicavel, mesmo a frente da atual
uo_steps.is_navigation_mode = u_pbt_stepbar.NAV_VISITED

// O assistente alcancou a etapa 4 e volta ao carrinho : as etapas 2 a 4 continuam a um clique
uo_steps.ii_current = 4
uo_steps.ii_current = 1

Sequência vertical #

// POSITION_START / POSITION_END : a sequencia desenha-se verticalmente, ideal a margem de um formulario
uo_steps.is_position = uo_steps.POSITION_START

// O TERCEIRO argumento e o icone : ocupa o lugar do numero da etapa
uo_steps.of_add_step(/*key*/ "account", /*label*/ "Conta", /*icon_file*/ "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_steps.of_add_step(/*key*/ "account",   /*label*/ "[b]Conta[/b][br][size=9](ligação)")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "[b]Perfil[/b][br][size=9](os seus dados)")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "[b]Pagamento[/b][br][size=9](cartão)")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "[accent][b]Concluído[/b][/accent]")

// O utilizador esta no passo 2 : o passo 1 aparece concluido
uo_steps.ii_current = 2

Navegação por clique #

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

Etapa condicional #

// Um cliente ja conhecido nao tem etapa "Perfil" a preencher
uo_steps.of_step(/*key*/ "profile").ib_visible = false

Boas práticas #

Dê a cada passo um identificador de negócio estável ("payment"): é 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.

Membros	Função	Detalhado em
`of_count` · `of_keys_at` · `of_has`	Percorrer o que o componente contém	3.2 Os items
`of_reset`	Repor o componente a zero	3.6 Repor um componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Atalhos de teclado do componente	3.5 Os atalhos de teclado
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se nasceu, se está pronto, o que falhou	3.7 Diagnóstico
`of_save_as_png` · `of_save_as_jpg`	Exportar a renderização como imagem	3.8 Exportar a representação como imagem
`of_set_redraw`	Agrupar as alterações num único repinte	3.10 Boas práticas
`of_preload_icons`	Ícones mostrados sem atraso	Apresentação instantânea: `of_icon`
`of_set_translation`	Traduzir uma legenda do componente	5.2 Adaptar uma etiqueta: `of_set_translation`
`of_focus_webview`	Dar o foco ao componente	6.4 Teclado e focus
`of_print` · `of_print_to_pdf`	Imprimir, ou escrever um PDF	6.9 Imprimir
`of_set_property` · `of_get_property` · `of_component_name`	Controlar uma propriedade pelo nome	3.1 O motor de propriedades

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.