shellexplorer — `u_pbt_shellexplorer` #

← Riferimento dei componenti · Sommario della guida

L'albero della shell di Windows: Desktop, Questo PC, unità, cartelle, Rete — con le vere icone della postazione.

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

In breve #

Userobject	`u_pbt_shellexplorer`
Serve a	Scegliere una cartella, o navigare, senza uscire dall'applicazione
Principio	Voi dite da dove partire; la shell dice cosa c'è, e voi ricevete ciò che l'utente ha scelto

Avvio rapido #

// Nothing to build : the tree starts at the shell root on its own
// (Desktop, This PC, Network - what the user already knows)
uo_tree.is_root = u_pbt_shellexplorer.ROOT_DESKTOP

La shell, non il file system #

Il componente non enumera directory: interroga la shell (IShellFolder). È ciò che mette nell'albero Questo PC, la Rete, il Cestino e le cartelle virtuali — l'albero che l'utente già conosce, invece di un elenco di unità.

Ogni nodo è identificato dal suo nome di analisi: un percorso per ciò che sta sul disco, una forma ::{GUID} per il resto. È l'unica chiave che la shell sa rileggere — quindi l'unica da conservare.

🚨 ue_selected vi dà il nome OLTRE al percorso, e non è una comodità. Il nome visualizzato di una cartella virtuale non è la fine del suo percorso: « Questo PC » non ha fine. Un'applicazione che spezza il percorso mostrerà ::{20D04FE0-…} al suo utente.

L'albero si costruisce man mano che lo si percorre: un ramo è chiesto solo alla sua apertura. Leggere un intero disco per disegnare un albero congelerebbe l'applicazione per minuti su un'unità di rete — ed è il caso normale nelle applicazioni in cui questa libreria vive.

// Event ue_selected : the path AND the display name
st_chemin.text = as_path
st_nom.text = as_name

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`is_root`	string	`""`	Da dove parte l'albero (costanti `ROOT_*`). Vuoto = la radice della shell. Un percorso parte invece da lì
`ib_show_files`	boolean	`false`	Mostra anche i file. Falso per impostazione predefinita: un albero serve a scegliere un luogo, e una cartella con quattromila file non è più un luogo
`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 di accento di questo componente (`-1` = accento del tema)
`is_tooltip`	string	`""`	Descrizione comando semplice mostrata al passaggio sul componente
`is_super_tooltip_title`	string	`""`	Titolo della descrizione arricchita (prevale su `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Testo della descrizione arricchita (markup ricco accettato)
`is_super_tooltip_image`	string	`""`	Immagine della descrizione arricchita

Metodi #

Metodo	Ruolo
`of_expand ( string as_path )`	Apre un ramo già disegnato. Un ramo che nessuno ha raggiunto non può aprirsi. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_collapse ( string as_path )`	Chiude un ramo. I suoi figli restano, quindi riaprirlo non costa nulla. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_select ( string as_path )`	Seleziona un nodo già disegnato, e lo segnala come farebbe un clic
`of_refresh ( )`	Ricostruisce l'albero dalla radice. Ciò che era aperto si chiude: la shell non può dire cosa è cambiato
`of_selected_key ( )`	Il nome di analisi del nodo scelto. L'unica chiave che la shell sa rileggere
`of_selected_name ( )`	Il nome visualizzato, come lo mostra Esplora risorse. Non deducetelo mai dal percorso
`of_reset ( )`	Torna alla radice della shell, solo cartelle, nulla selezionato. Restituisce `0` una volta applicato, `-2` se il componente non è creato

Eventi #

Evento	Scatta quando
`ue_selected (string as_path, string as_name)`	Un nodo è stato scelto: il suo percorso e il suo nome visualizzato
`ue_expanded (string as_path)`	Un ramo si apre. L'evento parte prima dell'arrivo dei figli — la shell è interrogata in quel momento, e su una condivisione di rete si prende il suo tempo
`ue_activated (string as_path)`	Doppio clic, o tasto Invio. È lì che un'applicazione apre la cartella, la carica, o chiude un selettore
`ue_error (string as_message)`	La shell rifiuta un ramo — unità scollegata, cartella senza diritti. L'albero resta utilizzabile

Le icone vengono dall'imagelist di sistema della postazione, non da noi: un file .dwg porta l'icona di AutoCAD se AutoCAD è installato, e quella generica altrimenti. È ciò che l'utente si aspetta, e nient'altro può darlo.

Esempi #

Partire altrove che dal Desktop #

// Only the drives, nothing above them
uo_tree.is_root = u_pbt_shellexplorer.ROOT_COMPUTER
// Or somewhere the application already knows
uo_tree.is_root = "C:\Projects"

Aprire ciò che l'utente ha confermato #

// Event ue_activated : a double-click, or Enter
of_ouvrir_dossier(as_path)

Buone pratiche #

🚨 Conservate of_selected_key(), mostrate of_selected_name(). Spezzare il percorso per un'etichetta funziona con C:\Clienti e mostra ::{20D04FE0-…} per Questo PC.
Lasciate ib_show_files a falso finché cercate una cartella. I file rendono l'albero illeggibile e lento.
Prevedete ue_error fin dalla prima versione: un'unità di rete scollegata è il caso ordinario, non l'eccezione.
Usate ue_activated, non ue_selected, per confermare. Selezionare è guardare; fare doppio clic è decidere.
Non aggiornate in ciclo. of_refresh richiude tutto: chiamatelo quando l'utente lo chiede, non su un timer.
Un percorso di partenza stretto batte un albero intero quando l'applicazione sa già dove lavora: partite da C:\Progetti.

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_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.