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

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); `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, 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 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. 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
`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
`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.