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 #

Userobject	`u_pbt_stepbar`
Clase de items	`n_pbt_stepbar_step` (un paso)
Sirve para	Situar al usuario en un asistente, en un formulario de varias páginas, en un proceso de validación
Principio	Usted declara los pasos y luego desplaza `ii_current`: los estados se calculan solos

Inicio rápido #

// event open de la ventana
uo_steps.of_add_step(/*key*/ "account",  /*label*/ "Cuenta")
uo_steps.of_add_step(/*key*/ "profile",  /*label*/ "Perfil")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Pago")
uo_steps.of_add_step(/*key*/ "done",     /*label*/ "Confirmación")

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

// Boton Siguiente del asistente : el paso siguiente, saltando los ocultos y los desactivados
uo_steps.of_next()

// Boton Anterior
uo_steps.of_previous()

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:

Posición	Estado	Representación
Antes del paso actual	`done` — terminado	Pastilla marcada
El paso actual	`current` — en curso	Pastilla destacada
Después del paso actual	`todo` — próximo	Pastilla numerada, tono discreto

Otros tres estados nunca se obtienen automáticamente: usted los fuerza en un paso — error cuando ha fallado, warning cuando está superado pero queda algo por revisar, skipped cuando se ha omitido (véase más abajo).

Propiedades #

