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_path.text = as_path
st_name.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
`ib_show_hidden`	boolean	impostazione di Esplora risorse	Mostra file e cartelle nascosti. Finché l'applicazione non la imposta, segue l'impostazione « Elementi nascosti » di Esplora risorse della postazione — e la rilegge. I file protetti di sistema seguono solo Esplora risorse
`is_file_filter`	string	`""`	Quali file sono mostrati quando `ib_show_files` è vero: modelli separati da punto e virgola (`.pdf;.docx`), confrontati con il vero nome del file. Le cartelle passano sempre, perché l'utente possa arrivare al file. Vuoto = tutti
`ib_enabled`	boolean	`true`	Falso: l'albero resta visibile, attenuato, e non risponde più né al clic né alla tastiera; esce dall'ordine di tabulazione. L'applicazione lo pilota comunque (`of_select`, `of_expand`, `of_refresh`)
`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	`""`	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
`long of_expand ( string as_path )`	Apre un ramo, e i rami chiusi sopra di esso: una sola chiamata per un percorso profondo, anche non ancora disegnato, da qualsiasi radice (sotto il Desktop, `C:\` si raggiunge da Questo PC). Una cartella creata dopo la lettura del suo genitore si trova rileggendo una volta il genitore. Maiuscole e barra rovesciata finale non contano. Un percorso irraggiungibile, o che non è un ramo, solleva `ue_path_not_found`. Come il chevron, solleva `ue_expanded` per ogni ramo che si apre lungo il percorso (nessuno per un ramo già aperto). Restituisce `0` una volta inviato, `-5` per un percorso vuoto, `-2` se il componente non è creato
`long of_collapse ( string as_path )`	Chiude un ramo. I suoi figli restano, quindi riaprirlo non costa nulla. Una selezione al suo interno risale sul ramo. Come un clic sul suo chevron, solleva `ue_collapsed`, e `ue_selected` quando la selezione risale sul ramo; nulla se il ramo è già chiuso. Restituisce `0` una volta applicato, `-5` per un percorso vuoto, `-2` se il componente non è creato
`long of_select ( string as_path )`	Seleziona un nodo. I rami sopra di esso si aprono, la selezione è visibile; un nodo non ancora disegnato si raggiunge come con `of_expand`, uno irraggiungibile solleva `ue_path_not_found`. Come un clic, solleva `ue_selected` (nulla se il nodo è già selezionato); `of_selected_key` lo rilegge una volta arrivato. Restituisce `0` una volta inviato, `-5` per un percorso vuoto, `-2` se il componente non è creato
`long of_refresh ( { string as_path } )`	Rilegge l'albero dalla shell — dopo che l'applicazione ha scritto sul disco. I rami aperti si riaprono e la selezione ritorna, ritrovati dal loro percorso; ciò che non esiste più è abbandonato, e una selezione scomparsa solleva `ue_selected` con due testi vuoti. Con un percorso, solo quel ramo è riletto (un ramo mai aperto non ha nulla da rileggere). Restituisce `0` una volta richiesto, `-5` per un percorso vuoto, `-2` se il componente non è creato
`string of_selected_key ( )`	Il nome di analisi del nodo scelto. L'unica chiave che la shell sa rileggere
`string of_selected_name ( )`	Il nome visualizzato, come lo mostra Esplora risorse. Non deducetelo mai dal percorso
`boolean of_selected_is_folder ( )`	Vero quando il nodo scelto è una cartella, falso per un file o se nulla è selezionato. Gli eventi danno solo il percorso
`boolean of_has ( string as_keys )`	Vero quando questo percorso è disegnato nell'albero, aperto o no. Un percorso è UNA chiave: le sue barre rovesciate non sono livelli. Le maiuscole non contano
`long of_count ( { string as_keys } )`	Senza percorso: quante righe l'albero mostra (un ramo chiuso nasconde i suoi figli). Con un percorso: quanti figli sono stati letti sotto di esso — `0` finché non è mai stato aperto, un ramo essendo letto solo alla sua apertura
`string of_keys_at ( string as_keys, long al_index )`	Il percorso del figlio di rango `al_index` (da 1) sotto un percorso, `""` oltre i limiti. Un percorso di figlio è già intero: si reinserisce così com'è in `of_has`, `of_count`, `of_select` o `of_expand`. `of_keys_at(al_index)` percorre allo stesso modo le righe mostrate
`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 è selezionato — dall'utente (clic, tastiera) o da `of_select` / `of_collapse`: il suo percorso e il suo nome visualizzato. Sollevato anche con due testi vuoti quando una rilettura trova che il nodo selezionato è scomparso
`ue_expanded (string as_path)`	Un ramo si apre — dall'utente (chevron, doppio clic, tastiera) o da `of_expand` / `of_select`, una volta per ogni ramo aperto lungo il percorso. 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 o la radice — unità scollegata, cartella senza diritti, condivisione che non risponde entro 30 secondi (`timeout`) —, con il percorso e il motivo. Il ramo si richiude e sarà richiesto di nuovo alla prossima apertura; una radice illeggibile lo scrive nell'albero
`ue_collapsed (string as_path)`	Un ramo si chiude — dall'utente o da `of_collapse`. Una selezione al suo interno risale sul ramo, e `ue_selected` lo segnala
`ue_path_not_found (string as_path, string as_action, string as_reason)`	Un `of_expand` o un `of_select` non ha potuto essere servito: il percorso non esiste, è fuori dalla radice, non è un ramo, o il suo ramo è illeggibile. `as_action` vale `expand` o `select`

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_open_folder(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.
Rileggete il ramo che è cambiato. Dopo aver scritto in una cartella, of_refresh(percorso) rilegge solo quella cartella; of_refresh() rilegge tutto ciò che è aperto — lo stato è conservato, ma su una condivisione di rete ogni ramo aperto costa un andata e ritorno.
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
`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.