listbar — `u_pbt_listbar` #

← Riferimento dei componenti · Sommario della guida

Barra di navigazione laterale: sezioni comprimibili a fisarmonica che contengono voci con icona, con banda d'accento sulla voce corrente e compressione in una barra di sole icone.

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

In breve #

Userobject	`u_pbt_listbar`
Classi degli item	`n_pbt_listbar_section` (sezione) → `n_pbt_listbar_item` (voce)
Serve per	Sostituire un menu laterale improvvisato a colpi di pulsanti con una navigazione strutturata, a tema e comprimibile
Opzioni opt-in	`ib_auto_width`, `ib_reorderable`

È l'unico componente della libreria a pubblicare ib_auto_width: la sua larghezza naturale ha un senso, poiché la barra compressa è nettamente più stretta di quella espansa. Del resto il caso più comune è già coperto senza attivare nulla: ib_collapsed = true restringe la barra alla sola striscia di icone, e le restituisce la larghezza quando viene espansa.

Avvio rapido #

// event open della finestra

uo_nav.of_add_section(/*key*/ "nav", /*titolo*/ "Navigazione")
uo_nav.of_add_item(/*keys*/ "nav/accueil",   /*etichetta*/ "Home",   /*icona*/ "mono:img\home.svg")
uo_nav.of_add_item(/*keys*/ "nav/documents", /*etichetta*/ "Documenti", /*icona*/ "mono:img\doc.svg")
uo_nav.of_add_item(/*keys*/ "nav/recherche", /*etichetta*/ "Ricerca", /*icona*/ "mono:img\find.svg")

uo_nav.of_add_section(/*key*/ "config", /*titolo*/ "Impostazioni")
uo_nav.of_add_item(/*keys*/ "config/preferences", /*etichetta*/ "Preferenze", /*icona*/ "mono:img\gear.svg")

// La selezione si imposta sulla VOCE, tramite il suo percorso completo
uo_nav.of_select_item("nav", "accueil")

// event ue_selection_changed di uo_nav : (string as_from_keys, string as_keys)
choose case as_keys
    case "nav/accueil"       ; of_ouvrir_accueil()
    case "nav/documents"     ; of_ouvrir_documents()
    case "config/preferences"; of_ouvrir_preferences()
end choose

Due livelli, un percorso obbligatorio #

Un identificatore di voce è univoco solo all'interno della sua sezione: non esiste quindi alcuna scorciatoia verso la voce. Ogni accesso passa dalla sezione, il che rende la scrittura non ambigua — vedere Gerarchie.

// Componente  ->  sezione        ->  voce        ->  proprieta
uo_nav        .of_section("nav") .of_item("docs") .is_text = "Documents"

