shellexplorer — u_pbt_shellexplorer #

← Référence des composants · Sommaire du guide

L'arborescence du shell Windows : Bureau, Ce PC, lecteurs, dossiers, Réseau — avec les vraies icônes du poste.

▶ Le voir en vrai — Application de démonstration, tuile Shell explorer : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

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

Puis, dans l'événement ue_selected de l'arbre :

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

Le shell, pas le système de fichiers #

Le composant n'énumère pas des répertoires : il interroge le shell (IShellFolder). C'est ce qui met dans l'arbre Ce PC, le Réseau, la Corbeille et les dossiers virtuels — c'est-à-dire l'arbre que l'utilisateur connaît, au lieu d'une liste de lecteurs.

Chaque nœud est identifié par son nom d'analyse : un chemin pour ce qui est sur le disque, une forme ::{GUID} pour le reste. C'est la seule clé que le shell sait relire — donc la seule à stocker si vous voulez rouvrir une branche demain.

🚨 ue_selected vous donne le nom EN PLUS du chemin, et ce n'est pas une commodité. Le nom affiché d'un dossier virtuel n'est pas la fin de son chemin : « Ce PC » n'a pas de fin. Une application qui découpe le chemin pour en tirer un libellé affichera ::{20D04FE0-…} à son utilisateur.

L'arbre se construit au fur et à mesure qu'on le parcourt : une branche n'est demandée qu'à son ouverture. Lire un disque entier pour dessiner un arbre gèlerait l'application pendant des minutes sur un lecteur réseau — et c'est le cas normal dans les applications où cette bibliothèque vit.

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

Propriétés #

Une propriété écrite avec la valeur qu'elle a déjà ne relit rien au shell : une fenêtre peut appliquer ses réglages à chaque ouverture sans rien payer.

Méthodes #

Événements #

Les icônes viennent de l'imagelist système du poste, pas de nous : un fichier .dwg porte l'icône d'AutoCAD si AutoCAD est installé, et l'icône générique sinon. C'est ce que l'utilisateur attend, et rien d'autre ne peut le donner.

Raisons d'un échec : les constantes REASON_* #

ue_path_not_found et ue_error donnent leur raison par une constante de u_pbt_shellexplorer, la même dans les deux événements et dans toutes les langues de Windows : testez-la, jamais le texte.

Clavier et souris #

• Clic sur un nœud : il est sélectionné (ue_selected, jamais une seconde fois pour le nœud déjà sélectionné) ; sur son chevron : il s'ouvre ou se ferme ; double-clic : ue_activated, et une branche s'ouvre ou se ferme ; clic droit : le nœud est sélectionné, puis ue_node_rclicked.
• Haut / Bas : le nœud précédent, le suivant ; Début / Fin : le premier, le dernier ; Page haut / Page bas : d'un écran. Ctrl + Haut / Bas fait défiler sans changer la sélection.
• Droite ouvre le nœud, puis descend sur son premier enfant ; Gauche le ferme, puis remonte au parent — inversées dans une application de droite à gauche. Retour arrière remonte au parent ; * du pavé numérique ouvre le nœud et les branches déjà lues dessous.
• Entrée : ue_activated (et une branche s'ouvre ou se ferme) ; F5 relit la branche en main (of_refresh) ; touche du menu contextuel ou Maj + F10 : ue_node_rclicked.
• Les premières lettres d'un nom, espace compris, sélectionnent le nœud affiché qui commence ainsi ; la même lettre tapée de nouveau passe au suivant.

Exemples #

Commencer ailleurs qu'au Bureau #

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

Ouvrir ce que l'utilisateur a validé #

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

Dire pourquoi une branche ne s'ouvre pas #

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

Ouvrir votre menu sur un clic droit #

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

Bonnes pratiques #

• 🚨 Stockez of_selected_key(), affichez of_selected_name(). Découper le chemin pour en tirer un libellé marche pour C:\Clients et affiche ::{20D04FE0-…} pour Ce PC.
• Laissez ib_show_files à faux tant que vous cherchez un dossier. Les fichiers rendent l'arbre illisible et sa lecture lente.
• Prévoyez ue_error dès la première version : un lecteur réseau déconnecté est le cas ordinaire, pas l'exception. Testez as_reason, jamais le texte : REASON_TIMEOUT dit qu'un partage ne répond pas dans toutes les langues de Windows.
• Utilisez ue_activated, pas ue_selected, pour valider. Sélectionner, c'est regarder ; double-cliquer, c'est décider.
• Relisez la branche qui a changé. Après avoir écrit dans un dossier, of_refresh(chemin) relit ce dossier seul ; of_refresh() relit tout ce qui est ouvert — l'état est gardé, mais sur un partage réseau chaque branche ouverte coûte un aller-retour.
• Un chemin de départ étroit vaut mieux qu'un arbre entier quand l'application sait déjà où elle travaille : partez de C:\Projets, l'utilisateur n'a plus rien à chercher.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide