shellexplorer — `u_pbt_shellexplorer` #

The Windows shell tree: Desktop, This PC, drives, folders, Network — with the real icons of the workstation.

▶ See it live — Demo application, Shell explorer tile: the preview, the code behind it and this page, side by side.

In brief #

Userobject	`u_pbt_shellexplorer`
Used for	Choosing a folder, or browsing, without leaving the application
Principle	You say where to start; the shell says what is there, and you receive what the user chose

Quick start #

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

The shell, not the file system #

The component does not enumerate directories: it asks the shell (IShellFolder). That is what puts This PC, Network, the Recycle Bin and the virtual folders in the tree — the tree the user already knows, instead of a list of drives.

Each node is identified by its parsing name: a path for what is on disk, a ::{GUID} form for the rest. It is the only key the shell can read back — so the only one to store if you want to reopen a branch tomorrow.

🚨 ue_selected gives you the name AS WELL AS the path, and that is not a convenience. The display name of a virtual folder is not the tail of its path: "This PC" has no tail. An application that splits the path to get a label will show ::{20D04FE0-…} to its user.

The tree is built as it is walked: a branch is asked for only when it opens. Reading a whole disk to draw a tree would freeze the application for minutes on a network drive — and that is the normal case in the applications this library lives in.

// Event ue_selected : the path AND the display name
st_path.text = as_path
st_name.text = as_name

Properties #

