breadcrumb — `u_pbt_breadcrumb` #

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

Ruta de navegación: el camino clicable que dice al usuario dónde está, y que lo devuelve con un clic a cualquier nivel superior.

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

En resumen #

Userobject	`u_pbt_breadcrumb`
Clase de elementos	`n_pbt_breadcrumb_item` (`of_item(dirección)`) · `n_pbt_breadcrumb_child` (`of_child(dirección)`)
Sirve para	Decir dónde se está en una jerarquía, y permitir salir de ella hacia arriba
Principio	Usted describe el camino; el plegado, el menú y la maquetación son nuestros

Inicio rápido #

// Cada vez que el usuario baja un nivel
uo_crumbs.of_add_item(/*keys*/ "home",                /*text*/ "H")
uo_crumbs.of_add_item(/*keys*/ "home/clients",        /*text*/ "C")
uo_crumbs.of_add_item(/*keys*/ "home/clients/dupont", /*text*/ "D")

// El ultimo anadido pasa a ser el lugar actual, y tambien es pulsable

Un segmento se nombra por su dirección: las claves desde la raíz, unidas por / — "home/clients/dupont". Una clave suelta ya no basta en cuanto se repite en dos niveles de la misma ruta: el componente prefiere entonces negarse a adivinar antes que llevarle a otro sitio.

Es exactamente lo que ue_item_clicked le devuelve, y exactamente lo que of_truncate, of_item o of_add_child vuelven a tomar: lo que recibe se reinyecta tal cual.

Un clic informa, no corta #

Hacer clic en un segmento no acorta la ruta. Subir significa salir de una pantalla, y salir de una pantalla suele significar guardar antes — algo que ningún clic puede decidir. El componente le dice qué se ha pulsado; quien corta es usted, con of_truncate, una vez pasadas sus comprobaciones.

Es el mismo reparto de papeles que en la stepbar, y por la misma razón. Un componente que se mueve solo obliga a la aplicación a deshacer un movimiento ya hecho, en vez de elegir simplemente si ocurre.

Dos segmentos no informan nunca de nada: uno deshabilitado, uno oculto. El último — donde se está — responde como los demás, hasta que ib_last_clickable diga que no.

// event ue_item_clicked : (string as_keys)
// Primero sus comprobaciones - salir de la pantalla lo decide usted, no un clic
if not of_can_leave() then return
uo_crumbs.of_truncate(/*keys*/ as_keys)
of_open_screen(as_keys)

Cuando el camino es demasiado largo #

Un camino es tan largo como los datos lo hagan, y el ancho es el que es. is_overflow_mode dice qué cede.

Constante	Qué ocurre
`OVERFLOW_COLLAPSE`	El centro se pliega en un `…` que abre lo que oculta — el valor predeterminado
`OVERFLOW_SCROLL`	Las etiquetas quedan enteras, la tira se desliza (también con la rueda del ratón)
`OVERFLOW_SHRINK`	Los segmentos del centro ceden terreno, hasta una letra y puntos suspensivos; el primero y el lugar actual ceden los últimos. Con sitio de sobra, no se corta nada

Ni el primer segmento ni el último se pliegan jamás. Perder la raíz es perder el ancla a la que todos vuelven; perder el final es perder el sitio en el que se está.

Un segmento plegado informa exactamente como los demás: elegirlo en el … lanza el mismo ue_item_clicked. Estar oculto por el ancho no cambia lo que un segmento significa.

ii_max_visible impone un techo firme, sea cual sea el sitio. Déjelo en 0 — el valor predeterminado — para que decida el ancho, que es lo que una ruta de navegación debería seguir normalmente.

El menú de hermanos #

of_add_child da a un segmento su propio desplegable: las otras ramas de ese nivel. Es lo que evita subir a la raíz para volver a bajar a la carpeta de al lado.

El chevron que sigue al segmento pasa entonces a ser el botón que las abre — es el mismo que el separador, como en el explorador de Windows: un solo chevron, un solo significado que aprender. Elegir una rama lanza ue_child_clicked, y también aquí la ruta no se mueve sola. Con el teclado, Flecha abajo en un segmento abre sus ramas, y en el … lo que oculta.

