breadcrumb — `u_pbt_breadcrumb` #

← Riferimento dei componenti · Sommario della guida

Filo di Arianna: il percorso cliccabile che dice all'utente dove si trova, e che lo riporta con un clic a qualsiasi livello superiore.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Breadcrumb: l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Userobject	`u_pbt_breadcrumb`
Classe degli item	`n_pbt_breadcrumb_item` (`of_item(indirizzo)`) · `n_pbt_breadcrumb_child` (`of_child(indirizzo)`)
Serve a	Dire dove ci si trova in una gerarchia, e permettere di risalirne
Principio	Lei descrive il percorso; il ripiegamento, il menu e l'impaginazione sono nostri

Avvio rapido #

// Ogni volta che l'utente scende di un livello
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")

// L'ultimo aggiunto diventa il luogo corrente, ed e cliccabile

Un segmento si nomina con il suo indirizzo: le chiavi dalla radice, unite da / — "home/clients/dupont". Una chiave nuda non basta più appena si ripete su due livelli dello stesso filo: il componente rifiuta allora di indovinare, invece di portarla altrove.

È esattamente ciò che ue_item_clicked le restituisce, ed esattamente ciò che of_truncate, of_item o of_add_child riprendono: ciò che riceve si reinserisce tale e quale.

Un clic riferisce, non taglia #

Cliccare un segmento non accorcia il filo. Risalire significa lasciare una schermata, e lasciare una schermata spesso significa salvare prima — cosa che nessun clic può decidere. Il componente le dice cosa è stato cliccato; a tagliare è lei, con of_truncate, una volta superati i suoi controlli.

È la stessa divisione dei ruoli della stepbar, e per la stessa ragione. Un componente che si sposta da sé obbliga l'applicazione a disfare un movimento già avvenuto, invece di scegliere semplicemente se avvenga.

Due segmenti non riferiscono mai nulla: un segmento disattivato, uno nascosto. L'ultimo — dove ci si trova — risponde come gli altri, finché ib_last_clickable non dice di no.

// event ue_item_clicked : (string as_keys)
// Prima i suoi controlli - lasciare la schermata lo decide lei, non un clic
if not of_can_leave() then return
uo_crumbs.of_truncate(/*keys*/ as_keys)
of_open_screen(as_keys)

Quando il percorso è troppo lungo #

Un percorso è lungo quanto i dati lo fanno, e la larghezza è quella che è. is_overflow_mode dice cosa cede.

Costante	Cosa succede
`OVERFLOW_COLLAPSE`	Il centro si ripiega in un `…` che apre ciò che nasconde — il valore predefinito
`OVERFLOW_SCROLL`	Le etichette restano intere, la striscia scorre (anche con la rotellina del mouse)
`OVERFLOW_SHRINK`	I segmenti centrali cedono terreno, fino a una lettera e ai puntini di sospensione; il primo e il luogo corrente cedono per ultimi. Con spazio sufficiente, nulla viene tagliato

Né il primo segmento né l'ultimo si ripiegano mai. Perdere la radice significa perdere l'ancora a cui tutti tornano; perdere la fine significa perdere il punto in cui ci si trova.

Un segmento ripiegato riferisce esattamente come gli altri: sceglierlo nel … solleva lo stesso ue_item_clicked. Essere nascosto dalla larghezza non cambia ciò che un segmento significa.

ii_max_visible impone un tetto rigido, qualunque sia lo spazio. Lo lasci a 0 — il valore predefinito — perché decida la larghezza, che è ciò che un filo di Arianna dovrebbe normalmente seguire.

of_add_child dà a un segmento il proprio menu a discesa: gli altri rami di quel livello. È ciò che evita di risalire alla radice per ridiscendere nella cartella accanto.

Il chevron che segue il segmento diventa allora il pulsante che li apre — è lo stesso del separatore, come nell'esplora risorse di Windows: un solo chevron, un solo significato da imparare. Scegliere un ramo solleva ue_child_clicked, e anche qui il filo non si muove da sé. Da tastiera, Freccia giù su un segmento apre i suoi rami, e sul … ciò che nasconde.

// 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")

I rami su richiesta #