Propiedad	Tipo	Predeterminado	Función
`ii_current`	integer	`1`	Paso en curso, numerado a partir de 1 (número de pasos + 1 = todo terminado). Asignarlo lanza `ue_step_changed` cuando la barra se mueve. El paso en curso se sigue por su identidad: añadir, retirar o desplazar un paso anterior no cambia el paso en curso. Asignado antes de los pasos, el valor se conserva y se aplica en cuanto el paso existe. Un paso en curso oculto no deja ningún paso «en curso» en pantalla. «Todo terminado» queda anclado en el último paso de ese momento: un paso añadido después de él pasa a ser el paso en curso (y lanza `ue_step_changed`); uno insertado antes no cambia nada
`is_position`	string	`"top"`	Orientación: `top` / `bottom` (hilo horizontal) o `start` / `end` (hilo vertical) — constantes `POSITION_TOP`, `POSITION_BOTTOM`, `POSITION_START`, `POSITION_END`. `START`/`END` son lógicas y siguen el sentido de escritura
`is_navigation_mode`	string	`"free"`	Lo que un clic puede alcanzar: `NAV_FREE` (cualquier paso, el valor predeterminado), `NAV_BACKWARD` (solo los pasos ya recorridos — volver atrás, nunca saltar adelante), `NAV_VISITED` (todo paso ya alcanzado, salvo el actual — tras volver atrás, los pasos alcanzados más adelante siguen a un clic) o `NAV_NONE` (nada: un simple indicador de progreso, gobernado únicamente por su código). Lo que sigue siendo pulsable lanza `ue_step_clicked`; la barra, en cambio, nunca se mueve con un clic
`is_overflow_mode`	string	`"auto"`	Demasiados pasos para el ancho: `OVERFLOW_AUTO` compacta la barra por debajo de un mínimo legible por paso (cada paso se convierte en un punto, solo el actual conserva su etiqueta, y todos siguen siendo pulsables), `OVERFLOW_SCROLL` conserva las etiquetas y desplaza, manteniendo a la vista el paso actual, `OVERFLOW_SHRINK` las comprime hasta los puntos suspensivos. Un hilo vertical nunca compacta
`is_theme_style`	string	`""`	Estilo visual del componente (constantes `THEME_STYLE_*`); vacío = el de la aplicación, seguido en cada cambio
`is_theme_mode`	string	`""`	Variante clara u oscura (constantes `THEME_MODE_*`); vacío = la de la aplicación, seguida en cada cambio
`il_theme_accent`	long	`-1`	Color de acento de este componente (`-1` = acento de la aplicación, o el del tema)
`is_tooltip`	string	`""`	Tooltip simple mostrado al pasar el ratón por el componente
`is_super_tooltip_title`	string	`""`	Título del tooltip enriquecido (prevalece sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto del tooltip enriquecido (se acepta el marcado enriquecido)
`is_super_tooltip_image`	string	`""`	Imagen del tooltip enriquecido

Propiedades de un paso — `n_pbt_stepbar_step` #

Obtenidas mediante of_step(id):

Propiedad	Tipo	Predeterminado	Función
`is_state`	string	`STATE_TODO`	Fuerza el estado del paso: `STATE_TODO`, `STATE_CURRENT`, `STATE_DONE`, `STATE_ERROR`, `STATE_WARNING` (superado, pero con algo que revisar: marcador ámbar con un «!», etiqueta ámbar), `STATE_SKIPPED` (omitido, ni hecho ni por hacer: marcador hueco con anillo discontinuo y un «–», etiqueta en cursiva). Los lectores de pantalla los anuncian «con una advertencia» y «omitido»; tras uno u otro, la línea se dibuja recorrida, como tras un paso hecho. `STATE_AUTO` = vuelta al cálculo automático; la relectura devuelve el estado efectivo del paso, no el forzado. Asignado a una clave que no nombra ningún paso, se ignora
`is_text`	string	—	Cambia la etiqueta del paso, se acepta el texto enriquecido con etiquetas
`is_description`	string	`""`	Segunda línea del paso — «Opcional», una fecha, un importe. Marcado de texto enriquecido aceptado. Se anuncia a un lector de pantalla como la descripción del paso, tras su nombre. Una cadena vacía la retira; una barra compactada la abandona para caber en una línea
`is_image`	string	`""`	Icono mostrado en lugar del número del paso (formas aceptadas)
`ib_enabled`	boolean	`true`	Paso activo; un paso desactivado ya no reacciona al clic
`ib_visible`	boolean	`true`	Oculta el paso sin retirarlo del modelo

Métodos #

Método	Función
`of_add_step (string as_key, string as_label)`	Añade un paso al final del hilo. Devuelve `0` una vez aplicado, `-5` ante una clave vacía, que contiene `/` o `	`, o ya presente en la barra,` -2` si el componente no está creado
`of_add_step (string as_key, string as_label, string as_icon_file)`	Lo mismo, con el icono en lugar del número del paso. Devuelve `0` una vez aplicado, `-5` ante una clave vacía, que contiene `/` o `	`, o ya presente en la barra,` -2` si el componente no está creado
`of_add_step (string as_key, string as_label, string as_icon_file, string as_desc)`	Lo mismo, con el icono y la segunda línea. Devuelve `0` una vez aplicado, `-5` ante una clave vacía, que contiene `/` o `	`, o ya presente en la barra,` -2` si el componente no está creado
`of_insert_step (string as_key, string as_label, integer ai_index)`	Inserta un paso en la posición indicada (contada a partir de 1; `0` o menos = al principio, más allá del final = al final). Devuelve `0` una vez aplicado, `-5` ante una clave vacía, que contiene `/` o `	`, o ya presente en la barra,` -2` si el componente no está creado
`of_insert_step (string as_key, string as_label, string as_icon_file, integer ai_index)`	Lo mismo, con el icono. Devuelve `0` una vez aplicado, `-5` ante una clave vacía, que contiene `/` o `	`, o ya presente en la barra,` -2` si el componente no está creado
`of_insert_step (string as_key, string as_label, string as_icon_file, string as_desc, integer ai_index)`	Lo mismo, con el icono y la segunda línea. Devuelve `0` una vez aplicado, `-5` ante una clave vacía, que contiene `/` o `	`, o ya presente en la barra,` -2` si el componente no está creado
`of_move_step (string as_key, integer ai_index)`	Desplaza un paso existente; el paso en curso sigue siéndolo. Devuelve `0` una vez aplicado, `-5` ante una clave vacía o que no designa ningún paso, `-2` si el componente no está creado
`of_next ( )`	Pasa al paso siguiente, saltando los ocultos y los desactivados — aquellos en los que `ii_current + 1` aterrizaría. Se detiene en el último alcanzable. El modo de navegación no se consulta: limita al usuario, no a su código. No se plantea ninguna pregunta, pero se lanza `ue_step_changed`. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_previous ( )`	Vuelve al paso anterior, las mismas reglas. Desde la posición «todo terminado» regresa al último paso. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_remove_step (string as_key)`	Retira un paso; los demás conservan su estado. Retirar el paso en curso pasa al siguiente alcanzable (o a «todo terminado») y lanza `ue_step_changed`. Devuelve `0` una vez aplicado, `-5` ante una clave vacía o que no designa ningún paso, `-2` si el componente no está creado
`of_clear_steps ( )`	Vacía el hilo. La barra vuelve a empezar en su primer paso: los pasos añadidos después forman un nuevo recorrido. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_step (string as_key)` → `n_pbt_stepbar_step`	Handle de un paso, para establecer sus propiedades
`of_reset ( )`	Vacía los pasos y devuelve todas las propiedades a su valor predeterminado. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_set_redraw (boolean)`	Agrupa una ráfaga de modificaciones en una sola representación. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exporta la representación como imagen. Devuelve `0` una vez escrita la imagen, `-4` si la escritura falla, `-2` si el componente no está creado

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 #

Evento	Se activa cuando
`ue_step_clicked (integer ai_index, string as_key)`	El usuario ha hecho clic en un paso. La barra no se mueve: programe este evento, haga sus comprobaciones y luego asigne `ii_current` si lo acepta
`ue_step_changed (integer ai_from_index, string as_from_key, integer ai_index, string as_key)`	La barra se ha desplazado: se asignó `ii_current` a otro paso, se llamó a `of_next` / `of_previous`, se retiró el paso en curso, o se añadió un paso después de «todo terminado». Un clic nunca llega aquí
`ue_ready ( )`	El componente ha terminado de cargarse; todo lo enviado antes se ha reproducido
`ue_runtime_missing ( )`	El runtime WebView2 está ausente: el componente permanece vacío
`ue_bg_color (long al_color)`	El componente ha calculado el color de fondo de su tema; el userobject ya lo ha adoptado (`backcolor`)

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. Esa pareja sirve para registrar o guardar el paso que se abandona; la regla «volver atrás sí, saltar adelante no» se escribe con NAV_BACKWARD.

is_navigation_mode sigue siendo el filtro del clic: NAV_NONE ya no lanza nada, NAV_BACKWARD solo deja pulsar los pasos ya recorridos. NAV_VISITED va más lejos: todo paso ya alcanzado sigue siendo pulsable, incluso por delante del actual — el usuario que volvió a corregir el paso 2 regresa de un clic al paso 4 que había alcanzado, algo que NAV_BACKWARD nunca permite. Una nueva lista de pasos olvida lo alcanzado, y un paso insertado nunca ha sido alcanzado.

Con el teclado #

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

Tecla	Efecto
Flechas	Desplazan el foco de un paso a otro, en bucle; los pasos ocultos, desactivados o fuera de alcance (véase `is_navigation_mode`) se saltan
Inicio / Fin	Primer / último paso alcanzable
Intro o Espacio	Informa de un clic en el paso enfocado (`ue_step_clicked`) — la barra no se mueve por ello

Las flechas no seleccionan, a diferencia de las pestañas de un dockcontainer: mueven el foco. Intro o Espacio sobre un paso informa del clic (ue_step_clicked), como el ratón; es su aplicación la que desplaza la barra. Recorrer una barra de ocho pasos con el teclado no debe enviar ocho clics.

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 #

// Los cuatro pasos del asistente, en orden
uo_steps.of_add_step(/*key*/ "account",   /*label*/ "Cuenta")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "Perfil")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Pago")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "Confirmación")

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