// Two branches under Clients : its chevron lists them
uo_crumbs.of_add_child(/*keys*/ "home/clients/durand", /*text*/ "D")
uo_crumbs.of_add_child(/*keys*/ "home/clients/martin", /*text*/ "M")

Las ramas bajo demanda #

Poner todas las ramas por adelantado no aguanta en un árbol profundo, ni en una base de datos. El explorador de Windows solo lee una carpeta cuando se abre su chevron; la ruta hace lo mismo: marque un segmento con ib_has_children, su chevron aparece de inmediato, y abrirlo lanza ue_children_needed. Usted pone las ramas en ese evento, y el menú se abre a su vuelta con lo que el segmento tenga en ese momento. Una carpeta grande no es un problema: añadir 30 000 ramas no relee nada, y en el menú abierto escribir las primeras letras («Win») salta a la primera rama que empieza así, como en el explorador.

// El segmento promete : el chevron aparece, nada se lee
uo_crumbs.of_item(/*keys*/ "home/clients").ib_has_children = true

// En ue_children_needed(as_keys) : leido ahora, luego se abre el menu
uo_crumbs.of_clear_children(/*keys*/ as_keys)
uo_crumbs.of_add_child(/*keys*/ as_keys + "/durand", /*text*/ "Durand SARL")

Escribir la ruta #

Con ib_editable, la parte vacía de la barra se comporta como la barra de direcciones del explorador de Windows: un clic (o F2, o of_edit) convierte la ruta en un campo de texto con la dirección mostrada — las claves unidas por /, lo que of_path devuelve. Intro lanza ue_path_entered con el texto tal como se escribió; Esc cancela. La ruta no se mueve sola, por la misma razón por la que un clic no la acorta: solo su aplicación sabe qué significan las palabras. ii_edit_skip deja los primeros segmentos fuera del campo — la raíz que nombra la máquina — y los vuelve a poner delante de lo escrito al informar.

Propiedades #