Porre tutti i rami in anticipo non regge su un albero profondo, né su una base di dati. L'esplora risorse di Windows legge una cartella solo quando se ne apre il chevron; il filo fa lo stesso: contrassegni un segmento con ib_has_children, il suo chevron appare subito, e aprirlo solleva ue_children_needed. Lei pone i rami in quell'evento, e il menu si apre al suo ritorno con ciò che il segmento porta in quel momento. Una cartella grande non è un problema: aggiungere 30 000 rami non rilegge nulla, e nel menu aperto digitare le prime lettere («Win») salta al primo ramo che comincia così, come nell'esplora risorse.

// Il segmento promette : il chevron appare, nulla viene letto
uo_crumbs.of_item(/*keys*/ "home/clients").ib_has_children = true

// In ue_children_needed(as_keys) : letto adesso, poi il menu si apre
uo_crumbs.of_clear_children(/*keys*/ as_keys)
uo_crumbs.of_add_child(/*keys*/ as_keys + "/durand", /*text*/ "Durand SARL")

Digitare il percorso #

Con ib_editable, la parte vuota della barra si comporta come la barra degli indirizzi dell'esplora risorse di Windows: un clic (o F2, o of_edit) trasforma il filo in un campo di testo con l'indirizzo mostrato — le chiavi unite da /, ciò che of_path restituisce. Invio solleva ue_path_entered con il testo come digitato; Esc annulla. Il filo non si muove da sé, per la stessa ragione per cui un clic non lo accorcia: solo la sua applicazione sa cosa significano le parole. ii_edit_skip lascia i primi segmenti fuori dal campo — la radice che nomina la macchina — e li rimette davanti a ciò che è stato digitato al momento del rapporto.

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`is_separator`	string	`chevron`	Il segno fra i segmenti (costanti `SEPARATOR_*`). Si gira da solo in una lingua che si scrive da destra a sinistra: scelga un significato, non una direzione. Un separatore che apre dei rami mantiene il segno scelto: sono il passaggio del mouse e il puntatore a dire che si apre
`is_overflow_mode`	string	`collapse`	Cosa cede quando il percorso non ci sta più (costanti `OVERFLOW_*`). In `scroll`, la striscia segue il luogo corrente
`ii_max_visible`	integer	`0`	Tetto rigido al numero di segmenti mostrati, il `…` non contato. `0` lascia decidere la larghezza
`ib_last_clickable`	boolean	`true`	L'ultimo segmento — dove ci si trova — risponde al clic? Vero per impostazione predefinita: un percorso serve anche a ricaricare ciò che si guarda, e ciò che il clic fa è affare della sua applicazione. Lo metta a falso quando il suo percorso si limita a navigare
`ib_editable`	boolean	`false`	Il percorso può essere digitato? Vero: un clic sulla parte vuota della barra (o `F2`, o `of_edit`) trasforma il filo in un campo di testo con l'indirizzo del luogo corrente (ciò che restituisce `of_path`); `Invio` solleva `ue_path_entered`, e così lasciare il campo dopo averlo modificato; `Esc` annulla. Un campo lasciato invariato non dice nulla; un clic su un altro controllo dell'applicazione convalida il testo, passare a un'altra applicazione conserva la digitazione. Il filo non si muove mai da solo
`ib_allow_drop`	boolean	`false`	Opt-in: accetta i file trascinati da Esplora risorse su un segmento. Il segmento sotto il puntatore si illumina durante il trascinamento, e `ue_drop_files` lo nomina con i percorsi completi
`ii_edit_skip`	integer	`0`	Numero di segmenti iniziali lasciati fuori dal campo di testo — una radice che nomina la macchina non si digita. Vengono rimessi davanti a ciò che è stato digitato al momento del rapporto: l'indirizzo resta completo
`is_theme_style`	string	`""`	Stile visivo del componente (costanti `THEME_STYLE_*`); vuoto = quello dell'applicazione, seguito a ogni cambio
`is_theme_mode`	string	`""`	Variante chiara o scura (costanti `THEME_MODE_*`); vuoto = quella dell'applicazione, seguita a ogni cambio
`il_theme_accent`	long	`-1`	Colore d'accento di questo componente (`-1` = accento dell'applicazione, o quello del tema)
`is_tooltip`	string	`""`	Tooltip semplice mostrato al passaggio del mouse sul componente
`is_super_tooltip_title`	string	`""`	Titolo del tooltip avanzato (prevale su `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Testo del tooltip avanzato (markup avanzato accettato)
`is_super_tooltip_image`	string	`""`	Immagine del tooltip avanzato

Metodi #

Metodo	Ruolo
`of_add_item (string as_keys, string as_text)`	Aggiunge un segmento in fondo: diventa il luogo corrente. `as_keys` è una chiave semplice o un indirizzo; un indirizzo è accettato solo se arriva dove dice — i suoi livelli sopra l'ultimo devono essere l'indirizzo dell'ultimo segmento. Restituisce `0` una volta applicato, `-5` per una chiave vuota, una chiave che contiene `	`o un indirizzo che finirebbe altrove,` -2` se il componente non è creato
`of_add_item (string as_keys, string as_text, string as_image)`	Lo stesso, con l'icona mostrata prima dell'etichetta — terzo argomento, come ovunque nella libreria. Un'etichetta vuota dà un segmento solo icona (la casa della radice). Restituisce `0` una volta applicato, `-5` per una chiave vuota, una chiave che contiene `	`o un indirizzo che finirebbe altrove,` -2` se il componente non è creato
`of_insert_item (string as_keys, string as_text, integer ai_index)`	Inserisce nella posizione scelta (prima posizione = 1). Un overload prende anche l'icona. Un indirizzo è accettato solo se i suoi livelli sopra l'ultimo sono l'indirizzo del segmento che segue. I segmenti successivi scendono di un livello: i loro indirizzi cambiano, i loro handle vengono rilasciati, i loro colori e tooltip li seguono. Restituisce `0` una volta applicato, `-5` per una chiave vuota, una chiave che contiene `	`o un indirizzo che finirebbe altrove,` -2` se il componente non è creato
`of_remove_item (string as_keys)`	Toglie un segmento, tramite il suo indirizzo; gli altri conservano il loro stato. I segmenti che lo seguivano risalgono di un livello: gli handle del segmento tolto e di tutto ciò che lo seguiva sono rilasciati. Restituisce `0` una volta applicato, `-5` se l'indirizzo non designa alcun segmento (sconosciuto, o chiave semplice ripetuta), `-2` se il componente non è creato
`of_truncate (string as_keys)`	Elimina tutto ciò che segue quel segmento, che diventa il luogo corrente. È il gesto per cui un filo di Arianna esiste; un indirizzo sconosciuto o una chiave semplice ripetuta non cambia nulla e restituisce `-5`. Gli handle dei segmenti eliminati sono rilasciati. Restituisce `0` una volta applicato, `-5` se l'indirizzo non designa alcun segmento, `-2` se il componente non è creato
`of_clear ( )`	Svuota il filo; gli handle dati per i suoi segmenti e rami sono rilasciati. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_add_child (string as_keys, string as_text)`	Aggiunge un ramo fratello all'indirizzo indicato: il segmento sopra guadagna un chevron che li apre. Un overload prende anche l'icona. Restituisce `0` una volta applicato, `-5` se il segmento sopra non esiste, se la chiave del ramo è già presa sotto di esso o contiene `	`,` -2` se il componente non è creato
`of_add_children (string as_keys, string as_child_keys[], string as_texts[])`	Aggiunge un intero livello di rami fratelli sotto il segmento `as_keys`, in una sola chiamata: ogni testo di `as_texts` (e ogni immagine, nell'overload che prende anche un elenco di immagini) va con la chiave dello stesso rango in `as_child_keys`; un testo mancante mostra la chiave. Gli stessi rami di un ciclo di `of_add_child`, senza un andata e ritorno per ciascuno: una cartella di 30 000 sottocartelle apre subito il suo menu. Restituisce `0` una volta applicato (una lista vuota non aggiunge nulla), `-5` se l'indirizzo non designa alcun segmento, o se una chiave è vuota, contiene `/` o `	`, è già presa sotto il segmento o compare due volte nella lista — allora non viene aggiunto nulla,` -2` se il componente non è creato
`of_clear_children (string as_keys)`	Toglie i rami fratelli di un segmento, e i loro handle; il suo separatore torna un semplice segno. Restituisce `0` una volta applicato, `-5` se l'indirizzo non designa alcun segmento, `-2` se il componente non è creato
`of_remove_child (string as_keys)`	Toglie un ramo fratello, tramite il suo indirizzo, e il suo handle; tolto l'ultimo, il chevron torna un semplice separatore. Restituisce `0` una volta applicato, `-5` se il segmento o il ramo non esiste, `-2` se il componente non è creato
`of_child (string as_keys)`	L'handle di un ramo fratello — l'indirizzo che `of_add_child` ha preso — per rinominarlo, disattivarlo o nasconderlo. Il menu è un popup nativo: disegna testo, immagine, disattivato e nascosto, nient'altro — il tooltip e i colori ereditati da un handle vi sono ignorati. Un indirizzo con un solo livello non ha segmento sopra: il suo handle è inerte
`of_path ( )`	Dove si è, sotto forma di indirizzo: le chiavi di tutti i segmenti fino all'ultimo visibile, separate da `/`. Un segmento nascosto vi resta — fa parte dell'indirizzo — e il limite della versione dimostrativa non lo taglia mai: `of_truncate(of_path())` va sempre a segno. Letto dal vivo: un'applicazione che ricostruisse questa stringa a mano finirebbe per non dire più la stessa cosa del filo
`of_edit ( )`	Apre il campo di testo del percorso — lo stesso di un clic sulla parte vuota della barra — da una voce di menu o da un pulsante suo. Richiede `ib_editable`. Restituisce `0` una volta applicato, `-4` se `ib_editable` è falso (non si apre nulla), `-2` se il componente non è creato
`of_item (string as_keys)`	L'handle di un segmento, per rinominarlo, disattivarlo o nasconderlo più tardi. Vive quanto il suo segmento: `of_clear`, `of_remove_item` e `of_truncate` rilasciano gli handle dei segmenti che tolgono
`of_set_redraw (boolean)`	Raggruppa una raffica di modifiche in un solo rendering. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Esporta il rendering come immagine. Restituisce `0` una volta scritta l'immagine, `-4` se la scrittura fallisce, `-2` se il componente non è creato

Eventi #

Evento	Scatta quando
`ue_item_clicked (string as_keys)`	Un segmento è stato cliccato — nel filo, o nel `…` che lo nasconde. Il filo non si accorcia da sé: chiami `of_truncate` una volta superati i suoi controlli
`ue_item_rclicked (string as_keys)`	Clic destro su un segmento — di solito un suo menu contestuale. `as_keys` è il suo indirizzo completo, come in `ue_item_clicked`
`ue_child_clicked (string as_keys)`	Un ramo fratello è stato scelto nel menu di un segmento; `as_keys` è l'indirizzo del ramo, pronto a rientrare in `of_add_item`
`ue_children_needed (string as_keys)`	Il chevron di un segmento contrassegnato `ib_has_children` si apre: ponga i suoi rami adesso (`of_add_child`), il menu si apre al ritorno dell'evento, con ciò che il segmento porta in quel momento. Chiesto a ogni apertura: svuoti e riponga quando i rami possono essere cambiati, non faccia nulla quando ciò che c'è vale ancora
`ue_path_entered (string as_path)`	L'utente ha digitato un percorso nella barra (`ib_editable`) e premuto Invio — o lasciato il campo dopo averlo modificato; `as_path` è il testo così come digitato, con i primi `ii_edit_skip` segmenti rimessi davanti. Un clic su un altro controllo dell'applicazione vale come lasciare il campo. `Esc`, un campo invariato o un'altra applicazione portata in primo piano non riportano nulla. Il filo non si muove da solo: verifichi le parole, poi lo ricostruisca con `of_clear` e `of_add_item` se è d'accordo
`ue_drop_files (string as_keys, string as_files[])`	Dei file sono stati trascinati da Esplora risorse su un segmento (`ib_allow_drop`): `as_keys` è l'indirizzo del segmento sotto il puntatore, vuoto se il rilascio è caduto accanto al filo; `as_files` i percorsi completi
`ue_drag_enter ( )` · `ue_drag_leave ( )`	Un trascinamento di file dall'Esplora risorse è entrato nel componente, o ne è uscito senza rilasciare — un rilascio solleva solo `ue_drop_files`
`ue_auto_height (long al_height)`	La barra annuncia l'altezza che le serve — una riga, decisa dal carattere e dal tema; lo userobject è già ridimensionato, riposizioni ciò che sta sotto
`ue_ready ( )`	Il componente ha finito di caricare; tutto ciò che era stato inviato prima è stato rigiocato
`ue_runtime_missing ( )`	Il runtime WebView2 è assente: il componente resta vuoto
`ue_bg_color (long al_color)`	Il componente ha calcolato il colore di sfondo del tema; l'userobject l'ha già adottato (`backcolor`)

Il filo non naviga. Dice dove ci si trova e riferisce ciò che gli si chiede; è la sua applicazione ad aprire la schermata — la stessa azione, avviata da un menu o dal filo, passa quindi per lo stesso codice.

Proprietà degli item #

Proprietà	Tipo	Predefinito	Ruolo
`is_text`	string	`""`	L'etichetta del segmento, modificabile senza ricostruire il filo (markup ricco accettato: un'etichetta che viene dai DATI — un nome di cartella — passa prima per `of_escape_markup` di `n_pbt_utils`, altrimenti `[b]Bozze` apparirebbe in grassetto senza parentesi)
`is_image`	string	`""`	L'icona mostrata prima dell'etichetta (prefissi `mono:` e `tint:` accettati)
`ib_enabled`	boolean	`true`	Un segmento disattivato è grigio e non riporta nulla: il livello esiste nel percorso, ma non ci si può risalire (diritti, una scheda in corso di modifica). Anche il suo chevron non apre nulla, e un trascinamento di file non lo evidenzia
`ib_visible`	boolean	`true`	Un segmento nascosto lascia il filo, separatore compreso — utile per un livello tecnico che non riguarda l'utente. È conservato: rimostrarlo non richiede alcuna ricostruzione
`ib_has_children`	boolean	`false`	Contrassegnato: c'è qualcosa sotto questo segmento. Il suo chevron appare senza ancora nulla dietro, e aprirlo solleva `ue_children_needed`, dove i rami vengono letti in quel momento. Un segmento i cui rami sono stati posti con `of_add_child` non ha bisogno del contrassegno

Proprietà di un figlio #

Ottenuta con of_child(indirizzo). Il menu è un popup nativo: una proprietà cambiata mentre è aperto si vede all'apertura successiva.

Proprietà	Tipo	Predefinito	Ruolo
`is_text`	string	`""`	L'etichetta del ramo nel menu
`is_image`	string	`""`	L'icona mostrata prima dell'etichetta
`ib_enabled`	boolean	`true`	Un ramo disattivato resta nel menu e non può essere scelto — nessun diritto su quel ramo
`ib_visible`	boolean	`true`	Un ramo nascosto esce dal menu senza essere rimosso; l'ultimo nascosto chiude il chevron

Esempi #

Seguirlo mentre si naviga #

// 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)

Risalire a 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 livello vietato, uno nascosto #

// Il livello esiste, ma non ci si puo risalire
uo_crumbs.of_item(/*keys*/ "home/clients/orders").ib_enabled = false

// E questo non riguarda l'utente : fuori dal filo, separatore compreso
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")

Buone pratiche #

Dia a ogni segmento la chiave della schermata che apre: il suo ue_item_clicked diventa un choose case che si legge, e lo stesso codice serve al menu.
Chiami of_truncate dentro il suo gestore del clic, non prima: è ciò che garantisce che una schermata non venga mai lasciata senza i suoi controlli.
Lasci ii_max_visible a 0 salvo che un progetto grafico lo imponga. Un filo che segue la larghezza mostra sempre il massimo di ciò che ci sta.
Chiami i segmenti con parole che l'utente riconosce — il nome del cliente, non il suo identificativo. Un filo si legge, non si decifra.
Ci metta solo livelli a cui si possa davvero tornare. Un segmento che fallisce una volta su due fa perdere fiducia in tutto il filo; se un livello è temporaneamente vietato, ib_enabled lo dice senza mentire.
Un filo di Arianna dice un luogo, non una progressione: per « passo 2 di 5 » ci vuole la stepbar.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Membri	Ruolo	Descritto in
`of_count` · `of_keys_at` · `of_has`	Percorrere ciò che il componente contiene	3.2 Gli item
`of_reset`	Riportare il componente a zero	3.6 Riportare un componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Scorciatoie da tastiera del componente	3.5 Le scorciatoie da tastiera
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se è nato, se è pronto, cosa è fallito	3.7 Diagnostica
`of_save_as_png` · `of_save_as_jpg`	Esportare il rendering in immagine	3.8 Esportare il rendering come immagine
`of_set_redraw`	Raggruppare le modifiche in un solo ridisegno	3.10 Buone pratiche
`of_preload_icons`	Icone mostrate senza ritardo	Visualizzazione istantanea: `of_icon`
`of_set_translation`	Tradurre una dicitura del componente	5.2 Adattare un'etichetta: `of_set_translation`
`of_focus_webview`	Dare il focus al componente	6.4 Tastiera e focus
`of_print` · `of_print_to_pdf`	Stampare, o scrivere un PDF	6.9 Stampare
`of_set_property` · `of_get_property` · `of_component_name`	Pilotare una proprietà per nome	3.1 Il motore delle proprietà

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.