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_path.text = as_path
st_name.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
`ib_show_hidden`	boolean	Explorer-Einstellung	Zeigt ausgeblendete Dateien und Ordner. Solange die Anwendung sie nicht setzt, folgt sie der Explorer-Einstellung „Ausgeblendete Elemente“ des Arbeitsplatzes — und liest diese zurück. Geschützte Systemdateien folgen nur dem Explorer
`is_file_filter`	string	`""`	Welche Dateien gezeigt werden, wenn `ib_show_files` wahr ist: durch Semikolon getrennte Muster (`.pdf;.docx`), am echten Dateinamen geprüft. Ordner erscheinen immer, damit der Benutzer bis zur Datei gehen kann. Leer = alle
`ib_enabled`	boolean	`true`	Falsch: Der Baum bleibt sichtbar, abgeblendet, und reagiert weder auf Klick noch Tastatur; er verlässt die Tab-Reihenfolge. Die Anwendung steuert ihn weiterhin (`of_select`, `of_expand`, `of_refresh`)
`is_theme_style`	string	`""`	Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`); leer = der der Anwendung, bei jeder Änderung übernommen
`is_theme_mode`	string	`""`	Helle oder dunkle Variante (Konstanten `THEME_MODE_*`); leer = die der Anwendung, bei jeder Änderung übernommen
`il_theme_accent`	long	`-1`	Akzentfarbe dieser Komponente (`-1` = Akzent der Anwendung, sonst der des Designs)
`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
`long of_expand ( string as_path )`	Öffnet einen Zweig und die geschlossenen Zweige darüber: ein Aufruf für einen tiefen Pfad, auch einen noch nicht gezeichneten, von jeder Wurzel aus (unter dem Desktop wird `C:\` über Dieser PC erreicht). Ein Ordner, der nach dem Lesen seines Elternteils angelegt wurde, wird durch einmaliges Neulesen des Elternteils gefunden. Groß-/Kleinschreibung und ein abschließender Backslash zählen nicht. Ein unerreichbarer Pfad, oder einer, der kein Zweig ist, löst `ue_path_not_found` aus. Wie der Pfeil löst es `ue_expanded` für jeden Zweig aus, der sich unterwegs öffnet (keines für einen bereits offenen Zweig). Liefert `0` nach dem Senden, `-5` bei leerem Pfad, `-2` wenn die Komponente nicht erzeugt ist
`long of_collapse ( string as_path )`	Schließt einen Zweig. Seine Kinder bleiben, das Wiederöffnen kostet also nichts. Eine Auswahl darin wandert zum Zweig hinauf. Wie ein Klick auf seinen Pfeil löst es `ue_collapsed` aus, und `ue_selected`, wenn die Auswahl zum Zweig hinaufwandert; nichts, wenn der Zweig schon geschlossen ist. Liefert `0` nach dem Anwenden, `-5` bei leerem Pfad, `-2` wenn die Komponente nicht erzeugt ist
`long of_select ( string as_path )`	Wählt einen Knoten. Die Zweige darüber öffnen sich, die Auswahl ist sichtbar; ein noch nicht gezeichneter Knoten wird wie mit `of_expand` erreicht, ein unerreichbarer löst `ue_path_not_found` aus. Wie ein Klick löst es `ue_selected` aus (nichts, wenn der Knoten schon gewählt ist); `of_selected_key` liest es, sobald es da ist. Liefert `0` nach dem Senden, `-5` bei leerem Pfad, `-2` wenn die Komponente nicht erzeugt ist
`long of_refresh ( { string as_path } )`	Liest den Baum erneut aus der Shell — nachdem die Anwendung auf die Platte geschrieben hat. Die offenen Zweige öffnen sich wieder und die Auswahl kehrt zurück, über ihre Pfade gefunden; was nicht mehr existiert, entfällt, und eine verschwundene Auswahl löst `ue_selected` mit zwei leeren Texten aus. Mit einem Pfad wird nur dieser Zweig neu gelesen (ein nie geöffneter Zweig hat nichts neu zu lesen). Gibt `0` zurück, sobald angefordert, `-5` bei leerem Pfad, `-2`, wenn die Komponente nicht erstellt ist
`string of_selected_key ( )`	Der Analysename des gewählten Knotens. Der einzige Schlüssel, den die Shell zurücklesen kann
`string of_selected_name ( )`	Der Anzeigename, wie der Explorer ihn zeigt. Leiten Sie ihn nie aus dem Pfad ab
`boolean of_selected_is_folder ( )`	Wahr, wenn der gewählte Knoten ein Ordner ist, falsch bei einer Datei oder ohne Auswahl. Die Ereignisse liefern nur den Pfad
`boolean of_has ( string as_keys )`	Wahr, wenn dieser Pfad im Baum gezeichnet ist, offen oder nicht. Ein Pfad ist EIN Schlüssel: seine Backslashes sind keine Ebenen. Groß-/Kleinschreibung zählt nicht
`long of_count ( { string as_keys } )`	Ohne Pfad: wie viele Zeilen der Baum zeigt (ein geschlossener Zweig verbirgt seine Kinder). Mit Pfad: wie viele Kinder darunter gelesen wurden — `0`, solange er nie geöffnet wurde, da ein Zweig erst beim Öffnen gelesen wird
`string of_keys_at ( string as_keys, long al_index )`	Der Pfad des Kindes an Position `al_index` (ab 1) unter einem Pfad, `""` außerhalb der Grenzen. Ein Kindpfad ist bereits vollständig: Er geht unverändert zurück in `of_has`, `of_count`, `of_select` oder `of_expand`. `of_keys_at(al_index)` durchläuft ebenso die angezeigten Zeilen
`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 wird gewählt — vom Benutzer (Klick, Tastatur) oder von `of_select` / `of_collapse`: sein Pfad und sein Anzeigename. Auch mit zwei leeren Texten ausgelöst, wenn ein Neulesen feststellt, dass der gewählte Knoten verschwunden ist
`ue_expanded (string as_path)`	Ein Zweig öffnet sich — durch den Benutzer (Pfeil, Doppelklick, Tastatur) oder durch `of_expand` / `of_select`, einmal je unterwegs geöffnetem Zweig. 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 oder die Wurzel — getrenntes Laufwerk, Ordner ohne Rechte, Freigabe, die nicht innerhalb von 30 Sekunden antwortet (`timeout`) —, mit Pfad und Grund. Der Zweig schließt sich und wird beim nächsten Öffnen neu angefragt; eine unlesbare Wurzel sagt es im Baum
`ue_collapsed (string as_path)`	Ein Zweig schließt sich — durch den Benutzer oder durch `of_collapse`. Eine Auswahl darin wandert zum Zweig hinauf, und `ue_selected` meldet es
`ue_path_not_found (string as_path, string as_action, string as_reason)`	Ein `of_expand` oder `of_select` konnte nicht bedient werden: Der Pfad existiert nicht, liegt außerhalb der Wurzel, ist kein Zweig, oder sein Zweig ist unlesbar. `as_action` ist `expand` oder `select`

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_open_folder(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.
Lesen Sie den geänderten Zweig neu. Nach dem Schreiben in einen Ordner liest of_refresh(Pfad) nur diesen Ordner; of_refresh() liest alles Offene neu — der Zustand bleibt, doch auf einer Netzfreigabe kostet jeder offene Zweig einen Hin- und Rückweg.
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.