Propiedad	Tipo	Predeterminado	Función
`is_separator`	string	`chevron`	El signo entre segmentos (constantes `SEPARATOR_*`). Se da la vuelta solo en una lengua que se escribe de derecha a izquierda: elija un significado, no una dirección. Un separador que abre ramas conserva el signo elegido: son el paso del ratón y el puntero los que dicen que se abre
`is_overflow_mode`	string	`collapse`	Qué cede cuando el camino ya no cabe (constantes `OVERFLOW_*`). En `scroll`, la banda sigue el lugar actual
`ii_max_visible`	integer	`0`	Techo firme del número de segmentos mostrados, sin contar el `…`. `0` lo deja al ancho
`ib_last_clickable`	boolean	`true`	¿El último segmento — donde se está — responde al clic? Verdadero por omisión: una ruta sirve también para recargar lo que se mira, y lo que hace el clic es asunto de su aplicación. Póngalo a falso cuando su ruta solo navega
`ib_editable`	boolean	`false`	¿Se puede escribir la ruta? Verdadero: un clic en la parte vacía de la barra (o `F2`, o `of_edit`) convierte la ruta en un campo de texto con la dirección del lugar actual (lo que devuelve `of_path`); `Intro` lanza `ue_path_entered`, y también salir del campo después de modificarlo; `Esc` cancela. Un campo abandonado sin cambios no dice nada; un clic en otro control de la aplicación valida el texto, pasar a otra aplicación conserva lo escrito. La ruta nunca se mueve sola
`ib_allow_drop`	boolean	`false`	Opt-in: acepta archivos soltados desde el Explorador de Windows sobre un segmento. El segmento bajo el puntero se ilumina durante el arrastre, y `ue_drop_files` lo nombra con las rutas completas
`ii_edit_skip`	integer	`0`	Número de segmentos iniciales que quedan fuera del campo de texto — una raíz que nombra la máquina no se escribe. Se vuelven a poner delante de lo escrito al informar: la dirección sigue completa
`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

Métodos #

Método	Función
`of_add_item (string as_keys, string as_text)`	Añade un segmento al final: pasa a ser el lugar actual. `as_keys` es una clave simple o una dirección; una dirección solo se acepta si llega adonde dice — sus niveles por encima del último deben ser la dirección del último segmento. Devuelve `0` una vez aplicado, `-5` ante una clave vacía, una clave que contiene `	`o una dirección que acabaría en otro sitio,` -2` si el componente no está creado
`of_add_item (string as_keys, string as_text, string as_image)`	Lo mismo, con el icono mostrado antes de la etiqueta — tercer argumento, como en toda la biblioteca. Una etiqueta vacía da un segmento solo icono (la casa de la raíz). Devuelve `0` una vez aplicado, `-5` ante una clave vacía, una clave que contiene `	`o una dirección que acabaría en otro sitio,` -2` si el componente no está creado
`of_insert_item (string as_keys, string as_text, integer ai_index)`	Inserta en la posición elegida (primera posición = 1). Una sobrecarga toma también el icono. Una dirección solo se acepta si sus niveles por encima del último son la dirección del segmento al que sigue. Los segmentos siguientes bajan un nivel: sus direcciones cambian, sus handles se liberan, sus colores y tooltips los siguen. Devuelve `0` una vez aplicado, `-5` ante una clave vacía, una clave que contiene `	`o una dirección que acabaría en otro sitio,` -2` si el componente no está creado
`of_remove_item (string as_keys)`	Quita un segmento, por su dirección; los demás conservan su estado. Los que lo seguían suben un nivel: los handles del segmento quitado y de todo lo que lo seguía se liberan. Devuelve `0` una vez aplicado, `-5` si la dirección no designa ningún segmento (desconocida, o clave simple repetida), `-2` si el componente no está creado
`of_truncate (string as_keys)`	Elimina todo lo que sigue a ese segmento, que pasa a ser el lugar actual. Es el gesto para el que existe una ruta de navegación; una dirección desconocida o una clave simple repetida no cambia nada y devuelve `-5`. Los handles de los segmentos eliminados se liberan. Devuelve `0` una vez aplicado, `-5` si la dirección no designa ningún segmento, `-2` si el componente no está creado
`of_clear ( )`	Vacía la ruta; los handles entregados para sus segmentos y ramas se liberan. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_add_child (string as_keys, string as_text)`	Añade una rama hermana en la dirección dada: el segmento de arriba gana un chevron que las abre. Una sobrecarga toma también el icono. Devuelve `0` una vez aplicado, `-5` si el segmento de arriba no existe, si la clave de la rama ya está ocupada bajo él o contiene `	`,` -2` si el componente no está creado
`of_add_children (string as_keys, string as_child_keys[], string as_texts[])`	Añade todo un nivel de ramas hermanas bajo el segmento `as_keys`, en una sola llamada: cada texto de `as_texts` (y cada imagen, en la sobrecarga que toma también una lista de imágenes) va con la clave del mismo rango en `as_child_keys`; un texto ausente muestra la clave. Las mismas ramas que un bucle de `of_add_child`, sin un ida y vuelta por cada una: una carpeta de 30 000 subcarpetas abre su menú enseguida. Devuelve `0` una vez aplicado (una lista vacía no añade nada), `-5` si la dirección no designa ningún segmento, o si una clave está vacía, contiene `/` o `	`, ya está ocupada bajo el segmento o aparece dos veces en la lista — entonces no se añade nada,` -2` si el componente no está creado
`of_clear_children (string as_keys)`	Quita las ramas hermanas de un segmento, y sus handles; su separador vuelve a ser una simple marca. Devuelve `0` una vez aplicado, `-5` si la dirección no designa ningún segmento, `-2` si el componente no está creado
`of_remove_child (string as_keys)`	Quita una rama hermana, por su propia dirección, y su handle; quitada la última, el chevron vuelve a ser un simple separador. Devuelve `0` una vez aplicado, `-5` si el segmento o la rama no existe, `-2` si el componente no está creado
`of_child (string as_keys)`	El handle de una rama hermana — la dirección que tomó `of_add_child` — para renombrarla, atenuarla u ocultarla. El menú es un popup nativo: dibuja texto, imagen, atenuado y oculto, nada más — el tooltip y los colores que hereda un handle se ignoran allí. Una dirección de un solo nivel no tiene segmento encima: su handle es inerte
`of_path ( )`	Dónde se está, en forma de dirección: las claves de todos los segmentos hasta el último visible, separadas por `/`. Un segmento oculto sigue en ella — forma parte de la dirección — y el límite de la versión de demostración nunca la corta: `of_truncate(of_path())` siempre acierta. Leído en directo: una aplicación que reconstruyera esta cadena a mano acabaría por no decir lo mismo que la ruta
`of_edit ( )`	Abre el campo de texto de la ruta — el mismo que un clic en la parte vacía de la barra — desde una entrada de menú o un botón suyo. Requiere `ib_editable`. Devuelve `0` una vez aplicado, `-4` si `ib_editable` es falso (no se abre nada), `-2` si el componente no está creado
`of_item (string as_keys)`	El handle de un segmento, para renombrarlo, atenuarlo u ocultarlo más tarde. Vive lo mismo que su segmento: `of_clear`, `of_remove_item` y `of_truncate` liberan los handles de los segmentos que quitan
`of_set_redraw (boolean)`	Agrupa una ráfaga de cambios en un solo renderizado. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exporta el renderizado como imagen. Devuelve `0` una vez escrita la imagen, `-4` si la escritura falla, `-2` si el componente no está creado