Property	Type	Default	Role
`is_root`	string	`""`	Where the tree starts (`ROOT_*` constants). Empty = the shell root. A path starts there instead
`ib_show_files`	boolean	`false`	Shows files as well. False by default: a tree is for choosing a place, and a folder with four thousand files is not a place
`ib_show_hidden`	boolean	Explorer setting	Shows hidden files and folders. Until the application sets it, it follows the Explorer setting "Hidden items" of the workstation — and reads that setting back. Protected system files only ever follow the Explorer
`is_file_filter`	string	`""`	Which files are shown when `ib_show_files` is true: patterns separated by a semicolon (`.pdf;.docx`), matched on the real file name. Folders always show, so the user can walk to the file. Empty = all
`ib_enabled`	boolean	`true`	False: the tree stays on screen, dimmed, and answers no click and no key; it leaves the tab order. The application still drives it (`of_select`, `of_expand`, `of_refresh`)
`is_theme_style`	string	`""`	Visual style of the component (`THEME_STYLE_*` constants); empty = the application's, followed at every change
`is_theme_mode`	string	`""`	Light or dark variant (`THEME_MODE_*` constants); empty = the application's, followed at every change
`il_theme_accent`	long	`-1`	Accent colour of this component (`-1` = the application accent, or the theme's)
`is_tooltip`	string	`""`	Plain tooltip shown when hovering the component
`is_super_tooltip_title`	string	`""`	Title of the rich tooltip (takes precedence over `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Text of the rich tooltip (rich markup accepted)
`is_super_tooltip_image`	string	`""`	Image of the rich tooltip

Methods #

Method	Role
`long of_expand ( string as_path )`	Opens a branch, and the closed branches above it: one call for a deep path, even one not drawn yet, from any root (under the Desktop, `C:\` is reached through This PC). A folder created after its parent was read is found by reading that parent once more. Case and a trailing backslash do not matter. A path that cannot be reached, or is not a branch, raises `ue_path_not_found`. Like the chevron, it raises `ue_expanded` for each branch that opens on the way (none for a branch already open). Returns `0` once sent, `-5` for an empty path, `-2` when the component is not created
`long of_collapse ( string as_path )`	Closes a branch. Its children stay in place, so reopening costs nothing. A selection inside it climbs to the branch. Like a click on its chevron, it raises `ue_collapsed`, and `ue_selected` when the selection climbs to the branch; nothing when the branch is already closed. Returns `0` once applied, `-5` for an empty path, `-2` when the component is not created
`long of_select ( string as_path )`	Selects a node. The branches above it open, so the selection is on screen; a node not drawn yet is reached as `of_expand` reaches it, one that cannot be reached raises `ue_path_not_found`. Like a click, it raises `ue_selected` (nothing when the node is already selected); `of_selected_key` reads it once it is there. Returns `0` once sent, `-5` for an empty path, `-2` when the component is not created
`long of_refresh ( { string as_path } )`	Reads the tree again from the shell — after the application wrote to disk. The open branches open again and the selection comes back, found by their paths; what no longer exists is dropped, and a selection that is gone raises `ue_selected` with two empty strings. With a path, only that branch is read again (a branch never opened has nothing to read). Returns `0` once asked, `-5` for an empty path, `-2` if the component is not created
`string of_selected_key ( )`	The parsing name of the chosen node. The only key the shell can read back
`string of_selected_name ( )`	The display name, as the Explorer shows it. Never derive it from the path
`boolean of_selected_is_folder ( )`	True when the chosen node is a folder, false for a file or when nothing is selected. The events only give the path
`boolean of_has ( string as_keys )`	True when this path is drawn in the tree, open or not. A path is ONE key: its backslashes are not levels. Case does not matter
`long of_count ( { string as_keys } )`	Without a path: how many rows the tree shows (a closed branch hides its children). With a path: how many children were read under it — `0` while it was never opened, a branch being read only when it opens
`string of_keys_at ( string as_keys, long al_index )`	The path of the child at rank `al_index` (from 1) under a path, `""` past either end. A child path is already whole: it feeds straight back into `of_has`, `of_count`, `of_select` or `of_expand`. `of_keys_at(al_index)` walks the rows shown the same way
`of_reset ( )`	Back to the shell root, folders only, nothing selected. Returns `0` once applied, `-2` when the component is not created

Events #

Event	Fired when
`ue_selected (string as_path, string as_name)`	A node is selected — by the user (click, keys) or by `of_select` / `of_collapse`: its path and its display name. Also raised with two empty strings when a refresh finds that the selected node is gone
`ue_expanded (string as_path)`	A branch opens — by the user (chevron, double-click, keys) or by `of_expand` / `of_select`, once for each branch opened on the way. The event fires before the children arrive — the shell is asked at that moment, and on a network share it takes its time
`ue_activated (string as_path)`	Double-click, or Enter. That is where an application opens the folder, loads it, or closes a chooser
`ue_error (string as_message)`	The shell refuses a branch or the root — disconnected drive, folder without rights, share that does not answer within 30 seconds (`timeout`) —, with the path and the reason. The branch closes again and is asked again at its next opening; an unreadable root says so in the tree
`ue_collapsed (string as_path)`	A branch closes — by the user or by `of_collapse`. A selection inside it climbs to the branch, and `ue_selected` reports it
`ue_path_not_found (string as_path, string as_action, string as_reason)`	An `of_expand` or `of_select` could not be served: the path does not exist, lies outside the root, is not a branch, or its branch could not be read. `as_action` is `expand` or `select`

The icons come from the workstation's system imagelist, not from us: a .dwg file carries the AutoCAD icon when AutoCAD is installed, and the generic one when it is not. That is what the user expects, and nothing else can provide it.

Examples #

Starting somewhere other than the 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"

Opening what the user confirmed #

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

Good practice #

🚨 Store of_selected_key(), display of_selected_name(). Splitting the path for a label works for C:\Customers and shows ::{20D04FE0-…} for This PC.
Leave ib_show_files false while you are looking for a folder. Files make the tree unreadable and slow to read.
Plan for ue_error from the first version: a disconnected network drive is the ordinary case, not the exception.
Use ue_activated, not ue_selected, to confirm. Selecting is looking; double-clicking is deciding.
Read again the branch that changed. After writing to a folder, of_refresh(path) reads that folder alone; of_refresh() reads everything that is open — the state is kept, but on a network share every open branch costs a round trip.
A narrow starting path beats a whole tree when the application already knows where it works: start at C:\Projects and the user has nothing left to search for.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Members	Role	Detailed in
`of_reset`	Put the component back to zero	3.6 Resetting a component: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	The component's keyboard chords	3.5 Keyboard shortcuts
`of_is_created` · `of_is_ready` · `of_get_last_error`	Whether it was born, whether it is ready, what failed	3.7 Diagnostics
`of_save_as_png` · `of_save_as_jpg`	Export the rendering as an image	3.8 Exporting the rendering as an image
`of_set_redraw`	Group changes into a single repaint	3.10 Best practices
`of_preload_icons`	Icons shown with no delay	Instant display: `of_icon`
`of_set_translation`	Translate one of the component's labels	5.2 Adapting a label: `of_set_translation`
`of_focus_webview`	Give the component the focus	6.4 Keyboard and focus
`of_print` · `of_print_to_pdf`	Print, or write a PDF	6.9 Printing
`of_set_property` · `of_get_property` · `of_component_name`	Driving a property by its name	3.1 The property engine

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents

shellexplorer — u_pbt_shellexplorer #