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 #

// Open event of the window : the tree starts where the application works
uo_tree.is_root = "C:\Projects"

Dann im Ereignis ue_selected des Baums:

// Event ue_selected : the folder the user chose, by its display name
st_folder.text = as_name

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. Gesetzt, solange `ib_show_files` falsch ist, liest er nichts: Er gilt mit den Dateien
`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
`is_selected_key`	string	`""`	Nur lesen. Der Analysename des gewählten Knotens. Der einzige Schlüssel, den die Shell zurücklesen kann
`is_selected_name`	string	`""`	Nur lesen. Der Anzeigename, wie der Explorer ihn zeigt. Leiten Sie ihn nie aus dem Pfad ab
`ib_selected_folder`	boolean	`false`	Nur lesen. Wahr, wenn der gewählte Knoten ein Ordner ist, falsch bei einer Datei oder ohne Auswahl. Die Ereignisse liefern nur den Pfad

Eine Eigenschaft, die mit ihrem bisherigen Wert geschrieben wird, liest nichts neu aus der Shell: Ein Fenster kann seine Einstellungen bei jedem Öffnen anwenden, ohne dafür zu zahlen.

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 oder nicht gezeichnet ist (es gibt nichts zu schließen). Ein zweimal gezeichneter Pfad schließt EINE Zeile, die, die `of_select` erreichen würde. 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); `is_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
`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, ebenso wenig `/` statt `\` (`C:/Data` ist `C:\Data`). Die Wurzel (ihr Pfad oder `""`) ist da, sobald die Shell sie gelesen hat
`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. Auch die Wurzel zählt, über ihren Pfad oder `""`: `of_count(is_root)` ist die Zahl der Knoten der ersten Ebene, was auch immer darunter offen ist
`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(is_root, i)` durchläuft die erste Ebene; `of_keys_at(al_index)` durchläuft ebenso die angezeigten Zeilen
`long 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. Bei einem Zweig öffnen oder schließen sie ihn auch: `ue_expanded` oder `ue_collapsed` folgt
`ue_error (string as_path, string as_reason, string as_message)`	Die Shell verweigert einen Zweig oder die Wurzel — getrenntes Laufwerk, Ordner ohne Rechte, Freigabe, die nicht innerhalb von 30 Sekunden antwortet —: `as_path` ist sein Pfad (`""` für den Desktop), `as_reason` eine `REASON_*`-Konstante, die Ihr Code prüfen kann (`REASON_ACCESS_DENIED`, `REASON_TIMEOUT`, `REASON_NOT_FOUND`, `REASON_UNREADABLE`), `as_message` der Text der Shell für einen Menschen, `Pfad : Text` (`(root) : …` für den Desktop). Der Zweig schließt sich (`ue_collapsed`) 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, durch `of_collapse` oder durch den Baum selbst, wenn ein von `ue_expanded` als offen gemeldeter Zweig leer zurückkommt oder von der Shell verweigert wird. 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. `as_action` ist `expand` oder `select`; `as_reason` eine `REASON_*`-Konstante (siehe unten): Der Pfad existiert nicht, der Baum zeigt ihn nicht, er liegt außerhalb der Wurzel, ist die Wurzel, ist kein Zweig, liegt jenseits der Demo-Grenze, oder sein Zweig ist unlesbar
`ue_node_rclicked (string as_path, long al_x, long al_y)`	Ein Rechtsklick auf einen Knoten — zuerst ausgewählt, wie im Explorer, also kommt `ue_selected` vorher, wenn sich die Auswahl ändert —, oder die Kontextmenütaste (oder `Umschalt + F10`) auf dem ausgewählten Knoten. `al_x`, `al_y` sind Bildschirmpixel (über die Tastatur die linke untere Ecke des Knotens), die, die ein contextmenu nimmt: `uo_menu.of_show(al_x, al_y)`; für ein PowerBuilder-Menü `PopMenu(PointerX(), PointerY())` Ihres Fensters

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.

Warum ein Pfad oder Zweig scheitert: die Konstanten `REASON_*` #

ue_path_not_found und ue_error geben ihren Grund als Konstante von u_pbt_shellexplorer an, gleich in beiden Ereignissen und in jeder Sprache von Windows: Prüfen Sie sie, nie den Text.

Konstante	Was sie sagt
`REASON_NOT_FOUND`	Der Pfad existiert nicht
`REASON_NOT_SHOWN`	Der Pfad existiert, der Baum zeigt ihn nicht: eine Datei, während `ib_show_files` falsch ist, ein ausgeblendetes Element, eine von `is_file_filter` ausgeschlossene Datei
`REASON_OUTSIDE_ROOT`	Der Pfad liegt nicht unter `is_root`
`REASON_THE_ROOT`	Der Pfad ist die Wurzel selbst: kein Knoten des Baums
`REASON_NOT_A_BRANCH`	`of_expand` einer Datei oder eines Ordners ohne Kinder
`REASON_ACCESS_DENIED`	Die Shell verweigert es: keine Rechte
`REASON_TIMEOUT`	Keine Antwort innerhalb von 30 Sekunden (eine verschwundene Freigabe); dieser Server antwortet danach 30 Sekunden lang sofort mit `timeout`, bis ein Lesen gelingt; `of_refresh` und F5 versuchen es sofort erneut
`REASON_UNREADABLE`	Jede andere Weigerung der Shell: `as_message` von `ue_error` gibt ihren Text
`REASON_DEMO_LIMIT`	Demomodus: jenseits der je Ebene gezeichneten Knoten

Tastatur und Maus #

Klick auf einen Knoten: Er wird gewählt (ue_selected, nie ein zweites Mal für den bereits gewählten Knoten); auf seinen Pfeil: Er öffnet oder schließt sich; Doppelklick: ue_activated, und ein Zweig öffnet oder schließt sich; Rechtsklick: Der Knoten wird gewählt, dann ue_node_rclicked.
Auf / Ab: der vorige Knoten, der nächste; Pos1 / Ende: der erste, der letzte; Bild auf / Bild ab: um einen Bildschirm. Strg + Auf / Ab rollt, ohne die Auswahl zu ändern.
Rechts öffnet den Knoten und geht dann zu seinem ersten Kind; Links schließt ihn und geht dann zum Elternteil — in einer Anwendung von rechts nach links vertauscht. Rücktaste geht zum Elternteil; * des Ziffernblocks öffnet den Knoten und die darunter bereits gelesenen Zweige.
Eingabe: ue_activated (und ein Zweig öffnet oder schließt sich); F5 liest den Zweig in der Hand neu (of_refresh); Kontextmenütaste oder Umschalt + F10: ue_node_rclicked.
Die ersten Buchstaben eines Namens, Leerzeichen eingeschlossen, wählen den angezeigten Knoten, der so beginnt; derselbe Buchstabe erneut getippt geht zum nächsten.

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)

Sagen, warum sich ein Zweig nicht öffnet #

// Event ue_error : test the reason, never the text of the shell
if as_reason = u_pbt_shellexplorer.REASON_TIMEOUT then
    st_status.text = "The network folder " + as_path + " does not answer"
else
    st_status.text = as_message
end if

Ihr Menü bei einem Rechtsklick öffnen #

// The entries of the menu, once : uo_menu is a contextmenu of the window, and
// is_menu_path a string instance variable that keeps the folder right-clicked
uo_menu.of_add_item(/*keys*/ "open", /*text*/ "Open")
uo_menu.of_add_item(/*keys*/ "refresh", /*text*/ "Refresh")

// event ue_node_rclicked of uo_tree : (string as_path, long al_x, long al_y)
// The folder is selected first, as in the Explorer : the menu opens where the
// user clicked (from the keyboard, under the folder)
is_menu_path = as_path
uo_menu.of_show(/*x*/ al_x, /*y*/ al_y)

// event ue_item_selected of uo_menu : (string as_keys)
// The entry chosen acts on the folder right-clicked
choose case as_keys
    case "open"
        of_open_folder(is_menu_path)
    case "refresh"
        uo_tree.of_refresh(/*path*/ is_menu_path)
end choose

Bewährte Praxis #

🚨 Speichern Sie is_selected_key, zeigen Sie is_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. Prüfen Sie as_reason, nie den Text: REASON_TIMEOUT sagt in jeder Sprache von Windows, dass eine Freigabe nicht antwortet.
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
`ib_created` · `ib_ready` · `is_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` · `is_component_name`	Eine Eigenschaft über ihren Namen steuern	3.1 Die Eigenschaften-Engine
`is_accessible_name` · `is_accessible_description`	Name und Beschreibung, die ein Bildschirmleser sagt	3.4 Optionale Eigenschaften und Events

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.