Eventos #

Evento	Se dispara cuando
`ue_item_clicked (string as_keys)`	Se ha pulsado un segmento — en la ruta, o en el `…` que lo oculta. La ruta no se acorta sola: llame a `of_truncate` cuando sus comprobaciones hayan pasado
`ue_item_rclicked (string as_keys)`	Clic derecho en un segmento — normalmente un menú contextual propio. `as_keys` es su dirección completa, como en `ue_item_clicked`
`ue_child_clicked (string as_keys)`	Se ha elegido una rama hermana en el menú de un segmento; `as_keys` es la dirección de la rama, lista para volver a `of_add_item`
`ue_children_needed (string as_keys)`	Se abre el chevron de un segmento marcado con `ib_has_children`: ponga sus ramas ahora (`of_add_child`), el menú se abre al volver del evento, con lo que el segmento tenga en ese momento. Se pregunta en cada apertura: vacíe y vuelva a poner cuando las ramas hayan podido cambiar, no haga nada cuando lo que hay sigue valiendo
`ue_path_entered (string as_path)`	El usuario escribió una ruta en la barra (`ib_editable`) y pulsó Intro — o salió del campo después de modificarlo; `as_path` es el texto tal como se escribió, con los primeros `ii_edit_skip` segmentos vueltos a poner delante. Un clic en otro control de la aplicación cuenta como salir del campo. `Esc`, un campo sin cambios u otra aplicación llevada al frente no informan de nada. La ruta no se mueve sola: compruebe las palabras y reconstrúyala con `of_clear` y `of_add_item` si está de acuerdo
`ue_drop_files (string as_keys, string as_files[])`	Se han soltado archivos desde el Explorador sobre un segmento (`ib_allow_drop`): `as_keys` es la dirección del segmento bajo el puntero, vacía si el soltado cayó junto a la ruta; `as_files` las rutas completas
`ue_drag_enter ( )` · `ue_drag_leave ( )`	Un arrastre de archivos desde el Explorador entró en el componente, o salió de él sin soltar — soltar lanza solo `ue_drop_files`
`ue_auto_height (long al_height)`	La barra anuncia la altura que necesita — una fila, decidida por la fuente y el tema; el userobject ya está redimensionado, recoloque lo que haya debajo
`ue_ready ( )`	El componente ha terminado de cargar; todo lo enviado antes se ha vuelto a reproducir
`ue_runtime_missing ( )`	El runtime WebView2 no está: el componente queda vacío
`ue_bg_color (long al_color)`	El componente ha calculado su color de fondo del tema; el userobject ya lo ha adoptado (`backcolor`)

La ruta no navega. Dice dónde se está e informa de lo que se le pide; es su aplicación la que abre la pantalla — la misma acción, lanzada desde un menú o desde la ruta, pasa por el mismo código.

Propiedades de elemento #