Anche gli event portano il percorso completo, e con esso la voce lasciata: ue_selection_changed(as_from_keys, as_keys).

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`ib_collapsed`	boolean	`false`	`true` comprime la barra in una barra di sole icone: le etichette scompaiono, le icone restano cliccabili
`ib_auto_width`	boolean	`false`	Opt-in: idem per la larghezza, anche da espansa (la barra si allinea all'etichetta più lunga). La compressione in striscia di icone, invece, si restringe già da sola; `ue_auto_width` segue in entrambi i casi
`ib_reorderable`	boolean	`false`	Opt-in: l'utente può spostare una voce con il mouse. Lo spostamento resta nella sua sezione — un identificatore di voce è unico solo lì, quindi attraversare rischierebbe due chiavi identiche (attiva `ue_item_reordered`)
`ib_veto_selection`	boolean	`true`	Chiedere prima che la selezione si sposti (attiva `ue_selection_changing`, che può rifiutare). Attivo per impostazione predefinita: non scrivere nulla lascia sempre passare. Lo metta a `false` per togliere l'andata e ritorno verso PowerBuilder (~35 ms) dove si noterebbe — navigazione da tastiera, selezione spostata in un ciclo
`is_theme_style`	string	`fluent`	Stile visivo del componente (costanti `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Variante chiara o scura (costanti `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Colore d'accento di questo componente (`-1` = accento 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

Proprietà di una sezione — `n_pbt_listbar_section` #

Proprietà	Tipo	Predefinito	Ruolo
`is_title`	string	`""`	Titolo della sezione. Accetta il testo formattato con tag. Un titolo vuoto non mostra alcuna riga di intestazione: la sezione diventa un semplice raggruppamento invisibile
`ib_collapsed`	boolean	`false`	Fisarmonica: `true` comprime le voci di questa sezione. L'intestazione resta visibile e il suo chevron ruota

Proprietà di una voce — `n_pbt_listbar_item` #

Proprietà	Tipo	Predefinito	Ruolo
`is_text`	string	`""`	Etichetta della voce, modificabile a caldo senza ricostruire la barra. Accetta il testo formattato con tag
`is_image`	string	`""`	Icona, modificabile a caldo (forme accettate: percorso, `mono:`, `tint:`, risorsa di DLL)
`ib_enabled`	boolean	`true`	`false` disattiva la voce e ne blocca il clic
`ib_visible`	boolean	`true`	`false` nasconde la voce senza rimuoverla dalla barra
`of_is_selected ( )` → `boolean`	—	—	Questa voce è quella selezionata? Sola lettura, e di proposito: la selezione è uno stato dell'intera barra, non un flag per voce. Per porla, `of_select` sul componente — che leva sempre l'evento
`is_tooltip`	string	`""`	Tooltip semplice mostrato al passaggio del mouse sull'item
`is_super_tooltip_title`	string	`""`	Titolo del tooltip avanzato dell'item (prevale su `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Testo del tooltip avanzato dell'item (markup avanzato accettato)
`is_super_tooltip_image`	string	`""`	Immagine del tooltip avanzato dell'item

Metodi #

Sul componente #

Metodo	Ruolo
`of_add_section (string as_key, string as_text)`	Aggiunge una sezione. Restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato), come ogni gesto di struttura: l'handle viene da `of_section("nav")` quando volete impostare una proprietà
`of_insert_section (string as_key, string as_text, integer ai_index)`	Aggiunge una sezione al rango richiesto (prima posizione = 0) anziché alla fine. L'indice conta sezioni, non righe. Un nome già preso viene lasciato stare: due sezioni con lo stesso nome renderebbero ambiguo l'indirizzo di ogni loro voce. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_move_section (string as_key, integer ai_index)`	Sposta una sezione al rango `ai_index`, con le sue voci. Spostare la sola intestazione lascerebbe cadere le voci nella sezione che si ritrova sopra di esse. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_remove_section (string as_key)`	Rimuove una sezione e tutto ciò che contiene. Svuotarla conservandone le voci le renderebbe orfane: porterebbero un identificatore di sezione che non nomina più nulla. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_section (string as_key)`	Handle di una sezione esistente (creato al primo accesso)
`of_add_item (string as_keys, string as_text, string as_image)`	Aggiunge una voce al suo indirizzo, `"nav/accueil"`: la sezione in cui atterra, poi il proprio identificatore. Restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato) — `-5` se il padre non è una sezione. Un overload omette l'icona
`of_item (string as_keys)`	Handle di una voce, tramite il suo indirizzo (creato al primo accesso)
`of_insert_item (string as_keys, string as_text, integer ai_index)`	Inserisce una voce nella posizione `ai_index` all'interno della sua sezione. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_insert_item (string as_keys, string as_text, string as_image, integer ai_index)`	Idem, con l’icona della voce: `of_add_item` ne accetta una, quindi anche l’inserimento deve poterla accettare. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_move_item (string as_keys, integer ai_index)`	Sposta una voce esistente all'interno della sua sezione, conservandone lo stato. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_remove_item (string as_keys)`	Rimuove una voce indicata dalla coppia sezione / identificatore. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_clear ( )`	Svuota la barra: tutte le sezioni e tutte le voci. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_select_item (string as_keys)`	Seleziona una voce — rigorosamente equivalente a un clic dell'utente: `ue_selection_changing` viene chiesto prima, poi `ue_selection_changed` annuncia lo spostamento. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_get_layout ( )`	Rilegge la disposizione corrente in JSON: le sezioni nell'ordine, ciascuna con le sue voci in ordine e il suo stato compresso. Da memorizzare (file, database, registro) e da restituire con `of_set_layout` all'avvio successivo. La stessa coppia porta gli stessi nomi su ogni componente riorganizzabile
`of_set_layout (string as_layout_json)`	Ripristina una disposizione letta con `of_get_layout` o ricevuta con `ue_layout_changed`. Ciò che la disposizione non nomina conserva il suo posto in fondo: una disposizione di ieri non deve far sparire ciò che è stato aggiunto da allora. Applicarla non genera alcun event — l'avete fornita voi. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_clear_selection ( )`	Non lascia selezionata alcuna voce. Annunciato come qualsiasi altro spostamento. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_selected_key ( )`	Indirizzo della voce selezionata — `"nav/docs"`, `""` se non ve n'è alcuna. È esattamente ciò che `ue_selection_changed` vi consegna: un confronto resta un confronto, non un rimontaggio. Sempre quella corrente: un clic e `of_select_item` ripassano entrambi dall'event
`of_reset ( )`	Svuota la barra e riporta il componente allo stato iniziale. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_set_redraw (boolean)`	Raggruppa una raffica di modifiche in un unico 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

Su una sezione — `n_pbt_listbar_section` #

Metodo	Ruolo

Event #

Event	Attivato quando
`ue_selection_changed (string as_from_keys, string as_keys)`	La selezione si è spostata — con un clic oppure tramite `of_select_item`. Stessi argomenti di `ue_selection_changing`: la domanda e il suo esito si leggono allo stesso modo, e la coppia `as_from_*` indica la voce lasciata (vuota se nessuna)
`ue_section_toggled (string as_key, boolean ab_collapsed)`	L'utente comprime o espande una sezione dalla sua intestazione
`ue_item_reordered (string as_keys, integer ai_index)`	L'utente ha finito di trascinare una voce. `ai_index` è il suo nuovo rango nella sua sezione, a partire da 1. Conservi quest'ordine per restituire all'utente la barra come l'ha lasciata
`ue_layout_changed (string as_layout_json)`	La disposizione è cambiata — l'utente ha riorganizzato qualcosa, o il vostro codice. Porta la disposizione intera, non solo ciò che si è mosso: conservarla è una sola assegnazione
`ue_selection_changing (string as_from_keys, string as_keys)` → boolean	Annullabile, posto prima che la selezione si sposti. Sollevato per impostazione predefinita; `ib_veto_selection = false` lo elimina. Restituisca `false` per mantenere l'utente dove si trova
`ue_auto_width (long al_width)`	Il componente ha ricalcolato la propria larghezza ideale — richiede `ib_auto_width = true`
`ue_ready ( )`	Il componente ha terminato il caricamento; tutto ciò che è stato inviato prima è stato riprodotto
`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 proprio tema; l'userobject lo ha già adottato (`backcolor`)

Esempi #


uo_nav.of_set_redraw(false)

uo_nav.of_add_section("dossiers", "Cartelle")
uo_nav.of_add_item("dossiers/recents",  "Recenti",  "mono:img\clock.svg")
uo_nav.of_add_item("dossiers/clients",  "Clienti",  "mono:img\user.svg")
uo_nav.of_add_item("dossiers/archives", "Archivi", "mono:img\box.svg")

uo_nav.of_add_section("outils", "Strumenti")
uo_nav.of_add_item("outils/import", "Importa", "mono:img\import.svg")
uo_nav.of_add_item("outils/export", "Esporta", "mono:img\export.svg")

uo_nav.of_set_redraw(true)
uo_nav.of_select_item("dossiers", "recents")

Barra comprimibile che libera spazio #

// Comprimere in una barra di sole icone : la barra si restringe da sola (e riprende la
// sua larghezza quando la si espande).
uo_nav.ib_collapsed = true

// event ue_auto_width di uo_nav : (long al_width)
// La barra ha appena adottato la sua larghezza ideale : riallineare cio che si trova a destra.
uo_contenu.x     = uo_nav.x + al_width
uo_contenu.width = parent.width - uo_contenu.x

Fisarmonica: comprimere una sezione #

// Comprimere la sezione degli archivi, usata di rado
uo_nav.of_section("archives").ib_collapsed = true

// event ue_section_toggled di uo_nav : (string as_keys, boolean ab_collapsed)
of_enregistrer_preference("section_" + as_keys, String(ab_collapsed))

Reagire alla navigazione #

// event ue_selection_changed di uo_nav : (string as_from_keys, string as_keys)
// L'indirizzo porta i due livelli : due sezioni possono avere una voce "liste".
n_pbt_utils lnv_utils   // autoinstantiate : niente da creare, niente da distruggere
string ls_ids[]

if lnv_utils.of_split_path(as_keys, ls_ids) < 2 then return
choose case ls_ids[1]
    case "dossiers" ; of_ouvrir_dossier(ls_ids[2])
    case "outils"   ; of_lancer_outil(ls_ids[2])
end choose

Rifiutare un cambio di selezione #

// La domanda e posta per IMPOSTAZIONE PREDEFINITA: niente da attivare. Questa
// riga fa il contrario, la toglie dove arbitrare non serve e il costo si vedrebbe.
uo_nav.ib_veto_selection = false

// event ue_selection_changing di uo_nav :
//   (string as_from_keys, string as_keys)
// Restituire FALSE mantiene l'utente sulla voce che sta lasciando.
if of_saisie_en_cours(as_from_keys) then
    MessageBox("Inserimento", "Completi la scheda in corso prima di navigare.")
    return false
end if
return true

Aggiornare una voce a caldo #

n_pbt_listbar_item lnv_entree

// Il percorso completo e obbligatorio : componente -> sezione -> voce
lnv_entree = uo_nav.of_section("dossiers").of_item("recents")
lnv_entree.is_text  = "Recenti (12)"
lnv_entree.is_image = "mono:img\clock_full.svg"

// Disattivare o nascondere in base ai diritti, senza ricostruire la barra
uo_nav.of_section("outils").of_item("import").ib_enabled = of_a_le_droit("import")
uo_nav.of_section("outils").of_item("export").ib_visible = gb_mode_expert

Selezione pilotata dal codice #

// Spostare la selezione altrove : la banda d'accento segue
uo_nav.of_select_item("dossiers", "clients")

// Oppure cancellarla completamente
uo_nav.of_clear_selection()

Ricostruire la barra #

// of_clear svuota sezioni e voci ; of_reset vi aggiunge i valori predefiniti del componente
uo_nav.of_clear()
of_construire_menu_selon_profil()

Buone pratiche #

Una voce si aggiunge tramite il suo indirizzo: of_add_item("nav/accueil", ...). L'handle di sezione serve ormai solo a impostare una proprietà, e of_section("nav") lo restituisce al primo accesso.
Usi mono: per le icone: si ricolorano con il tema, sia chiaro sia scuro, e restano leggibili una volta che la barra è compressa in barra di sole icone.
Un titolo di sezione vuoto funge da raggruppamento discreto: le voci sono distanziate senza che appaia alcuna riga di intestazione.
ib_collapsed restringe l'userobject alla striscia di icone, ma non sposta i suoi altri controlli: gestisca ue_auto_width per occupare lo spazio liberato, altrimenti resta vuoto.
In modalità barra di sole icone restano solo le icone: imposti un tooltip su ogni voce affinché le etichette restino accessibili.
La domanda è posta per impostazione predefinita: un ue_selection_changing lasciato vuoto autorizza sempre lo spostamento, non deve fare nulla. La disattivi con ib_veto_selection = false dove il clic è ripetuto — navigazione da tastiera, selezione pilotata in un ciclo — perché ogni domanda costa un andata e ritorno verso PowerBuilder.
ib_enabled = false è preferibile a ib_visible = false quando la voce tornerà disponibile: il menu non cambia forma sotto gli occhi dell'utente.

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

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.