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_chemin.text = as_path
st_nom.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
`is_theme_style`	string	`fluent`	Visual style of the component (`THEME_STYLE_*` constants)
`is_theme_mode`	string	`light`	Light or dark variant (`THEME_MODE_*` constants)
`il_theme_accent`	long	`-1`	Accent colour of this component (`-1` = the theme's accent)
`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
`of_expand ( string as_path )`	Opens a branch already drawn. A branch nobody has reached cannot open: the tree is built by walking it. Returns `0` once applied, `-2` when the component is not created
`of_collapse ( string as_path )`	Closes a branch. Its children stay in place, so reopening costs nothing. Returns `0` once applied, `-2` when the component is not created
`of_select ( string as_path )`	Selects a node already drawn, and reports it exactly as a click would
`of_refresh ( )`	Rebuilds the tree from the root. What was open closes: the shell has no way to say what changed
`of_selected_key ( )`	The parsing name of the chosen node. The only key the shell can read back
`of_selected_name ( )`	The display name, as the Explorer shows it. Never derive it from the path
`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 was chosen: its path and its display name
`ue_expanded (string as_path)`	A branch opens. 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 — disconnected drive, folder without rights. The tree stays usable

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_ouvrir_dossier(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.
Do not refresh in a loop. of_refresh closes everything: call it when the user asks, not on a timer.
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

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 #