Propiedad	Tipo	Predeterminado	Función
`is_text`	string	`""`	La etiqueta del segmento, modificable sin reconstruir la ruta (se acepta marcado enriquecido: una etiqueta que viene de los DATOS — un nombre de carpeta — pasa antes por `of_escape_markup` de `n_pbt_utils`, si no `[b]Borradores` saldría en negrita y sin corchetes)
`is_image`	string	`""`	El icono mostrado antes de la etiqueta (se aceptan los prefijos `mono:` y `tint:`)
`ib_enabled`	boolean	`true`	Un segmento desactivado aparece atenuado y no informa de nada: el nivel existe en la ruta, pero no se puede volver a él (permisos, una ficha en edición). Su chevron tampoco abre nada, y un arrastre de archivos no lo resalta
`ib_visible`	boolean	`true`	Un segmento oculto sale de la ruta, separador incluido — útil para un nivel técnico que no le incumbe al usuario. Se conserva: volver a mostrarlo no exige reconstrucción
`ib_has_children`	boolean	`false`	Marcado: hay algo bajo este segmento. Su chevron aparece sin nada detrás todavía, y abrirlo lanza `ue_children_needed`, donde las ramas se leen en ese momento. Un segmento cuyas ramas se pusieron con `of_add_child` no necesita la marca

Propiedades de un hijo #

Obtenida con of_child(dirección). El menú es un popup nativo: una propiedad cambiada mientras está abierto se ve en la siguiente apertura.

Propiedad	Tipo	Predeterminado	Función
`is_text`	string	`""`	La etiqueta de la rama en el menú
`is_image`	string	`""`	El icono mostrado antes de la etiqueta
`ib_enabled`	boolean	`true`	Una rama atenuada se queda en el menú y no se puede elegir — sin derechos sobre esa rama
`ib_visible`	boolean	`true`	Una rama oculta sale del menú sin ser eliminada; la última oculta cierra el chevron

Ejemplos #

Seguirlo al navegar #

// Rebuild the trail in a single redraw : freeze, clear, add, insert, redraw
uo_crumbs.of_set_redraw(/*on*/ false)
uo_crumbs.of_clear()
uo_crumbs.of_add_item(/*keys*/ "home", /*text*/ "H", /*image*/ "mono:img\packimages.dll:svg/samples/folder-open")
uo_crumbs.of_insert_item(/*keys*/ "home/region", /*text*/ "R", /*index*/ 2)
uo_crumbs.of_set_redraw(/*on*/ true)

Subir con un clic #

// Cut the trail after Clients, then read the path that remains
uo_crumbs.of_truncate(/*keys*/ "home/clients")
ls_path = uo_crumbs.of_path()

Un nivel prohibido, uno oculto #

// El nivel existe, pero no se puede volver a el
uo_crumbs.of_item(/*keys*/ "home/clients/orders").ib_enabled = false

// Y este no le incumbe al usuario : fuera de la ruta, separador incluido
uo_crumbs.of_item(/*keys*/ "home").ib_visible = false

// Slash separator, scrolling on overflow, at most 4 segments shown, last one not clickable
uo_crumbs.is_separator = uo_crumbs.SEPARATOR_SLASH
uo_crumbs.is_overflow_mode = uo_crumbs.OVERFLOW_SCROLL
uo_crumbs.ii_max_visible = 4
uo_crumbs.ib_last_clickable = false

// Remove one segment, then the branches offered under another
uo_crumbs.of_remove_item(/*keys*/ "home/region")
uo_crumbs.of_clear_children(/*keys*/ "home/clients")

Buenas prácticas #

Dé a cada segmento la clave de la pantalla que abre: su ue_item_clicked se convierte en un choose case que se lee, y el mismo código sirve al menú.
Llame a of_truncate dentro de su manejador de clic, no antes: es lo que garantiza que nunca se sale de una pantalla sin sus comprobaciones.
Deje ii_max_visible en 0 salvo que un diseño lo imponga. Una ruta que sigue el ancho muestra siempre todo lo que cabe.
Nombre los segmentos con palabras que el usuario reconozca — el nombre del cliente, no su identificador. Una ruta se lee, no se descifra.
Ponga en ella solo niveles a los que se pueda volver de verdad. Un segmento que falla una vez de cada dos hace perder la confianza en toda la ruta; si un nivel está prohibido temporalmente, ib_enabled lo dice sin mentir.
Una ruta de navegación dice un lugar, no una progresión: para « paso 2 de 5 » lo que hace falta es la stepbar.

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.