Señalar un paso en error #

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

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

Paso omitido, paso por revisar, volver hacia delante #

// Los cuatro pasos del pedido
uo_steps.of_add_step(/*key*/ "cart",    /*label*/ "Carrito")
uo_steps.of_add_step(/*key*/ "coupon",    /*label*/ "Cupón")
uo_steps.of_add_step(/*key*/ "delivery", /*label*/ "Entrega")
uo_steps.of_add_step(/*key*/ "payment",  /*label*/ "Pago")

// El cliente no tiene codigo promocional : el paso se omite, ni hecho ni por hacer
uo_steps.of_step(/*key*/ "coupon").is_state = n_pbt_stepbar_step.STATE_SKIPPED

// Direccion no verificada : el paso esta superado, pero hay que revisarlo
uo_steps.of_step(/*key*/ "delivery").is_state = n_pbt_stepbar_step.STATE_WARNING

// Todo paso ya alcanzado sigue siendo pulsable, incluso por delante del actual
uo_steps.is_navigation_mode = u_pbt_stepbar.NAV_VISITED

// El asistente alcanzo el paso 4 y vuelve al carrito : los pasos 2 a 4 siguen a un clic
uo_steps.ii_current = 4
uo_steps.ii_current = 1

Hilo vertical #

// POSITION_START / POSITION_END : el hilo se dibuja verticalmente, ideal al margen de un formulario
uo_steps.is_position = uo_steps.POSITION_START

// El TERCER argumento es el icono : ocupa el lugar del numero del paso
uo_steps.of_add_step(/*key*/ "account", /*label*/ "Cuenta", /*icon_file*/ "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_steps.of_add_step(/*key*/ "account",   /*label*/ "[b]Cuenta[/b][br][size=9](conexión)")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "[b]Perfil[/b][br][size=9](sus datos)")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "[b]Pago[/b][br][size=9](tarjeta)")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "[accent][b]Terminado[/b][/accent]")

// El usuario esta en el paso 2 : el paso 1 aparece completado
uo_steps.ii_current = 2

Navegación con clic #

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

Paso condicional #

// Un cliente ya conocido no tiene un paso "Perfil" que rellenar
uo_steps.of_step(/*key*/ "profile").ib_visible = false

Buenas prácticas #

Dé a cada paso un identificador funcional estable ("payment"): 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.

Miembros	Función	Detallado en
`of_count` · `of_keys_at` · `of_has`	Recorrer lo que el componente contiene	3.2 Los items
`of_reset`	Poner el componente a cero	3.6 Poner un componente a cero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Atajos de teclado del componente	3.5 Los atajos de teclado
`of_is_created` · `of_is_ready` · `of_get_last_error`	Si ha nacido, si está listo, qué ha fallado	3.7 Diagnóstico
`of_save_as_png` · `of_save_as_jpg`	Exportar el render como imagen	3.8 Exportar la representación como imagen
`of_set_redraw`	Agrupar los cambios en un solo repintado	3.10 Buenas prácticas
`of_preload_icons`	Iconos mostrados sin retardo	Visualización instantánea: `of_icon`
`of_set_translation`	Traducir una etiqueta del componente	5.2 Adaptar una etiqueta: `of_set_translation`
`of_focus_webview`	Dar el foco al componente	6.4 Teclado y foco
`of_print` · `of_print_to_pdf`	Imprimir, o escribir un PDF	6.9 Imprimir
`of_set_property` · `of_get_property` · `of_component_name`	Controlar una propiedad por su nombre	3.1 El motor de propiedades

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.