stepbar — u_pbt_stepbar #

← Referencia de componentes · Índice de la guía

Hilo de pasos de un asistente: los pasos ya superados, el que está en curso y los que quedan por delante, en horizontal o en vertical.

▶ Verlo en vivo — Aplicación de demostración, mosaico Stepbar: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Inicio rápido #

// event open de la ventana
uo_etapes.of_add_step(/*key*/ "compte",  /*etiqueta*/ "Cuenta")
uo_etapes.of_add_step(/*key*/ "profil",  /*etiqueta*/ "Perfil")
uo_etapes.of_add_step(/*key*/ "paiement", /*etiqueta*/ "Pago")
uo_etapes.of_add_step(/*key*/ "fin",     /*etiqueta*/ "Confirmación")

// Paso en curso (1 = el primero)
uo_etapes.ii_current = 1

// Boton Siguiente del asistente
uo_etapes.ii_current = uo_etapes.ii_current + 1

El modelo: un paso, tres estados automáticos #

Un paso no tiene ningún estado que gestionar a mano. Se deduce de su posición respecto a ii_current:

Un cuarto estado, error, nunca se obtiene automáticamente: usted lo fuerza en un paso que ha fallado (véase más abajo).

Propiedades #

Propiedades de un paso — n_pbt_stepbar_step #

Obtenidas mediante of_step(id):

Métodos #

El tercer argumento es el icono, como en todo el resto de la biblioteca (of_add_item de la listbar, of_add_panel de la statusbar, of_add_tile de la tilesbox). La segunda línea va después.

Eventos #

La barra NO navega sola. Un clic informa (ue_step_clicked) y nada más: la barra se queda donde está. Es usted quien la desplaza, asignando ii_current o llamando a of_next / of_previous — y esos desplazamientos se anuncian con ue_step_changed.

Este reparto no es una restricción, es el sentido del componente: una barra de pasos refleja un recorrido que su aplicación gobierna. Alcanzar el paso 3 suele significar que un formulario era válido y que se guardó un registro; ningún clic puede decidirlo por usted.

ue_step_clicked lleva el paso apuntado, ue_step_changed lleva además el paso abandonado — tanto por identificador funcional como por rango. Es esa pareja la que permite escribir «volver atrás sí, saltar adelante no» en una línea.

is_navigation_mode sigue siendo el filtro del clic: NAV_NONE ya no lanza nada, NAV_BACKWARD solo deja pulsar los pasos ya recorridos.

Con el teclado #

La barra es una sola parada de tabulación: una vez alcanzada, se recorre íntegramente con el teclado.

Las flechas no seleccionan, a diferencia de las pestañas de un dockcontainer. Alcanzar un paso plantea una pregunta a su aplicación: recorrer una barra de ocho pasos enviaría ocho, y un rechazo a medio camino dejaría el foco y el paso actual desincronizados.

Cada paso es un verdadero botón: lleva su etiqueta y su estado en su nombre hablado («Cuenta - completado»), el paso actual está marcado con aria-current="step", y un paso desactivado es un botón desactivado — no solo un texto atenuado. La viñeta numerada no se lee en voz alta: un número de orden no enseña nada.

Ejemplos #

Avanzar en el asistente #

uo_etapes.of_add_step(/*key*/ "compte",   /*etiqueta*/ "Cuenta")
uo_etapes.of_add_step(/*key*/ "profil",   /*etiqueta*/ "Perfil")
uo_etapes.of_add_step(/*key*/ "paiement", /*etiqueta*/ "Pago")
uo_etapes.of_add_step(/*key*/ "fin",      /*etiqueta*/ "Confirmación")

// Los pasos 1 y 2 pasan automaticamente a "terminado" (marca)
uo_etapes.ii_current = 3

Señalar un paso en error #

// El estado de un paso se fuerza mediante su handle
uo_etapes.of_step(/*key*/ "profil").is_state = n_pbt_stepbar_step.STATE_ERROR

// Una vez corregido el problema, se devuelve el mando al calculo automatico
uo_etapes.of_step(/*key*/ "profil").is_state = n_pbt_stepbar_step.STATE_AUTO

Hilo vertical #

// left / right : el hilo se dibuja verticalmente, ideal al margen de un formulario
uo_etapes.is_position = uo_etapes.POSITION_START

// El TERCER argumento es el icono : ocupa el lugar del numero del paso
uo_etapes.of_add_step(/*key*/ "compte", /*etiqueta*/ "Cuenta", /*icono*/ "mono:img\packimages.dll:svg/samples/folder-open")

Etiquetas enriquecidas en dos líneas #

// La etiqueta de un paso acepta el texto enriquecido con etiquetas
uo_etapes.of_add_step("compte",   "[b]Cuenta[/b][br][size=9](conexión)")
uo_etapes.of_add_step("profil",   "[b]Perfil[/b][br][size=9](sus datos)")
uo_etapes.of_add_step("paiement", "[b]Pago[/b][br][size=9](tarjeta)")
uo_etapes.of_add_step("fin",      "[accent][b]Terminado[/b][/accent]")

uo_etapes.ii_current = 2

Navegación con clic #

// event ue_step_clicked de uo_etapes : (integer ai_index, string as_key)
// La barra NO se ha movido : aqui se decide.
if ai_index > uo_etapes.ii_current then
    MessageBox("Asistente", "Termine el paso actual antes de continuar.")
    return
end if
uo_etapes.ii_current = ai_index

Paso condicional #

// Un cliente ya conocido no tiene un paso "Perfil" que rellenar
uo_etapes.of_step("profil").ib_visible = false

Buenas prácticas #

• Dé a cada paso un identificador funcional estable ("paiement"): es el que recibe en ue_step_clicked y ue_step_changed, no un número que se mueve a la menor inserción.
• Deje que el componente calcule los estados; fuerce is_state únicamente para el error.
• El clic en un paso es una simple señal: le corresponde a usted autorizar (o no) el salto, en particular hacia un paso todavía no alcanzado.
• Enmarque la declaración de los pasos entre of_set_redraw(false) / of_set_redraw(true) cuando sean numerosos.
• Llame a of_reset() antes de reutilizar el mismo hilo para otro asistente.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía