shellexplorer — `u_pbt_shellexplorer` #

← Komponentenreferenz · Inhalt des Handbuchs

Der Baum der Windows-Shell: Desktop, Dieser PC, Laufwerke, Ordner, Netzwerk — mit den echten Symbolen des Arbeitsplatzes.

▶ Live ansehen — Demoanwendung, Kachel Shell explorer : die Vorschau, der erzeugende Code und diese Seite nebeneinander.

Kurz gefasst #

Userobject	`u_pbt_shellexplorer`
Dient zu	Einen Ordner wählen oder navigieren, ohne die Anwendung zu verlassen
Prinzip	Sie sagen, wo es beginnt; die Shell sagt, was da ist, und Sie erhalten, was der Benutzer gewählt hat

Schnellstart #

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

Die Shell, nicht das Dateisystem #

Die Komponente zählt keine Verzeichnisse auf: Sie fragt die Shell (IShellFolder). Das bringt Dieser PC, Netzwerk, den Papierkorb und die virtuellen Ordner in den Baum — den Baum, den der Benutzer kennt, statt einer Liste von Laufwerken.

Jeder Knoten wird durch seinen Analysenamen bezeichnet: ein Pfad für das, was auf der Platte liegt, eine ::{GUID}-Form für den Rest. Es ist der einzige Schlüssel, den die Shell zurücklesen kann — also der einzige, den man speichert.

🚨 ue_selected liefert den Namen ZUSÄTZLICH zum Pfad, und das ist keine Bequemlichkeit. Der Anzeigename eines virtuellen Ordners ist nicht das Ende seines Pfades: „Dieser PC“ hat kein Ende. Eine Anwendung, die den Pfad zerlegt, zeigt ihrem Benutzer ::{20D04FE0-…}.

Der Baum entsteht beim Gehen: Ein Zweig wird erst beim Öffnen erfragt. Eine ganze Platte zu lesen, um einen Baum zu zeichnen, würde die Anwendung auf einem Netzlaufwerk minutenlang einfrieren — und das ist der Normalfall in den Anwendungen, in denen diese Bibliothek lebt.

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

Eigenschaften #

Eigenschaft	Typ	Standard	Rolle
`is_root`	string	`""`	Wo der Baum beginnt (Konstanten `ROOT_*`). Leer = die Shell-Wurzel. Ein Pfad beginnt stattdessen dort
`ib_show_files`	boolean	`false`	Zeigt auch Dateien. Standardmäßig falsch: Ein Baum dient dazu, einen Ort zu wählen, und ein Ordner mit viertausend Dateien ist kein Ort mehr
`is_theme_style`	string	`fluent`	Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Helle oder dunkle Variante (Konstanten `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Akzentfarbe dieser Komponente (`-1` = Akzent des Themas)
`is_tooltip`	string	`""`	Einfacher Tooltip beim Überfahren der Komponente
`is_super_tooltip_title`	string	`""`	Titel des erweiterten Tooltips (hat Vorrang vor `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Text des erweiterten Tooltips (Rich-Markup erlaubt)
`is_super_tooltip_image`	string	`""`	Bild des erweiterten Tooltips

Methoden #

Methode	Rolle
`of_expand ( string as_path )`	Öffnet einen bereits gezeichneten Zweig. Ein Zweig, den niemand erreicht hat, kann nicht öffnen. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_collapse ( string as_path )`	Schließt einen Zweig. Seine Kinder bleiben, das Wiederöffnen kostet also nichts. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_select ( string as_path )`	Wählt einen bereits gezeichneten Knoten und meldet ihn wie ein Klick
`of_refresh ( )`	Baut den Baum von der Wurzel neu auf. Was offen war, schließt sich: Die Shell kann nicht sagen, was sich geändert hat
`of_selected_key ( )`	Der Analysename des gewählten Knotens. Der einzige Schlüssel, den die Shell zurücklesen kann
`of_selected_name ( )`	Der Anzeigename, wie der Explorer ihn zeigt. Leiten Sie ihn nie aus dem Pfad ab
`of_reset ( )`	Zurück zur Shell-Wurzel, nur Ordner, nichts gewählt. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist

Ereignisse #

Ereignis	Ausgelöst wenn
`ue_selected (string as_path, string as_name)`	Ein Knoten wurde gewählt: sein Pfad und sein Anzeigename
`ue_expanded (string as_path)`	Ein Zweig öffnet sich. Das Ereignis kommt vor den Kindern — die Shell wird in diesem Moment gefragt, und auf einer Netzfreigabe lässt sie sich Zeit
`ue_activated (string as_path)`	Doppelklick oder Eingabetaste. Dort öffnet eine Anwendung den Ordner, lädt ihn oder schließt eine Auswahl
`ue_error (string as_message)`	Die Shell verweigert einen Zweig — getrenntes Laufwerk, Ordner ohne Rechte. Der Baum bleibt benutzbar

Die Symbole stammen aus der System-Imagelist des Arbeitsplatzes, nicht von uns: Eine .dwg-Datei trägt das AutoCAD-Symbol, wenn AutoCAD installiert ist, und sonst das allgemeine. Genau das erwartet der Benutzer, und nichts anderes kann es liefern.

Beispiele #

Woanders als am Desktop beginnen #

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

Öffnen, was der Benutzer bestätigt hat #

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

Bewährte Praxis #

🚨 Speichern Sie of_selected_key(), zeigen Sie of_selected_name(). Den Pfad für ein Etikett zu zerlegen funktioniert bei C:\Kunden und zeigt ::{20D04FE0-…} bei Dieser PC.
Lassen Sie ib_show_files auf falsch, solange Sie einen Ordner suchen. Dateien machen den Baum unlesbar und langsam.
Planen Sie ue_error von der ersten Fassung an ein: Ein getrenntes Netzlaufwerk ist der gewöhnliche Fall, nicht die Ausnahme.
Benutzen Sie ue_activated, nicht ue_selected, zum Bestätigen. Wählen heißt schauen; Doppelklicken heißt entscheiden.
Aktualisieren Sie nicht in einer Schleife. of_refresh schließt alles: Rufen Sie es auf, wenn der Benutzer es verlangt, nicht auf einem Zeitgeber.
Ein enger Startpfad schlägt einen ganzen Baum, wenn die Anwendung schon weiß, wo sie arbeitet: Beginnen Sie bei C:\Projekte.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Mitglieder	Rolle	Beschrieben in
`of_reset`	Die Komponente zurücksetzen	3.6 Eine Komponente zurücksetzen: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Tastenkürzel der Komponente	3.5 Tastenkombinationen
`of_is_created` · `of_is_ready` · `of_get_last_error`	Ob sie entstanden ist, ob sie bereit ist, was fehlschlug	3.7 Diagnose
`of_save_as_png` · `of_save_as_jpg`	Die Darstellung als Bild exportieren	3.8 Die Darstellung als Bild exportieren
`of_set_redraw`	Änderungen zu einem einzigen Neuzeichnen bündeln	3.10 Best Practices
`of_preload_icons`	Symbole ohne Verzögerung	Sofortige Anzeige: `of_icon`
`of_set_translation`	Eine Beschriftung der Komponente übersetzen	5.2 Eine Beschriftung anpassen: `of_set_translation`
`of_focus_webview`	Der Komponente den Fokus geben	6.4 Tastatur und Fokus
`of_print` · `of_print_to_pdf`	Drucken oder ein PDF schreiben	6.9 Drucken
`of_set_property` · `of_get_property` · `of_component_name`	Eine Eigenschaft über ihren Namen steuern	3.1 Die Eigenschaften-Engine

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.